Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 18 additions & 0 deletions .dockerignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
# 构建上下文里不需要的大文件与敏感文件
.env
.env.*
!.env.example
.git
node_modules
logs
data
agent_service/.venv
agent_service/.venv-win
agent_service/models
agent_service/chroma_db
**/__pycache__
**/*.pyc
eval
docs
example
best_model
13 changes: 12 additions & 1 deletion .env.example
Original file line number Diff line number Diff line change
Expand Up @@ -3,11 +3,22 @@
LLM_API_KEY=your_deepseek_key_here
# 高德 Web 服务 Key(仅网关使用)
AMAP_WEB_SERVICE_KEY=your_amap_web_service_key_here
AMAP_JS_KEY=your_amap_js_key_here # 仅 example/runAmapExample.js 使用
# 高德 JS API Key 与安全密钥(地图页使用,由网关 /api/config 下发到浏览器)
AMAP_JS_KEY=your_amap_js_key_here
AMAP_JS_SECURITY_CODE=your_amap_js_security_code_here

# ===== Node 网关 =====
PORT=3000
AGENT_BASE=http://127.0.0.1:8002
# 监控页 /admin.html 与 /api/metrics:设置后凭 token 访问;不设置时只允许本机访问(Docker 部署时必须设置)
ADMIN_TOKEN=
# 限流:每个 IP 每分钟的请求数(0 表示不限);重请求 = 规划 / 聊天 / 问答
RATE_LIMIT_API_PER_MIN=120
RATE_LIMIT_HEAVY_PER_MIN=10
# 过载保护:同时进行的重请求上限,超过直接返回“当前使用人数较多”
HEAVY_MAX_IN_FLIGHT=8

# Neo4j(本地 Docker 容器)
NEO4J_PASSWORD=change_me
# Docker 部署(可选):指向本机已下载的 HuggingFace 模型缓存,避免容器首次启动重新下载
# HF_CACHE_DIR=C:/Users/you/.cache/huggingface
66 changes: 66 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,66 @@
# 每次推送和 PR 都跑:Python 单元测试、网关单元测试、两个 Docker 镜像能否构建
name: CI

on:
push:
branches: [main]
pull_request:

concurrency:
group: ci-${{ github.ref }}
cancel-in-progress: true # 同一分支连续推送时,只保留最新一次

jobs:
python:
name: agent_service 测试
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with:
python-version: "3.13"
cache: pip
cache-dependency-path: agent_service/requirements*.txt
- name: 安装依赖(CPU 版 torch)
run: |
pip install torch==2.14.1 --index-url https://download.pytorch.org/whl/cpu
pip install -r agent_service/requirements.txt -r agent_service/requirements-dev.txt -r agent_service/requirements-train.txt
- name: pytest
working-directory: agent_service
run: python -m pytest -q tests

gateway:
name: 网关测试
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 22
cache: npm
- run: npm ci
- run: node --check server.js
- run: npm test

docker:
name: Docker 镜像构建
runs-on: ubuntu-latest
needs: [python, gateway] # 测试通过后再构建,省时间
steps:
- uses: actions/checkout@v4
- uses: docker/setup-buildx-action@v3
- name: 构建网关镜像
uses: docker/build-push-action@v6
with:
context: .
push: false
cache-from: type=gha
cache-to: type=gha,mode=max
- name: 构建 agent_service 镜像
uses: docker/build-push-action@v6
with:
context: .
file: agent_service/Dockerfile
push: false
cache-from: type=gha
cache-to: type=gha,mode=max
3 changes: 3 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -11,3 +11,6 @@ logs/
agent_service/models/
data/memory.sqlite3
data/neo4j/

# 个人面试准备笔记,只保留在本地
docs/interview_notes.md
20 changes: 20 additions & 0 deletions Dockerfile
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
# Node 网关镜像:docker build -t wanderai-gateway .
FROM node:22-alpine

WORKDIR /app
ENV NODE_ENV=production

COPY package.json package-lock.json ./
RUN npm ci --omit=dev

# 只拷网关运行需要的文件(页面、前端脚本、网关代码)
COPY server.js ./
COPY gateway/ gateway/
COPY src/ src/
COPY ai-chat.html output-map.html rag-search.html admin.html ./

USER node
EXPOSE 3000
HEALTHCHECK --interval=15s --timeout=5s --start-period=10s --retries=3 \
CMD wget -qO- http://127.0.0.1:3000/ai-chat.html >/dev/null || exit 1
CMD ["node", "server.js"]
127 changes: 127 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,127 @@
# 行界 WanderAI · 智能旅行规划助手

输入目的地、天数和偏好,生成**每个地点都真实存在、交通时长可执行**的行程,并在地图上展示;之后可以继续用聊天追问、修改行程。

2025 百度文心黑客松参赛项目,赛后独立重构为可评测、可容错的版本(重构过程见 [docs/upgrade_plan.md](docs/upgrade_plan.md))。

## 功能

| 能力 | 做法 |
|---|---|
| **Agent 行程规划** | Function Calling 循环编排游记检索、高德 POI / 路线 / 天气等工具,以结构化 JSON 提交行程;规则校验器检查地点真实性、城市一致、相邻两站 ≤60 分钟、每日 ≤12 小时,不通过的问题回填给 LLM 自行修正 |
| **混合检索 RAG** | 地名过滤 + BM25(jieba)与 bge 向量的 RRF 融合 + bge-reranker 重排,基于 217 篇游记回答经验类问题并标注引用 |
| **知识图谱** | 游记中的地点对齐到高德 POI,存入 Neo4j(共现、邻近、所属关系);“附近有什么”“去了 A 还去哪”类问题通过参数化 Cypher 模板查询 |
| **动态路由** | 聊天消息按 5 类意图分发:修改行程 / 游记问答 / 地点关系 / 天气与交通 / 闲聊;本地 RoBERTa 路由模型置信度不足时交给 LLM |
| **长期记忆** | 记住同行人、饮食、行动限制、预算、喜好等 8 类信息并在规划时遵守;写入时校验证据必须出自用户原话,过滤敏感信息,支持改口覆盖 |
| **工程化** | 统一错误码与用户提示语;LLM / 高德 / 图谱客户端均有超时、按错误类型重试、熔断与并发控制,任一依赖失败时逐级降级;request-id 全链路追踪;配置外置 |
| **运维** | 网关按 IP 令牌桶限流与重请求过载保护;检索结果缓存;指标接口(JSON / Prometheus)与监控页;Docker Compose 一键部署;GitHub Actions 运行测试与镜像构建 |

## 架构

```mermaid
flowchart LR
B[浏览器<br/>ai-chat / output-map / rag-search] --> G[Node 网关 :3000<br/>request-id · 统一错误 · 高德代理]
G --> A[agent_service :8002<br/>FastAPI]
G --> AM[高德 Web 服务]
A --> R{动态路由}
R -->|修改行程| P[PlanAgent<br/>Function Calling + 校验自纠]
R -->|游记问答| Q[RAG<br/>BM25 + 向量 + 重排]
R -->|附近 / 常一起去| T[工具问答]
R -->|天气 / 交通| T
P & T --> AM
P & Q --> V[(Chroma 向量库)]
T --> N[(Neo4j 图谱)]
A --> M[(SQLite 记忆)]
A --> L[DeepSeek API]
```

## 评测结果

下表的数字都可以用 `eval/` 下的脚本复现,报告在同一目录。

| 场景 | 对比 | 结果 | 报告 |
|---|---|---|---|
| 行程可执行性 | 旧流程(文本生成 + 正则解析)vs Agent,同批 20 个需求 | 超过 60 分钟的路段 22.3% → **0%** | [agent_report](eval/agent_report.md) |
| 校验自纠 | 首次提交 vs 自纠后 | 通过率 80% → **100%** | 同上 |
| 动态路由 | 每句都重新规划 vs 按意图分发,40 条人工消息 | 延迟 14.5s → **5.3s**,token -80%,误改行程 17/32 → **0/32** | [router_report](eval/router_report.md) |
| 长期记忆 | 不带记忆 vs 带记忆,6 个场景 × 3 轮 | 违反用户约束 14/18 → **3/18** | [memory_report](eval/memory_report.md) |
| 知识图谱 | 只用高德周边搜索 vs 加图谱,16 个问题 × 3 次 | 有游记依据的推荐 2.2 → **5.3** 个,延迟 -33%,token -23% | [graph_report](eval/graph_report.md) |
| 实体对齐 | 三轮人工抽检,每轮重新抽样 | 精确率 70% → **82%~88%** | [alignment_review](eval/graph_alignment_review.md) |
| 压测 | 模拟 LLM(固定 1 秒),单机 | 聊天并发 1 → 32 无失败、吞吐受 LLM 闸门约束在 7.4 次/秒;40 个同时请求时 32 个在 0.2 秒内收到“繁忙”;熔断后失败耗时约 1.5s → **33~75ms** | [load_test](eval/load_test.md) |

检索指标(nDCG / Recall / MRR)的相关性标注由 LLM 完成,人工抽检完成前不列出,见 [rag_report](eval/rag_report.md)。

## 快速开始

### Docker(推荐)

需要 Docker Desktop,以及 DeepSeek 与高德的 Key。

```bash
cp .env.example .env # 填入 LLM_API_KEY、AMAP_WEB_SERVICE_KEY、AMAP_JS_KEY、NEO4J_PASSWORD、ADMIN_TOKEN
docker compose up -d --build # 启动网关、agent_service、Neo4j
```

浏览器打开 http://localhost:3000/。监控页是 http://localhost:3000/admin.html,打开时输入 `ADMIN_TOKEN`。
向量库(`agent_service/chroma_db`)和知识图谱需要先按下面的本地方式入库、建图,容器会挂载这些目录。

### 本地运行

需要 Node 18+、Python 3.10+、[DeepSeek API Key](https://platform.deepseek.com/)(或任意 OpenAI 兼容服务)和[高德 Web 服务 Key](https://console.amap.com/)。

```bash
cp .env.example .env # 填入 LLM_API_KEY、AMAP_WEB_SERVICE_KEY
npm install

cd agent_service
python -m venv .venv-win
.venv-win/Scripts/pip install -r requirements.txt
.venv-win/Scripts/python ingest_csv.py --csv ../data/travel_notes.csv --reset # 游记入库(向量库)
.venv-win/Scripts/python app.py # Python 服务 :8002
```

另开一个终端:

```bash
npm start # 网关 :3000,浏览器打开 http://localhost:3000/
```

可选组件:

- **知识图谱**:在 `.env` 设置 `NEO4J_PASSWORD`,执行 `docker compose up -d neo4j`,然后在 `agent_service` 目录下运行 `python -m graph.build --reset`。不启用时,地点关系类问题自动改用高德周边搜索。
- **本地分类模型**:模型文件体积较大,没有放进仓库。按 [agent_service/README.md](agent_service/README.md#意图分类) 训练后放到 `agent_service/models/`;缺少模型时自动改用 LLM 分类。

健康检查:`GET /api/readyz`,会列出 LLM、向量库、分类模型、图谱各自的状态。
运行指标:`GET /api/metrics`(JSON,监控页使用)或 `GET /api/metrics?format=prometheus`。

## 目录

```text
server.js Node 网关
gateway/ 限流、过载保护、指标
admin.html 监控页
ai-chat.html 等 前端页面
agent_service/
core/ 配置、日志、错误码、LLM / 高德客户端、重试与熔断
agent/ PlanAgent、工具、校验器、动态路由、工具问答
rag/ 分块、入库、元数据抽取、BM25、重排、混合检索
graph/ 实体对齐、建图、Cypher 模板、Neo4j 客户端
memory/ 长期记忆、会话摘要
classifier/ 风格 / 路由分类模型与训练脚本
tests/ pytest 用例
eval/ 评测脚本与报告
docs/ 升级规划与设计说明
```

## 文档

- [project_documentation.md](project_documentation.md):模块说明、配置、接口、已知问题
- [agent_service/README.md](agent_service/README.md):Python 服务的安装、入库、训练与测试
- [docs/upgrade_plan.md](docs/upgrade_plan.md):从参赛版本到当前版本的分阶段改造

## 局限

- 游记语料只有 217 篇,图谱中多数地点只被 1 篇游记提到。
- 没有登录体系,记忆按浏览器生成的匿名 ID 隔离,仅适合演示。
- 一次 Agent 规划约 30~50 秒;高德个人 Key 有 QPS 和日配额限制。
- 限流、缓存与指标都在进程内,只适合单实例;多实例部署需要换成 Redis 等共享存储。
Loading
Loading