diff --git a/.dockerignore b/.dockerignore
new file mode 100644
index 0000000..84547a8
--- /dev/null
+++ b/.dockerignore
@@ -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
diff --git a/.env.example b/.env.example
index 716bf36..6d5db17 100644
--- a/.env.example
+++ b/.env.example
@@ -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
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
new file mode 100644
index 0000000..a95b36b
--- /dev/null
+++ b/.github/workflows/ci.yml
@@ -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
diff --git a/.gitignore b/.gitignore
index 9707347..323b075 100644
--- a/.gitignore
+++ b/.gitignore
@@ -11,3 +11,6 @@ logs/
agent_service/models/
data/memory.sqlite3
data/neo4j/
+
+# 个人面试准备笔记,只保留在本地
+docs/interview_notes.md
diff --git a/Dockerfile b/Dockerfile
new file mode 100644
index 0000000..246af44
--- /dev/null
+++ b/Dockerfile
@@ -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"]
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..c5e6069
--- /dev/null
+++ b/README.md
@@ -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[浏览器
ai-chat / output-map / rag-search] --> G[Node 网关 :3000
request-id · 统一错误 · 高德代理]
+ G --> A[agent_service :8002
FastAPI]
+ G --> AM[高德 Web 服务]
+ A --> R{动态路由}
+ R -->|修改行程| P[PlanAgent
Function Calling + 校验自纠]
+ R -->|游记问答| Q[RAG
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 等共享存储。
diff --git a/admin.html b/admin.html
new file mode 100644
index 0000000..9925de9
--- /dev/null
+++ b/admin.html
@@ -0,0 +1,210 @@
+
+
+
+
+
+ WanderAI 运行监控
+
+
+
+
+ WanderAI 运行监控
+ 检查中
+ 每 5 秒刷新 · — ·
+
+
+
+
+
+ 依赖状态
+
+
+ 接口(网关)
+
+
+ 接口(Agent 服务)
+
+
+
+
+
+
+
+
+
+
diff --git a/agent_service/Dockerfile b/agent_service/Dockerfile
new file mode 100644
index 0000000..ff86c6f
--- /dev/null
+++ b/agent_service/Dockerfile
@@ -0,0 +1,30 @@
+# agent_service 镜像。构建上下文是项目根目录(需要 config.yaml):
+# docker build -f agent_service/Dockerfile -t wanderai-agent .
+FROM python:3.13-slim
+
+ENV PYTHONDONTWRITEBYTECODE=1 \
+ PYTHONUNBUFFERED=1 \
+ PIP_NO_CACHE_DIR=1 \
+ HF_HOME=/models/hf
+
+WORKDIR /app
+
+# 先装依赖再拷代码:代码改动不会让依赖层失效,重新构建只需几秒
+RUN pip install torch==2.14.1 --index-url https://download.pytorch.org/whl/cpu
+COPY agent_service/requirements.txt agent_service/requirements.txt
+RUN pip install -r agent_service/requirements.txt
+
+COPY config.yaml ./
+COPY agent_service/ agent_service/
+
+# 不用 root 运行
+RUN useradd --create-home --uid 1000 app && mkdir -p /app/logs /models/hf && chown -R app /app /models
+USER app
+
+WORKDIR /app/agent_service
+EXPOSE 8002
+# 容器内必须监听 0.0.0.0,端口是否对外暴露由 compose 决定
+ENV SERVER__HOST=0.0.0.0
+HEALTHCHECK --interval=15s --timeout=5s --start-period=120s --retries=5 \
+ CMD python -c "import urllib.request,sys; sys.exit(0 if urllib.request.urlopen('http://127.0.0.1:8002/healthz', timeout=3).status == 200 else 1)"
+CMD ["python", "app.py"]
diff --git a/agent_service/agent/tools.py b/agent_service/agent/tools.py
index 72000c3..b5527f2 100644
--- a/agent_service/agent/tools.py
+++ b/agent_service/agent/tools.py
@@ -16,6 +16,7 @@
from graph.queries import TEMPLATES, run_template
from rag.metadata import normalize_place
from core.logging import get_logger
+from core.metrics import metrics
from rag.retriever import Retriever
log = get_logger("agent.tools")
@@ -260,6 +261,7 @@ def _record(self, ctx: PlanContext, name: str, args: Dict[str, Any], result: Dic
latency_ms=round((time.perf_counter() - started) * 1000),
)
ctx.records.append(rec)
+ metrics.tool_call(name, rec.ok)
log.info("tool call", extra={"tool": name, "ok": rec.ok, "empty": rec.empty, "latency_ms": rec.latency_ms,
"error": rec.error or None})
@@ -343,6 +345,8 @@ async def _graph_query(self, ctx: PlanContext, args: Dict[str, Any]) -> Dict[str
rows = await run_template(self.graph, template, place=str(args.get("place") or "").strip(),
city=city, tag=str(args.get("tag") or "").strip())
except AppError as e:
+ log.warning("graph query failed", extra={"template": template, "code": e.code.value,
+ "detail": str(e.detail)[:300] if e.detail else None})
if e.code == ErrorCode.GRAPH_UNAVAILABLE:
return degraded
raise
diff --git a/agent_service/app.py b/agent_service/app.py
index ad21169..3407efb 100644
--- a/agent_service/app.py
+++ b/agent_service/app.py
@@ -12,7 +12,7 @@
from fastapi import FastAPI, Request
from fastapi.exceptions import RequestValidationError
-from fastapi.responses import JSONResponse, StreamingResponse
+from fastapi.responses import JSONResponse, PlainTextResponse, StreamingResponse
from pydantic import BaseModel, Field
from starlette.concurrency import run_in_threadpool
from starlette.exceptions import HTTPException as StarletteHTTPException
@@ -28,6 +28,7 @@
from core.errors import AppError, ErrorCode, error_body
from core.llm import LLMClient
from core.logging import get_logger, request_id_var, setup_logging
+from core.metrics import metrics
from rag.ingest import load_csv_records
from rag.pipeline import RagPipeline
from rag.retriever import Retriever
@@ -79,6 +80,10 @@ async def lifespan(_app: FastAPI):
services.amap, services.memory)
if not settings.amap_enabled:
log.warning("AMAP_WEB_SERVICE_KEY is not set; /plan will fail")
+ metrics.register_gauge("caches", lambda: {"amap": services.amap.cache.stats(),
+ "retrieval": services.retriever.cache.stats()})
+ metrics.register_gauge("breakers", lambda: [services.llm.breaker.snapshot(), services.graph.breaker.snapshot()])
+ metrics.register_gauge("llm_concurrency", services.llm.concurrency)
# 预加载 embedding 模型、向量库、BM25 索引和重排模型,避免首个请求因冷启动超时;
# 失败不阻止启动,由 /readyz 反映,请求时会再次尝试加载
try:
@@ -108,12 +113,16 @@ async def request_context(request: Request, call_next):
token = request_id_var.set(rid)
started = time.perf_counter()
status = 500
+ metrics.request_started()
try:
response = await call_next(request)
status = response.status_code
response.headers["X-Request-ID"] = rid
return response
finally:
+ # 按路由模板统计(/memory/{memory_id} 而不是每个 id 一行);未匹配的路径归为 unmatched
+ route = getattr(request.scope.get("route"), "path", "unmatched")
+ metrics.request_finished(request.method, route, status, (time.perf_counter() - started) * 1000)
log.info(
"access",
extra={
@@ -137,6 +146,7 @@ def _error_response(code: ErrorCode, message: Optional[str] = None) -> JSONRespo
@app.exception_handler(AppError)
async def handle_app_error(_request: Request, exc: AppError):
+ metrics.error(exc.code.value)
level = log.error if exc.code == ErrorCode.INTERNAL else log.warning
level("request failed", extra={"code": exc.code.value, "detail": str(exc.detail)[:500] if exc.detail else None})
return _error_response(exc.code, exc.message)
@@ -157,6 +167,7 @@ async def handle_http_error(_request: Request, exc: StarletteHTTPException):
@app.exception_handler(Exception)
async def handle_unexpected(_request: Request, exc: Exception):
+ metrics.error(ErrorCode.INTERNAL.value)
log.exception("unhandled error")
return _error_response(ErrorCode.INTERNAL)
@@ -212,6 +223,14 @@ async def healthz():
return {"status": "ok"}
+@app.get("/metrics")
+async def get_metrics(format: str = "json"):
+ """运行指标。format=prometheus 时返回 Prometheus 文本格式,便于接入 Prometheus / Grafana。"""
+ if format == "prometheus":
+ return PlainTextResponse(metrics.prometheus(), media_type="text/plain; version=0.0.4")
+ return metrics.snapshot()
+
+
@app.get("/readyz")
async def readyz():
"""就绪探针:逐项检查依赖。任一关键依赖不可用返回 503。"""
diff --git a/agent_service/config.py b/agent_service/config.py
index 2d8b57e..0432253 100644
--- a/agent_service/config.py
+++ b/agent_service/config.py
@@ -53,6 +53,8 @@ class RetrievalConfig(BaseModel):
reranker_max_length: int = Field(256, ge=64, le=1024)
city_filter: bool = True # 查询中识别到城市/省份时,只在相关笔记中检索
metadata_path: Path = Path("data/notes_metadata.jsonl")
+ cache_size: int = Field(1024, ge=0) # 检索结果缓存条数;0 关闭。重新入库时清空
+ cache_ttl_s: int = Field(3600, ge=0)
class AmapConfig(BaseModel):
diff --git a/agent_service/core/amap.py b/agent_service/core/amap.py
index fc0b1ed..20c07dc 100644
--- a/agent_service/core/amap.py
+++ b/agent_service/core/amap.py
@@ -6,12 +6,12 @@
"""
import asyncio
import time
-from collections import OrderedDict
from typing import Any, Dict, List, Optional, Tuple
import httpx
from config import Settings
+from core.cache import TTLCache
from core.errors import AppError, ErrorCode
from core.logging import get_logger
from core.resilience import retry_async
@@ -44,33 +44,6 @@ async def wait(self) -> None:
await asyncio.sleep(delay)
-class TTLCache:
- def __init__(self, maxsize: int, ttl_s: int):
- self.maxsize = maxsize
- self.ttl_s = ttl_s
- self._data: "OrderedDict[Tuple, Tuple[float, Any]]" = OrderedDict()
- self.hits = 0
- self.misses = 0
-
- def get(self, key: Tuple) -> Optional[Any]:
- item = self._data.get(key)
- if item is None or (self.ttl_s and time.monotonic() - item[0] > self.ttl_s):
- self._data.pop(key, None)
- self.misses += 1
- return None
- self._data.move_to_end(key)
- self.hits += 1
- return item[1]
-
- def set(self, key: Tuple, value: Any) -> None:
- if self.maxsize <= 0:
- return
- self._data[key] = (time.monotonic(), value)
- self._data.move_to_end(key)
- while len(self._data) > self.maxsize:
- self._data.popitem(last=False)
-
-
def parse_location(text: str) -> Optional[Dict[str, float]]:
try:
lng, lat = (float(x) for x in str(text).split(","))
diff --git a/agent_service/core/cache.py b/agent_service/core/cache.py
new file mode 100644
index 0000000..4f71f31
--- /dev/null
+++ b/agent_service/core/cache.py
@@ -0,0 +1,44 @@
+"""线程安全的 LRU + TTL 缓存,带命中统计。高德请求与检索结果共用。"""
+import threading
+import time
+from collections import OrderedDict
+from typing import Any, Hashable, Optional, Tuple
+
+
+class TTLCache:
+ def __init__(self, maxsize: int, ttl_s: float):
+ self.maxsize = maxsize
+ self.ttl_s = ttl_s
+ self._data: "OrderedDict[Hashable, Tuple[float, Any]]" = OrderedDict()
+ self._lock = threading.Lock() # 检索在线程池里执行,可能并发读写
+ self.hits = 0
+ self.misses = 0
+
+ def get(self, key: Hashable) -> Optional[Any]:
+ with self._lock:
+ item = self._data.get(key)
+ if item is None or (self.ttl_s and time.monotonic() - item[0] > self.ttl_s):
+ self._data.pop(key, None)
+ self.misses += 1
+ return None
+ self._data.move_to_end(key)
+ self.hits += 1
+ return item[1]
+
+ def set(self, key: Hashable, value: Any) -> None:
+ if self.maxsize <= 0:
+ return
+ with self._lock:
+ self._data[key] = (time.monotonic(), value)
+ self._data.move_to_end(key)
+ while len(self._data) > self.maxsize:
+ self._data.popitem(last=False)
+
+ def clear(self) -> None:
+ with self._lock:
+ self._data.clear()
+
+ def stats(self) -> dict:
+ total = self.hits + self.misses
+ return {"size": len(self._data), "maxsize": self.maxsize, "hits": self.hits, "misses": self.misses,
+ "hit_rate": round(self.hits / total, 3) if total else None}
diff --git a/agent_service/core/llm.py b/agent_service/core/llm.py
index 1880978..39e49aa 100644
--- a/agent_service/core/llm.py
+++ b/agent_service/core/llm.py
@@ -12,7 +12,8 @@
from config import Settings
from core.errors import AppError, ErrorCode
from core.logging import get_logger
-from core.resilience import CircuitBreaker, retry_async
+from core.metrics import metrics
+from core.resilience import CircuitBreaker, CircuitOpenError, retry_async
log = get_logger("llm")
@@ -40,6 +41,8 @@ def __init__(self, settings: Settings):
self._endpoint = f"{self._cfg.base_url}/chat/completions"
self._client = httpx.AsyncClient(timeout=httpx.Timeout(self._cfg.timeout_s, connect=10.0))
self._gate = asyncio.Semaphore(self._cfg.max_concurrency)
+ self._waiting = 0 # 等待并发闸门的调用数(排队长度),用于监控
+ self._in_use = 0
# 进程内累计用量(评测时取前后差值即可得到单次请求的 token 消耗)
self.usage_total = {"calls": 0, "prompt_tokens": 0, "completion_tokens": 0}
self.breaker = CircuitBreaker(
@@ -59,6 +62,9 @@ def default_model(self) -> str:
async def aclose(self) -> None:
await self._client.aclose()
+ def concurrency(self) -> Dict[str, int]:
+ return {"limit": self._cfg.max_concurrency, "in_use": self._in_use, "waiting": self._waiting}
+
async def chat(
self,
messages: List[Dict[str, Any]],
@@ -108,17 +114,26 @@ async def complete(
async def _call_once(self, payload: Dict[str, Any], purpose: str) -> Dict[str, Any]:
if not self.breaker.allow():
- raise AppError(ErrorCode.UPSTREAM_LLM_UNAVAILABLE, detail="circuit open")
+ raise CircuitOpenError(ErrorCode.UPSTREAM_LLM_UNAVAILABLE, "llm")
started = time.perf_counter()
status: Optional[int] = None
try:
- async with self._gate:
+ self._waiting += 1
+ try:
+ await self._gate.acquire()
+ finally:
+ self._waiting -= 1
+ self._in_use += 1
+ try:
resp = await self._client.post(
self._endpoint,
headers={"Authorization": f"Bearer {self._api_key}"},
json=payload,
)
+ finally:
+ self._in_use -= 1
+ self._gate.release()
status = resp.status_code
if status != 200:
code = _classify_http_error(status, resp.text)
@@ -158,6 +173,8 @@ def _finish(self, payload, purpose, started, status, code: Optional[ErrorCode],
"latency_ms": round((time.perf_counter() - started) * 1000),
"ok": code is None,
}
+ metrics.llm_call(purpose, code is None, fields["latency_ms"],
+ int((usage or {}).get("prompt_tokens") or 0), int((usage or {}).get("completion_tokens") or 0))
if code is None:
self.usage_total["calls"] += 1
self.usage_total["prompt_tokens"] += int((usage or {}).get("prompt_tokens") or 0)
diff --git a/agent_service/core/metrics.py b/agent_service/core/metrics.py
new file mode 100644
index 0000000..0072fac
--- /dev/null
+++ b/agent_service/core/metrics.py
@@ -0,0 +1,164 @@
+"""进程内指标:请求量、延迟分位、错误码、LLM 调用与 token、缓存命中、熔断状态。
+
+单进程服务,不引入 Prometheus 客户端库:计数直接累加,延迟保留每个路由最近 N 次用于计算分位数。
+GET /metrics 返回 JSON(监控页使用),GET /metrics?format=prometheus 返回 Prometheus 文本格式。
+"""
+import threading
+import time
+from collections import Counter, defaultdict, deque
+from typing import Callable, Deque, Dict, List, Optional
+
+WINDOW = 2000 # 每个序列保留最近多少次耗时
+
+
+def percentile(values: List[float], p: float) -> Optional[float]:
+ if not values:
+ return None
+ s = sorted(values)
+ k = min(len(s) - 1, max(0, round(p / 100 * (len(s) - 1))))
+ return s[k]
+
+
+def _summary(latencies: Deque[float]) -> Dict[str, Optional[float]]:
+ vals = list(latencies)
+ return {"p50": percentile(vals, 50), "p95": percentile(vals, 95), "p99": percentile(vals, 99),
+ "max": max(vals) if vals else None}
+
+
+class Metrics:
+ def __init__(self) -> None:
+ self._lock = threading.Lock()
+ self.started_at = time.time()
+ self.in_flight = 0
+ self.requests: Counter = Counter() # (method, route, status) -> 次数
+ self.errors: Counter = Counter() # 错误码 -> 次数
+ self.latency: Dict[str, Deque[float]] = defaultdict(lambda: deque(maxlen=WINDOW))
+ self.llm_calls: Counter = Counter() # (purpose, ok) -> 次数
+ self.llm_tokens: Counter = Counter() # prompt / completion
+ self.llm_latency: Dict[str, Deque[float]] = defaultdict(lambda: deque(maxlen=WINDOW))
+ self.tool_calls: Counter = Counter() # (tool, ok) -> 次数
+ # 由各组件注册的“现场读取”数据源:缓存命中、熔断状态等
+ self._gauges: Dict[str, Callable[[], dict]] = {}
+
+ # ---------- 记录 ----------
+ def request_started(self) -> None:
+ with self._lock:
+ self.in_flight += 1
+
+ def request_finished(self, method: str, route: str, status: int, latency_ms: float,
+ error_code: Optional[str] = None) -> None:
+ with self._lock:
+ self.in_flight -= 1
+ self.requests[(method, route, status)] += 1
+ self.latency[f"{method} {route}"].append(latency_ms)
+ if error_code:
+ self.errors[error_code] += 1
+
+ def error(self, code: str) -> None:
+ with self._lock:
+ self.errors[code] += 1
+
+ def llm_call(self, purpose: str, ok: bool, latency_ms: float, prompt_tokens: int = 0,
+ completion_tokens: int = 0) -> None:
+ with self._lock:
+ self.llm_calls[(purpose, ok)] += 1
+ self.llm_latency[purpose].append(latency_ms)
+ self.llm_tokens["prompt"] += prompt_tokens
+ self.llm_tokens["completion"] += completion_tokens
+
+ def tool_call(self, tool: str, ok: bool) -> None:
+ with self._lock:
+ self.tool_calls[(tool, ok)] += 1
+
+ def register_gauge(self, name: str, fn: Callable[[], dict]) -> None:
+ self._gauges[name] = fn
+
+ # ---------- 读取 ----------
+ def snapshot(self) -> dict:
+ with self._lock:
+ routes: Dict[str, dict] = {}
+ for (method, route, status), n in self.requests.items():
+ r = routes.setdefault(f"{method} {route}", {"count": 0, "errors_5xx": 0, "errors_4xx": 0})
+ r["count"] += n
+ if status >= 500:
+ r["errors_5xx"] += n
+ elif status >= 400:
+ r["errors_4xx"] += n
+ for key, r in routes.items():
+ r["latency_ms"] = _summary(self.latency[key])
+ total = sum(self.requests.values())
+ errors_5xx = sum(n for (_, _, s), n in self.requests.items() if s >= 500)
+ llm: Dict[str, dict] = {}
+ for (purpose, ok), n in self.llm_calls.items():
+ d = llm.setdefault(purpose, {"ok": 0, "failed": 0})
+ d["ok" if ok else "failed"] += n
+ for purpose, d in llm.items():
+ d["latency_ms"] = _summary(self.llm_latency[purpose])
+ tools: Dict[str, dict] = {}
+ for (tool, ok), n in self.tool_calls.items():
+ d = tools.setdefault(tool, {"ok": 0, "failed": 0})
+ d["ok" if ok else "failed"] += n
+ snap = {
+ "uptime_s": round(time.time() - self.started_at),
+ "in_flight": self.in_flight,
+ "requests_total": total,
+ "errors_5xx_total": errors_5xx,
+ "routes": dict(sorted(routes.items())),
+ "error_codes": dict(self.errors.most_common()),
+ "llm": {"by_purpose": dict(sorted(llm.items())), "tokens": dict(self.llm_tokens)},
+ "tools": dict(sorted(tools.items())),
+ }
+ for name, fn in self._gauges.items():
+ try:
+ snap[name] = fn()
+ except Exception as e: # 指标读取失败不能影响接口本身
+ snap[name] = {"error": str(e)[:100]}
+ return snap
+
+ def prometheus(self) -> str:
+ """Prometheus 文本格式。延迟以 summary 的分位数形式输出(窗口内估计,非累计直方图)。"""
+ lines: List[str] = []
+
+ def esc(v: str) -> str:
+ return str(v).replace("\\", "\\\\").replace('"', '\\"')
+
+ snap = self.snapshot()
+ lines += ["# TYPE wanderai_up gauge", "wanderai_up 1",
+ "# TYPE wanderai_uptime_seconds gauge", f"wanderai_uptime_seconds {snap['uptime_s']}",
+ "# TYPE wanderai_in_flight_requests gauge", f"wanderai_in_flight_requests {snap['in_flight']}",
+ "# TYPE wanderai_http_requests_total counter"]
+ with self._lock:
+ items = list(self.requests.items())
+ for (method, route, status), n in sorted(items):
+ lines.append(f'wanderai_http_requests_total{{method="{method}",route="{esc(route)}",status="{status}"}} {n}')
+ lines.append("# TYPE wanderai_http_latency_ms summary")
+ for key, r in snap["routes"].items():
+ method, route = key.split(" ", 1)
+ for q in ("p50", "p95", "p99"):
+ v = r["latency_ms"][q]
+ if v is not None:
+ lines.append(f'wanderai_http_latency_ms{{method="{method}",route="{esc(route)}",'
+ f'quantile="0.{q[1:]}"}} {v:.1f}')
+ lines.append("# TYPE wanderai_errors_total counter")
+ for code, n in snap["error_codes"].items():
+ lines.append(f'wanderai_errors_total{{code="{code}"}} {n}')
+ lines.append("# TYPE wanderai_llm_calls_total counter")
+ for purpose, d in snap["llm"]["by_purpose"].items():
+ for outcome in ("ok", "failed"):
+ lines.append(f'wanderai_llm_calls_total{{purpose="{esc(purpose)}",outcome="{outcome}"}} {d[outcome]}')
+ lines.append("# TYPE wanderai_llm_tokens_total counter")
+ for kind, n in snap["llm"]["tokens"].items():
+ lines.append(f'wanderai_llm_tokens_total{{kind="{kind}"}} {n}')
+ lines += ["# TYPE wanderai_cache_hits_total counter", "# TYPE wanderai_cache_misses_total counter"]
+ for name, cache in (snap.get("caches") or {}).items():
+ if isinstance(cache, dict) and "hits" in cache:
+ lines.append(f'wanderai_cache_hits_total{{cache="{name}"}} {cache["hits"]}')
+ lines.append(f'wanderai_cache_misses_total{{cache="{name}"}} {cache["misses"]}')
+ lines.append("# TYPE wanderai_breaker_state gauge") # 0 关闭 / 1 半开 / 2 打开
+ for b in snap.get("breakers") or []:
+ state = {"closed": 0, "half_open": 1, "open": 2}.get(b.get("state"), -1)
+ lines.append(f'wanderai_breaker_state{{name="{b.get("name")}"}} {state}')
+ return "\n".join(lines) + "\n"
+
+
+metrics = Metrics()
diff --git a/agent_service/core/resilience.py b/agent_service/core/resilience.py
index d4507b2..5096335 100644
--- a/agent_service/core/resilience.py
+++ b/agent_service/core/resilience.py
@@ -15,6 +15,14 @@
_now = time.monotonic
+class CircuitOpenError(AppError):
+ """熔断器打开时的拒绝。错误码沿用对应服务的“暂时不可用”(对用户而言可稍后重试),
+ 但重试逻辑必须立即放弃:冷却期内再试也一定被拒,退避等待只会拖慢失败(压测中实测多耗 1~1.5 秒)。"""
+
+ def __init__(self, code: ErrorCode, breaker: str):
+ super().__init__(code, detail=f"circuit open: {breaker}")
+
+
class CircuitBreaker:
"""连续失败达到阈值后断开,冷却期内直接拒绝;冷却结束放行一次试探请求(半开)。"""
@@ -79,7 +87,7 @@ async def retry_async(
try:
return await fn()
except AppError as e:
- if not e.retryable or attempt == attempts:
+ if not e.retryable or attempt == attempts or isinstance(e, CircuitOpenError):
raise
delay = min(max_delay_s, base_delay_s * 2 ** (attempt - 1)) * random.uniform(0.5, 1.5)
log.warning(
diff --git a/agent_service/graph/client.py b/agent_service/graph/client.py
index 6b4f70e..ead72e3 100644
--- a/agent_service/graph/client.py
+++ b/agent_service/graph/client.py
@@ -9,7 +9,7 @@
from config import Settings
from core.errors import AppError, ErrorCode
from core.logging import get_logger
-from core.resilience import CircuitBreaker
+from core.resilience import CircuitBreaker, CircuitOpenError
log = get_logger("graph")
@@ -34,7 +34,7 @@ async def run(self, query: str, params: Optional[Dict[str, Any]] = None, write:
if not self.enabled:
raise AppError(ErrorCode.GRAPH_UNAVAILABLE, detail="graph disabled or NEO4J_PASSWORD missing")
if not self.breaker.allow():
- raise AppError(ErrorCode.GRAPH_UNAVAILABLE, detail="circuit open")
+ raise CircuitOpenError(ErrorCode.GRAPH_UNAVAILABLE, "graph")
started = time.perf_counter()
try:
# 注意:execute_query 的未知关键字参数会被当成 Cypher 参数,读超时要放在 Query 对象上
@@ -45,7 +45,12 @@ async def run(self, query: str, params: Optional[Dict[str, Any]] = None, write:
except (ServiceUnavailable, OSError, asyncio.TimeoutError) as e:
self.breaker.record_failure()
raise AppError(ErrorCode.GRAPH_UNAVAILABLE, detail=str(e)[:200]) from e
- except Neo4jError as e: # 查询本身的错误(语法、约束),不代表服务挂了
+ except Neo4jError as e:
+ # 服务端事务超时属于“暂时不可用”:降级并计入熔断;其余(语法、约束)是查询本身的错误,不代表服务挂了
+ code = (e.code or "").lower() # 如 Neo.ClientError.Transaction.TransactionTimedOutClientConfiguration
+ if "timedout" in code or "timeout" in code:
+ self.breaker.record_failure()
+ raise AppError(ErrorCode.GRAPH_UNAVAILABLE, detail=f"query timeout: {str(e)[:200]}") from e
raise AppError(ErrorCode.INTERNAL, "图谱查询失败", detail=str(e)[:300]) from e
self.breaker.record_success()
log.info("graph query", extra={"latency_ms": round((time.perf_counter() - started) * 1000),
diff --git a/agent_service/rag/retriever.py b/agent_service/rag/retriever.py
index f093ea5..ce5ee81 100644
--- a/agent_service/rag/retriever.py
+++ b/agent_service/rag/retriever.py
@@ -2,11 +2,13 @@
全部为同步 CPU 操作,异步层通过线程池调用。每一步都可通过参数开关,供评测脚本做消融对比。
"""
+import copy
import threading
import time
from typing import Any, Dict, List, Optional, Set
from config import RetrievalConfig
+from core.cache import TTLCache
from core.logging import get_logger
from rag.bm25 import BM25Index, add_user_words, rrf_fuse
from rag.metadata import PlaceMatcher, load_metadata, note_places
@@ -26,11 +28,13 @@ def __init__(self, store: VectorStore, cfg: RetrievalConfig):
self._rows_by_place: Dict[str, Set[str]] = {}
self._bm25: Optional[BM25Index] = None
self._lock = threading.Lock()
+ self.cache = TTLCache(cfg.cache_size, cfg.cache_ttl_s)
# ---------- 构建 ----------
def load(self) -> None:
"""加载元数据、构建 BM25 索引;入库后需要重新调用。"""
with self._lock:
+ self.cache.clear() # 语料或元数据变了,旧结果作废
self.metadata = load_metadata(self.cfg.metadata_path)
self.matcher = PlaceMatcher.from_metadata(self.metadata)
rows_by_place: Dict[str, Set[str]] = {}
@@ -79,6 +83,17 @@ def retrieve(
rerank = rerank or self.cfg.rerank
city_filter = self.cfg.city_filter if city_filter is None else city_filter
candidate_k = candidate_k or self.cfg.candidate_k
+ key = (query, top_k, mode, rerank, city_filter, candidate_k, self.cfg.rrf_k, self.cfg.rerank_k)
+ cached = self.cache.get(key)
+ if cached is not None:
+ # 返回副本:调用方会往 hit 里补字段,不能改到缓存里的对象
+ return {**copy.deepcopy(cached), "timings_ms": {"cache_hit": 1}}
+ result = self._retrieve_uncached(query, top_k, mode, rerank, city_filter, candidate_k)
+ self.cache.set(key, copy.deepcopy(result))
+ return result
+
+ def _retrieve_uncached(self, query: str, top_k: int, mode: str, rerank: str, city_filter: bool,
+ candidate_k: int) -> Dict[str, Any]:
timings: Dict[str, int] = {}
places = self.matcher.find(query) if city_filter else []
diff --git a/agent_service/requirements-dev.txt b/agent_service/requirements-dev.txt
index ee4ba01..766f89b 100644
--- a/agent_service/requirements-dev.txt
+++ b/agent_service/requirements-dev.txt
@@ -1,2 +1,2 @@
-pytest
-pytest-asyncio
+pytest==9.1.1
+pytest-asyncio==1.4.0
diff --git a/agent_service/requirements-train.txt b/agent_service/requirements-train.txt
new file mode 100644
index 0000000..7b3d59f
--- /dev/null
+++ b/agent_service/requirements-train.txt
@@ -0,0 +1,2 @@
+# 训练意图分类模型时才需要(python -m classifier.train.*)
+scikit-learn==1.9.1
diff --git a/agent_service/requirements.txt b/agent_service/requirements.txt
index 1b96a12..0c01a44 100644
--- a/agent_service/requirements.txt
+++ b/agent_service/requirements.txt
@@ -1,10 +1,14 @@
-fastapi
-uvicorn
-pandas
-chromadb
-sentence-transformers
-httpx
-pydantic-settings
-pyyaml
-jieba
-rank_bm25
+# 运行依赖(版本与开发环境一致,Docker 镜像与 CI 用同一份)
+# torch 不在这里:CPU 版从 PyTorch 官方源单独安装(见 Dockerfile),否则会拉下 GPU 版的数 GB 依赖
+fastapi==0.143.0
+uvicorn==0.54.0
+pandas==3.0.6
+chromadb==1.5.9
+sentence-transformers==6.1.0
+transformers==5.19.0
+httpx==0.28.1
+pydantic-settings==2.15.0
+PyYAML==6.0.3
+jieba==0.42.1
+rank-bm25==0.2.2
+neo4j==6.4.0
diff --git a/agent_service/tests/test_graph.py b/agent_service/tests/test_graph.py
index 70b6445..33aad2d 100644
--- a/agent_service/tests/test_graph.py
+++ b/agent_service/tests/test_graph.py
@@ -111,3 +111,40 @@ async def go():
return e.code
assert asyncio.run(go()) == ErrorCode.GRAPH_UNAVAILABLE
assert not g.breaker.allow() # 失败计入熔断
+
+
+def test_graph_server_timeout_becomes_unavailable():
+ """Neo4j 服务端事务超时(容器里实测出现过)应按“暂时不可用”降级,而不是报内部错误。"""
+ import asyncio
+ from types import SimpleNamespace
+
+ from neo4j.exceptions import Neo4jError
+
+ from core.errors import AppError, ErrorCode
+ from core.resilience import CircuitBreaker
+ from graph.client import GraphClient
+
+ class TimeoutDriver:
+ async def execute_query(self, *a, **k):
+ raise Neo4jError._hydrate_neo4j(code="Neo.ClientError.Transaction.TransactionTimedOutClientConfiguration",
+ message="The transaction has been terminated")
+
+ class SyntaxDriver:
+ async def execute_query(self, *a, **k):
+ raise Neo4jError._hydrate_neo4j(code="Neo.ClientError.Statement.SyntaxError", message="bad")
+
+ def client(driver):
+ g = GraphClient.__new__(GraphClient)
+ g._cfg = SimpleNamespace(timeout_s=1)
+ g.enabled, g._driver = True, driver
+ g.breaker = CircuitBreaker("graph-test", failure_threshold=5, recovery_timeout_s=30)
+ return g
+
+ async def code_of(g):
+ try:
+ await g.run("RETURN 1")
+ except AppError as e:
+ return e.code
+
+ assert asyncio.run(code_of(client(TimeoutDriver()))) == ErrorCode.GRAPH_UNAVAILABLE
+ assert asyncio.run(code_of(client(SyntaxDriver()))) == ErrorCode.INTERNAL # 查询写错不算服务不可用
diff --git a/agent_service/tests/test_ops.py b/agent_service/tests/test_ops.py
new file mode 100644
index 0000000..345671a
--- /dev/null
+++ b/agent_service/tests/test_ops.py
@@ -0,0 +1,106 @@
+"""P8:指标、缓存、/metrics 接口。"""
+import time
+
+from core.cache import TTLCache
+from core.metrics import Metrics, percentile
+
+
+def test_percentile_nearest_rank():
+ vals = list(range(1, 101))
+ assert percentile(vals, 50) in (50, 51)
+ assert percentile(vals, 95) in (95, 96)
+ assert percentile([], 95) is None
+
+
+def test_ttl_cache_lru_ttl_and_stats(monkeypatch):
+ c = TTLCache(maxsize=2, ttl_s=10)
+ c.set("a", 1)
+ c.set("b", 2)
+ assert c.get("a") == 1 # a 变为最近使用
+ c.set("c", 3) # 淘汰最久未用的 b
+ assert c.get("b") is None
+ assert c.stats()["hits"] == 1 and c.stats()["misses"] == 1
+ now = time.monotonic()
+ monkeypatch.setattr("core.cache.time.monotonic", lambda: now + 11)
+ assert c.get("a") is None # 过期
+ c.clear()
+ assert c.stats()["size"] == 0
+
+
+def test_metrics_snapshot_and_prometheus():
+ m = Metrics()
+ for ms in (10, 20, 30):
+ m.request_started()
+ m.request_finished("POST", "/retrieve", 200, ms)
+ m.request_started()
+ m.request_finished("POST", "/chat", 503, 5, error_code="UPSTREAM_LLM_UNAVAILABLE")
+ m.llm_call("chat.tool_qa", True, 800, prompt_tokens=100, completion_tokens=20)
+ m.llm_call("chat.tool_qa", False, 30)
+ m.register_gauge("caches", lambda: {"retrieval": {"hits": 3, "misses": 1}})
+ m.register_gauge("broken", lambda: 1 / 0) # 数据源出错不影响整体
+
+ snap = m.snapshot()
+ assert snap["requests_total"] == 4 and snap["errors_5xx_total"] == 1 and snap["in_flight"] == 0
+ assert snap["routes"]["POST /retrieve"]["latency_ms"]["max"] == 30
+ assert snap["error_codes"] == {"UPSTREAM_LLM_UNAVAILABLE": 1}
+ assert snap["llm"]["by_purpose"]["chat.tool_qa"] == {"ok": 1, "failed": 1, "latency_ms": snap["llm"]["by_purpose"]["chat.tool_qa"]["latency_ms"]}
+ assert snap["llm"]["tokens"] == {"prompt": 100, "completion": 20}
+ assert "error" in snap["broken"]
+
+ text = m.prometheus()
+ assert 'wanderai_http_requests_total{method="POST",route="/chat",status="503"} 1' in text
+ assert 'wanderai_llm_tokens_total{kind="prompt"} 100' in text
+ assert 'wanderai_cache_hits_total{cache="retrieval"} 3' in text
+
+
+def test_retriever_cache_returns_copies(monkeypatch):
+ from config import RetrievalConfig
+ from rag.retriever import Retriever
+
+ calls = []
+
+ class FakeRetriever(Retriever):
+ ready = True
+
+ def _retrieve_uncached(self, query, *args):
+ calls.append(query)
+ return {"hits": [{"chunk_id": "c1", "text": "t"}], "places": [], "filtered": False, "timings_ms": {}}
+
+ r = FakeRetriever.__new__(FakeRetriever)
+ r.cfg = RetrievalConfig()
+ r.cache = TTLCache(16, 60)
+ first = r.retrieve("成都美食")
+ first["hits"][0]["mutated"] = True # 调用方修改结果不能污染缓存
+ second = r.retrieve("成都美食")
+ assert calls == ["成都美食"]
+ assert "mutated" not in second["hits"][0]
+ assert second["timings_ms"] == {"cache_hit": 1}
+ r.retrieve("成都美食", top_k=3) # 参数不同 → 不命中
+ assert len(calls) == 2
+
+
+def test_open_circuit_is_not_retried(monkeypatch):
+ """熔断打开时立即失败:压测发现拒绝被当成可重试错误,白白退避 1~1.5 秒。"""
+ import asyncio
+
+ import pytest
+
+ from core.errors import ErrorCode
+ from core.resilience import CircuitOpenError, retry_async
+
+ slept = []
+
+ async def fake_sleep(s):
+ slept.append(s)
+
+ monkeypatch.setattr("core.resilience._sleep", fake_sleep)
+ calls = {"n": 0}
+
+ async def rejected():
+ calls["n"] += 1
+ raise CircuitOpenError(ErrorCode.UPSTREAM_LLM_UNAVAILABLE, "llm")
+
+ with pytest.raises(CircuitOpenError) as ei:
+ asyncio.run(retry_async(rejected, attempts=3))
+ assert ei.value.code == ErrorCode.UPSTREAM_LLM_UNAVAILABLE and ei.value.retryable # 对用户仍是“稍后再试”
+ assert calls["n"] == 1 and slept == []
diff --git a/config.yaml b/config.yaml
index 1f15660..e0225f4 100644
--- a/config.yaml
+++ b/config.yaml
@@ -26,6 +26,8 @@ retrieval:
reranker_max_length: 256
city_filter: true # 查询里出现城市/省份时只检索相关笔记
metadata_path: data/notes_metadata.jsonl
+ cache_size: 1024 # 检索结果缓存(相同查询与参数直接返回);0 关闭
+ cache_ttl_s: 3600
amap:
base_url: https://restapi.amap.com
diff --git a/docker-compose.yml b/docker-compose.yml
index 3eb3f9a..d0c9e4a 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -1,5 +1,8 @@
-# 本地依赖服务。当前只有 Neo4j(P7 知识图谱);P8 会把网关与 agent_service 也加进来。
-# 启动:docker compose up -d neo4j 浏览器控制台:http://localhost:7474
+# 一键启动:网关 + agent_service + Neo4j
+# 1) cp .env.example .env,填好 LLM_API_KEY、AMAP_WEB_SERVICE_KEY、AMAP_JS_KEY、NEO4J_PASSWORD
+# 2) 首次需要入库(向量库在 agent_service/chroma_db,见 README)
+# 3) docker compose up -d --build 浏览器打开 http://localhost:3000
+# 只要图数据库:docker compose up -d neo4j
services:
neo4j:
image: neo4j:5.26-community
@@ -21,3 +24,52 @@ services:
timeout: 5s
retries: 12
restart: unless-stopped
+
+ agent:
+ build:
+ context: .
+ dockerfile: agent_service/Dockerfile
+ image: wanderai-agent
+ container_name: wanderai-agent
+ # 不发布端口:只有网关能访问(同一 compose 网络内用服务名 agent:8002)
+ expose:
+ - "8002"
+ environment:
+ LLM_API_KEY: ${LLM_API_KEY:?请在 .env 中设置 LLM_API_KEY}
+ AMAP_WEB_SERVICE_KEY: ${AMAP_WEB_SERVICE_KEY:-}
+ NEO4J_PASSWORD: ${NEO4J_PASSWORD:-}
+ GRAPH__URI: bolt://neo4j:7687
+ volumes:
+ - ./agent_service/chroma_db:/app/agent_service/chroma_db # 向量库
+ - ./data:/app/data # 语料、元数据、记忆数据库
+ - ./agent_service/models:/app/agent_service/models:ro # 本地分类模型(缺失时退回 LLM)
+ - ./logs:/app/logs
+ - ${HF_CACHE_DIR:-hf-cache}:/models/hf # embedding / 重排模型缓存,首次启动会下载
+ depends_on:
+ neo4j:
+ condition: service_healthy # 图谱是可选依赖,但同时启动时等它就绪,避免启动初期的降级
+ restart: unless-stopped
+
+ gateway:
+ build: .
+ image: wanderai-gateway
+ container_name: wanderai-gateway
+ ports:
+ - "3000:3000"
+ environment:
+ AGENT_BASE: http://agent:8002
+ AMAP_WEB_SERVICE_KEY: ${AMAP_WEB_SERVICE_KEY:-}
+ AMAP_JS_KEY: ${AMAP_JS_KEY:-}
+ AMAP_JS_SECURITY_CODE: ${AMAP_JS_SECURITY_CODE:-}
+ # 容器里请求来自 Docker 网桥而不是 127.0.0.1,监控页需要 ADMIN_TOKEN 才能访问
+ ADMIN_TOKEN: ${ADMIN_TOKEN:-}
+ RATE_LIMIT_API_PER_MIN: ${RATE_LIMIT_API_PER_MIN:-120}
+ RATE_LIMIT_HEAVY_PER_MIN: ${RATE_LIMIT_HEAVY_PER_MIN:-10}
+ HEAVY_MAX_IN_FLIGHT: ${HEAVY_MAX_IN_FLIGHT:-8}
+ depends_on:
+ agent:
+ condition: service_healthy # agent 加载完模型、能响应后再启动网关
+ restart: unless-stopped
+
+volumes:
+ hf-cache:
diff --git a/docs/interview_notes.md b/docs/interview_notes.md
deleted file mode 100644
index 0446f9f..0000000
--- a/docs/interview_notes.md
+++ /dev/null
@@ -1,686 +0,0 @@
-# 面试准备笔记:行界 WanderAI
-
-> 用途:面试前快速回忆“做了什么、为什么这么做、遇到什么问题、数字从哪来”。每完成一个阶段追加一节。
-> 配套文档:现状说明 `project_documentation.md`,路线图 `docs/upgrade_plan.md`,检索评测 `eval/rag_report.md`,Agent 评测 `eval/agent_report.md`,分类评测 `eval/classifier_report.md`,路由评测 `eval/router_report.md`、`eval/route_threshold_report.md`,记忆评测 `eval/memory_report.md`。
-> 最后更新:2026-10-13(P1~P7 完成)
-
----
-
-## 0. 简历可用数据一览(随阶段更新)
-
-**判断原则**:数字必须能在仓库里复现,并且能说清楚怎么测的。LLM 判分在人工核验通过前不算“已验证”。
-
-### ✅ 现在就可以写
-
-| 内容 | 数据 / 事实 | 出处(面试被追问时能拿出来) |
-|---|---|---|
-| 架构 | Node 网关(Express)+ Python 服务(FastAPI)两层;所有 LLM 调用集中在 Python 侧,网关不持有 LLM 密钥 | `server.js`、`agent_service/app.py` |
-| 容错 | 超时 60s;仅对超时/429/5xx 指数退避重试(最多 3 次);连续 5 次服务端失败熔断 30s;LLM 并发上限 8;额度不足/鉴权失败不重试也不触发熔断 | `config.yaml`、`core/llm.py`、`core/resilience.py` |
-| 错误处理 | 16 个统一错误码(HTTP 状态 + 是否可重试 + 用户提示语),网关与 Python 服务格式一致 | `core/errors.py` |
-| 降级 | RAG 的改写、重排、回答任一步失败都不让请求失败,跳过的步骤写入响应 `degraded`;已用“LLM 地址指向死端口”的实例实测 | §1.4 |
-| 可观测性 | JSON 结构化日志;request-id 从网关贯穿到 Python 服务和每次 LLM 调用;`/healthz` 存活、`/readyz` 就绪探针 | `core/logging.py` |
-| 配置外置 | `config.yaml` + `.env` + 环境变量三层覆盖,pydantic-settings 启动时校验 | `config.py` |
-| 测试 | 62 个 pytest 用例(图谱对齐规则、查询工具与降级、驱动超时转降级、工具标记清洗;记忆写入规则与改口、证据校验与敏感信息过滤、摘要折叠、追问改写、从对话推断城市、规划步数耗尽的兜底;动态路由分发、日志轮转被占用时的容错;意图分类的格式、指标、阈值、LLM 兜底、路由只用于聊天消息;熔断、重试、错误映射、配置、分块、BM25、RRF、地名识别、CSV 清洗、行程校验规则、Agent 循环与自纠、预算保护) | `agent_service/tests/` |
-| 安全 | 发现并修复网关把整个项目目录作为静态资源暴露的问题(配置、数据、日志、源码可直接下载);高德 Key 移到服务端代理 | §1.5 |
-| 检索架构 | 地名过滤 + BM25(jieba)与 bge 向量的 RRF 混合召回 + bge-reranker 交叉编码器重排 | `rag/retriever.py` |
-| 检索延迟(单机 CPU) | 混合 + 地名过滤 P95 36ms;加交叉编码器重排 P95 3.7s(因此只在问答页开重排,行程规划走 36ms 路径) | `eval/rag_report.md` |
-| 评测体系 | 186 条查询评测集(136 条基于笔记生成 + 50 条开放式),4 路检索结果合并为候选池(平均 17.7 篇),0/1/2 分级标注;7 组配置消融 | `eval/` |
-| 数据治理 | 发现语料由两个文件拼接、82 个 ID 重复,改为内容哈希主键;LLM 抽取 217 篇笔记的城市/景点/人群元数据 | §2.2 |
-| Agent 架构 | Function Calling 循环编排 5 个工具(笔记检索、高德 POI、路线、天气、提交行程),同一轮工具并发执行,结果回填上下文 | `agent/orchestrator.py` |
-| 校验自纠 | 规则校验器(POI 必须来自本次检索、城市一致、天数、去重、相邻两站 ≤60 分钟、每日 ≤12 小时),不通过的问题作为工具结果回填让 LLM 修正;20 个用例首次通过 80% → 自纠后 100% | §3.5、`eval/agent_report.md` |
-| 可执行性对比 | 同批 20 个需求:旧流程(文本 + 正则解析 + 三级地理编码)22.3% 的路段公交/地铁超过 60 分钟(33/148),Agent 为 0%(0/157) | §3.5 |
-| 工具调用成功率 | 100%(462/462,含客户端重试;运行中高德原始 QPS 超限 4 次均被重试恢复) | §3.5 |
-| 意图分类流程 | 针对旧模型“训练用游记长文、推理用表单短串”的分布错配重建数据:统一输入格式函数,训练/测试分开生成(测试集换提示词、15 个训练未见城市、去近重复);对比逻辑回归、bge-small 与 RoBERTa 微调、LLM 零样本;模型与级联阈值只按验证集选择 | §4 |
-| 动态路由 | 聊天消息按 5 类意图分发到规划 / RAG / 周边与路线工具 / 天气工具 / 直接回复;40 条人工消息上对比“每句都重新规划”:平均延迟 14.5s → 5.3s,token 22.3k → 4.5k / 条,非修改类消息误改行程 17/32 → 0/32 | §5、`eval/router_report.md` |
-| 路由级联 | 本地路由置信度 < 0.97 交给 LLM(阈值在人工 dev 集上选);人工 held-out 集准确率 75% → 92.5%,本地处理 72% | §5、`eval/route_threshold_report.md` |
-| 长期记忆 | 固定 8 键 + 确定性写入规则(证据须出自原话、敏感信息丢弃、待确认机制、改口覆盖);18 个人工用例:应记的 14/14 全部记住,6 个陷阱用例(临时需求、手机号、证件号、夸奖)0 误记,敏感信息 0 存储 | §6、`eval/memory_report.md` |
-| 记忆约束生效 | 同一规划请求带 / 不带长期记忆,6 个场景 × 3 轮:违反用户约束 14/18 → 3/18(除 1 个规则判断场景外由 LLM 判分) | §6 |
-| 成本与延迟优化 | 预算保护 + 限制冗余路线查询:route_plan 调用 -67%,token -21%(71.7k → 56.9k/次),P95 56s → 40s,成功率 19/20 → 20/20 | §3.6 |
-| 知识图谱 | Neo4j(Docker)构建游记地点图谱:POI 465、城市 30、标签 18、游记 156,共现边 1,813、邻近边 848;地名对齐到高德 POI,4 个参数化 Cypher 模板作为 Agent 工具 | §7、`data/graph/build_stats.json` |
-| 实体对齐 | 三轮人工抽检迭代对齐规则(每轮重新抽样):精确率 70% → 82%~88%(后两轮 60 条) | §7.4、`eval/graph_alignment_review.md` |
-| 图谱效果 | 16 个地点关系问题 × 3 次运行,对比只用高德周边搜索:回答中有游记依据的地点 2.2 → 5.3 个,延迟 7.6s → 5.1s(-33%),token -23% | §7.5、`eval/graph_report.md` |
-| 图谱容错 | 读超时 + 熔断 + 工具层降级到高德周边搜索;停掉 Neo4j 实测:单次 6 秒内失败,3 次后熔断直接降级,回答正常 | §7.6 |
-
-### ⏳ 人工核验通过后才能写
-
-| 内容 | 当前数值(LLM 判分) | 解锁条件 |
-|---|---|---|
-| nDCG@5 | 0.775(纯向量)→ 0.859(混合 + 地名过滤 + 重排),相对 +10.8% | 第二轮人工抽检 `eval/data/rag_review.csv` 加权 kappa ≥ 0.6 |
-| Recall@5 | 0.845 → 0.896,相对 +6.0% | 同上 |
-| MRR@10 | 0.846 → 0.922,相对 +9.0% | 同上 |
-
-| 风格多标签(RoBERTa 微调) | micro-F1 0.805、整行全对 60.4%、“综合”F1 0.828;DeepSeek 零样本 0.797 / 55.6% / 0.745;单条 43ms vs 约 1s | 测试标签为生成意图,需人工盲审 `classifier/data/review_style.csv` |
-| 路由 5 类(RoBERTa 微调) | LLM 生成测试集 macro-F1 0.954(DeepSeek 0.967),23ms vs 约 0.8s;**但人工编写的 held-out 消息上只有 75%**,见 §5.5 | 人工盲审 `review_route.csv` |
-
-追问预案(评测集来源、基线定义、RRF、BM25 引擎、提升拆分)见 §2.5.1;分类指标见 §4.5。
-
-核验通过前可以写成定性描述:“搭建检索评测集与消融实验,量化混合检索与重排的收益”。
-
-### ❌ 不能写(还没做 / 与事实不符)
-
-- “语义分块”——现在是按标点的递归分块
-- **“地理匹配率提升”——已测量,不成立**:这批 20 个需求上旧流程的地点匹配率和城市一致率本来就是 100%(三级地理编码 184/185 走的是“同城 POI”)。Agent 的收益在“路线可执行性”和“坐标可信(只能来自 POI 检索)”,不是匹配率。
-- “意图分类准确率 XX%”——P4 数字待测试集人工盲审;而且路由模型**不如** LLM(0.954 vs 0.967),只能讲“以 1.3 个点的代价换 35 倍速度、零调用成本”
-- 意图分类“SFT 微调”——旧模型已弃用,新模型在 P4
-- “高并发”——还没做压测(P8)
-- “图谱让回答质量提升”——LLM 盲评三次运行结果互相矛盾(5/4/7、4/8/4、6/4/6),16 个问题不足以证明;只能写“有依据的推荐更多、更快、更省”
-- “Text2Cypher / GraphRAG”——用的是固定模板,不是 LLM 生成 Cypher
-
-### 当前可用的简历写法(不含待核验数字)
-
-> - **工程化**:设计 Node 网关 + FastAPI 两层服务,统一 16 类错误码与降级策略;LLM 客户端实现按错误类型重试、熔断与并发控制,request-id 全链路追踪,配置外置并在启动时校验。
-> - **RAG 检索**:实现地名过滤 + BM25 / 向量 RRF 混合召回 + bge-reranker 重排;构建 186 条查询的分级评测集,完成 7 组配置消融,并据延迟(36ms vs 3.7s)为行程规划与问答场景选择不同检索路径。
-> - **Agent 工具编排与校验自纠**:基于 Function Calling 编排笔记检索、高德 POI / 路线 / 天气等工具,结构化输出行程;规则校验器约束地点真实性、城市一致性与交通时长,问题回填 LLM 自动修正,20 个规划用例首次通过率 80% → 自纠后 100%,超 60 分钟路段占比由旧流程的 22.3% 降至 0%;通过预算保护与冗余调用约束,token 降低 21%、P95 延迟 56s → 40s。
-> - **动态路由**:聊天消息按 5 类意图分发到行程规划、游记 RAG、周边与路线工具、天气工具或直接回复,本地路由模型低置信度时交给 LLM;相比“每句话都重新规划”,平均延迟 14.5s → 5.3s、token 降低约 80%,非修改类消息不再误改行程(17/32 → 0/32)。
-> - **长期记忆**:设计固定键的用户画像记忆与“证据必须出自原话”的写入校验,过滤敏感信息、支持待确认与改口覆盖,会话侧保留最近对话并滚动摘要、改写指代追问;6 个约束场景各跑 3 轮,规划违反用户约束的次数由 14/18 降至 3/18。
-> - **知识图谱**:将游记地点对齐到高德 POI 并构建 Neo4j 图谱(465 个地点、1,813 条共现关系、848 条邻近关系),三轮人工抽检迭代对齐规则,精确率由 70% 提升至 82%~88%;以参数化 Cypher 模板作为 Agent 工具回答“附近 / 常一起去”类问题,相比仅用高德周边搜索,回答中有游记依据的推荐由 2.2 个增至 5.3 个,延迟降低 33%、token 降低 23%;图谱不可用时超时熔断并自动降级。
-> - **意图识别**:定位旧分类模型“训练用游记长文、推理用表单短串”的分布错配,统一输入格式并重建数据(训练/测试分开生成、未见城市测试、去近重复);微调 RoBERTa 实现 6 类多标签风格识别与 5 类意图路由,与逻辑回归、bge-small、LLM 零样本对比,本地 CPU 推理 23~43ms,较 LLM 零样本(约 0.8~1s)快 20~35 倍。
-
----
-
-## 1. P1 工程地基
-
-### 1.1 做之前的状态(问题是什么)
-
-- LLM 调用分散:行程生成在 Node 里直接调,RAG 在 Python 里用同步 `requests` 调,各自写错误处理,没有重试和熔断。
-- 错误格式五花八门:`{error:'proxy_failed'}`、`{detail:...}`、厂商原始报错直接透传给前端。
-- 配置散在 `.env` 平铺变量里,Python 和 Node 各读各的,写错了要到运行时才发现。
-- 只有 `console.log`,出了问题无法把一次用户请求在两个服务里的日志对上。
-
-### 1.2 做了什么
-
-| 模块 | 做法 | 关键代码 |
-|---|---|---|
-| 服务拆分 | `rag_service` → `agent_service`,拆为 `core/`(基础设施)、`rag/`、`classifier/`;Node 只做网关 | `agent_service/` |
-| 配置 | pydantic-settings:`config.yaml`(非敏感)+ `.env`(密钥)+ 环境变量(`LLM__MODEL=x` 双下划线覆盖嵌套字段);相对路径统一按项目根目录解析 | `config.py` |
-| 错误码 | 枚举 + 规格表(HTTP 状态、是否可重试、提示语);`AppError` 由全局异常处理器统一输出 | `core/errors.py` |
-| LLM 客户端 | httpx 异步;`asyncio.Semaphore` 限并发;按状态码与响应体把厂商错误翻译成错误码;重试 + 熔断;每次调用记录用途、耗时、token | `core/llm.py` |
-| 熔断器 | 三态:关闭 → 连续失败达阈值打开 → 冷却后半开放行一次试探,成功关闭、失败重新打开 | `core/resilience.py` |
-| 日志 | JSON 行,`contextvars` 保存 request-id;按天滚动保留 14 天,错误单独一个文件 | `core/logging.py` |
-| 网关 | request-id 生成/透传、统一错误、下游超时、`/api/readyz` 聚合、只托管页面 | `server.js` |
-
-### 1.3 关键设计决策(面试常问“为什么”)
-
-1. **哪些错误重试?** 只重试“过一会儿可能好”的:超时、429、5xx。额度不足(DeepSeek 402 / DashScope 403 + `AllocationQuota`)、鉴权失败、参数错误重试也没用,反而浪费时间。
-2. **哪些错误计入熔断?** 只有“服务端不可用”类(超时、5xx、429)。额度不足不代表服务挂了,计入熔断会把“欠费”误判成“故障”。有单元测试覆盖这一点。
-3. **为什么自己写熔断/重试而不用 tenacity、pybreaker?** 逻辑只有几十行,自己写能精确控制“哪些错误码重试/熔断”,并且面试能讲清每一行;依赖少。
-4. **为什么 Agent 编排放 Python、Node 只做网关?** 检索、模型推理、后续图数据库驱动都在 Python 生态;网关负责边缘职责(静态托管、密钥隔离、请求追踪)。
-5. **为什么不直接上 LangChain?** 项目规模小,自研代码可控、易调试;简历上能说清楚原理比“调了一个框架”更有说服力。
-6. **request-id 为什么放在 body 解析之前?** 否则请求体 JSON 非法时,解析失败的错误响应里没有 request-id(实际踩到过,见 1.5)。
-
-### 1.4 怎么验证的
-
-- 单元测试:熔断三态与半开失败、只重试可重试错误、各厂商错误码映射、用 `httpx.MockTransport` 模拟“503 后成功”“402 不重试”“连续 500 触发熔断”。
-- 降级实测:另起一个实例,把 LLM 地址指向不存在的端口:
- - `/search` 仍返回检索片段,`degraded: [query_rewrite, llm_rerank, answer]`
- - `/classify` 返回默认标签,`source: "default"`
- - `/itinerary` 返回 `UPSTREAM_LLM_UNAVAILABLE` 统一错误
- - 3 次失败后 `/readyz` 显示熔断器 `open`
-- 链路追踪:带固定 `X-Request-ID` 请求,在 `logs/agent.log` 中查到同一 ID 的 LLM 调用记录与访问记录。
-
-### 1.5 遇到的问题(讲故事用)
-
-1. **静态资源暴露整个项目**:`express.static(__dirname)` 把项目根目录当静态目录,`config.yaml`、`data/`、日志、Python 源码、向量库文件都能直接下载(`.env` 因为 dotfiles 默认忽略才幸免)。改为只开放三个页面和 `src/`,逐个验证返回 404。
-2. **测试把机器内存跑到 9.7GB**:测试里用 `monkeypatch` 替换 `core.resilience.asyncio.sleep`,但那其实就是全局 `asyncio.sleep`,替换后的函数又调用 `asyncio.sleep`,变成调用自己。修复:在模块内保存引用 `_sleep = asyncio.sleep`、`_now = time.monotonic`,测试只替换模块属性。**教训:monkeypatch 要打在“被使用的位置”,而且不要打在共享的全局对象上。**之后加了内存上限守护脚本再跑测试。
-3. **请求体非法时缺 request-id**:中间件顺序问题,把 request-id 中间件挪到 `express.json()` 之前。
-4. **localhost 与 127.0.0.1**:曾让 Node 只监听 `127.0.0.1`,结果浏览器用 `localhost` 访问时走 IPv6 `::1` 连不上,改回默认监听;真正的风险点(入库接口)已从网关移除。
-
-### 1.6 可能被问到的问题
-
-- **Q:重试会不会把下游打挂?** A:指数退避加随机抖动(0.5~1.5 倍),最多 3 次;熔断打开后直接快速失败,不再请求;并发闸门限制同时在途的 LLM 调用。
-- **Q:熔断器半开状态怎么处理并发?** A:半开时只放行一个试探请求(`_half_open_in_flight` 标记),其他请求仍快速失败;试探成功关闭,失败重新计时。
-- **Q:为什么用 contextvars 存 request-id?** A:asyncio 下每个请求是一个任务,contextvars 在任务间隔离,线程局部变量在异步代码里不可靠。
-- **Q:配置写错了会怎样?** A:pydantic 在启动时校验类型和范围(如端口 1–65535),失败直接退出并指出字段;网关启动时也校验端口和下游地址。
-
----
-
-## 2. P2 RAG 2.0
-
-### 2.1 做之前的状态
-
-纯向量召回(bge-small-zh + Chroma)+ LLM 重排;没有任何评测,无法回答“检索效果好不好、改了之后好了多少”。
-
-### 2.2 数据问题(先修数据,再谈算法)
-
-1. **语料是两个 CSV 拼起来的**:第 137 行是混入的表头;后半部分 `id` 又从 `row_0` 开始,217 篇中有 82 个 ID 重复。第一次抽元数据时按 `id` 存,结果一篇云南笔记被覆盖成了贵州,217 篇只剩 135 条。
- - 修复:笔记 ID 改为 `md5(标题+正文)` 前 12 位(稳定、唯一、重复导入幂等),原 `id` 保留为 `csv_id`;读取时跳过与列名相同的行,按内容去重。
-2. **元数据**:用 LLM 为每篇笔记抽取城市、省份、景点、适用人群、季节、预算,增量写入 `data/notes_metadata.jsonl`(已抽过的跳过),共 217 次调用。
-
-### 2.3 检索流程
-
-```text
-查询 → 地名识别(语料地名词典,最长匹配,不调 LLM)
- → 限定到涉及该地的笔记(结果不足 top_k 时自动放宽)
- → 向量召回 30 条 ┐
- → BM25 召回 30 条 ┴→ RRF 融合 → bge-reranker 重排前 20 条 → top_k
-```
-
-| 组件 | 实现 | 为什么 |
-|---|---|---|
-| BM25 | jieba 分词 + 停用词(含“宝子”“攻略”等小红书口水词)+ rank_bm25;城市、景点名加入用户词典 | 向量模型对专有名词(店名、景点名)不敏感,关键词能补上 |
-| RRF | `score = Σ 1/(60 + rank)` | 只用名次,不用把余弦相似度和 BM25 分数统一尺度 |
-| 地名过滤 | 用元数据构建地名词典,查询里出现就限定范围 | 语料多城市,向量检索容易把“成都美食”召回成“重庆美食”;词典匹配几乎零延迟 |
-| 交叉编码器 | bge-reranker-base,只重排前 20 条,max_length 256 | 双塔向量只比较各自的向量,交叉编码器同时看查询和片段,更准但更慢 |
-
-### 2.4 评测集怎么建(面试必问)
-
-1. **查询**:DeepSeek 为 100 篇抽样笔记写“这篇笔记能回答的用户问题”(要求不抄标题、约七成带目的地),再按 5 个主题(美食、拍照、人群、预算季节、路线避坑)写 50 条开放式问题,去重后 186 条。
-2. **候选池(pooling)**:每条查询取 4 种检索方式(向量、BM25、混合 + 地名过滤、再加重排)各自前 10 篇,加上来源笔记,取并集,平均 17.7 篇。这是 TREC 的标准做法,避免只用一种方法定义“相关”。
-3. **判分**:DeepSeek 对池内每篇笔记打 0/1/2 分(2 = 能直接回答且目的地对;1 = 目的地或主题有一项对得上;0 = 不相关),共 3300 个判断。
-4. **指标在笔记级计算**:同一篇笔记的多个片段只算一次。Recall@5、MRR@10 只看 2 分笔记;nDCG@5 用分级增益;没有 2 分笔记的 34 条查询不参与 Recall/MRR。
-5. **人工核验**:盲标(表中不显示 LLM 分数),按 LLM 分数分层抽 60 对,用二次加权 kappa 衡量一致性。
-
-### 2.5 结果(LLM 判分,待人工核验)
-
-| 配置 | Recall@5 | MRR@10 | nDCG@5 | P95 延迟 |
-|---|---|---|---|---|
-| 向量 | 0.845 | 0.846 | 0.775 | 17 ms |
-| BM25 | 0.765 | 0.760 | 0.658 | 4 ms |
-| 混合(RRF) | 0.848 | 0.869 | 0.793 | 18 ms |
-| 向量 + 地名过滤 | 0.845 | 0.848 | 0.801 | 29 ms |
-| 混合 + 地名过滤 | 0.854 | 0.879 | 0.826 | 36 ms |
-| 混合 + 地名过滤 + 重排 | 0.896 | 0.922 | 0.859 | 3.7 s |
-| 再加 LLM 改写 | 0.895 | 0.930 | 0.847 | 3.2 s(不含改写) |
-
-**能讲的结论:**
-- BM25 单独不行,但与向量互补:融合后 MRR +0.023。
-- 地名过滤对开放式问题帮助最大(开放式 nDCG@5 0.655 → 0.726),几乎不增加延迟。
-- 重排收益最大,但延迟从 36ms 到 3.7s → **按场景取舍**:问答页开重排,行程规划不开。
-- LLM 改写没有带来稳定收益,开放式问题反而下降(0.744 → 0.704);这个配置 6% 的结果落在候选池外按不相关计,分数偏保守,暂不下结论。
-
-### 2.5.1 指标深挖预案(这组数字最容易被追问)
-
-**一句话版本(先背熟):**
-> 186 条查询、4 路检索结果做候选池、0/1/2 分级标注;基线是纯 bge 语义召回,最终方案是“地名过滤 + BM25/向量 RRF 融合 + bge-reranker 重排”,nDCG@5 0.775 → 0.859(+10.8%),Recall@5 0.845 → 0.896(+6.0%),MRR@10 0.846 → 0.922(+9.0%)。
-
-**Q1:评测集怎么来的?多少条 query?relevance 怎么标?**
-- **186 条查询**:
- - 136 条“基于笔记”:随机抽 100 篇笔记(固定随机种子),让 DeepSeek 为每篇写“这篇笔记能回答的用户问题”。要求口语化、不抄标题、约七成带目的地;部分笔记生成了不止一条。
- - 50 条“开放式”:给出语料覆盖的 40 个目的地,按 5 个主题(美食 / 拍照 / 特定人群 / 预算与季节 / 路线与避坑)各写 10 条,一半带目的地。
-- **候选池(pooling,TREC 做法)**:每条查询取 4 种检索方式(纯向量、纯 BM25、混合 + 地名过滤、再加重排)各自前 10 篇笔记,再加上生成该查询的来源笔记,取并集,平均 17.7 篇/查询。
-- **分级标注**:DeepSeek 对池内每篇打 0/1/2,共 3300 个判断(0 分 1897、1 分 1045、2 分 358)。
- - 2 = 能直接回答问题且目的地对
- - 1 = 目的地或主题只对上一项
- - 0 = 不相关
-- **人工核验**:盲标(表里不显示 LLM 分数),按 LLM 分数分层抽 60 对(每档 20),用二次加权 kappa 衡量一致性。第一轮因人工标注仓促(kappa 0.25)作废并存档,换新样本重标。
-- **统计口径**:
- - 笔记级计算,同一笔记的多个 chunk 只算一次。
- - Recall@5 / MRR@10 只认 2 分笔记;152 条查询有 2 分笔记,参与这两个指标;另 34 条没有,只参与 nDCG。
- - nDCG@5 用分级增益 2^g − 1。
- - 池外笔记按不相关计。
-
-**Q2:baseline 0.775 是纯 bge 语义召回吗?**
-- 是。`BAAI/bge-small-zh-v1.5` 向量(归一化)+ ChromaDB(HNSW、余弦距离),**不做地名过滤、不重排、不做查询改写**。
-- 召回 40 个 chunk 后按笔记去重取前 10。
-- 语料是 217 篇笔记,按 400 字、80 字重叠切成 382 个 chunk。
-
-**Q3:混合检索里向量和全文怎么融合?加权吗?**
-- **RRF(Reciprocal Rank Fusion),不是线性加权**:`score(d) = Σ 1/(k + rank_i(d))`,k = 60。
-- 两路各召回前 30 个 chunk(`candidate_k`),融合后取前 30。
-- 为什么不用线性加权:余弦相似度在 [0,1],BM25 分数没有上界且随查询长度变化,线性加权要先归一化、再调权重,而 RRF 只用名次、无需调参。
-- 如果追问:线性加权在有标注数据时可以网格搜索权重,可能略优,但在 186 条查询上调参有过拟合风险,可以作为后续实验。
-
-**Q4:全文检索用什么引擎?**
-- **没有用 Elasticsearch**:是进程内的 BM25(`rank_bm25` 的 BM25Okapi,默认 k1 = 1.5、b = 0.75)。
-- 分词:jieba,加载从元数据得到的城市名和景点名作为用户词典(避免“宽窄巷子”被切开),并过滤停用词,其中包括“宝子”“攻略”这类小红书口水词。
-- 服务启动时从向量库读出全部 382 个 chunk 构建索引,入库后重建。
-- 为什么不上 ES:语料只有几百个 chunk,内存 BM25 单次查询 ~4ms,引入 ES 增加部署和运维成本却没有收益。数据量到十万级或需要实时增量、分布式时,会换成 Elasticsearch / OpenSearch(IK 分词)并保持 RRF 融合不变。
-
-**Q5:+10.8% 是哪一部分带来的?(拆分贡献)**
-- **对比口径**:基线 vs 完整方案。
-- **逐步消融**(nDCG@5,相对纯向量):
-
-| 逐步叠加 | nDCG@5 | 相对基线 |
-|---|---|---|
-| 纯向量(基线) | 0.775 | — |
-| + BM25(RRF 融合) | 0.793 | +2.3% |
-| + 地名过滤 | 0.826 | +6.6% |
-| + bge-reranker 重排 | 0.859 | +10.8% |
-
-- **另两个指标**(基线 → 完整方案):Recall@5 0.845 → 0.896(+6.0%),MRR@10 0.846 → 0.922(+9.0%)。
-- **要主动说明代价**:重排把 P95 延迟从 36ms 拉到 3.7s,所以行程规划走不重排的路径(nDCG@5 0.826,+6.6%)。
-
-**Q6:LLM 生成 + LLM 判分,可信吗?**
-- 承认有偏差,说明做了哪些控制:
- - 候选池来自 4 种不同方法。
- - 人工盲标抽检并计算 kappa。
- - “基于笔记”和“开放式”两类查询分开报告:开放式 nDCG@5 基线 0.671 → 0.744,提升趋势与总体一致。
-- 再说明局限:语料只有 217 篇,样本量有限,没做显著性检验(计划补 bootstrap 置信区间)。
-
-**Q7:Recall@5 都 0.84 了,为什么基线这么高?**
-- 语料小(217 篇),每条查询的高度相关笔记平均只有 2 篇左右,前 5 名容易覆盖。
-- 而且约 3/4 的查询由某篇笔记生成,和来源笔记词面接近。
-- 所以更有区分度的是 nDCG@5 和 MRR@10(排序质量),以及开放式查询的结果。
-
-### 2.6 遇到的问题
-
-1. **交叉编码器在 CPU 上很慢**:实测约 140ms/条候选,重排 30 条要 5 秒。测了 max_length 512/256 与候选数 30/20/10 的组合,选“重排前 20 条、截断 256”约 2.8 秒;进一步的量化/ONNX 放到 P8。
-2. **LLM 判分与人工不一致**:第一轮人工抽检加权 kappa 只有 0.25。排查:先排除表格错位(把人工分数上下平移重算,一致性更差),再逐条看分歧——LLM 判 0、人工判 2 的 8 条里,多数是人工看快了(例如“北京预算”的问题配了一篇贵州笔记)。结论:第一轮作废并存档(`rag_review_round1_discarded.csv`),换一批新样本(避免记住答案)重新盲标,正文从 150 字放宽到 300 字。**教训:人工标注本身也要质控;评分标准要写成可操作的规则(“只有目的地对上最多 1 分”)。**
-3. **评测脚本里的偏差**:73% 的查询由某篇笔记生成,词面重合可能偏向 BM25;报告中把“基于笔记”和“开放式”两类查询的 nDCG 分开列出。
-
-### 2.7 可能被问到的问题
-
-- **Q:为什么用 RRF 而不是加权求和?** A:两路分数尺度不同(余弦相似度 vs BM25 无上界),加权求和要归一化和调权重;RRF 只看名次,无需调参,k=60 是常用值。
-- **Q:评测集是 LLM 生成、LLM 判分,会不会自己评自己?** A:会有偏差,所以做了三件事:候选池来自 4 种方法而不是单一方法;人工盲标抽检并计算 kappa;分开报告“基于笔记”和“开放式”两类查询的结果。
-- **Q:池外文档怎么处理?** A:按不相关计(TREC 惯例),报告里列了每种配置前 5 名的“判分覆盖率”,带 LLM 改写的配置只有 94%,所以它的分数偏保守。
-- **Q:为什么地名识别不用 LLM?** A:词典最长匹配零延迟、结果确定;LLM 改写实测没有稳定收益且多 1–2 秒。
-- **Q:chunk 级和笔记级指标有什么区别?** A:同一篇笔记切成多个 chunk,chunk 级会把同一篇重复计分;用户关心的是“找到了哪几篇笔记”,所以按笔记去重后算。
-- **Q:重排太慢怎么办?** A:只重排前 20 条;场景分流(行程规划不重排);后续计划 ONNX 导出 + 动态量化。
-
----
-
-## 3. P3 Agent + Function Calling
-
-### 3.1 做之前的状态
-
-- LLM 只输出一段“第N天 / - [城市] 景点(备注)”格式的文字,地图页用正则解析,再逐个景点做“同城 POI → 全国 POI → 地址编码”三级匹配。
-- LLM 看不到任何真实数据:景点之间多远、是否存在、在不在这个城市,全靠模型记忆;路线是否顺、一天排不排得下,没人检查。
-- 简历里写的 Function Calling、“工具结果回填上下文”、“校验纠错”在代码里都不存在。
-
-### 3.2 做了什么
-
-```text
-用户需求 → 地理编码目的地(拿到 adcode)
- → LLM(tools) 循环(最多 12 轮):
- search_notes / poi_search / route_plan / get_weather(同一轮多个调用并发执行,结果作为 tool 消息回填)
- → submit_itinerary(结构化行程 JSON) → 规则校验器
- ├ 通过:用高德实算的交通时长覆盖模型填写的值 → 返回
- └ 不通过:问题列表作为 submit_itinerary 的工具结果回填 → LLM 修正(最多 2 次)
-```
-
-| 模块 | 要点 | 代码 |
-|---|---|---|
-| 工具定义 | OpenAI tools 格式;`submit_itinerary` 的参数就是行程 JSON Schema,把“最终输出”也变成一次工具调用 | `agent/tools.py` |
-| 工具执行 | 失败不抛异常,返回 `{ok:false, error, hint}` 让模型换关键词重试;每次调用记入 trace | `agent/tools.py` |
-| 会话登记 | 本次 `poi_search` 返回过的 POI 都记在 `PlanContext.pois`,校验器只认这里面的 `poi_id` | `agent/tools.py` |
-| 校验器 | 纯规则 + 高德实算,不用 LLM:结构、天数、POI 真实性、城市一致(adcode 前缀,直辖市/省取 2 位)、去重、相邻两站 ≤60 分钟、每日 ≤12 小时 | `agent/validator.py` |
-| 高德客户端 | 异步;客户端限速 3 QPS;QPS 超限错误重试、其他业务错误不重试;LRU + TTL 缓存 | `core/amap.py` |
-| 流式进度 | `/plan/stream` 用 SSE 推送 status / tool_call / validation;网关逐块透传,浏览器断开就取消规划 | `app.py`、`server.js` |
-| 多轮修改 | 把上一版结构化行程作为 `previous_itinerary` 传回,其中的地点视为已查询过 | `agent/orchestrator.py` |
-| 前端 | 一个原地刷新的进度气泡;地图页直接用已校验坐标,不再做地理编码;Agent 失败自动回退旧流程 | `ai-chat.html`、`output-map.html` |
-
-### 3.3 关键设计决策
-
-1. **为什么让“提交行程”也是一个工具,而不是让模型最后输出 JSON?** 校验结果可以作为这个工具的返回值自然回填,自纠就在同一个 Function Calling 循环里完成,不需要额外的“修正提示词”流程;参数还有 JSON Schema 约束。
-2. **为什么校验器不用 LLM?** 规则检查结果确定、可解释、毫秒级、不花 token;“LLM 评 LLM”既慢又可能互相迁就。
-3. **怎么防止模型编造坐标?** 坐标根本不让模型填——模型只给 `poi_id`,服务端按本次检索登记表回填坐标;`poi_id` 不在登记表里就判不通过。这是“幻觉防护”的核心。
-4. **交通时长为什么要覆盖?** 模型估的时长不可信;校验器用高德实算每一段,既用于判断,也用于展示(标 `verified: true`)。
-5. **为什么不用 LangChain / LangGraph?** 循环本身不到 200 行;自己写能精确控制:并发执行、提交与修正计数、预算保护、事件推送、trace 统计。面试能逐行讲清。
-6. **SSE 而不是 WebSocket?** 单向推送进度就够了,SSE 基于普通 HTTP、网关透传简单;断开时取消后台任务,避免白花 LLM 调用。
-
-### 3.4 怎么验证的
-
-- **单元测试**(假 LLM + 假高德,离线确定性):合法行程通过且坐标/路段被回填;编造的 `poi_id` 被拒;外地 POI、超长路段、天数不符、重复地点、结构错误都能识别;完整循环“查 POI → 提交错误行程 → 收到问题 → 修正 → 通过”,并检查每个 tool_call 都有对应的 tool 消息;预算保护在第 3 轮强制 `tool_choice`。
-- **浏览器实测**:西安 2 天 49 秒(13/13 地点、11/11 路段实算);追加“第二天下午太累,去掉大雁塔换个喝茶的地方” 15 秒完成局部修改;地图页 0 次地理编码。
-- **对比评测**:见 3.5。
-
-### 3.5 评测与结果(`eval/agent_report.md`)
-
-**怎么测的(先背熟):**
-- 20 个出行需求、20 个城市(其中 4 个城市不在笔记语料里),1~3 天,不同偏好与补充要求(带父母、带小孩、穷游、一天打卡尽量多等)。
-- 同一个需求分别跑**新流程**(Agent)和**旧流程**。旧流程在 `eval/legacy_flow.py` 里**逐行复刻**前端:同一提示词、同样的笔记检索、同一套解析正则、同样的候选名生成与 POI 打分规则。
-- “超长路段”两边用**同一口径**:相邻两站公交/地铁时长(无方案时步行)> 60 分钟。
-
-| 指标 | 旧流程 | Agent |
-|---|---|---|
-| 成功产出行程 | 20/20 | 20/20 |
-| 地点匹配到坐标 / 位于目的地 | 100% / 100% | 100% / 100% |
-| **超过 60 分钟的路段** | **22.3%(33/148)** | **0%(0/157)** |
-| 端到端 P50 / P95 | 27s / 32s | 31s / 40s |
-
-| Agent 指标 | 数值 |
-|---|---|
-| 工具调用成功率 | 100%(462/462,含客户端重试;原始 QPS 超限 4 次) |
-| 首次提交通过 → 自纠后通过 | 80%(16/20)→ 100%(20/20) |
-| 平均修正次数 / LLM 轮数 | 0.20 / 6.8 |
-| 平均 token / 次 | 56,861(输入约 5.4 万、输出约 0.3 万) |
-
-**要主动讲清楚的两点(诚实的边界):**
-1. **地理匹配率没有提升**——旧流程在这批用例上已经是 100%,因为提示词要求写 `[城市]`,三级匹配 185 个地点里 184 个走的是“同城 POI”。所以简历不写“地理匹配率提升”。
-2. **0% 超长路段是校验规则保证的**,不是模型自己变聪明了;能讲的是“旧流程有 22.3% 的路段不可执行,加入校验 + 自纠后全部满足约束,且只用了平均 0.2 次修正”。
-
-### 3.6 遇到的问题
-
-1. **高德 QPS 限流(10021)**:模型同一轮并行发 7~8 个 `poi_search`,个人 Key 每秒配额不够,一半请求失败,模型被迫在后几轮反复重搜同一批地点。最初还把 10021 当成不可重试的业务错误。修复:客户端固定间隔限速(3 QPS)+ 把 10019/10020/10021 归为可重试;10 个并发搜索全部成功。**教训:工具并发要和下游配额匹配;错误分类要区分“稍后会好”和“永远不会好”。**
-2. **步数预算耗尽(v1 长沙用例失败)**:复现发现模型要花约 8 轮收集信息(笔记 2 轮、POI 3 轮、路线 3 轮)才第一次提交,12 轮预算里一旦需要修正或多搜一轮就会超限。修复:剩余轮数只够“提交 + 修正”时用 `tool_choice` 强制提交;提示词说明服务端会算所有路段、`route_plan` 最多 4 次。效果(v1 → v2):成功 19/20 → 20/20,route_plan 284 → 93 次(-67%),token -21%,P95 56s → 40s。
-3. **前端调用顺序 bug**:第一版把 Agent 调用插在“风格识别”之前,Agent 拿不到风格提示;在浏览器里发现“偏好识别”消息缺失后定位并调整。
-4. **评测公平性**:旧流程不能随手写个简化版来对比,那样会“打稻草人”;所以逐行移植前端逻辑,连 `dedupeList` 会丢掉空字符串这种细节都保持一致。
-
-### 3.7 可能被问到的问题
-
-- **Q:工具调用成功率 100% 是不是太理想?** A:口径是“工具最终返回给模型的结果没有报错”,包含客户端重试;运行中高德原始返回了 4 次 QPS 超限,都被重试恢复。如果按“首次请求成功率”算会低一点,报告里写明了。
-- **Q:模型不调用工具、直接输出文字怎么办?** A:提醒它调用 `submit_itinerary`,最多提醒 2 次;预算快用完时用 `tool_choice` 强制调用。
-- **Q:一轮里模型同时提交了多次行程?** A:只校验最后一次,其余返回“已忽略”,保证每个 tool_call 都有对应的 tool 消息(否则下一轮 API 会报错)。
-- **Q:修正 2 次还不通过怎么办?** A:返回行程并把剩余问题写进 `warnings`,前端提示“部分问题未能自动修正”,不让用户什么都拿不到。
-- **Q:为什么延迟比旧流程高?** A:多了工具调用与校验(P50 +4s);换来的是坐标可信与路线可执行。用 SSE 实时展示进度,用户感知的是“在干活”而不是卡住。
-- **Q:怎么判断地点在不在目的地?** A:比较 adcode 前缀:普通城市取前 4 位;直辖市(11/12/31/50 开头)和省级目的地取前 2 位,因为北京城区 adcode 是 1101xx,而北京市本身是 110000。
-- **Q:多轮修改怎么保证不推翻原行程?** A:把上一版结构化行程放进提示词并要求“未提到的部分尽量保留”;上一版的地点预先登记,模型可直接沿用 `poi_id`,不必重新搜索。实测“去掉大雁塔换喝茶的地方”只换了一个点,15 秒完成。
-
----
-
-## 4. P4 意图分类微调
-
-### 4.1 做之前的状态
-
-- 旧模型:PaddleNLP 上微调 ERNIE 做 8 分类,训练数据是 217 篇小红书游记长文(平均 411 字),推理时的输入却是“出发地:…;目的地:…;偏好:…”这种表单短串——**训练和推理分布完全不同**,效果差是必然的。
-- 每类只有 19~45 条,标签也有 15% 前后不一致,拍照和 Vlog 难以区分,“智能综合”是个兜底类。
-
-### 4.2 做了什么
-
-| 环节 | 做法 | 代码 |
-|---|---|---|
-| 标签重设计 | 风格改为 6 类**多标签**(food / nature / culture / citywalk / photo / rush),拍照与 Vlog 合并,“综合” = 全部不命中;新增 5 类**路由**(plan / notes_qa / graph_qa / realtime / chitchat),供 P5 动态路由 | `classifier/labels.py` |
-| 统一输入格式 | `format_input(目的地, 偏好, 原话)` 一个函数,训练数据生成、线上推理、评测都走它,从代码上杜绝分布错配 | `classifier/labels.py` |
-| 数据构造 | DeepSeek 按指定意图生成:风格 160 批(标签组合随机:1 个 50%、2 个 35%、3 个 5%、无 10%)、路由每类 20 批(含易混边界);输入形态混合(只有原话 / 偏好 + 原话 / 只有偏好) | `classifier/train/gen_data.py` |
-| 防泄漏 | 测试集**分开生成**:不同提示词(口语、错别字、否定)、15 个训练集没出现过的城市;bge 余弦 ≥0.92 的近重复去掉,测试样本与任何训练样本 ≥0.90 的剔除 | 同上 |
-| 训练 | 纯 PyTorch 循环:编码器 CLS + 线性头;多标签 BCE + pos_weight(正样本少的标签加权);分类头学习率 ×30;warmup 10% + 线性衰减;梯度裁剪;按验证集选最优 epoch;多标签阈值在验证集上逐标签调 | `classifier/train/train.py` |
-| 对照 | 句向量 + 逻辑回归、bge-small 微调(5 / 10 轮)、chinese-roberta-wwm-ext 微调、DeepSeek 零样本,同一测试集同一指标 | `train.py`、`eval_llm.py` |
-| 级联分析 | 本地模型置信就用本地,否则交给 LLM;阈值在验证集上选 | `classifier/train/report.py` |
-| 上线 | `/classify`:本地模型优先、缺失时退回 LLM;返回兼容前端旧的 8 类风格提示词;路由只对聊天原话做 | `classifier/service.py` |
-
-数据规模:风格训练 1367(含 10% 验证)、测试 250;路由训练 1047、测试 220。
-
-### 4.3 关键设计决策
-
-1. **为什么用 LLM 造数据?** 没有真实用户请求日志;人工写上千条不现实。用 LLM 按“指定意图”生成,再用分开生成的测试集 + 人工盲审控制质量。上线后应该用真实请求替换。
-2. **为什么要多标签?** “带爸妈去吃本地小吃顺便拍照”同时是 food + photo;单标签会逼模型二选一。
-3. **为什么不用 HF Trainer?** 依赖少(不用 accelerate),每一步(加权 loss、分层学习率、按验证集保存)都能讲清楚。
-4. **为什么部署 RoBERTa 而不是更快的 bge-small?** 验证集上 RoBERTa 两个任务都最好;43ms / 23ms 对接口来说完全够用。bge-small 只要 8ms、96MB,是资源受限时的备选。
-5. **为什么级联最后选了“全部本地”?** 阈值只能在验证集上选;验证集上本地模型已经足够好,加 LLM 没有收益。测试集上某些阈值看起来更好(路由 0.972),但那是看着测试集挑的,不能用。
-
-### 4.4 怎么验证的
-
-- 同一测试集、同一指标对比 5 种方法;模型、epoch、阈值、级联阈值全部只在验证集上决定。
-- 上线前用 7 条典型输入通过网关实测(见 4.6 第 4、5 条发现的问题)。
-- 单元测试覆盖输入格式、多标签指标与“综合”类、阈值搜索、模型缺失时退回 LLM、多标签映射到前端旧标签、路由只用于聊天消息。
-
-### 4.5 结果(`eval/classifier_report.md`,测试标签待人工盲审)
-
-**风格(多标签,测试 250 条,含 28 条“综合”)**
-
-| 方法 | micro-F1 | 整行全对 | “综合”F1 | 单条延迟 |
-|---|---|---|---|---|
-| 句向量 + 逻辑回归 | 0.727 | 45.2% | 0.678 | 10ms |
-| bge-small 微调 | 0.770 | 55.2% | 0.667 | 8ms |
-| **RoBERTa 微调** | **0.805** | **60.4%** | **0.828** | 43ms |
-| DeepSeek 零样本 | 0.797 | 55.6% | 0.745 | ~1s |
-
-**路由(单标签,测试 220 条)**
-
-| 方法 | macro-F1 | 单条延迟 |
-|---|---|---|
-| 句向量 + 逻辑回归 | 0.941 | 11ms |
-| bge-small 微调 | 0.940 | 5ms |
-| RoBERTa 微调 | 0.954 | 23ms |
-| **DeepSeek 零样本** | **0.967** | ~0.8s |
-
-**一句话版本:** 风格多标签上微调 RoBERTa 略超 DeepSeek 零样本(micro-F1 0.805 vs 0.797,整行全对 60.4% vs 55.6%),延迟从约 1 秒降到 43 毫秒;路由上比 LLM 低 1.3 个点,换来 35 倍速度和零调用成本。
-
-**⚠️ P5 修正**:路由模型在人工编写的消息上只有 75%(LLM 生成测试集上 95.4%),线上改为低置信度交给 LLM 的级联,详见 §5.5。讲 P4 时必须同时讲这一点。
-
-**要主动讲的边界:** 测试标签是生成意图,且由同一个 LLM 生成——这对 LLM 零样本是“主场优势”,对比可能偏向 LLM;人工盲审会给出标签噪声水平。
-
-### 4.6 遇到的问题(讲故事用)
-
-1. **测试集里没有“综合”样本**:所有方法的“综合”F1 都是 0,包括 LLM——这不正常。排查发现测试集 222 条里“综合”样本为 0(训练集有 154 条)——测试集只有 24 批、按 10% 概率随机抽“无标签”批次,最终没有产出任何“综合”样本。补生成 28 条(同样的测试集流程、同样去重)后,“综合”F1 才有意义,而且暴露了 LLM 恰恰在这一类上最弱(0.745)。**教训:指标全是 0 或全是 1 时先查数据,不要先怀疑模型。**
-2. **LLM 延迟测量失真**:第一次测出 12.5 秒,因为 220 个请求同时发出、在并发闸门(8)里排队。改为顺序调用 20 条测单次延迟:约 0.8~1 秒。
-3. **用测试集选模型的泄漏**:第一版报告按测试集分数挑“最佳模型”做级联分析——改为按验证集。级联阈值也改为在验证集上选,结果是“全部本地”,于是不宣称级联收益。
-4. **路由模型在分布外输入上“自信地错”**:上线抽查发现表单拼接输入被判成 chitchat,置信度 0.99。路由模型只见过单句消息。处理:路由只用于聊天原话。**教训:高置信度不等于正确,分布外输入要在调用侧拦住。**
-5. **“综合”仍有个例漏判**:“经典景点都去看看就行”被判成 nature + culture + rush。整体 F1 不错不代表典型样本没问题;后续可以加“综合”样本或“命中 3 个及以上降级为综合”的规则。
-6. **一次延迟异常**:RoBERTa 风格模型训练完立即测得 517ms,复测 43ms(训练刚结束时内存与 CPU 状态影响);最终报告用复测值,评测脚本加了预热。
-
-### 4.7 可能被问到的问题
-
-- **Q:为什么本地模型能超过 LLM?** A:只在风格任务上略超,主要赢在“综合”类(0.828 vs 0.745)——LLM 对“综合”的召回只有 0.68(28 条里有 9 条硬找出了风格),平均每条预测 1.52 个标签而真实是 1.43;微调模型从训练数据里学到了“无明显风格”的分布。路由任务上 LLM 仍更好。
-- **Q:多标签阈值怎么定?** A:每个标签在验证集上从 0.2~0.8 网格搜索使 F1 最大的阈值,而不是统一用 0.5;正样本少的标签阈值通常更低。
-- **Q:怎么保证测试集不泄漏?** A:分开生成(不同提示词)、只用训练集未出现的城市、与训练样本 bge 相似度 ≥0.90 的剔除;模型选择只看验证集。
-- **Q:数据是 LLM 生成的,模型学的是不是 LLM 的口吻?** A:有这个风险,所以测试集刻意改成更口语、带错别字和否定的写法;真正的解决办法是上线后收集真实请求做抽样标注,这在报告里写为后续工作。
-- **Q:CPU 上训练要多久?** A:bge-small 风格 5 轮约 3 分钟;RoBERTa 风格约 43 分钟、路由约 9 分钟(12 线程 CPU,没有 GPU)。
-
----
-
-## 5. P5 动态路由
-
-### 5.1 做之前的状态
-
-生成行程后,聊天框里的**每一句话**都会交给 Agent 在原行程上重新规划:“谢谢”要等 10 秒、花 2 万 token;“明天下雨吗”可能把行程改掉。40 条测试消息里,32 条不该改行程的消息有 17 条把行程改了。
-
-### 5.2 做了什么
-
-| 路由 | 处理 | 代码 |
-|---|---|---|
-| plan | PlanAgent 在上一版行程上修改 | `agent/router.py` |
-| notes_qa | RAG 问答(混合检索 + 重排 + 引用),检索词自动补行程城市 | 同上 |
-| graph_qa | 工具问答(最多 4 轮):poi_search / **nearby_search(新增,高德周边搜索)** / route_plan / search_notes | `agent/qa.py`、`agent/tools.py` |
-| realtime | 工具问答:get_weather / poi_search / route_plan | 同上 |
-| chitchat | 直接简短回复 | `agent/router.py` |
-
-- 路由:P4 的 RoBERTa 路由模型;最高概率 < 0.97 时交给 LLM 零样本判断(级联)。
-- 工具问答最后一轮用 `tool_choice: "none"` 强制作答;行程里的地点预先登记,“附近”可直接用 poi_id。
-- 规划 Agent 的工具集固定为 P3 评测时的 5 个(`PLAN_TOOLS`),新工具只给问答用,保证 P3 数字可复现。
-- 前端:聊天框走 `/api/chat/stream`,进度气泡显示“🔀 识别为:…”;只有 plan 路由会更新行程和地图;没有行程也能聊天。
-
-### 5.3 关键设计决策
-
-1. **为什么不用一个大 Agent 处理所有问题?** 一个带全部工具的 Agent 也能回答,但每次都要带完整规划提示词和工具定义(几万 token),延迟 10 秒以上,还可能顺手改行程。路由后每类只给需要的工具和提示词。
-2. **知识图谱还没做,graph_qa 怎么办?** 先用高德周边搜索 + 路线规划实现“附近 / 顺路”,结果是实时、真实的;P7 接入图谱后作为另一个数据源。
-3. **为什么阈值不用 P4 验证集选出的 0?** 见 5.5:LLM 生成的验证集和真实用户写法差距很大。
-
-### 5.4 评测一:路由 vs 每句都重新规划(`eval/router_report.md`)
-
-- 固定上下文:成都 2 天行程(生成一次后缓存);40 条**人工编写**的消息(每类 8 条)。
-- 同一消息分别走旧方式与路由方式(此处路由为阈值 0,即全部用本地模型)。
-
-| 指标 | 每句都重新规划 | 路由 |
-|---|---|---|
-| 平均延迟 | 14.5s | 5.3s |
-| 平均 token / 条 | 22,327 | 4,522 |
-| 非修改类消息误改行程 | 17/32 | 0/32 |
-| 修改类消息真正改了行程 | 8/8 | 5/8 |
-
-各类:闲聊 10.1s → 1.1s(token 16k → 60);天气/时长 10.2s → 3.5s;周边 16.8s → 6.2s;经验问答 17.8s → 5.8s。
-
-**代价**:8 条修改请求里有 2 条被路由成闲聊,用户想改行程却没改——这引出了评测二。
-
-### 5.5 评测二:路由置信度阈值(`eval/route_threshold_report.md`)
-
-**协议(面试重点):**
-- dev 集 = 评测一的 40 条;在 dev 上扫描阈值,选准确率最高者(并列时“修改类漏判”少者优先)→ **0.97**。
-- held-out 集 = 另写的 40 条(换城市、更口语、更间接),**在任何评测之前写好并提交 git**,只在最后看一次。
-
-| held-out(40 条人工消息) | 本地处理占比 | 准确率 | 修改类漏判 |
-|---|---|---|---|
-| 全部本地 | 100% | **75.0%** | 6/8 |
-| 级联(阈值 0.97) | 72% | **92.5%** | 2/8 |
-| 全部 LLM | 0% | 100% | 0/8 |
-
-**这是 P4 的重要修正**:路由模型在 LLM 生成的测试集上 95.4%,在人工写的消息上只有 75%。错误集中在“下午那个点我不想去了,换个室内的吧”这类间接、口语化的修改请求,被判成闲聊——训练数据的口吻比真实用户“规整”。
-
-**还没解决的**:级联后仍有 2/8 修改请求漏判(模型以 ≥0.97 的高置信度判错)。可选方案:路由全部交给 LLM(held-out 100%,每条多约 0.8 秒、约 150 token);或用真实对话补训练数据。
-
-### 5.6 遇到的问题
-
-1. **生成数据的测试集高估了模型**:P4 报告 0.954,换成人写的消息 75%。**教训:合成数据只能用于开发,最终要用真实(或至少人工编写的)样本验证;验证集和测试集都要覆盖真实分布。**
-2. **方法名覆盖属性**:给分类服务加 `route()` 方法时,类里已有 `self.route`(路由模型)实例属性,调用会拿到模型对象而不是方法。写完审查时发现,改名 `predict_route`。
-3. **Windows 日志轮转失败**:日期跨天时 `TimedRotatingFileHandler` 要把 agent.log 改名,但服务进程和评测脚本同时打开着它,Windows 不允许改名,之后每条日志都报 WinError 32。修复:每个进程写各自的日志文件(服务 agent.log、脚本 eval.log);自定义 Handler 在改名失败时继续写当前文件、下个周期再试;加了模拟“文件被占用”的单元测试。P8 多 worker 部署同样会遇到这个问题。
-4. **防止“偷看” held-out**:先写好并提交 held-out 消息,再跑阈值实验,git 时间线可以证明没有按 held-out 结果调参。
-
-### 5.7 可能被问到的问题
-
-- **Q:路由错了怎么办?** A:代价不对称。把闲聊判成规划,只是多花时间;把修改请求判成闲聊,用户的需求就丢了。所以低置信度交给 LLM,并在报告里单列“修改类漏判”。后续可以在回复里加“需要我修改行程吗?”的确认按钮兜底。
-- **Q:为什么不直接全部用 LLM 路由?** A:这是成本和准确率的取舍:本地模型 23ms、零成本,处理了 72% 的消息;LLM 每条约 0.8 秒。如果更看重准确率,把 `route_confidence` 设为 1.01 即可全部交给 LLM,代码不用改。
-- **Q:40 条够吗?** A:不够,只能说明趋势,而且都是我自己写、自己标的。真正的做法是上线后记录路由结果与用户后续行为(例如紧接着又重复了一遍修改请求),把这些当作弱标签持续评估。
-
----
-
-## 6. P6 记忆
-
-### 6.1 做之前的状态
-
-- 每次对话从零开始:说过“不吃辣”“带爸妈”,下次规划还会推荐水煮鱼和爬山。
-- 聊天里的追问(“那附近呢”)没有上下文,只能看当前这一句。
-
-### 6.2 做了什么
-
-| 层 | 内容 | 代码 |
-|---|---|---|
-| 长期记忆 | 固定 8 个键:同行人、行动限制、预算、节奏、常住城市(单值);饮食、喜欢、不喜欢(多值)。SQLite 存储,按匿名 user_id 隔离 | `memory/store.py` |
-| 抽取 | LLM 只提候选(键、值、原话证据、置信度),写入由规则把关 | `memory/extractor.py` |
-| 会话 | 每轮存原文;未摘要轮数 > 10 时把除最近 6 轮外的内容压缩成固定字段摘要(后台);含指代或很短的追问先改写成独立问题 | `memory/session.py` |
-| 使用 | 规划提示词加“用户长期偏好与约束(必须遵守)”;工具问答带偏好;没有行程时从问题和最近对话里识别城市 | `agent/prompts.py`、`agent/router.py` |
-| 用户可控 | “我的偏好”面板查看、逐条删除、清空;新记住的内容在聊天里提示 | `ai-chat.html`、`/memory` 接口 |
-
-**写入规则(面试重点,全部是确定性的、可单元测试):**
-1. 键必须在固定集合内。
-2. **证据必须是用户原话的子串**——防止模型“记住”用户没说过的话(例如把“这次想吃火锅”推断成“喜欢吃辣”)。
-3. 手机号、证件号、邮箱、银行卡号丢弃。
-4. 置信度 < 0.7(“一般”“可能”)先进“待确认”,**同一条再提到一次才生效**。
-5. 单值键新值覆盖旧值、保留历史;但**低置信度的新说法不能推翻已确认的旧值**。
-6. “不喜欢 X”覆盖“喜欢 X”(按去掉“喜欢/不喜欢/逛”等词后的对象比较)。
-
-### 6.3 关键设计决策
-
-1. **为什么用固定键而不是自由文本记忆?** 自由文本没法去重、没法判断冲突、没法让用户理解“记了什么”。固定键让覆盖、去重、改口都变成确定性规则。代价是覆盖面有限,需要时再加键。
-2. **为什么不用向量库存记忆?** 每个用户的记忆只有几条到几十条,全部注入提示词就够了,不需要检索;向量检索适合大量非结构化记忆。
-3. **为什么抽取和回答并行?** 抽的是用户原话,不依赖回答结果;并行后记忆功能不增加回复延迟。
-4. **为什么摘要放后台?** 摘要只影响后面的轮次,不该让当前回复等它。
-5. **隐私**:只记旅行相关的长期偏好;敏感信息正则拦截;用户可删除(软删除,保留审计);没有登录体系,user_id 是浏览器本地生成的匿名 ID——这是演示级限制,面试要主动说。
-
-### 6.4 评测(`eval/memory_report.md`)
-
-**A. 抽取质量**——18 个人工编写用例(含 6 个“不该记”的陷阱:临时需求、手机号、证件号、夸奖、明天去哪):
-
-| 指标 | 结果 |
-|---|---|
-| 应记住的被记住 | 14/14 |
-| 记住的是对的 | 14/15(多记的 1 条“不喜欢一天赶多个景点”其实是合理理解,标签偏严,未事后修改) |
-| 陷阱用例误记 | 0/6 |
-| 敏感信息被存储 | 0 |
-
-**B. 约束遵守**——6 个场景(不喜欢博物馆、不吃辣、膝盖不好、带孩子推婴儿车、学生预算、素食),同一请求带 / 不带记忆各规划一次,**跑 3 轮**:
-
-| | 违反用户约束 |
-|---|---|
-| 不带记忆 | 14/18 |
-| 带记忆 | **3/18** |
-
-仍违反的 3 次都很“细”:把麻辣冷吃兔推荐成伴手礼、景山有台阶不适合推婴儿车、素食者的行程里出现一道牛腩捞面。需要在校验器里加规则(但“不辣的蹄花”这种否定表达会让关键词规则误报),列为后续工作。
-
-**C. 摘要保留**——14 轮对话,前 8 轮压缩进摘要,6 个关键事实(目的地、日期、天数、熊猫基地、否决都江堰、吃火锅)全部保留。
-
-**为什么跑 3 轮**:第一次单轮结果“带记忆 0/6 违反”,同样的代码第二次是 1/6——单次结果不足以下结论。
-
-### 6.5 遇到的问题(讲故事用)
-
-1. **改口没生效**:评测用例“我喜欢逛博物馆 → 其实我不喜欢博物馆”跑完,两条记忆同时生效。原因:LLM 把动词写进了 value(“喜欢逛博物馆” vs “不喜欢博物馆”),改口规则按字面比较。修复:比较去掉“喜欢/不喜欢/逛/去”等词后的对象(并用包含关系),同时在提示词里要求 value 只写对象。**教训:不能假设 LLM 输出格式稳定,规则层要对表述差异有容忍度。**
-2. **评测暴露了 P3 规划 Agent 的一个健壮性 bug**:一次规划报 PLAN_INVALID。原因是预算保护只强制“第一次提交”——提交被打回后,模型又去调别的工具,步数耗尽;最后一轮提交失败且还有修正次数时,也什么都不返回。修复:按“剩余修正次数”计算是否强制提交,并在步数耗尽时返回最近一次结构合法的行程 + 未解决问题作为 warnings。补了回归测试。(P3 的评测数据是在修复前的代码上跑的,修复只影响达到步数上限的情况。)
-3. **单次评测的随机性**:同一代码两次结果不同(0/6 vs 1/6),改为每个场景跑 3 轮报告比例。
-4. **追问找不到城市**:没有行程时问“那宽窄巷子附近有什么吃的”,系统反问城市——改写已经生效,但目的地只从行程里取。修复:从问题本身、再从最近对话里用地名词典识别城市。上线验证时,回答还用上了上一个会话留下的长期记忆(“适合不吃辣、带爸妈”)。
-
-### 6.6 可能被问到的问题
-
-- **Q:怎么防止记错?** A:三道关——证据必须出自原话(防止模型推测)、低置信度先待确认(防止一次模糊表达被当真)、用户可以看和删。
-- **Q:记忆冲突怎么处理?** A:单值键新覆盖旧并保留历史;低置信度的新说法不推翻已确认的;“不喜欢 X”覆盖“喜欢 X”。本次请求和记忆冲突时以本次为准(提示词里明确写了)。
-- **Q:记忆会不会越来越多?** A:固定键限制了规模;多值键去重;后续可以按 updated_at 做过期。
-- **Q:短期记忆为什么不全部带上?** A:上下文越长成本越高、模型越容易忽略关键信息;“最近 6 轮原文 + 固定字段摘要”兼顾了细节和长度,摘要保留评测 6/6。
-- **Q:多用户隔离?** A:所有读写都带 user_id 条件,有单元测试验证不能删除别人的记忆;但没有认证,user_id 可以被伪造——生产环境要接登录体系。
-
----
-
-## 7. P7 知识图谱(Neo4j)
-
-### 7.1 做之前的状态
-
-- 地点关系类问题(“去了 A 还能去哪”“A 附近有什么”)只能靠高德周边搜索:结果是“离得近的店”,和“真实旅行者推荐”没关系,而且一个问题要多次 poi_search / nearby_search。
-- 217 篇游记里的地点只存在于文本和 LLM 抽取的元数据里,彼此之间没有关系。
-
-### 7.2 做了什么
-
-| 步骤 | 做法 | 关键代码 |
-|---|---|---|
-| 实体抽取 | 复用 P2 的 LLM 元数据(每篇笔记的城市、地点名) | `rag/metadata.py` |
-| 实体对齐 | 每个(地点名, 笔记城市)调用高德 POI 搜索,按名称匹配、同城优先选候选;泛称(“美食街”“夜市”)直接跳过;870 个地名中 669 个找到候选 | `graph/align.py` → `data/graph/poi_alignment.jsonl` |
-| 对齐过滤 | 建图前用规则拒绝误配(类别不符、只匹配到泛称片段、借名商户),三轮人工抽检迭代,最终采用 490 个 | `graph/build.py:accept` |
-| 建图 | 节点 POI / City / Tag / Note;边 LOCATED_IN、HAS_TAG(由高德类别映射 18 个标签)、MENTIONS、CO_MENTIONED(同一篇笔记共现,带次数)、NEAR(同城直线 ≤1.5km,猜测的连锁分店不参与);`UNWIND + MERGE` 批量写入,可重复执行 | `graph/build.py` |
-| 部署 | Neo4j 5.26 社区版 Docker,只绑定 127.0.0.1,密码在 `.env`,限制堆内存 512MB | `docker-compose.yml` |
-| 查询 | 4 个参数化 Cypher 模板:nearby、co_visit(同时返回直线距离)、by_tag、evidence。LLM 只选模板和填参数,不直接写 Cypher | `graph/queries.py` |
-| 接入 | 新工具 `graph_query` 加入 P5 的 graph_qa 路由;提示词按问题类型规定工具用法 | `agent/tools.py`、`agent/router.py` |
-| 容错 | 客户端读超时 + 熔断(3 次失败打开 30 秒)+ 统一错误码 `GRAPH_UNAVAILABLE`;工具返回“图谱不可用,改用 nearby_search”提示让模型自己降级;`/readyz` 显示图谱状态但不因图谱挂掉而判定不就绪 | `graph/client.py`、`app.py` |
-
-图谱规模:POI 465、City 30、Tag 18、Note 156;MENTIONS 761、CO_MENTIONED 1,813、NEAR 848、HAS_TAG 551(`data/graph/build_stats.json`)。
-
-### 7.3 关键设计决策(面试常问“为什么”)
-
-- **为什么要图谱,向量检索不够吗?** 向量检索回答“哪段文字和问题像”;“去了 A 的人还去了哪”是**关系**问题,需要跨多篇笔记聚合(A 和 B 在多少篇里一起出现)。这在图里是一跳查询,用 RAG 要把很多篇笔记塞给 LLM 自己数。
-- **为什么要对齐到高德 POI?** 同一个地方在笔记里有多种写法(“宽窄巷子”“宽窄”),对齐到 poi_id 后才能合并成一个节点;同时拿到坐标,才能算 NEAR 和距离。
-- **为什么用模板而不是让 LLM 写 Cypher(Text2Cypher)?** 防注入、结果可预期、好测试;问题类型就三四种,模板够用。代价是灵活性低。
-- **为什么 co_visit 要返回距离?** “一起出现”不等于“顺路”:评测中熊猫基地“顺路”被推荐了 13~17 公里外的地点。返回距离后,提示词要求超过 5 公里时说明“常一起去但不顺路”。
-- **为什么图谱不可用不影响就绪?** 图谱是增强而不是必需,挂掉时还有高德周边搜索可用;如果因此判定不就绪,负载均衡会把整个服务摘掉,得不偿失。
-- **为什么连锁分店不参与 NEAR?** 笔记只写了“紫光园”,高德给的是“紫光园(隆福寺店)”,具体哪家店是猜的,坐标不可信,算“附近”会误导。
-
-### 7.4 实体对齐的人工抽检(`eval/graph_alignment_review.md`)
-
-| 轮次 | 规则 | 抽样 | 精确率 |
-|---|---|---|---|
-| 1 | v1(只有名称匹配 + 类别过滤) | 随机 30 条 | 70%(21/30) |
-| 2 | v2(加两条规则:拒绝“只匹配到泛称片段”和“借名商户”) | **换种子重新抽** 30 条 | 83%~90% |
-| 3 | v3(街区 / 步行街 / 市场豁免规则 2) | 再换种子 30 条 | 80%~87% |
-| 2+3 合计 | | 60 条 | **82%~88%**(正确 49,错误 7,不确定 4) |
-
-- 每次改规则后都**重新抽样**,避免“在同一批样本上调到 100%”的过拟合。
-- 剩余错误已不在对齐规则,而在更早的抽取:菜名、工艺品、展览被当成地点(肠旺面 → 老七肠旺面)、多城市笔记归错城市(春熙路 → 深圳)。所以停止调规则,列为后续工作(抽取阶段区分地点 / 菜品 / 商品)。
-- 局限:抽检人是我自己,单人判断。
-
-### 7.5 效果评测(`eval/graph_report.md`)
-
-16 个人工编写的地点关系问题(6 个城市,co_visit / nearby / by_tag 各约 1/3),同一问题分别用“带图谱工具”和“P5 工具集(高德周边搜索等)”回答,各跑 3 次(v1~v3):
-
-| 指标 | 不带图谱 | 带图谱 | 变化 | 三次是否稳定 |
-|---|---|---|---|---|
-| 回答中有游记依据的地点数 | 2.2 | 5.3 | 约 2.4 倍 | 稳定(v1~v3:5.4 / 5.4 / 5.3) |
-| 平均延迟 | 7.6s | 5.1s | -33% | 稳定 |
-| 平均 token | 6,174 | 4,756 | -23% | 稳定(-23%~-27%) |
-| LLM 盲评(两种顺序都判胜才算) | | | v1 5胜4负7平;v2 4胜8负4平;v3 6胜4负6平 | **不稳定,不能写** |
-
-- “有游记依据的地点数”的定义:回答里出现的、至少被 1 篇游记提到过的图谱 POI 名称个数。它衡量“推荐是否有真实旅行者依据”,**不是正确性**,而且带图谱的回答天然更容易命中,面试时要主动说明。
-- 延迟和 token 下降的原因:一次图谱查询替代了多次 poi_search + nearby_search。
-- v3 是**开发集结果**:同一批 16 个问题既用于发现问题(顺路误用、工具标记泄漏)也用于验证修改。
-
-### 7.6 遇到的问题(讲故事用)
-
-1. **工具调用语法泄漏到回答里**:最后一轮用 `tool_choice="none"` 禁止调工具时,DeepSeek 偶尔把内部的工具调用标记(`<|DSML|invoke…>`)当正文输出,v1 有一条回答整段是这个。修复:最后一轮不传工具、追加“直接用文字回答”指令,并清洗残留标记,清洗后为空就返回兜底话术;加了单元测试。P5 路由评测里也出现过一次,同一个根因。
-2. **“一起出现”被当成“顺路”**:v2 中“熊猫基地顺路去哪”推荐了 13~17 公里外的地点,因为 co_visit 只按共现次数排序。修复:co_visit 用 `point.distance` 返回直线距离,提示词按问题类型规定工具。
-3. **对齐规则误删地标**:规则 2(拒绝“查询 + 很多字”的商户名)把“春熙路 → 春熙路步行街”“洪崖洞 → 洪崖洞夜市街区”也删了,导致真实问题查不到。逐条看了规则 2 拒绝的 80 条,只对街区、步行街、市场类名称豁免。
-4. **图谱挂掉时降级太慢**:停掉 Neo4j 实测,Neo4j 驱动连不上时**默认自己重试 30 秒**,我配置的 3 秒超时只作用在服务端的事务上,降级形同虚设。修复:限制驱动重试时间,读查询外面再套 `asyncio.wait_for` 整体时限;实测单次 6 秒内失败,连续 3 次后熔断,之后直接降级,回答改用高德周边 + 游记检索。补了“驱动卡住”的回归测试。
-5. **其他坑**:`execute_query` 的未知关键字参数会被当成 Cypher 参数(`timeout=` 没生效),要放在 `Query` 对象上;去括号后比较名称导致“紫光园”和“紫光园(隆福寺店)”判为相等,分店判断要用原始全名;高德偶尔返回没有 poi_id 的条目,要直接拒绝。
-
-### 7.7 可能被问到的问题
-
-- **图谱多大?为什么这么小?** 465 个 POI、1,813 条共现边,来自 217 篇游记。规模受语料限制,多数地点只被 1 篇游记提到,所以“推荐度”区分度有限,提示词要求只有 1 篇提到时不强调推荐度。扩充语料是最直接的改进。
-- **对齐精确率怎么算的?** 人工判断“高德 POI 是不是笔记说的那个地方”,三轮共 90 条,后两轮 60 条在最终规则附近,82%~88%(不确定项分别按错 / 对计)。
-- **为什么不用 GraphRAG / LLM 抽三元组?** 这个场景的关系类型很少(共现、邻近、所属),用确定性规则从元数据和坐标生成更可控、可复现;LLM 抽关系成本高且难评测。
-- **Neo4j 挂了怎么办?** 见 7.6 第 4 条:超时 + 熔断 + 工具层降级提示 + 就绪探针不受影响,实测过。
-- **怎么证明图谱有用?** 能证明的是:回答里有游记依据的推荐更多(2.2 → 5.3),延迟 -33%、token -23%,三次运行都稳定。不能证明“回答更好”:LLM 盲评三次结果互相矛盾,16 个问题太少。
-- **Cypher 注入?** LLM 只能选模板名和填参数,参数通过驱动参数化传入,不拼接字符串。
-
----
-
-## 8. 演示脚本(面试现场或录屏)
-
-```powershell
-# 启动
-cd D:\gaode_test\agent_service; .\.venv-win\Scripts\python.exe app.py
-cd D:\gaode_test; npm start
-
-# 1) 健康检查:展示依赖状态、熔断器状态、重排模型已加载
-Invoke-RestMethod http://127.0.0.1:3000/api/readyz | ConvertTo-Json -Depth 6
-
-# 2) 统一错误格式 + request-id
-Invoke-RestMethod -Method POST http://127.0.0.1:3000/api/classify -ContentType application/json -Body '{}'
-
-# 3) 跑测试、看评测报告
-.\agent_service\.venv-win\Scripts\python.exe -m pytest -q agent_service\tests
-Get-Content eval\rag_report.md
-```
-
-浏览器:`http://localhost:3000/rag-search.html` 演示问答与引用;`http://localhost:3000/ai-chat.html` 演示行程生成 → 地图。
diff --git a/docs/upgrade_plan.md b/docs/upgrade_plan.md
index 924e3c7..791679c 100644
--- a/docs/upgrade_plan.md
+++ b/docs/upgrade_plan.md
@@ -612,7 +612,7 @@ Chroma 中按用途拆分 collection:`notes`(游记经验)、`poi_profiles
| P5 ✅ | 动态路由 + 多知识库 | 0.5 周 | 路由准确率 |
| P6 ✅ | Memory:抽取/存储/摘要/约束校验/偏好面板 | 1 周 | 约束遵守率 |
| P7 ✅(规划聚类未做) | 知识图谱:抽取、对齐、Neo4j、Cypher 模板、规划聚类 | 1.5 周 | 图谱规模、对齐率、交通时长对比 |
-| P8 | 性能与运维:缓存、限流、压测、监控页面、Docker | 1 周 | `eval/load_test.md`、`admin.html` |
+| P8 ✅ | 性能与运维:缓存、限流、压测、监控页面、Docker | 1 周 | `eval/load_test.md`、`admin.html` |
| 可选 | LoRA 槽位解析模型 | 1–2 周 | 槽位 F1 |
总计约 10–11 周。时间不够时的优先级:**P1 → P2 → P3 → P4**(覆盖简历四条主线并产出全部【待填】数字)> P6 > P5 > P8 > P7。
diff --git a/eval/data/load_test_results.json b/eval/data/load_test_results.json
new file mode 100644
index 0000000..8cbca9c
--- /dev/null
+++ b/eval/data/load_test_results.json
@@ -0,0 +1,394 @@
+{
+ "retrieval": {
+ "cold": [
+ {
+ "concurrency": 1,
+ "requests": 40,
+ "ok": 40,
+ "throughput_rps": 33.78,
+ "wall_s": 1.18,
+ "p50_ms": 23,
+ "p95_ms": 34,
+ "max_ms": 256,
+ "status": {
+ "200": 40
+ },
+ "routes": {}
+ },
+ {
+ "concurrency": 4,
+ "requests": 40,
+ "ok": 40,
+ "throughput_rps": 66.67,
+ "wall_s": 0.6,
+ "p50_ms": 53,
+ "p95_ms": 86,
+ "max_ms": 102,
+ "status": {
+ "200": 40
+ },
+ "routes": {}
+ },
+ {
+ "concurrency": 16,
+ "requests": 40,
+ "ok": 40,
+ "throughput_rps": 54.72,
+ "wall_s": 0.73,
+ "p50_ms": 267,
+ "p95_ms": 373,
+ "max_ms": 546,
+ "status": {
+ "200": 40
+ },
+ "routes": {}
+ }
+ ],
+ "warm": [
+ {
+ "concurrency": 1,
+ "requests": 80,
+ "ok": 80,
+ "throughput_rps": 111.98,
+ "wall_s": 0.71,
+ "p50_ms": 9,
+ "p95_ms": 11,
+ "max_ms": 42,
+ "status": {
+ "200": 80
+ },
+ "routes": {}
+ },
+ {
+ "concurrency": 4,
+ "requests": 80,
+ "ok": 80,
+ "throughput_rps": 499.56,
+ "wall_s": 0.16,
+ "p50_ms": 7,
+ "p95_ms": 11,
+ "max_ms": 16,
+ "status": {
+ "200": 80
+ },
+ "routes": {}
+ },
+ {
+ "concurrency": 16,
+ "requests": 80,
+ "ok": 80,
+ "throughput_rps": 277.67,
+ "wall_s": 0.29,
+ "p50_ms": 36,
+ "p95_ms": 153,
+ "max_ms": 208,
+ "status": {
+ "200": 80
+ },
+ "routes": {}
+ }
+ ],
+ "cache": {
+ "size": 120,
+ "maxsize": 1024,
+ "hits": 240,
+ "misses": 120,
+ "hit_rate": 0.667
+ }
+ },
+ "chat": {
+ "rows": [
+ {
+ "concurrency": 1,
+ "requests": 12,
+ "ok": 12,
+ "throughput_rps": 0.95,
+ "wall_s": 12.69,
+ "p50_ms": 1058,
+ "p95_ms": 1067,
+ "max_ms": 1094,
+ "status": {
+ "200": 12
+ },
+ "routes": {
+ "chitchat": 12
+ },
+ "llm_calls": 12,
+ "llm_max_in_flight": 1
+ },
+ {
+ "concurrency": 8,
+ "requests": 24,
+ "ok": 24,
+ "throughput_rps": 6.66,
+ "wall_s": 3.6,
+ "p50_ms": 1171,
+ "p95_ms": 1275,
+ "max_ms": 1276,
+ "status": {
+ "200": 24
+ },
+ "routes": {
+ "chitchat": 24
+ },
+ "llm_calls": 24,
+ "llm_max_in_flight": 8
+ },
+ {
+ "concurrency": 16,
+ "requests": 48,
+ "ok": 48,
+ "throughput_rps": 7.18,
+ "wall_s": 6.68,
+ "p50_ms": 2048,
+ "p95_ms": 2499,
+ "max_ms": 2515,
+ "status": {
+ "200": 48
+ },
+ "routes": {
+ "chitchat": 48
+ },
+ "llm_calls": 48,
+ "llm_max_in_flight": 8
+ },
+ {
+ "concurrency": 32,
+ "requests": 96,
+ "ok": 96,
+ "throughput_rps": 7.39,
+ "wall_s": 12.99,
+ "p50_ms": 4060,
+ "p95_ms": 4697,
+ "max_ms": 4848,
+ "status": {
+ "200": 96
+ },
+ "routes": {
+ "chitchat": 96
+ },
+ "llm_calls": 96,
+ "llm_max_in_flight": 8
+ }
+ ],
+ "llm_concurrency_limit": 8
+ },
+ "overload": {
+ "summary": {
+ "concurrency": 40,
+ "requests": 40,
+ "ok": 8,
+ "throughput_rps": 3.4,
+ "wall_s": 2.35,
+ "p50_ms": 2345,
+ "p95_ms": 2349,
+ "max_ms": 2349,
+ "status": {
+ "200": 8,
+ "503 SERVER_BUSY": 32
+ },
+ "routes": {
+ "chitchat": 8
+ }
+ },
+ "rejected_p95_ms": 172
+ },
+ "rate_limit": {
+ "rows": [
+ {
+ "i": 1,
+ "status": 200,
+ "code": "",
+ "retry_after": null
+ },
+ {
+ "i": 2,
+ "status": 200,
+ "code": "",
+ "retry_after": null
+ },
+ {
+ "i": 3,
+ "status": 200,
+ "code": "",
+ "retry_after": null
+ },
+ {
+ "i": 4,
+ "status": 200,
+ "code": "",
+ "retry_after": null
+ },
+ {
+ "i": 5,
+ "status": 200,
+ "code": "",
+ "retry_after": null
+ },
+ {
+ "i": 6,
+ "status": 200,
+ "code": "",
+ "retry_after": null
+ },
+ {
+ "i": 7,
+ "status": 200,
+ "code": "",
+ "retry_after": null
+ },
+ {
+ "i": 8,
+ "status": 200,
+ "code": "",
+ "retry_after": null
+ },
+ {
+ "i": 9,
+ "status": 200,
+ "code": "",
+ "retry_after": null
+ },
+ {
+ "i": 10,
+ "status": 200,
+ "code": "",
+ "retry_after": null
+ },
+ {
+ "i": 11,
+ "status": 429,
+ "code": "RATE_LIMITED",
+ "retry_after": "6"
+ },
+ {
+ "i": 12,
+ "status": 429,
+ "code": "RATE_LIMITED",
+ "retry_after": "6"
+ },
+ {
+ "i": 13,
+ "status": 429,
+ "code": "RATE_LIMITED",
+ "retry_after": "6"
+ },
+ {
+ "i": 14,
+ "status": 429,
+ "code": "RATE_LIMITED",
+ "retry_after": "6"
+ },
+ {
+ "i": 15,
+ "status": 429,
+ "code": "RATE_LIMITED",
+ "retry_after": "6"
+ }
+ ],
+ "counts": {
+ "200": 10,
+ "429 RATE_LIMITED": 5
+ }
+ },
+ "breaker": {
+ "timeline": [
+ {
+ "i": 1,
+ "status": 503,
+ "code": "UPSTREAM_LLM_UNAVAILABLE",
+ "ms": 2051,
+ "upstream_calls": 3,
+ "breaker": "closed"
+ },
+ {
+ "i": 2,
+ "status": 503,
+ "code": "UPSTREAM_LLM_UNAVAILABLE",
+ "ms": 1488,
+ "upstream_calls": 2,
+ "breaker": "open"
+ },
+ {
+ "i": 3,
+ "status": 503,
+ "code": "UPSTREAM_LLM_UNAVAILABLE",
+ "ms": 75,
+ "upstream_calls": 0,
+ "breaker": "open"
+ },
+ {
+ "i": 4,
+ "status": 503,
+ "code": "UPSTREAM_LLM_UNAVAILABLE",
+ "ms": 33,
+ "upstream_calls": 0,
+ "breaker": "open"
+ },
+ {
+ "i": 5,
+ "status": 503,
+ "code": "UPSTREAM_LLM_UNAVAILABLE",
+ "ms": 37,
+ "upstream_calls": 0,
+ "breaker": "open"
+ },
+ {
+ "i": 6,
+ "status": 503,
+ "code": "UPSTREAM_LLM_UNAVAILABLE",
+ "ms": 36,
+ "upstream_calls": 0,
+ "breaker": "half_open"
+ },
+ {
+ "i": 7,
+ "status": 503,
+ "code": "UPSTREAM_LLM_UNAVAILABLE",
+ "ms": 746,
+ "upstream_calls": 1,
+ "breaker": "open"
+ },
+ {
+ "i": 8,
+ "status": 503,
+ "code": "UPSTREAM_LLM_UNAVAILABLE",
+ "ms": 39,
+ "upstream_calls": 0,
+ "breaker": "open"
+ },
+ {
+ "i": "恢复后 1",
+ "status": 200,
+ "code": "",
+ "ms": 112,
+ "upstream_calls": 1,
+ "breaker": "closed"
+ },
+ {
+ "i": "恢复后 2",
+ "status": 200,
+ "code": "",
+ "ms": 159,
+ "upstream_calls": 1,
+ "breaker": "closed"
+ },
+ {
+ "i": "恢复后 3",
+ "status": 200,
+ "code": "",
+ "ms": 116,
+ "upstream_calls": 1,
+ "breaker": "closed"
+ }
+ ]
+ },
+ "env": {
+ "date": "2026-10-13",
+ "os": "Windows-11-10.0.26200-SP0",
+ "cpu": "Intel64 Family 6 Model 186 Stepping 2, GenuineIntel",
+ "cpu_count": 16,
+ "python": "3.13.7",
+ "node": "v22.18.0"
+ }
+}
\ No newline at end of file
diff --git a/eval/data/load_test_results_v1.json b/eval/data/load_test_results_v1.json
new file mode 100644
index 0000000..4a334aa
--- /dev/null
+++ b/eval/data/load_test_results_v1.json
@@ -0,0 +1,394 @@
+{
+ "retrieval": {
+ "cold": [
+ {
+ "concurrency": 1,
+ "requests": 40,
+ "ok": 40,
+ "throughput_rps": 34.28,
+ "wall_s": 1.17,
+ "p50_ms": 22,
+ "p95_ms": 34,
+ "max_ms": 263,
+ "status": {
+ "200": 40
+ },
+ "routes": {}
+ },
+ {
+ "concurrency": 4,
+ "requests": 40,
+ "ok": 40,
+ "throughput_rps": 68.74,
+ "wall_s": 0.58,
+ "p50_ms": 50,
+ "p95_ms": 99,
+ "max_ms": 138,
+ "status": {
+ "200": 40
+ },
+ "routes": {}
+ },
+ {
+ "concurrency": 16,
+ "requests": 40,
+ "ok": 40,
+ "throughput_rps": 54.57,
+ "wall_s": 0.73,
+ "p50_ms": 244,
+ "p95_ms": 490,
+ "max_ms": 565,
+ "status": {
+ "200": 40
+ },
+ "routes": {}
+ }
+ ],
+ "warm": [
+ {
+ "concurrency": 1,
+ "requests": 80,
+ "ok": 80,
+ "throughput_rps": 114.35,
+ "wall_s": 0.7,
+ "p50_ms": 9,
+ "p95_ms": 11,
+ "max_ms": 13,
+ "status": {
+ "200": 80
+ },
+ "routes": {}
+ },
+ {
+ "concurrency": 4,
+ "requests": 80,
+ "ok": 80,
+ "throughput_rps": 442.86,
+ "wall_s": 0.18,
+ "p50_ms": 8,
+ "p95_ms": 16,
+ "max_ms": 25,
+ "status": {
+ "200": 80
+ },
+ "routes": {}
+ },
+ {
+ "concurrency": 16,
+ "requests": 80,
+ "ok": 80,
+ "throughput_rps": 285.01,
+ "wall_s": 0.28,
+ "p50_ms": 44,
+ "p95_ms": 155,
+ "max_ms": 206,
+ "status": {
+ "200": 80
+ },
+ "routes": {}
+ }
+ ],
+ "cache": {
+ "size": 120,
+ "maxsize": 1024,
+ "hits": 240,
+ "misses": 120,
+ "hit_rate": 0.667
+ }
+ },
+ "chat": {
+ "rows": [
+ {
+ "concurrency": 1,
+ "requests": 12,
+ "ok": 12,
+ "throughput_rps": 0.95,
+ "wall_s": 12.69,
+ "p50_ms": 1051,
+ "p95_ms": 1086,
+ "max_ms": 1100,
+ "status": {
+ "200": 12
+ },
+ "routes": {
+ "chitchat": 12
+ },
+ "llm_calls": 12,
+ "llm_max_in_flight": 1
+ },
+ {
+ "concurrency": 8,
+ "requests": 24,
+ "ok": 24,
+ "throughput_rps": 6.52,
+ "wall_s": 3.68,
+ "p50_ms": 1196,
+ "p95_ms": 1323,
+ "max_ms": 1323,
+ "status": {
+ "200": 24
+ },
+ "routes": {
+ "chitchat": 24
+ },
+ "llm_calls": 24,
+ "llm_max_in_flight": 8
+ },
+ {
+ "concurrency": 16,
+ "requests": 48,
+ "ok": 48,
+ "throughput_rps": 7.19,
+ "wall_s": 6.68,
+ "p50_ms": 2041,
+ "p95_ms": 2519,
+ "max_ms": 2559,
+ "status": {
+ "200": 48
+ },
+ "routes": {
+ "chitchat": 48
+ },
+ "llm_calls": 48,
+ "llm_max_in_flight": 8
+ },
+ {
+ "concurrency": 32,
+ "requests": 96,
+ "ok": 96,
+ "throughput_rps": 7.39,
+ "wall_s": 12.99,
+ "p50_ms": 4075,
+ "p95_ms": 4635,
+ "max_ms": 4775,
+ "status": {
+ "200": 96
+ },
+ "routes": {
+ "chitchat": 96
+ },
+ "llm_calls": 96,
+ "llm_max_in_flight": 8
+ }
+ ],
+ "llm_concurrency_limit": 8
+ },
+ "overload": {
+ "summary": {
+ "concurrency": 40,
+ "requests": 40,
+ "ok": 8,
+ "throughput_rps": 3.37,
+ "wall_s": 2.38,
+ "p50_ms": 2366,
+ "p95_ms": 2371,
+ "max_ms": 2371,
+ "status": {
+ "200": 8,
+ "503 SERVER_BUSY": 32
+ },
+ "routes": {
+ "chitchat": 8
+ }
+ },
+ "rejected_p95_ms": 173
+ },
+ "rate_limit": {
+ "rows": [
+ {
+ "i": 1,
+ "status": 200,
+ "code": "",
+ "retry_after": null
+ },
+ {
+ "i": 2,
+ "status": 200,
+ "code": "",
+ "retry_after": null
+ },
+ {
+ "i": 3,
+ "status": 200,
+ "code": "",
+ "retry_after": null
+ },
+ {
+ "i": 4,
+ "status": 200,
+ "code": "",
+ "retry_after": null
+ },
+ {
+ "i": 5,
+ "status": 200,
+ "code": "",
+ "retry_after": null
+ },
+ {
+ "i": 6,
+ "status": 200,
+ "code": "",
+ "retry_after": null
+ },
+ {
+ "i": 7,
+ "status": 200,
+ "code": "",
+ "retry_after": null
+ },
+ {
+ "i": 8,
+ "status": 200,
+ "code": "",
+ "retry_after": null
+ },
+ {
+ "i": 9,
+ "status": 200,
+ "code": "",
+ "retry_after": null
+ },
+ {
+ "i": 10,
+ "status": 200,
+ "code": "",
+ "retry_after": null
+ },
+ {
+ "i": 11,
+ "status": 429,
+ "code": "RATE_LIMITED",
+ "retry_after": "6"
+ },
+ {
+ "i": 12,
+ "status": 429,
+ "code": "RATE_LIMITED",
+ "retry_after": "6"
+ },
+ {
+ "i": 13,
+ "status": 429,
+ "code": "RATE_LIMITED",
+ "retry_after": "6"
+ },
+ {
+ "i": 14,
+ "status": 429,
+ "code": "RATE_LIMITED",
+ "retry_after": "6"
+ },
+ {
+ "i": 15,
+ "status": 429,
+ "code": "RATE_LIMITED",
+ "retry_after": "6"
+ }
+ ],
+ "counts": {
+ "200": 10,
+ "429 RATE_LIMITED": 5
+ }
+ },
+ "breaker": {
+ "timeline": [
+ {
+ "i": 1,
+ "status": 503,
+ "code": "UPSTREAM_LLM_UNAVAILABLE",
+ "ms": 1556,
+ "upstream_calls": 3,
+ "breaker": "closed"
+ },
+ {
+ "i": 2,
+ "status": 503,
+ "code": "UPSTREAM_LLM_UNAVAILABLE",
+ "ms": 1099,
+ "upstream_calls": 2,
+ "breaker": "open"
+ },
+ {
+ "i": 3,
+ "status": 503,
+ "code": "UPSTREAM_LLM_UNAVAILABLE",
+ "ms": 1531,
+ "upstream_calls": 0,
+ "breaker": "open"
+ },
+ {
+ "i": 4,
+ "status": 503,
+ "code": "UPSTREAM_LLM_UNAVAILABLE",
+ "ms": 1793,
+ "upstream_calls": 1,
+ "breaker": "open"
+ },
+ {
+ "i": 5,
+ "status": 503,
+ "code": "UPSTREAM_LLM_UNAVAILABLE",
+ "ms": 1012,
+ "upstream_calls": 0,
+ "breaker": "open"
+ },
+ {
+ "i": 6,
+ "status": 503,
+ "code": "UPSTREAM_LLM_UNAVAILABLE",
+ "ms": 1684,
+ "upstream_calls": 0,
+ "breaker": "half_open"
+ },
+ {
+ "i": 7,
+ "status": 503,
+ "code": "UPSTREAM_LLM_UNAVAILABLE",
+ "ms": 1592,
+ "upstream_calls": 1,
+ "breaker": "open"
+ },
+ {
+ "i": 8,
+ "status": 503,
+ "code": "UPSTREAM_LLM_UNAVAILABLE",
+ "ms": 993,
+ "upstream_calls": 0,
+ "breaker": "open"
+ },
+ {
+ "i": "恢复后 1",
+ "status": 200,
+ "code": "",
+ "ms": 114,
+ "upstream_calls": 1,
+ "breaker": "closed"
+ },
+ {
+ "i": "恢复后 2",
+ "status": 200,
+ "code": "",
+ "ms": 114,
+ "upstream_calls": 1,
+ "breaker": "closed"
+ },
+ {
+ "i": "恢复后 3",
+ "status": 200,
+ "code": "",
+ "ms": 110,
+ "upstream_calls": 1,
+ "breaker": "closed"
+ }
+ ]
+ },
+ "env": {
+ "date": "2026-10-13",
+ "os": "Windows-11-10.0.26200-SP0",
+ "cpu": "Intel64 Family 6 Model 186 Stepping 2, GenuineIntel",
+ "cpu_count": 16,
+ "python": "3.13.7",
+ "node": "v22.18.0"
+ }
+}
\ No newline at end of file
diff --git a/eval/load_test.md b/eval/load_test.md
new file mode 100644
index 0000000..e6ee1a9
--- /dev/null
+++ b/eval/load_test.md
@@ -0,0 +1,81 @@
+# 压测报告
+
+- 运行日期:2026-10-13;单机:Windows-11-10.0.26200-SP0,16 逻辑核;Python 3.13.7,Node v22.18.0
+- 压测客户端与服务在同一台机器上;LLM 为本地模拟服务(固定延迟),**不包含 DeepSeek 的真实延迟和限流**
+- 链路:压测客户端 → Node 网关 → agent_service(单进程 uvicorn)→ 模拟 LLM
+- 复现:`python eval/load_test.py`(原始数据 `eval/data/load_test_results.json`)
+
+## 1. 检索接口(本地 CPU:embedding + BM25 + RRF,不重排)
+
+**首次查询(全部是没查过的问题)**
+
+| 并发 | 请求 | 成功 | 吞吐 (次/秒) | P50 | P95 | 最大 |
+|---|---|---|---|---|---|---|
+| 1 | 40 | 40 | 33.78 | 23 ms | 34 ms | 256 ms |
+| 4 | 40 | 40 | 66.67 | 53 ms | 86 ms | 102 ms |
+| 16 | 40 | 40 | 54.72 | 267 ms | 373 ms | 546 ms |
+
+**重复查询(命中检索缓存)**
+
+| 并发 | 请求 | 成功 | 吞吐 (次/秒) | P50 | P95 | 最大 |
+|---|---|---|---|---|---|---|
+| 1 | 80 | 80 | 111.98 | 9 ms | 11 ms | 42 ms |
+| 4 | 80 | 80 | 499.56 | 7 ms | 11 ms | 16 ms |
+| 16 | 80 | 80 | 277.67 | 36 ms | 153 ms | 208 ms |
+
+检索缓存累计:命中 240、未命中 120。
+
+## 2. 聊天接口(模拟 LLM 每次 1 秒)
+
+agent_service 的 LLM 并发上限为 8;网关不限流。
+
+| 并发 | 请求 | 成功 | 吞吐 (次/秒) | P50 | P95 | 最大 | LLM 调用数 | 上游最大并发 | 路由 |
+|---|---|---|---|---|---|---|---|---|---|
+| 1 | 12 | 12 | 0.95 | 1058 ms | 1067 ms | 1094 ms | 12 | 1 | chitchat 12 |
+| 8 | 24 | 24 | 6.66 | 1171 ms | 1275 ms | 1276 ms | 24 | 8 | chitchat 24 |
+| 16 | 48 | 48 | 7.18 | 2048 ms | 2499 ms | 2515 ms | 48 | 8 | chitchat 48 |
+| 32 | 96 | 96 | 7.39 | 4060 ms | 4697 ms | 4848 ms | 96 | 8 | chitchat 96 |
+
+## 3. 过载保护(同时 40 个聊天请求,模拟 LLM 2 秒,网关重请求并发上限 8)
+
+- 结果分布:{'200': 8, '503 SERVER_BUSY': 32}
+- 被拒绝的请求 P95 返回时间:172 ms(立即告知“当前使用人数较多”,而不是排队到超时)
+- 放行请求 P50 2345 ms、P95 2349 ms
+
+## 4. 限流(同一 IP 连续 15 个重请求,配额 10 次/分钟)
+
+- 结果分布:{'200': 10, '429 RATE_LIMITED': 5}
+- 被限流的响应带 `Retry-After`:6s, 6s, 6s, 6s, 6s
+
+## 5. LLM 故障与熔断(模拟 LLM 全部返回 500,之后恢复)
+
+| 请求 | 状态 | 错误码 | 耗时 | 本次打到上游的次数 | 熔断器状态(请求后) |
+|---|---|---|---|---|---|
+| 1 | 503 | UPSTREAM_LLM_UNAVAILABLE | 2051 ms | 3 | closed |
+| 2 | 503 | UPSTREAM_LLM_UNAVAILABLE | 1488 ms | 2 | open |
+| 3 | 503 | UPSTREAM_LLM_UNAVAILABLE | 75 ms | 0 | open |
+| 4 | 503 | UPSTREAM_LLM_UNAVAILABLE | 33 ms | 0 | open |
+| 5 | 503 | UPSTREAM_LLM_UNAVAILABLE | 37 ms | 0 | open |
+| 6 | 503 | UPSTREAM_LLM_UNAVAILABLE | 36 ms | 0 | half_open |
+| 7 | 503 | UPSTREAM_LLM_UNAVAILABLE | 746 ms | 1 | open |
+| 8 | 503 | UPSTREAM_LLM_UNAVAILABLE | 39 ms | 0 | open |
+| 恢复后 1 | 200 | — | 112 ms | 1 | closed |
+| 恢复后 2 | 200 | — | 159 ms | 1 | closed |
+| 恢复后 3 | 200 | — | 116 ms | 1 | closed |
+
+### 修复记录:熔断打开后仍然很慢
+
+第一次压测(`eval/load_test_v1.md`)中,熔断已经打开、上游调用次数为 0 的请求仍然要 **1.0~1.8 秒**才返回。
+原因:熔断器拒绝时抛出的错误码是“暂时不可用(可重试)”,重试逻辑对它做了两次指数退避(0.5s + 1s)。
+修复:熔断拒绝改为单独的 `CircuitOpenError`,重试逻辑遇到它立即放弃(对用户的提示语和错误码不变)。
+
+| 熔断打开后的请求 | 修复前 | 修复后 |
+|---|---|---|
+| 耗时 | 993~1793 ms | 33~75 ms |
+| 打到上游的次数 | 0 | 0 |
+
+## 说明
+
+- 吞吐和延迟受本机 CPU 影响,换机器数值会变;这里关注的是**随并发变化的趋势**和**保护机制是否按设计生效**。
+- 聊天吞吐的上限由 LLM 并发闸门决定(约 并发上限 ÷ 单次 LLM 耗时),真实环境下还受 DeepSeek 自身限流影响。
+- 检索是 CPU 密集计算,在线程池中执行;单进程下并发提高后吞吐有限,扩容需要多进程 / 多实例。
diff --git a/eval/load_test.py b/eval/load_test.py
new file mode 100644
index 0000000..a734fd3
--- /dev/null
+++ b/eval/load_test.py
@@ -0,0 +1,323 @@
+"""压测:网关 + agent_service 的吞吐、延迟、限流、过载保护与熔断。
+
+LLM 换成本地模拟服务(eval/mock_llm.py,固定延迟),测的是本系统的并发与保护能力,
+不包含 DeepSeek 的速度与费用。脚本自己启动 模拟 LLM / agent_service / 网关(独立端口与日志目录),
+按场景重启网关以切换限流配置,结束后全部关闭。
+
+python eval/load_test.py # 约 3~4 分钟,输出 eval/load_test.md
+"""
+import asyncio
+import json
+import os
+import platform
+import statistics
+import subprocess
+import sys
+import time
+from collections import Counter
+from datetime import date
+from pathlib import Path
+from typing import Dict, List, Optional
+
+import httpx
+
+ROOT = Path(__file__).resolve().parent.parent
+PY = sys.executable
+MOCK_PORT, AGENT_PORT, GW_PORT = 8099, 8012, 3010
+MOCK = f"http://127.0.0.1:{MOCK_PORT}"
+AGENT = f"http://127.0.0.1:{AGENT_PORT}"
+GW = f"http://127.0.0.1:{GW_PORT}"
+REPORT = ROOT / "eval" / "load_test.md"
+RESULTS = ROOT / "eval" / "data" / "load_test_results.json"
+LOG_DIR = ROOT / "logs" / "loadtest"
+
+CITIES = ["成都", "重庆", "西安", "广州", "厦门", "北京", "上海", "杭州", "南京", "长沙", "昆明", "大理",
+ "青岛", "苏州", "武汉", "贵阳", "桂林", "拉萨", "哈尔滨", "三亚"]
+TOPICS = ["美食推荐", "两天怎么玩", "亲子景点", "夜景去哪看", "小众景点", "住哪里方便", "博物馆", "拍照打卡"]
+CHAT_MESSAGES = ["你好", "谢谢你", "你好呀", "好的谢谢", "哈哈好的", "你是谁"]
+
+
+# ---------------- 进程管理 ----------------
+def start(cmd: List[str], cwd: Path, env: Dict[str, str], name: str) -> subprocess.Popen:
+ LOG_DIR.mkdir(parents=True, exist_ok=True)
+ out = open(LOG_DIR / f"{name}.out.log", "w", encoding="utf-8")
+ return subprocess.Popen(cmd, cwd=cwd, env={**os.environ, **env}, stdout=out, stderr=subprocess.STDOUT)
+
+
+def stop(p: Optional[subprocess.Popen]) -> None:
+ if p and p.poll() is None:
+ p.terminate()
+ try:
+ p.wait(timeout=10)
+ except subprocess.TimeoutExpired:
+ p.kill()
+
+
+async def wait_ready(url: str, timeout_s: float = 180) -> None:
+ deadline = time.monotonic() + timeout_s
+ async with httpx.AsyncClient() as c:
+ while time.monotonic() < deadline:
+ try:
+ if (await c.get(url, timeout=2)).status_code == 200:
+ return
+ except httpx.HTTPError:
+ pass
+ await asyncio.sleep(1)
+ raise RuntimeError(f"{url} not ready after {timeout_s}s")
+
+
+def start_gateway(**limits) -> subprocess.Popen:
+ env = {"PORT": str(GW_PORT), "AGENT_BASE": AGENT,
+ "RATE_LIMIT_API_PER_MIN": str(limits.get("api", 0)),
+ "RATE_LIMIT_HEAVY_PER_MIN": str(limits.get("heavy", 0)),
+ "HEAVY_MAX_IN_FLIGHT": str(limits.get("in_flight", 0))}
+ return start(["node", "server.js"], ROOT, env, "gateway")
+
+
+# ---------------- 压测原语 ----------------
+async def one(client: httpx.AsyncClient, method: str, path: str, body: Optional[dict]) -> Dict:
+ t0 = time.perf_counter()
+ try:
+ r = await client.request(method, GW + path, json=body, timeout=120)
+ code = ""
+ if r.status_code >= 400:
+ try:
+ code = r.json()["error"]["code"]
+ except Exception:
+ code = "?"
+ route = ""
+ if r.status_code == 200 and path == "/api/chat":
+ route = r.json().get("route", "")
+ return {"status": r.status_code, "code": code, "ms": (time.perf_counter() - t0) * 1000, "route": route,
+ "retry_after": r.headers.get("retry-after")}
+ except httpx.HTTPError as e:
+ return {"status": 0, "code": type(e).__name__, "ms": (time.perf_counter() - t0) * 1000, "route": ""}
+
+
+async def run_load(path: str, bodies: List[dict], concurrency: int) -> Dict:
+ """固定并发:concurrency 个 worker 依次领取请求,直到 bodies 用完。"""
+ queue = list(bodies)
+ results: List[Dict] = []
+ async with httpx.AsyncClient(limits=httpx.Limits(max_connections=concurrency + 4)) as client:
+ async def worker():
+ while queue:
+ results.append(await one(client, "POST", path, queue.pop()))
+ t0 = time.perf_counter()
+ await asyncio.gather(*[worker() for _ in range(concurrency)])
+ wall = time.perf_counter() - t0
+ return summarize(results, wall, concurrency)
+
+
+def pct(values: List[float], p: float) -> float:
+ s = sorted(values)
+ return s[min(len(s) - 1, max(0, round(p / 100 * (len(s) - 1))))] if s else 0.0
+
+
+def summarize(results: List[Dict], wall: float, concurrency: int) -> Dict:
+ ok = [r for r in results if r["status"] == 200]
+ lat = [r["ms"] for r in ok]
+ return {"concurrency": concurrency, "requests": len(results), "ok": len(ok),
+ "throughput_rps": round(len(ok) / wall, 2) if wall else 0, "wall_s": round(wall, 2),
+ "p50_ms": round(pct(lat, 50)), "p95_ms": round(pct(lat, 95)), "max_ms": round(max(lat)) if lat else 0,
+ "status": dict(Counter(f"{r['status']} {r['code']}".strip() for r in results)),
+ "routes": dict(Counter(r["route"] for r in ok if r["route"]))}
+
+
+async def mock(**mode) -> Dict:
+ async with httpx.AsyncClient() as c:
+ return (await c.post(MOCK + "/mode", json=mode)).json()
+
+
+async def agent_metrics() -> Dict:
+ async with httpx.AsyncClient() as c:
+ return (await c.get(AGENT + "/metrics")).json()
+
+
+# ---------------- 场景 ----------------
+async def scenario_retrieval() -> Dict:
+ """检索:纯本地 CPU 计算(embedding + BM25 + RRF,不重排)。先全是新查询,再重复查询看缓存。"""
+ unique = [f"{c}{t}" for t in TOPICS for c in CITIES] # 160 条互不相同
+ out = {"cold": [], "warm": []}
+ i = 0
+ for conc in (1, 4, 16):
+ n = 40
+ bodies = [{"query": q, "top_k": 5, "use_rerank": False} for q in unique[i:i + n]]
+ i += n
+ out["cold"].append(await run_load("/api/rag/retrieve", bodies, conc))
+ hot = unique[:20] # 已经查过 → 缓存命中
+ for conc in (1, 4, 16):
+ bodies = [{"query": hot[k % 20], "top_k": 5, "use_rerank": False} for k in range(80)]
+ out["warm"].append(await run_load("/api/rag/retrieve", bodies, conc))
+ out["cache"] = (await agent_metrics())["caches"]["retrieval"]
+ return out
+
+
+async def scenario_chat_capacity() -> Dict:
+ """聊天(闲聊路由):模拟 LLM 每次 1 秒。网关不限流,看 LLM 并发闸门(8)如何决定吞吐。"""
+ await mock(delay=1.0, fail=False)
+ rows = []
+ for conc in (1, 8, 16, 32):
+ await mock(reset_stats=True)
+ n = max(12, conc * 3)
+ bodies = [{"message": CHAT_MESSAGES[k % len(CHAT_MESSAGES)]} for k in range(n)]
+ row = await run_load("/api/chat", bodies, conc)
+ st = await mock()
+ row["llm_calls"] = st["calls"]
+ row["llm_max_in_flight"] = st["max_in_flight"]
+ rows.append(row)
+ return {"rows": rows, "llm_concurrency_limit": (await agent_metrics())["llm_concurrency"]["limit"]}
+
+
+async def scenario_overload() -> Dict:
+ """过载保护:同时打进 40 个聊天请求,网关只放行 8 个,其余立即返回 SERVER_BUSY。"""
+ await mock(delay=2.0, fail=False)
+ bodies = [{"message": "你好"} for _ in range(40)]
+ async with httpx.AsyncClient(limits=httpx.Limits(max_connections=50)) as client:
+ t0 = time.perf_counter()
+ results = await asyncio.gather(*[one(client, "POST", "/api/chat", b) for b in bodies])
+ wall = time.perf_counter() - t0
+ rejected = [r["ms"] for r in results if r["code"] == "SERVER_BUSY"]
+ return {"summary": summarize(results, wall, 40),
+ "rejected_p95_ms": round(pct(rejected, 95)) if rejected else None}
+
+
+async def scenario_rate_limit() -> Dict:
+ """限流:同一 IP 连续 15 个重请求,每分钟配额 10。"""
+ await mock(delay=0.05, fail=False)
+ rows = []
+ async with httpx.AsyncClient() as client:
+ for k in range(15):
+ r = await one(client, "POST", "/api/chat", {"message": "你好"})
+ rows.append({"i": k + 1, "status": r["status"], "code": r["code"], "retry_after": r["retry_after"]})
+ return {"rows": rows, "counts": dict(Counter(f"{r['status']} {r['code']}".strip() for r in rows))}
+
+
+async def scenario_breaker() -> Dict:
+ """LLM 故障:模拟 LLM 全部返回 500 → 重试 → 熔断后快速失败、不再打上游 → 恢复后半开探测成功。"""
+ await mock(delay=0.05, fail=True, reset_stats=True)
+ timeline = []
+ async with httpx.AsyncClient() as client:
+ for k in range(8):
+ before = (await mock())["calls"]
+ r = await one(client, "POST", "/api/chat", {"message": "你好"})
+ after = (await mock())["calls"]
+ m = await agent_metrics()
+ llm_state = next(b["state"] for b in m["breakers"] if b["name"] == "llm")
+ timeline.append({"i": k + 1, "status": r["status"], "code": r["code"], "ms": round(r["ms"]),
+ "upstream_calls": after - before, "breaker": llm_state})
+ await mock(fail=False)
+ await asyncio.sleep(6) # 冷却时间配置为 5 秒
+ for k in range(3):
+ before = (await mock())["calls"]
+ r = await one(client, "POST", "/api/chat", {"message": "你好"})
+ after = (await mock())["calls"]
+ m = await agent_metrics()
+ llm_state = next(b["state"] for b in m["breakers"] if b["name"] == "llm")
+ timeline.append({"i": f"恢复后 {k + 1}", "status": r["status"], "code": r["code"], "ms": round(r["ms"]),
+ "upstream_calls": after - before, "breaker": llm_state})
+ return {"timeline": timeline}
+
+
+# ---------------- 主流程 ----------------
+async def main() -> None:
+ mock_p = agent_p = gw_p = None
+ results: Dict = {}
+ try:
+ mock_p = start([PY, str(ROOT / "eval" / "mock_llm.py"), "--port", str(MOCK_PORT)], ROOT, {}, "mock_llm")
+ agent_p = start([PY, "app.py"], ROOT / "agent_service", {
+ "SERVER__PORT": str(AGENT_PORT), "LLM__BASE_URL": MOCK, "LLM_API_KEY": "mock-key",
+ "LLM__BREAKER_RECOVERY_S": "5", "LOGGING__DIR": str(LOG_DIR), "LOGGING__LEVEL": "WARNING"}, "agent")
+ await wait_ready(MOCK + "/stats")
+ await wait_ready(AGENT + "/healthz")
+
+ gw_p = start_gateway() # 容量测试:网关不限流
+ await wait_ready(GW + "/api/readyz")
+ print("retrieval ...", flush=True)
+ results["retrieval"] = await scenario_retrieval()
+ print("chat capacity ...", flush=True)
+ results["chat"] = await scenario_chat_capacity()
+ stop(gw_p)
+
+ gw_p = start_gateway(in_flight=8)
+ await wait_ready(GW + "/api/readyz")
+ print("overload ...", flush=True)
+ results["overload"] = await scenario_overload()
+ stop(gw_p)
+
+ gw_p = start_gateway(heavy=10)
+ await wait_ready(GW + "/api/readyz")
+ print("rate limit ...", flush=True)
+ results["rate_limit"] = await scenario_rate_limit()
+ stop(gw_p)
+
+ gw_p = start_gateway()
+ await wait_ready(GW + "/api/readyz")
+ print("breaker ...", flush=True)
+ results["breaker"] = await scenario_breaker()
+ finally:
+ for p in (gw_p, agent_p, mock_p):
+ stop(p)
+ results["env"] = {"date": date.today().isoformat(), "os": platform.platform(), "cpu": platform.processor(),
+ "cpu_count": os.cpu_count(), "python": platform.python_version(),
+ "node": subprocess.run(["node", "--version"], capture_output=True, text=True).stdout.strip()}
+ RESULTS.write_text(json.dumps(results, ensure_ascii=False, indent=1), encoding="utf-8")
+ write_report(results)
+
+
+def write_report(res: Dict) -> None:
+ env = res["env"]
+ L = ["# 压测报告", "",
+ f"- 运行日期:{env['date']};单机:{env['os']},{env['cpu_count']} 逻辑核;Python {env['python']},Node {env['node']}",
+ "- 压测客户端与服务在同一台机器上;LLM 为本地模拟服务(固定延迟),**不包含 DeepSeek 的真实延迟和限流**",
+ "- 链路:压测客户端 → Node 网关 → agent_service(单进程 uvicorn)→ 模拟 LLM",
+ "- 复现:`python eval/load_test.py`(原始数据 `eval/data/load_test_results.json`)", ""]
+
+ def table(rows, extra=()):
+ head = "| 并发 | 请求 | 成功 | 吞吐 (次/秒) | P50 | P95 | 最大 |" + "".join(f" {h} |" for h, _ in extra)
+ sep = "|---" * (7 + len(extra)) + "|"
+ out = [head, sep]
+ for r in rows:
+ out.append(f"| {r['concurrency']} | {r['requests']} | {r['ok']} | {r['throughput_rps']} | {r['p50_ms']} ms | "
+ f"{r['p95_ms']} ms | {r['max_ms']} ms |" + "".join(f" {fn(r)} |" for _, fn in extra))
+ return out
+
+ rt = res["retrieval"]
+ L += ["## 1. 检索接口(本地 CPU:embedding + BM25 + RRF,不重排)", "",
+ "**首次查询(全部是没查过的问题)**", ""] + table(rt["cold"]) + [
+ "", "**重复查询(命中检索缓存)**", ""] + table(rt["warm"]) + [
+ "", f"检索缓存累计:命中 {rt['cache']['hits']}、未命中 {rt['cache']['misses']}。", ""]
+
+ ch = res["chat"]
+ L += ["## 2. 聊天接口(模拟 LLM 每次 1 秒)", "",
+ f"agent_service 的 LLM 并发上限为 {ch['llm_concurrency_limit']};网关不限流。", ""] + table(
+ ch["rows"], extra=[("LLM 调用数", lambda r: r["llm_calls"]),
+ ("上游最大并发", lambda r: r["llm_max_in_flight"]),
+ ("路由", lambda r: ", ".join(f"{k} {v}" for k, v in r["routes"].items()))]) + [""]
+
+ ov = res["overload"]
+ s = ov["summary"]
+ L += ["## 3. 过载保护(同时 40 个聊天请求,模拟 LLM 2 秒,网关重请求并发上限 8)", "",
+ f"- 结果分布:{s['status']}",
+ f"- 被拒绝的请求 P95 返回时间:{ov['rejected_p95_ms']} ms(立即告知“当前使用人数较多”,而不是排队到超时)",
+ f"- 放行请求 P50 {s['p50_ms']} ms、P95 {s['p95_ms']} ms", ""]
+
+ rl = res["rate_limit"]
+ L += ["## 4. 限流(同一 IP 连续 15 个重请求,配额 10 次/分钟)", "",
+ f"- 结果分布:{rl['counts']}",
+ "- 被限流的响应带 `Retry-After`:" + ", ".join(str(r["retry_after"]) + "s" for r in rl["rows"] if r["retry_after"]), ""]
+
+ br = res["breaker"]
+ L += ["## 5. LLM 故障与熔断(模拟 LLM 全部返回 500,之后恢复)", "",
+ "| 请求 | 状态 | 错误码 | 耗时 | 本次打到上游的次数 | 熔断器状态(请求后) |", "|---|---|---|---|---|---|"]
+ for t in br["timeline"]:
+ L.append(f"| {t['i']} | {t['status']} | {t['code'] or '—'} | {t['ms']} ms | {t['upstream_calls']} | {t['breaker']} |")
+ L += ["", "## 说明", "",
+ "- 吞吐和延迟受本机 CPU 影响,换机器数值会变;这里关注的是**随并发变化的趋势**和**保护机制是否按设计生效**。",
+ "- 聊天吞吐的上限由 LLM 并发闸门决定(约 并发上限 ÷ 单次 LLM 耗时),真实环境下还受 DeepSeek 自身限流影响。",
+ "- 检索是 CPU 密集计算,在线程池中执行;单进程下并发提高后吞吐有限,扩容需要多进程 / 多实例。"]
+ REPORT.write_text("\n".join(L) + "\n", encoding="utf-8")
+ print(f"report -> {REPORT}")
+
+
+if __name__ == "__main__":
+ asyncio.run(main())
diff --git a/eval/load_test_v1.md b/eval/load_test_v1.md
new file mode 100644
index 0000000..eb9721a
--- /dev/null
+++ b/eval/load_test_v1.md
@@ -0,0 +1,70 @@
+# 压测报告
+
+- 运行日期:2026-10-13;单机:Windows-11-10.0.26200-SP0,16 逻辑核;Python 3.13.7,Node v22.18.0
+- 压测客户端与服务在同一台机器上;LLM 为本地模拟服务(固定延迟),**不包含 DeepSeek 的真实延迟和限流**
+- 链路:压测客户端 → Node 网关 → agent_service(单进程 uvicorn)→ 模拟 LLM
+- 复现:`python eval/load_test.py`(原始数据 `eval/data/load_test_results.json`)
+
+## 1. 检索接口(本地 CPU:embedding + BM25 + RRF,不重排)
+
+**首次查询(全部是没查过的问题)**
+
+| 并发 | 请求 | 成功 | 吞吐 (次/秒) | P50 | P95 | 最大 |
+|---|---|---|---|---|---|---|
+| 1 | 40 | 40 | 34.28 | 22 ms | 34 ms | 263 ms |
+| 4 | 40 | 40 | 68.74 | 50 ms | 99 ms | 138 ms |
+| 16 | 40 | 40 | 54.57 | 244 ms | 490 ms | 565 ms |
+
+**重复查询(命中检索缓存)**
+
+| 并发 | 请求 | 成功 | 吞吐 (次/秒) | P50 | P95 | 最大 |
+|---|---|---|---|---|---|---|
+| 1 | 80 | 80 | 114.35 | 9 ms | 11 ms | 13 ms |
+| 4 | 80 | 80 | 442.86 | 8 ms | 16 ms | 25 ms |
+| 16 | 80 | 80 | 285.01 | 44 ms | 155 ms | 206 ms |
+
+检索缓存累计:命中 240、未命中 120。
+
+## 2. 聊天接口(模拟 LLM 每次 1 秒)
+
+agent_service 的 LLM 并发上限为 8;网关不限流。
+
+| 并发 | 请求 | 成功 | 吞吐 (次/秒) | P50 | P95 | 最大 | LLM 调用数 | 上游最大并发 | 路由 |
+|---|---|---|---|---|---|---|---|---|---|
+| 1 | 12 | 12 | 0.95 | 1051 ms | 1086 ms | 1100 ms | 12 | 1 | chitchat 12 |
+| 8 | 24 | 24 | 6.52 | 1196 ms | 1323 ms | 1323 ms | 24 | 8 | chitchat 24 |
+| 16 | 48 | 48 | 7.19 | 2041 ms | 2519 ms | 2559 ms | 48 | 8 | chitchat 48 |
+| 32 | 96 | 96 | 7.39 | 4075 ms | 4635 ms | 4775 ms | 96 | 8 | chitchat 96 |
+
+## 3. 过载保护(同时 40 个聊天请求,模拟 LLM 2 秒,网关重请求并发上限 8)
+
+- 结果分布:{'200': 8, '503 SERVER_BUSY': 32}
+- 被拒绝的请求 P95 返回时间:173 ms(立即告知“当前使用人数较多”,而不是排队到超时)
+- 放行请求 P50 2366 ms、P95 2371 ms
+
+## 4. 限流(同一 IP 连续 15 个重请求,配额 10 次/分钟)
+
+- 结果分布:{'200': 10, '429 RATE_LIMITED': 5}
+- 被限流的响应带 `Retry-After`:6s, 6s, 6s, 6s, 6s
+
+## 5. LLM 故障与熔断(模拟 LLM 全部返回 500,之后恢复)
+
+| 请求 | 状态 | 错误码 | 耗时 | 本次打到上游的次数 | 熔断器状态(请求后) |
+|---|---|---|---|---|---|
+| 1 | 503 | UPSTREAM_LLM_UNAVAILABLE | 1556 ms | 3 | closed |
+| 2 | 503 | UPSTREAM_LLM_UNAVAILABLE | 1099 ms | 2 | open |
+| 3 | 503 | UPSTREAM_LLM_UNAVAILABLE | 1531 ms | 0 | open |
+| 4 | 503 | UPSTREAM_LLM_UNAVAILABLE | 1793 ms | 1 | open |
+| 5 | 503 | UPSTREAM_LLM_UNAVAILABLE | 1012 ms | 0 | open |
+| 6 | 503 | UPSTREAM_LLM_UNAVAILABLE | 1684 ms | 0 | half_open |
+| 7 | 503 | UPSTREAM_LLM_UNAVAILABLE | 1592 ms | 1 | open |
+| 8 | 503 | UPSTREAM_LLM_UNAVAILABLE | 993 ms | 0 | open |
+| 恢复后 1 | 200 | — | 114 ms | 1 | closed |
+| 恢复后 2 | 200 | — | 114 ms | 1 | closed |
+| 恢复后 3 | 200 | — | 110 ms | 1 | closed |
+
+## 说明
+
+- 吞吐和延迟受本机 CPU 影响,换机器数值会变;这里关注的是**随并发变化的趋势**和**保护机制是否按设计生效**。
+- 聊天吞吐的上限由 LLM 并发闸门决定(约 并发上限 ÷ 单次 LLM 耗时),真实环境下还受 DeepSeek 自身限流影响。
+- 检索是 CPU 密集计算,在线程池中执行;单进程下并发提高后吞吐有限,扩容需要多进程 / 多实例。
diff --git a/eval/mock_llm.py b/eval/mock_llm.py
new file mode 100644
index 0000000..06e0a57
--- /dev/null
+++ b/eval/mock_llm.py
@@ -0,0 +1,60 @@
+"""压测用的模拟 LLM:OpenAI 兼容 /chat/completions,固定延迟后返回一句话。
+
+压测要测的是“我们系统”的并发与保护能力,不应把 DeepSeek 的速度和费用算进来;
+延迟和故障模式可在运行中通过 POST /mode 切换(用于熔断测试)。
+
+python eval/mock_llm.py --port 8099 --delay 1.0
+"""
+import argparse
+import asyncio
+
+import uvicorn
+from starlette.applications import Starlette
+from starlette.requests import Request
+from starlette.responses import JSONResponse
+from starlette.routing import Route
+
+state = {"delay": 1.0, "fail": False, "calls": 0, "in_flight": 0, "max_in_flight": 0}
+
+
+async def completions(request: Request):
+ await request.body()
+ state["calls"] += 1
+ state["in_flight"] += 1
+ state["max_in_flight"] = max(state["max_in_flight"], state["in_flight"])
+ try:
+ await asyncio.sleep(state["delay"])
+ if state["fail"]:
+ return JSONResponse({"error": {"message": "mock upstream failure"}}, status_code=500)
+ return JSONResponse({
+ "choices": [{"message": {"role": "assistant", "content": "你好!想去哪里玩?可以告诉我目的地和天数。"}}],
+ "usage": {"prompt_tokens": 50, "completion_tokens": 20},
+ })
+ finally:
+ state["in_flight"] -= 1
+
+
+async def mode(request: Request):
+ body = await request.json()
+ for k in ("delay", "fail"):
+ if k in body:
+ state[k] = body[k]
+ if body.get("reset_stats"):
+ state.update(calls=0, max_in_flight=0)
+ return JSONResponse(state)
+
+
+async def stats(_request: Request):
+ return JSONResponse(state)
+
+
+app = Starlette(routes=[Route("/chat/completions", completions, methods=["POST"]),
+ Route("/mode", mode, methods=["POST"]), Route("/stats", stats)])
+
+if __name__ == "__main__":
+ ap = argparse.ArgumentParser()
+ ap.add_argument("--port", type=int, default=8099)
+ ap.add_argument("--delay", type=float, default=1.0)
+ args = ap.parse_args()
+ state["delay"] = args.delay
+ uvicorn.run(app, host="127.0.0.1", port=args.port, log_level="warning")
diff --git a/gateway/ops.js b/gateway/ops.js
new file mode 100644
index 0000000..f1c85de
--- /dev/null
+++ b/gateway/ops.js
@@ -0,0 +1,140 @@
+// 网关的运维组件:按 IP 的令牌桶限流、重请求并发闸门、进程内指标。
+// 单进程网关,状态放内存即可;多实例部署时限流需要换成 Redis 等共享存储。
+
+// ---------------- 令牌桶限流 ----------------
+// 每个 key(IP + 档位)一个桶:容量 = 每分钟配额,按时间匀速补充。允许短时突发,长期速率受限。
+export class RateLimiter {
+ constructor(perMinute, { now = () => Date.now() } = {}) {
+ this.capacity = perMinute;
+ this.refillPerMs = perMinute / 60000;
+ this.now = now;
+ this.buckets = new Map();
+ this.rejected = 0;
+ }
+
+ // 返回 { ok, retryAfterS }
+ take(key) {
+ if (this.capacity <= 0) return { ok: true, retryAfterS: 0 }; // 0 表示不限流
+ const t = this.now();
+ let b = this.buckets.get(key);
+ if (!b) {
+ b = { tokens: this.capacity, at: t };
+ this.buckets.set(key, b);
+ }
+ b.tokens = Math.min(this.capacity, b.tokens + (t - b.at) * this.refillPerMs);
+ b.at = t;
+ if (b.tokens >= 1) {
+ b.tokens -= 1;
+ return { ok: true, retryAfterS: 0 };
+ }
+ this.rejected += 1;
+ return { ok: false, retryAfterS: Math.ceil((1 - b.tokens) / this.refillPerMs / 1000) };
+ }
+
+ // 清理已经补满的桶,避免 IP 越来越多导致内存增长
+ sweep() {
+ const t = this.now();
+ for (const [key, b] of this.buckets) {
+ if (b.tokens + (t - b.at) * this.refillPerMs >= this.capacity) this.buckets.delete(key);
+ }
+ }
+}
+
+// ---------------- 并发闸门(过载保护) ----------------
+// 规划 / 聊天一次要几十秒、多次 LLM 调用。超过上限直接返回“繁忙”,而不是让所有请求一起变慢直到超时。
+export class ConcurrencyGate {
+ constructor(limit) {
+ this.limit = limit;
+ this.inFlight = 0;
+ this.rejected = 0;
+ }
+
+ tryEnter() {
+ if (this.limit > 0 && this.inFlight >= this.limit) {
+ this.rejected += 1;
+ return null;
+ }
+ this.inFlight += 1;
+ let released = false;
+ return () => { // 幂等释放:finish 和 close 都可能触发
+ if (!released) {
+ released = true;
+ this.inFlight -= 1;
+ }
+ };
+ }
+}
+
+// ---------------- 指标 ----------------
+const WINDOW = 2000;
+
+export function percentile(values, p) {
+ if (!values.length) return null;
+ const s = [...values].sort((a, b) => a - b);
+ const k = Math.min(s.length - 1, Math.max(0, Math.round((p / 100) * (s.length - 1))));
+ return s[k];
+}
+
+export class GatewayMetrics {
+ constructor() {
+ this.startedAt = Date.now();
+ this.inFlight = 0;
+ this.routes = new Map(); // "METHOD route" -> { count, errors4xx, errors5xx, latencies[] }
+ this.errorCodes = new Map();
+ }
+
+ started() {
+ this.inFlight += 1;
+ }
+
+ finished(method, route, status, latencyMs, errorCode) {
+ this.inFlight -= 1;
+ const key = `${method} ${route}`;
+ let r = this.routes.get(key);
+ if (!r) {
+ r = { count: 0, errors4xx: 0, errors5xx: 0, latencies: [] };
+ this.routes.set(key, r);
+ }
+ r.count += 1;
+ if (status >= 500) r.errors5xx += 1;
+ else if (status >= 400) r.errors4xx += 1;
+ r.latencies.push(latencyMs);
+ if (r.latencies.length > WINDOW) r.latencies.shift();
+ if (errorCode) this.errorCodes.set(errorCode, (this.errorCodes.get(errorCode) || 0) + 1);
+ }
+
+ snapshot(extra = {}) {
+ const routes = {};
+ let total = 0;
+ let errors5xx = 0;
+ for (const [key, r] of [...this.routes].sort()) {
+ total += r.count;
+ errors5xx += r.errors5xx;
+ routes[key] = {
+ count: r.count,
+ errors_4xx: r.errors4xx,
+ errors_5xx: r.errors5xx,
+ latency_ms: {
+ p50: percentile(r.latencies, 50),
+ p95: percentile(r.latencies, 95),
+ p99: percentile(r.latencies, 99),
+ max: r.latencies.length ? Math.max(...r.latencies) : null
+ }
+ };
+ }
+ return {
+ uptime_s: Math.round((Date.now() - this.startedAt) / 1000),
+ in_flight: this.inFlight,
+ requests_total: total,
+ errors_5xx_total: errors5xx,
+ routes,
+ error_codes: Object.fromEntries([...this.errorCodes].sort((a, b) => b[1] - a[1])),
+ ...extra
+ };
+ }
+}
+
+// 只认本机回环地址(含 IPv4 映射到 IPv6 的形式)
+export function isLoopback(ip = '') {
+ return ip === '127.0.0.1' || ip === '::1' || ip === '::ffff:127.0.0.1';
+}
diff --git a/gateway/ops.test.js b/gateway/ops.test.js
new file mode 100644
index 0000000..9a806d5
--- /dev/null
+++ b/gateway/ops.test.js
@@ -0,0 +1,63 @@
+// 网关运维组件的单元测试:npm test
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { ConcurrencyGate, GatewayMetrics, RateLimiter, isLoopback, percentile } from './ops.js';
+
+test('令牌桶:允许突发到容量,之后按速率补充,并给出 Retry-After', () => {
+ let now = 0;
+ const rl = new RateLimiter(10, { now: () => now });
+ for (let i = 0; i < 10; i++) assert.equal(rl.take('ip').ok, true);
+ const denied = rl.take('ip');
+ assert.equal(denied.ok, false);
+ assert.equal(denied.retryAfterS, 6); // 每分钟 10 个 → 6 秒补 1 个
+ assert.equal(rl.take('other-ip').ok, true); // 不同客户端互不影响
+ now += 6000;
+ assert.equal(rl.take('ip').ok, true);
+ assert.equal(rl.rejected, 1);
+});
+
+test('令牌桶:配额为 0 表示不限流;sweep 清理已补满的桶', () => {
+ assert.equal(new RateLimiter(0).take('x').ok, true);
+ let now = 0;
+ const rl = new RateLimiter(60, { now: () => now });
+ rl.take('a');
+ now += 60000;
+ rl.sweep();
+ assert.equal(rl.buckets.size, 0);
+});
+
+test('并发闸门:超过上限拒绝,释放可重复调用但只生效一次', () => {
+ const gate = new ConcurrencyGate(2);
+ const r1 = gate.tryEnter();
+ const r2 = gate.tryEnter();
+ assert.equal(gate.tryEnter(), null);
+ assert.equal(gate.rejected, 1);
+ r1();
+ r1(); // finish 和 close 都会触发释放
+ assert.equal(gate.inFlight, 1);
+ assert.ok(gate.tryEnter());
+ r2();
+});
+
+test('指标:按路由统计次数、错误与分位数', () => {
+ const m = new GatewayMetrics();
+ for (const ms of [10, 20, 30, 40]) {
+ m.started();
+ m.finished('POST', '/api/chat', 200, ms);
+ }
+ m.started();
+ m.finished('POST', '/api/chat', 503, 1, 'SERVER_BUSY');
+ const s = m.snapshot({ extra: 1 });
+ assert.equal(s.requests_total, 5);
+ assert.equal(s.errors_5xx_total, 1);
+ assert.equal(s.in_flight, 0);
+ assert.equal(s.routes['POST /api/chat'].latency_ms.max, 40);
+ assert.deepEqual(s.error_codes, { SERVER_BUSY: 1 });
+ assert.equal(s.extra, 1);
+ assert.equal(percentile([], 50), null);
+});
+
+test('isLoopback 只认本机地址', () => {
+ assert.ok(isLoopback('127.0.0.1') && isLoopback('::1') && isLoopback('::ffff:127.0.0.1'));
+ assert.ok(!isLoopback('172.18.0.1') && !isLoopback('192.168.1.5'));
+});
diff --git a/output-map.html b/output-map.html
index 0978877..3d61767 100644
--- a/output-map.html
+++ b/output-map.html
@@ -295,7 +295,29 @@
}
-
+
@@ -343,7 +365,7 @@
操作提示