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 服务)

+
+ +
+
+

LLM 调用

+
+
+
+

工具调用

+
+
+
+ +
+
+

错误码

+
+
+
+

缓存与保护

+
+
+
+
+ + + + 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 @@

操作提示