TravelPlanner-Agent

Ein intelligenter Reiseplanungs-Agent auf Basis von LangGraph + MCP. Über natürliche Sprachdialoge werden automatisch die 高德地图-API aufgerufen, um echte Wetter- und Sehenswürdigkeitsdaten abzurufen, nach geografischer Distanz geclustert und gruppiert, um strukturierte mehrtägige Reiserouten zu generieren (inklusive Kartenmarkierungen und Restaurantempfehlungen in der Nähe).

Funktionen

• Multi-Agent-Orchestrierung: LangGraph-graphgesteuert (Präferenzextraktion → Gedächtnisabruf → Absichtserkennung → Tool-Aufruf → Reiseplanung)

• Echte Daten: Verbindung zu 高德地图 über MCP, Abruf von Echtzeit-Wetter, Sehenswürdigkeiten (mit Koordinaten) und umliegenden Restaurants

• Routenplanung: K-means-Clustering + Nearest-Neighbor-Kette, geografisch nahe Sehenswürdigkeiten werden am selben Tag geplant, Besichtigung ohne Umwege

• Vektor-Gedächtnis: Lokales Embedding-Modell + ChromaDB, automatische Extraktion von Benutzerpräferenzen und Injektion per semantischer Suche

• Strukturierte Ausgabe: with_structured_output generiert TripPlan-JSON, Frontend-Karten + 高德地图-Anzeige

• Eval-Regression: Automatische Bewertung von Absichtsweiterleitung, strukturierter Ausgabe, Tool-Aufrufen und Präferenzextraktion anhand fester Testfälle

Related MCP server: Ingrids Reisetjenester

Technologie-Stack

Architektur

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

Schnellstart

Systemanforderungen

• Python 3.10+

• Lokales Embedding-Modell (BGE, muss heruntergeladen werden, siehe unten)

1. Abhängigkeiten installieren

pip install -r requirements.txt

2. Lokales Embedding-Modell herunterladen

Das Projekt verwendet BAAI/bge-small-zh-v1.5 für die Vektorsuche. Laden Sie es von ModelScope in das Verzeichnis models/ herunter:

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. Umgebungsvariablen konfigurieren

Kopieren Sie .env.example zu .env und füllen Sie Ihre Schlüssel aus:

# 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. Frontend-高德 JS Key

Öffnen Sie app.py und ersetzen Sie YOUR_AMAP_JS_KEY im HTML durch Ihren 高德 JS-API-Key (dieser unterscheidet sich vom Web-Service-Key).

5. Starten

python app.py

Öffnen Sie http://localhost:8000 im Browser und geben Sie z. B. „Helfen Sie mir, eine dreitägige Reise nach Xi'an zu planen" ein.

Verzeichnisstruktur

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 ausführen

python eval_app.py

Es werden 6 Testfälle ausgeführt, die automatisch bewerten: Absichtsweiterleitung, Vollständigkeit der strukturierten Ausgabe, Tool-Aufrufe und Präferenzextraktion.

Sicherheitshinweise

• .env ist in .gitignore aufgenommen, bitte keine echten API-Keys committen

• Der 高德 JS Key ist ein Frontend-Key, der im Klartext exponiert ist und durch Domain-Whitelists eingeschränkt wird; bitte konfigurieren Sie Ihre eigene Whitelist

• Lokale Modelle und Vektordatenbank-Daten werden nicht ins Repository committet

Lizenz

MIT