🤖 8단계 : 최종 통합 설계 및 회고 - 100-hours-a-week/7-team-ddb-wiki GitHub Wiki

Dolpin AI - 장소 추천 시스템

프로젝트 개요

Dolpin AI는 사용자의 자연어 입력을 기반으로 장소를 추천하는 AI 시스템입니다. LLM을 활용하여 키워드를 추출하고, 벡터 데이터베이스를 통해 유사한 장소를 찾아 추천합니다.

주요 기능

자연어 기반 장소 추천
LLM을 활용한 키워드 추출
벡터 데이터베이스 기반 유사도 검색
실시간 추천 처리

서비스 아키텍쳐

서비스 아키텍쳐 설명

해당 이미지는 전체 서비스에서 AI 서버의 동작을 나타내는 아키텍쳐로 사용자의 요청과 서버 모니터링에 대한 흐름을 나타낸다

사용자로부터 요청을 받으면 FE/BE를 거쳐 AI 서버에 요청이 전달
LLM을 통해 요청에 대한 처리 진행
벡터 DB 조회로 장소 탐색
BE에 장소 전달
Prometheus / Grafana를 통한 서버 모니터링 진행

AI 내부 아키텍쳐

AI 아키텍쳐 설명

벡엔드에서 endpoint를 통해 유저 입력 전달
LLM을 사용하여 유저 입력으로부터 키워드 추출 진행
추출된 키워드를 임베딩하여 user query 벡터 생성
place 벡터와 유사도 비교
유사도 순서대로 반환

기술 스택

FastAPI: 백엔드 프레임워크
LangChain: LLM 통합
Chroma: 벡터 데이터베이스
Celery: 비동기 작업 처리
Redis: 캐싱
Docker: 컨테이너화
Prometheus/Grafana: 모니터링

프로젝트 구조

dolpin_ai/
├── app/
│   ├── main.py                      # FastAPI 진입점
│   ├── api/                         # 엔드포인트 정의
│   │   ├── deps.py                  # Depends 의존성
│   │   └── v1/
│   │       ├── endpoints/
│   │       │   └── recommend.py     # 추천 요청 엔드포인트
│   │       └── router.py            # v1 router 통합
│   ├── services/                    # 서비스 로직
│   │   ├── recommender.py           # 추천 알고리즘
│   │   ├── rag_engine.py            # RAG 체인
│   │   ├── prompt_manager.py        # 프롬프트 관리
│   │   └── vector_store.py          # 벡터DB 연동
│   ├── ml/                          # 모델 로딩 및 추론
│   │   ├── model_loader.py          # 모델 로딩
│   │   └── inference.py             # 추론 엔진
│   ├── schemas/                     # Pydantic 모델
│   │   └── recommend_schema.py      # 입력/출력 스키마
│   ├── core/                        # 설정, 보안, CORS 등
│   │   ├── config.py                # 기본 설정
│   │   └── init_app.py              # 앱 부트스트랩
│   │
│   ├── models/                      # DB 모델 정의
│   │   ├── base.py                  # 기본 모델
│   │   └── place.py                 # 장소 모델
│   │
│   ├── database/                    # DB 설정
│   │   ├── session.py               # DB 세션 관리
│   │   └── migrations/              # Alembic 마이그레이션
│   │
│   ├── cache/                       # 캐싱
│   │   ├── redis.py                 # Redis 설정
│   │   └── decorators.py            # 캐시 데코레이터
│   │
│   ├── tasks/                       # 비동기 작업
│   │   ├── celery.py                # Celery 설정
│   │   └── workers/                 # 워커 정의
│   │
│   ├── exceptions/                  # 예외 처리
│   │   ├── handlers.py              # 예외 핸들러
│   │   └── custom.py                # 커스텀 예외
│   │
│   ├── logging/                     # 로깅
│   │   ├── config.py                # 로깅 설정
│   │   └── middleware.py            # 로깅 미들웨어
│   │
│   └── utils/                       # 보조 유틸 함수
│       ├── logger.py                # loguru/structlog 기반 로거
│       ├── text_cleaner.py          # 텍스트 전처리 유틸
│       └── timer.py                 # 성능 측정 데코레이터
│
├── tests/                           # 테스트
│   ├── unit/                        # 단위 테스트
│   ├── integration/                 # 통합 테스트
│   └── e2e/                         # E2E 테스트
│
├── docs/                            # 문서화
│   ├── api/                         # API 문서
│   └── architecture/                # 아키텍처 문서
│
├── scripts/                         # 유틸리티
│   ├── setup.sh                     # 환경 설정
│   └── deploy.sh                    # 배포 스크립트
│
├── monitoring/                      # 모니터링
│   ├── prometheus/                  # Prometheus 설정
│   └── grafana/                     # Grafana 대시보드
│
├── config/                          # 환경 설정
│   ├── development.py               # 개발 환경
│   ├── testing.py                   # 테스트 환경
│   └── production.py                # 운영 환경
│
├── Dockerfile                       # 컨테이너 설정
├── docker-compose.yml               # 컨테이너 구성
├── requirements.txt                 # 의존성
└── README.md                        # 프로젝트 문서

