TravelPlanner-Agent

LangGraph + MCP 기반의 지능형 여행 플래닝 Agent. 자연어 대화를 통해 자동으로 高德地图 API를 호출하여 실제 날씨와 관광지 데이터를 가져오고, 지리적 거리별로 클러스터링하여 구조화된 여러 날 일정(지도 마커, 인근 레스토랑 추천 포함)을 생성합니다.

기능 특성

• 다중 Agent 오케스트레이션: LangGraph 그래프 기반 (선호도 추출 → 메모리 검색 → 의도 판단 → 도구 호출 → 일정 계획)

• 실제 데이터: MCP를 통해 高德地图에 연결하여 실시간 날씨, 관광지(좌표 포함), 주변 레스토랑 획득

• 경로 계획: K-means 클러스터링 + 최근접 이웃 체인, 지리적으로 가까운 관광지를 같은 날에 배치하여 이동 경로가 겹치지 않음

• 벡터 메모리: 로컬 embedding 모델 + ChromaDB, 사용자 선호도를 자동 추출하고 의미론적 검색으로 주입

• 구조화된 출력: with_structured_output로 TripPlan JSON 생성, 프론트엔드 카드 + 高德地图 표시

• Eval 회귀 테스트: 고정 테스트 케이스로 의도 분류, 구조화된 출력, 도구 호출, 선호도 추출 자동 평가

Related MCP server: Ingrids Reisetjenester

기술 스택

아키텍처

用户输入
  → extract（偏好提取，两级过滤：关键词粗筛 + LLM 精判）
  → retrieve（记忆检索，从向量库查相关偏好注入）
  → route（意图判断：规划 or 闲聊）
  → model（LLM 决定调用工具）
  → tools（MCP 高德：天气 / 景点 / 周边餐厅）
  → plan（K-means 聚类分组 + LLM 结构化输出 TripPlan）
  → 前端卡片 + 地图展示

빠른 시작

환경 요구사항

• Python 3.10+

• 로컬 embedding 모델 (BGE, 다운로드 필요, 아래 참조)

1. 의존성 설치

pip install -r requirements.txt

2. 로컬 embedding 모델 다운로드

프로젝트는 BAAI/bge-small-zh-v1.5를 벡터 검색에 사용합니다. 魔搭(ModelScope)에서 models/ 디렉토리로 다운로드하세요:

mkdir -p models
python -c "from modelscope import snapshot_download; snapshot_download('AI-ModelScope/bge-small-zh-v1.5', local_dir='./models/bge-small-zh-v1.5')"

3. 환경 변수 설정

.env.example을 .env로 복사하고 key를 입력하세요:

# DeepSeek（主对话 + 结构化输出 + 偏好提取）
DEEPSEEK_API_KEY=your_deepseek_key
DEEPSEEK_BASE_URL=https://api.deepseek.com

# 高德地图（Web 服务 API Key，后端调天气/景点/餐厅）
AMAP_API_KEY=your_amap_web_key

4. 프론트엔드 高德 JS Key

app.py를 열고 HTML의 YOUR_AMAP_JS_KEY를 본인의 高德 JS API Key로 교체하세요 (Web 서비스 Key와는 다른 key입니다).

5. 시작

python app.py

브라우저에서 http://localhost:8000 에 접속하여 "帮我规划西安三天行程"과 같은 입력을 하세요.

디렉토리 구조

TravelPlanner-Agent/
├── app.py                # 主后端（FastAPI + LangGraph 图）
├── amap_mcp_server.py    # 高德 MCP Server（天气/景点/周边餐厅）
├── config.py             # 配置（从 .env 读取）
├── eval_app.py           # Eval 回归测试
├── requirements.txt      # 依赖
└── examples/             # 学习版示例（V0-V5 逐步搭建过程）
    ├── main.py           # V0 最小 LLM 调用
    ├── trip_agent.py     # V2 手写 Agent Loop
    ├── graph_agent.py    # V3 LangGraph 版
    ├── v4_memory.py      # V4 手工记忆
    ├── v4_vector_memory.py  # V4 向量检索记忆
    ├── v5_eval.py        # V5 Eval
    └── test_structured.py   # 结构化输出验证

Eval 실행

python eval_app.py

6개의 테스트 케이스를 실행하여 의도 분류, 구조화된 출력 완전성, 도구 호출, 선호도 추출을 자동 평가합니다.

보안 안내

• .env는 .gitignore에 추가되어 있습니다. 실제 API Key를 커밋하지 마세요

• 高德 JS Key는 프론트엔드 key로, 평문으로 노출되며 도메인 화이트리스트로 제한됩니다. 본인의 화이트리스트를 구성하세요

• 로컬 모델과 벡터 라이브러리 데이터는 저장소에 커밋되지 않습니다

License

MIT