TravelPlanner-Agent

Интеллектуальный агент планирования путешествий на основе LangGraph + MCP. Через диалог на естественном языке автоматически вызывает API карт Amap для получения реальных данных о погоде и достопримечательностях, группирует по географической близости и генерирует структурированный многодневный маршрут (с метками на карте и рекомендациями ближайших ресторанов).

Возможности

• Многоагентная оркестрация: граф LangGraph (извлечение предпочтений → поиск в памяти → определение намерений → вызов инструментов → планирование маршрута)

• Реальные данные: подключение к картам Amap через MCP, получение актуальной погоды, достопримечательностей (с координатами) и ближайших ресторанов

• Планирование маршрута: кластеризация K-means + цепочка ближайших соседей, географически близкие достопримечательности планируются на один день, осмотр без возвратов

• Векторная память: локальная модель эмбеддингов + ChromaDB, автоматическое извлечение предпочтений пользователя и внедрение через семантический поиск

• Структурированный вывод: with_structured_output генерирует JSON TripPlan, карточки на фронтенде + отображение на карте Amap

• Eval-регрессия: фиксированные тестовые сценарии автоматически оценивают разделение намерений, структурированный вывод, вызовы инструментов и извлечение предпочтений

Related MCP server: Ingrids Reisetjenester

Технологический стек

Архитектура

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

Быстрый старт

Требования к окружению

• Python 3.10+

• Локальная модель эмбеддингов (BGE, требуется загрузка, см. ниже)

1. Установка зависимостей

pip install -r requirements.txt

2. Загрузка локальной модели эмбеддингов

Проект использует 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 и заполните свои ключи:

# 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-ключ Amap для фронтенда

Откройте app.py и замените YOUR_AMAP_JS_KEY в HTML на ваш JS API Key Amap (это другой ключ, не Web Service 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-ключи

• JS-ключ Amap — это фронтенд-ключ, открытый в открытом виде и ограниченный белым списком доменов; настройте свой белый список

• Локальная модель и данные векторной базы не загружаются в репозиторий

Лицензия

MIT