데이터베이스 관리
- models/: SQLAlchemy 기반 DB 모델 정의
- database/: DB 세션 관리 및 마이그레이션
- vector_store.py: FAISS/Chroma 벡터 DB 연동
캐싱 (cache/)
- redis.py: Redis 연결 및 설정
- decorators.py: 캐시 데코레이터 구현
- 성능 최적화를 위한 캐싱 전략
비동기 작업
- tasks/: Celery 기반 비동기 작업 관리
- workers/: 임베딩 생성 등 백그라운드 작업
- celery_app.py: Celery 설정 및 워커 정의
예외 처리 (exceptions/)
- handlers.py: 전역 예외 핸들러
- custom.py: 커스텀 예외 클래스
- 에러 응답 표준화
로깅 (logging/)
- config.py: 로깅 설정
- middleware.py: 요청/응답 로깅
- utils/logger.py: 구조화된 로깅
유틸리티 (utils/)
- text_cleaner.py: 텍스트 전처리
- timer.py: 성능 측정
- logger.py: 로깅 유틸리티
테스트 (tests/)
- unit/: 단위 테스트
- integration/: 통합 테스트
- e2e/: End-to-End 테스트
문서화 (docs/)
- api/: API 문서
- architecture/: 시스템 아키텍처 문서
- README.md: 프로젝트 개요
모니터링 (monitoring/)
- prometheus/: 메트릭 수집
- grafana/: 대시보드 및 시각화
- 성능 모니터링
환경 설정 (config/)
- development.py: 개발 환경
- testing.py: 테스트 환경
- production.py: 운영 환경
배포 관련
- Dockerfile: 컨테이너 이미지 정의
- docker-compose.yml: 서비스 구성
- requirements.txt: 의존성 관리
API 엔드포인트 (api/)
- v1/endpoints/: API 버전 1 엔드포인트
- deps.py: 의존성 주입
- router.py: 라우터 통합
서비스 로직 (services/)
- recommender.py: 추천 알고리즘
- rag_engine.py: RAG 체인
- prompt_manager.py: 프롬프트 관리
ML 모델 (ml/)
- model_loader.py: 모델 로딩
- inference.py: 추론 엔진
- LLM 및 임베딩 모델 관리
데이터 스키마 (schemas/)
- recommend_schema.py: 추천 관련 스키마
- Pydantic 기반 데이터 검증
핵심 설정 (core/)
- config.py: 기본 설정
- init_app.py: 앱 초기화
- CORS, 미들웨어 등 설정

프로젝트 구조 이점

모듈화
확장 가능한 아키텍처
유지보수 용이성
테스트 용이성
배포 자동화
모니터링 용이성

API 응답 예시

POST /api/v1/recommend
Content-Type: application/json

{
    "text": "맛있는 한식집 추천해줘"
}

응답:

{
    "recommendations": [
        {
            "id": 1,
            "similarity_score": 0.95
        },
        {
            "id": 21,
            "similarity_score": 0.95
        },
        {
            "id": 32,
            "similarity_score": 0.95
        }
    ]
}

모니터링 기술스택

Prometheus: 메트릭 수집
Grafana: 대시보드 및 시각화
로깅: 구조화된 로그 수집

버전별 인프라 기술 및 서비스 명세

항목	초기 (Jetson Orin Nano)	확장 시 (클라우드 기반 EC2/K8s)
모델 서버	단일 FastAPI 서버 (Docker 컨테이너)	여러 EC2 인스턴스에 동일한 컨테이너 배포 (Kubernetes 또는 Auto Scaling)
트래픽 분산	GCP Load Balancer (단일 서버 내 라우팅)	AWS ALB 또는 Kubernetes Ingress를 통한 부하 분산
서버 운영 방식	온프레미스 Jetson 운영 (하루 15시간)	트래픽 피크 시간대에 EC2 스팟 인스턴스 추가 운용 (예: 식사시간대)
모니터링	Prometheus + Grafana (Jetson 내 모니터링)	동일 스택을 EC2 인스턴스에도 적용하여 전체 리소스 사용 모니터링

모니터링 대상 지표 목록과 수집/시각화 방법

구성요소	역할	도구
서버/애플리케이션	API 요청 수, 응답 시간, 에러율	FastAPI 내 Prometheus exporter
시스템 리소스	CPU, 메모리, 디스크 I/O, 네트워크 지표	Node Exporter, DCGM Exporter
시스템 대시보드	실시간 시각화 및 모니터링	Grafana
알림	이상 징후 발생 시 경고 전송	Alertmanager (Discord)

-> 간이 부하 테스트 또는 시뮬레이션 결과와 그에 따른 시스템 자원 사용량/응답시간 변화 분석

운영 관점에서 인프라 확장 및 모니터링의 이유

초기 운영:
- 극소수 사용자 대상으로 Jetson Orin Nano에서 Docker 컨테이너 기반 FastAPI 서버로 운영.
- Gemini API 프리티어 제한 내에서 운영하며, 실시간 모니터링을 통해 무료 한도 초과 시 유료 전환 예정.
확장 전략:
- 특정 시간대(예: 식사 시간대, 부하 테스트 기간) 및 트래픽 증가 시 EC2 인스턴스를 추가하여 수평 확장 대응.
- AWS ALB 또는 K8s Ingress로 API 요청 분산.
모니터링 및 대응:
- Prometheus + Grafana로 실시간 지표 확인, Alertmanager로 자동 알림 연동.

단계별 설계 적용 계획(추후 진행 방향)

MVP : Gemini를 활용한 사용자 데이터 수집 및 성능 보장
v2 : Local LLM을 사용한 키워드 추출모델 개발
v3 : 딥러닝 모델을 활용한 추천 알고리즘 고도화