AI Server

협업 여행 서비스의 AI 기능을 담당하는 FastAPI 서버다.

Spring Boot BE와 분리된 독립 서버로, 채팅 요약과 여행 맥락 기반 AI 응답을 처리한다.

주요 기능

• 채팅 메시지를 기반으로 rolling structured summary 생성
• 일정, 북마크, 최근 대화 맥락을 반영한 AI 응답 생성
• 장소 추천 요청 시 Google Places 기반 후보 조회
• 여행 도메인 외 질문은 unsupported intent로 분리
• OpenAI structured output 기반 intent 분기 및 응답 스키마 고정

API

Method	Path	Description
GET	/health	서버 상태 확인
POST	/v1/ai/context/summaries	이전 summary와 신규 메시지로 요약 갱신
POST	/v1/ai/chat/plan	사용자 질문을 intent별로 처리하고 AI 응답 생성

전체 구조

app/
├─ main.py
├─ dependencies.py
├─ api/
│  └─ routes.py
├─ core/
│  └─ config.py
├─ schemas/
│  ├─ chat.py
│  └─ planner.py
├─ clients/
│  ├─ openai_travel.py
│  └─ google_places.py
└─ services/
   ├─ chat_plan_responses.py
   ├─ context_selection.py
   ├─ place_details.py
   ├─ summary.py
   └─ orchestrator.py

현재 동작 방식

• 채팅 요약 API는 previous_summary + messages_since_last_summary를 받아 rolling structured summary를 만든다.
• 채팅 플랜 API는 summary + delta + recent_messages + request_message를 받아 intent를 분기한다.
• intent는 place_recommendation, conversation_summary, travel_general_chat, unsupported 4개로 고정했다.
• 장소 추천은 북마크/일정 맥락을 반영하고, 필요 시 Google Places 후보를 반환한다.
• 사용자가 추천 개수를 명시하면 1~3개 범위에서 반영하고, 명시하지 않으면 기본 3개를 반환한다.
• OpenAI 호출은 summary 생성, intent 분기, 최종 답변 생성에 structured-output 프롬프트를 사용한다.

환경 변수

필수 환경 변수는 아래 2개다.

Name	Description
OPENAI_API_KEY	OpenAI API 호출용 키
GOOGLE_MAPS_API_KEY	Google Places API 호출용 키
AI_LOG_LEVEL	로그 레벨, 기본값 INFO
AI_LOG_FILE_PATH	JSON 파일 로그 경로, 예: logs/app.log
AI_PRIVATE_IP	운영 compose에서 앱/노드 exporter 포트를 바인딩할 private IP
LOKI_PUSH_URL	Alloy가 AI 서버 JSON 로그를 push할 Loki endpoint

실행

cp .env.example .env
pip install -e .

uvicorn app.main:app --reload

기본 주소는 http://127.0.0.1:8000 이고 Swagger는 /docs 에서 확인할 수 있다. Prometheus metrics는 /metrics에서 확인할 수 있다. FastAPI HTTP metrics와 기본 Python/process metrics가 함께 노출된다.

Docker Compose 실행

개발 환경은 .env, 운영 환경은 .env.prod 파일을 사용한다. 개발 환경 예시는 .env.example, 운영 환경 예시는 .env.prod.example를 참고한다.

cp .env.example .env
docker compose -f compose.dev.yaml up --build

cp .env.prod.example .env.prod
docker compose -f compose.prod.yaml pull
docker compose -f compose.prod.yaml up --wait --wait-timeout 120

운영 compose는 백엔드 모니터링 구성과 같은 방식으로 AI 서버의 8000 포트와 node-exporter 9100 포트를 AI_PRIVATE_IP에만 바인딩한다. ai-server는 /app/logs/application.log에 JSON 로그를 쓰고, 함께 실행되는 Grafana Alloy가 해당 파일을 LOKI_PUSH_URL로 push한다. 백엔드 모니터링 서버의 Prometheus는 infra/monitoring/prometheus/targets/ai.json에 렌더링된 ${AI_PRIVATE_IP}:8000 타깃을 /metrics 경로로 scrape한다.