一个
docker compose up就能跑起来的智能客服系统参考实现。 它把六个工程难题做成可运行、可消融、可复现的闭环: 三路意图融合 · MCP 工具调用 · 三级记忆 · 多 Agent 编排 · Monitor 闭环 · LLM-as-Judge 评测。
零密钥可运行:默认 EM_LLM__PROVIDER=fake,不填任何 API Key、不联外网,
也能跑通「感知 → 记忆 → 编排 → 工具 → 生成 → 监控 → 评测」全链路并产出评测报告。
编排层用 LangGraph 1.x 实现,并且保留了一份自研实现,两者可通过一个环境变量切换 —— 这不是为了炫技,而是为了拿到「同一条 Pipeline 上两种编排实现的对照数据」(见 实测结果)。
git clone https://github.com/N10086/EchoMind.git && cd EchoMind
cp .env.example .env # 零密钥模式:一个字都不用改
docker compose up -d --build # 起 bootstrap / api / worker / postgres / redis
curl localhost:8000/health第一次启动会自动把数据灌好:一次性服务 bootstrap(em bootstrap)在 api 之前跑完
「迁移 → 播种 data/seed/*.jsonl → 建知识库索引 data/kb/*.md」,api 通过
depends_on: condition: service_completed_successfully 等它退出。
因此 docker compose up 之后直接就能问真实订单:
curl -s localhost:8000/v1/chat -H 'Content-Type: application/json' \
-d '{"user_id":"u_10086","message":"我的订单 SO20250101001 现在到哪了?"}'流式(SSE)走同一个入口,事件序是契约的一部分:
curl -N localhost:8000/v1/chat/stream -H 'Content-Type: application/json' \
-d '{"user_id":"u_10086","message":"退货政策是什么?"}'
# meta → memory → intent → routing → tool* → token* → citation* → debug? → done引导是幂等的:重启不会重复播种或重复建索引(Seeder 按业务主键 upsert,
索引指纹一致就跳过)。想看引导做了什么:docker compose logs bootstrap;
想看库里的真实状态:docker compose exec api em doctor。
手工维护数据:
docker compose exec api em seed # 幂等灌种子数据
docker compose exec api em seed --only orders # 只灌子集
docker compose exec api em seed --reset # 先清空再灌(prod 环境拒绝执行)
docker compose exec api em reindex # 增量建索引
docker compose exec api em reindex --rebuild # 清空重建(换嵌入后端后必须)
docker compose exec api em bootstrap # 迁移 + 播种 + 建索引想要一个空库(不要演示数据):.env 里设 EM_APP__AUTO_BOOTSTRAP=false。
auto 会降级并告警)。
Hash 嵌入的召回质量明显弱于语义模型,判断检索效果前请先知道这一点。
要真实语义向量:DOCKER_BUILDKIT=0 docker compose build --build-arg INSTALL_ONNX=1,
再把模型放到 /models,然后 em reindex --rebuild。
注意:Dockerfile 刻意不含 build-essential,因此它是否可构建取决于「所有依赖都有
manylinux wheel 或为纯 Python」。这一点做过依赖清单核查(结论是通过),但
镜像构建本身尚未实测 —— 见 诚实记录。
跑评测:
docker compose exec api em eval intent # 意图识别三路消融(174 条)
docker compose exec api em eval retrieval # 检索消融(Recall@k / MRR)
docker compose exec api em eval golden # 端到端四维打分(49 条金标集)报告写到 reports/(该目录被 .gitignore 排除,因此仓库里没有现成报告,需自己跑出来)。
em demo / em bench 尚未实现 —— 不提供说谎的命令。
接入真实模型(可选):
# .env
EM_LLM__PROVIDER=openai_compat
EM_LLM__API_KEY=sk-xxxxxxxx
EM_LLM__MODEL=deepseek-chat
EM_LLM__JUDGE_MODEL=deepseek-reasoner # Judge 建议与主模型不同,避免自我偏好START → load_memory → detect_intent ─┬─(提前退出:寒暄/OOS)→ early_exit ─┐
└─(需执行)→ route → execute_agent ─┤
▼
write_memory → persist_trace → END
detect_intent 之后是一条纯函数条件边(同输入同输出、不改 state —— 带副作用的判定
在图重放时会执行第二次,那种 bug 只在开启 checkpointer 之后才暴露)。
prepare(工具轮次 / 检索 / 拼素材 —— 全部可能失败的阶段)
└─→ generate | emit_ready → 最终生成
这条拆分的意义不只是「能流式」:它让 ADR-014 的时序要求从「纪律」升级为「拓扑」 ——
「所有可能失败的阶段必须在首个 token 之前完成」不再依赖实现者的自觉,而是由图的边序保证,
并且可以被单测断言。生成阶段只允许「流中断 → 发 error 事件 + 补记 status=error 的 trace」,
因为文本不可回滚。
EM_ORCHESTRATOR=langgraph # 默认
EM_ORCHESTRATOR=builtin # 自研实现,一行未删,用于对照实验与回滚两者共用同一套 Pipeline 阶段实现,因此 REST / SSE 契约不变:docs/04 的响应字段集合、
SSE 事件名序列、route_decision 键集合、intent_detail 键集合在两个引擎下完全一致
(实测见下)。
EM_ORCHESTRATOR 只能是顶层标量(EM_ORCHESTRATOR=langgraph),这是刻意的:
pydantic-settings 对模型字段要求 JSON,而裸取值才是运维与验收脚本的口径。
需要子键时走一个只做映射的自定义 env 源(EM_ORCHESTRATOR__STREAM_VALIDATION →
顶层标量 orchestrator_stream_validation),而不是把主键改名 —— 改名会让
「一条配置回滚」这条承诺在回滚当天失效。
EM_ORCHESTRATOR__STREAM_VALIDATION=incremental # 默认:真流式
EM_ORCHESTRATOR__STREAM_VALIDATION=buffered # 改造前行为:整段生成后按 3 字符切片incremental 下 prepare 一完成就吐首个 token;代价是实体校验不能再拦截 ——
因为「答案里是否原样出现了关键实体」需要完整答案。处置不是把校验删掉,而是把它变成可见的:
route_decision.answer_checks = {checked, missing, must_keep_ok, advisory},
advisory=false 表示这次检查仍然拦截(buffered,与改造前一致),
advisory=true 表示只记录不拦截(incremental)。非流式接口始终走完整强校验。
langgraph 只允许出现在 src/echomind/orchestration/。这不是一句口号:
tests/unit/test_framework_containment.py 用 AST 扫描全部 src/(不是 grep —— 本仓库文档里
到处都是 "langgraph" 字样),断言 orchestration/ 之外没有对它的 import,
并带一棵临时目录树做负向对照(否则一个永远绿的测试比没有测试更糟)。
用 AST 还顺带覆盖了 TYPE_CHECKING 块与函数体内的延迟 import。
| 特性 | 机制核心 | 代码位置 | 设计文档 |
|---|---|---|---|
| 端到端意图识别 | 规则 / 向量 / LLM 三路 → 校准 → 加权投票 → 仲裁澄清 | src/echomind/intent/ |
05 |
| MCP 工具调用框架 | 查询改写 → 混合召回 → RRF → 覆盖率检查 → LLM 重排 | src/echomind/mcp/ rag/ |
07 |
| 多轮对话记忆管理 | L1 工作 / L2 摘要 / L3 长期 + 水位触发的异步压缩 | src/echomind/memory/ |
06 |
| 多 Agent 路由编排 | 意图路由 + 性能路由(utility + Thompson)+ 熔断 + 降级链 | src/echomind/agents/ orchestration/ |
08 |
| Monitor 闭环监控 | 全链路埋点 → 滑窗聚合 → 带安全阀的权重调优 → 版本化回滚 | src/echomind/monitor/ |
09 |
| 端到端评测 | LLM-as-Judge 四维打分 + 置信区间 + 基线 diff + 回归门禁 | src/echomind/eval/ |
10 |
一、零密钥可运行。 fake Provider 不是测试桩,而是一等公民。代价是每次 LLM 调用
都必须有结构化契约(Pydantic),收益是真实模型的输出解析从「祈祷式正则」升级为
「校验 + 修复重试」。
二、全链路可归因。 每个请求一个 trace_id:三路原始分、校准分、融合权重版本、
路由候选与采样值、降级原因、每次工具调用的入参与耗时、记忆水位——全部落库。
GET /v1/traces/{trace_id} 是排障与演示的主要入口。
三、闭环必须带安全阀。 任何在线自调都必须有刹车:最小样本量、单步幅度上限、 参数上下界、EMA 平滑、影子模式、版本可回滚,总开关默认关闭。
L6 评测层 golden_set → runner ──▶ judge(四维) → report → 回归门禁
▲ 复用线上同一条 Pipeline(只注入 user_input / LLM Provider)
L5 观测层 tracer → windows(滑窗) → tuner(安全阀) → weight_store(版本化 + 回滚)
L4 编排层 orchestration(main graph) → intent_router → perf_router(utility + Thompson)
→ execute_agent(agent subgraph) → fallback_chain
L3 能力层 intent(三路融合) │ memory(L1/L2/L3) │ mcp + rag(改写→召回→RRF→重排)
L2 工具层 kb_server / order_server / ticket_server (MCP 协议)
L1 基建层 llm(fake | openai_compat | routing) │ PostgreSQL 16 + pgvector │ Redis 7
依赖方向是明确约定(api → orchestration → agents → {intent, memory, mcp → rag} → llm → common;
monitor 可被 api/agents 调用但绝不反向 import agents;eval 只读不写线上行为)。
诚实说明:仓库里没有 CI、也没有 import-linter 配置,因此除「框架隔离」那一条
(有单测强制)之外,其余依赖方向目前是文档约定而非机器强制。这是一处已知落差,
记在 docs/12 §8.4。
完整时序图见 docs/01-architecture.md。
以下数字都是在本仓库默认配置(EM_LLM__PROVIDER=fake)下实测得到的。
换真实模型结论会变,因此不要把它们当作「回答质量」的证据 —— 它们证明的是机制成立与
行为一致。复现命令见下。
EM_ORCHESTRATOR=langgraph .venv/Scripts/python.exe scripts/dev/verify_all.py --full
EM_ORCHESTRATOR=builtin .venv/Scripts/python.exe scripts/dev/verify_all.py --fullPASS 单元测试(内存实现,不需 Redis/PG)
PASS 集成测试(真实依赖:探针 + SSE 时序契约)
PASS M2/G3 真依赖验收:30 轮关键实体保留率
PASS M4/G4 真依赖验收:注入 Agent 故障与降级归因
PASS M5/G5 真依赖验收:调优闭环与六道安全阀
PASS API 路由真依赖验收
PASS 评测:M1 三路消融(分类 F1 / 端到端 F1)
PASS 评测:M3 检索消融(Recall@k / MRR)
PASS 评测:M6 端到端四维打分(LLM-as-Judge)
整体结果:全部通过
pytest tests/unit tests/integration = 306 passed(0 failed / 0 skipped)。
在同一套评测集上、每次运行前清掉全库共享的自适应状态、交替运行两个引擎:
| 评测集 | 结果 |
|---|---|
| 金标集 49 条 × 3 轮配对 | 四维 overall 2.6803 vs 2.6820(差 +0.0017);意图准确率、工具调用数逐次相同 |
| 意图集 174 条 × 三路消融 7 个变体 | 7 个变体的整个 metrics 字典逐字段相同;fusion macro-F1 = 0.549 |
结论:重写没有改变任何可测量的评测结果。 唯一差异是 relevance 上 1 个用例的 1 分。
可重跑入口:scripts/dev/verify_engine_parity.py。
| 指标 | incremental |
buffered |
差异 |
|---|---|---|---|
| TTFT 均值 | 64 ms(n=6) | 164 ms(n=6) | −60.8% |
| TTFT 中位数 | 56 ms | 158 ms | −64.2% |
| 首 token 之后的耗时 | 210 ms | 0 ms | 拆分拿掉的正是这一段 |
测法必须说清:默认 Fake Provider 的 stream() 是「先整段算好再切块」,生成耗时≈0 ms ——
那种配置下两种取值的 TTFT 本来就测不出差别。因此验收脚本注入每块 8 ms 的确定性生成耗时:
complete 付「块数 × 8ms」、stream 每块付 8ms,总耗时相同,只隔离
「这段耗时发生在首个 token 之前还是之后」。不注入时脚本会明确写出「差异在噪声量级,不作为结论」。
框架自身的运行时开销是另一件事,同进程交替发同一请求(n=12)测得
ttft_ms 配对差 +6 ms p50(图 compile() 首次 10.2 ms、缓存后 0.001 ms)。
这个项目把「哪里没做到」当作交付的一部分。完整清单在 docs/12-testing-and-roadmap.md,以下是最需要先知道的几条。
未实测 / 无法在此环境验证
- Docker 镜像构建从未实测。镜像是否可构建取决于依赖是否有 wheel(已核查:通过), 但构建期网络与代理风险仍然成立。这是当前最大的未验证项。
- 所有数字都来自 Fake Provider。仓库里没有真实模型跑出来的效果数据。
- 金标集的分辨率不够:不清状态时同一引擎连跑三次,意图准确率会在 0.6531 / 0.6939 / 0.7551
之间跳。所以上面的「差 0」应读作**「小于这把尺子的分辨率」**,而真正可当硬证据的是
确定性的意图消融。金标集的判分器是确定性启发式,
docs/10已注明它 「只证明机制成立,不证明回答质量」。 mypy在本机完全跑不起来(numpy stub 用了 3.12 语法,与python_version=3.11错配); ruff 有若干既有 finding。
未达标 / 未完成
- G1 未达标:意图融合的 macro-F1 = 0.549,目标 0.85。差距如实记录,未通过调整口径掩盖。
- G2 未判定:检索消融报告未入库(
reports/被 gitignore 排除,gate._check_g2找不到证据)。 - G6 fail:四维报告齐备但没有基线 diff。
- 规划-调用-观察循环(
tool_loop)不存在:工具选择目前由各 Agent 的提示词与代码分支驱动, 不是 function calling;mcp/registry.py/mcp/tool_loop.py/mcp/client.py不存在。 - checkpointer 未接:
interrupt()与「写回后恢复」都未实现。ADR-018 记了一处必须先知道的 约束:无 checkpointer 时不要传durability("sync"会直接抛AttributeError)。 worker的保留期清理仍是占位:traces会无限增长。em demo/em bench不存在;无 CI(见上)。
已知缺陷(已定位,未修)
must_keep没有轮次作用域:ContextBundle.must_keep是整个会话生命周期内抽取到的 全部事实,却被当作每一轮回答的硬闸门 —— 于是多轮对话里第 2 轮起,无关实体会被 要求出现在无关回答里(实测在复用会话的验收流量上命中率 53.4%)。 流式路径已改为「只记录不拦截」,根因未修,三步修法记在 docs/12 §8.1 缺口 17。traces.ticket_no/rewrite_rounds/retrieved_docs在响应里取不到值(OrchestrationResult未透传);EM_RAG__HYDE_ENABLED等多个配置键无消费者(清单见 docs/12 §8.2)。- P50 预算表无实测数据;
uv.lock未入库。
这一节留在 README 里,是因为它比功能清单更能说明工程判断力 —— 这三次没有一次是算错, 全是测错了东西:
- 延迟
+91.1%里含一处 +38 ms 的测点差异:图的write_memory排在persist_trace之前,于是图路径的latency_ms把一次记忆写回算了进去,而自研路径没有。 而latency_ms是p95_latency_ms与性能路由 β 项的输入 —— 这会把「两个引擎测的不是 同一件事」读成「框架更慢」。修法是让两条路径在答案产出那一刻打点。 - TTFT
+14.6%的取数方式错了:原实现按「查询时刻最后 5 条有ttft_ms的行」取数, 而两个变体的运行重叠了其中 4 条 —— 两侧有效样本各 1 条且互相污染。 - 一次假的「LangGraph 差 0.12」:不清共享自适应状态时,金标集上看着差 0.12。
追下去,差异全部来自 2 个该走
order_agent的用例,在 langgraph 那一次运行里 一个工具都没调用就降级到模板;而复跑 3 次,该失败只在 3 次 langgraph 的第 1 次出现、 3 次 builtin 一次都没出现,且两个用例同时翻转 —— 这是熔断器被并发运行推开的形状 (em:cb:*按 Agent 名全库共享,不随会话隔离)。清掉后差值降到 +0.0017。
纪律由此固定下来:对照必须在每次运行前清掉全库共享的自适应状态,并报出清状态的动作、 每侧的运行次数、以及逐用例差异 —— 只报一个百分比,读者无法判断它是实现差异还是状态残留。
uv venv .venv --python 3.11
uv pip install -e ".[dev]"
cp .env.example .env
# 本机直跑需要把服务名换成 localhost,并注意**宿主端口不是默认值**:
# EM_DB__DSN=postgresql+asyncpg://echomind:echomind@localhost:55432/echomind
# EM_REDIS__URL=redis://localhost:56379/0
# (55432 / 56379 是为了不与开发机上已有的 PostgreSQL / Redis 抢端口;
# 可用 POSTGRES_PORT / REDIS_PORT 环境变量覆盖。)
em doctor # 体检:配置校验 + DB/Redis/Provider 连通性
em serve # 启动 API
pytest # 跑测试(集成测试在依赖不可用时自动 skip)某些受限环境里 pip install 会在「下载完成 → 回读解包」这一步失败。仓库自带一个
零依赖的替代安装器:
python scripts/dev/pip_lite.py install -r requirements.txt -t .pylibs
python scripts/dev/pip_lite.py download --wheels-dir ./wheels -r requirements.txt
python scripts/dev/pip_lite.py install --offline --wheels-dir ./wheels -r requirements.txtdocs/ 设计文档(00~12)+ adr/ 架构决策记录
src/echomind/
api/ HTTP 契约、鉴权、SSE、错误映射
orchestration/ ★ LangGraph 主图 + Agent 子图 + 两种实现(框架只允许出现在这里)
pipeline.py ★ 唯一入口:api 与 eval 都只调它,保证「评测 = 线上」
intent/ 三路意图识别与融合
memory/ 三级记忆与压缩调度
rag/ 切分、嵌入、混合召回、RRF、重排
mcp/ MCP 协议通信、工具注册、查询改写
agents/ Agent 实现、双路由、熔断、降级链
monitor/ 埋点、指标、调优闭环、权重版本
eval/ 评测集、Judge、报告、门禁
llm/ Provider 抽象(fake / openai_compat / routing)
storage/ PG 与 Redis 连接、ORM 模型、迁移
common/ 日志、错误、重试、熔断、ID、AC 自动机、文本
data/ 意图体系、意图示例、知识库、种子数据、评测集
docker/ Dockerfile 与 compose
scripts/ 验收脚本(verify_all.py 等)、开发工具
tests/ unit / integration / e2e
| 文档 | 内容 |
|---|---|
| 00 概述 | 目标、非目标、指标口径、术语表 |
| 01 架构总览 | 分层、请求时序、失败语义、性能预算 |
| 02 技术选型 | 选型理由与 ADR 摘要 |
| 03 数据模型 | 全部表结构、Redis key、JSON schema |
| 04 API 契约 | 接口、SSE 事件序、配置全集与校验规则 |
| 05~10 | 六大模块深化 |
| 11 部署运维 | 镜像、compose、配置、排障 |
| 12 测试策略与路线图 | 测试清单、缺口清单、诚实记录 |
| adr/ | 架构决策记录(含 ADR-018 引入 LangGraph、ADR-017 流式偏离已解决) |
MIT,见 LICENSE。