TraceMind 面向产品售后客服场景，构建一套接近真实客服系统的可信 Agent：
- 面向用户：用 ChatGPT 式低认知聊天界面解决产品使用、故障排查、操作咨询和售后判断问题。
- 面向团队：用 Trace Console 观察 Agent 为什么这么回答、检索命中了什么、什么时候澄清、什么时候 fallback 或转人工。
项目当前支持文本问题、图片输入、产品手册知识库、多轮澄清、路由前知识范围收缩、混合检索、轻量 rerank、证据返回和离线回归评测。
TraceMind
├── User Chat
│ ├── 聊天
│ ├── 历史记录
│ └── 设置
└── Trace Console
├── Dashboard
├── Session
├── 检索分析
├── 质量分析
└── 系统监控
用户端只保留客服体验，不展示 Session ID、RAG 状态、模型名称、Token、Raw JSON 等内部字段。
当前能力：
- 多轮客服对话
- 模糊问题反问澄清
- 图片上传
- 快捷入口：故障诊断、产品咨询、售后支持
- 回答底部折叠展示“回答依据”
- 澄清候选按钮区分“真实选项”和“待用户补槽信息”
内部管理端用于研发、产品和答辩展示，重点解释 Agent 的运行链路。
当前能力：
- Session 状态观察
- Router / Query Rewrite / Retrieval / Rerank / Answer 链路展示
- 命中 source、chunk 数量、top 片段、fallback 状态
- Raw JSON 调试
- 离线评测指标展示口径
- Backend：FastAPI
- Frontend：React + Vite
- Vector DB：Milvus
- Retrieval：BM25 + 向量检索 + 轻量规则 rerank
- LLM API：OpenAI-compatible 接口，推荐 DashScope / Qwen，也兼容 DeepSeek 等国内模型
- Agent 编排：以自研 pipeline 和多轮澄清状态机为主
- LangChain：用于模型调用、Prompt、OutputParser、Milvus Retriever、Text Splitter 等链路
- LangGraph：当前作为依赖引入，并在通用问答链路中使用 checkpoint 相关能力；主流程暂未使用完整 StateGraph 编排
TraceMind/
├── README.md
├── interface.py # FastAPI 启动入口
├── pipeline.py # 兼容导出入口
├── milvus-docker-compose.yml
├── pyproject.toml
├── tracemind/
│ ├── api.py # API 与 Playground 静态入口
│ ├── pipeline.py # 在线主链路
│ ├── clarifier.py # 首轮澄清判断
│ ├── conversation_state_machine.py # 分阶段澄清状态机
│ ├── clarification_resolver.py # 多轮补槽解析
│ ├── followup_classifier.py # 追问/补充/切换分类
│ ├── session_store.py # 会话状态
│ ├── query_classification.py # 查询分类与路由
│ ├── query_rewriter.py # 增强查询改写
│ ├── routing_scope.py # 路由前知识范围收缩
│ ├── retriever.py # 混合检索与可观测输出
│ ├── answer_product_query.py # 产品问答
│ ├── answer_general_query.py # 通用问答
│ ├── model_factory.py # 模型工厂
│ └── utils.py
├── frontend/
│ ├── src/
│ ├── package.json
│ └── vite.config.js
├── scripts/
│ ├── build_kb.py # 推荐建库脚本
│ ├── evaluate_tracemind.py # 离线评测
│ └── generate_multiturn_benchmark.py # 合成多轮评测集生成
├── tests/
├── docs/
├── eval/
│ ├── multiturn_benchmark_50.csv
│ └── multiturn_benchmark_200.csv
├── processed_data/
├── catalog/
├── data/
└── assets/
推荐使用 uv：
uv sync -i https://pypi.tuna.tsinghua.edu.cn/simple如果已经有 .venv，也可以：
.\.venv\Scripts\activate
pip install -e .复制模板：
Copy-Item .env.example .env至少需要配置：
CHAT_BASE_URL=
CHAT_API_KEY=
CHAT_MODEL=
EMBEDDING_BASE_URL=
EMBEDDING_API_KEY=
EMBEDDING_MODEL=
MILVUS_HOST=127.0.0.1
MILVUS_PORT=19530
MILVUS_DB_NAME=default
USE_CONTEXTUAL_AUGMENTATION=1
USE_QUERY_CLS=1推荐 DashScope / Qwen 示例：
CHAT_BASE_URL="https://dashscope.aliyuncs.com/compatible-mode/v1"
CHAT_API_KEY="你的 DashScope API Key"
CHAT_MODEL="qwen-plus"
EMBEDDING_BASE_URL="https://dashscope.aliyuncs.com/compatible-mode/v1"
EMBEDDING_API_KEY="你的 DashScope API Key"
EMBEDDING_MODEL="text-embedding-v3"DeepSeek 可作为文本模型兼容选项，但它不具备多模态视觉能力；如果要测试图片理解，建议换成支持视觉输入的模型服务。
需要本机安装 Docker Desktop。
docker compose -f milvus-docker-compose.yml up -d
docker ps正常情况下会看到：
milvus-standalonemilvus-etcdmilvus-minio
当前推荐直接使用仓库中已经整理好的 processed_data/ 建库：
.\.venv\Scripts\python -m scripts.build_kb建库脚本会：
- 读取
processed_data/ - 按 Markdown 标题结构切分
- 写入 Milvus
- 输出手册数量、source 覆盖、chunk 数量等统计信息
如果只想调试某一本手册：
$env:MANUAL_FILTER="吹风机"
.\.venv\Scripts\python -m scripts.build_kb
Remove-Item Env:MANUAL_FILTER当前知识库覆盖口径：
- 预期手册数：40
- 已入库 source 数：40
- 缺失 source：0
- 额外 source：0
.\.venv\Scripts\python interface.py默认访问：
- API 文档：http://127.0.0.1:8000/scalar
- Playground 静态页：http://127.0.0.1:8000/playground
也可以指定端口启动：
@'
import uvicorn
uvicorn.run("tracemind.api:app", host="0.0.0.0", port=8765, env_file=".env", reload=False)
'@ | .\.venv\Scripts\python -cd frontend
npm install
npm run dev -- --host 127.0.0.1 --port 5173访问：
http://127.0.0.1:5173/playground-static/
前端包含两个视角：
聊天：用户端客服体验观测：Trace Console 内部调试和分析
可以先问：
使用吹风机时，人员需要佩戴哪些防护装备？
或测试多轮澄清：
这个功能不好用
期望现象：
- 模糊问题会先触发澄清
- 如果点击“补充产品名称”等空槽位按钮，前端只会提示输入具体信息，不会把按钮文案当成用户回答
- 补充产品和任务后，系统会收敛到对应手册
- Trace Console 可查看 route source、检索片段、fallback 状态和 Raw JSON
当前仓库提供合成多轮评测集，用于回归测试和模块行为验证：
eval/multiturn_benchmark_50.csveval/multiturn_benchmark_200.csv
生成脚本：
.\.venv\Scripts\python -m scripts.generate_multiturn_benchmark --size 200 --output-file eval/multiturn_benchmark_200.csv评测命令：
.\.venv\Scripts\python -m scripts.evaluate_tracemind `
--question-file eval/multiturn_benchmark_200.csv `
--output-dir eval/multiturn_benchmark_200_run `
--top-k 19最近一次 200 条合成多轮评测 run4：
- 系统异常：0
- response type 准确率：100%
- source top-1 准确率：97.73%
- source top-k recall：98.3%
- topic switch 准确率：95.5%
- required keyword 全匹配率：98.3%
- fallback 触发率：2.5%
分类结果：
single_followup：回答率 100%，澄清解决率 100%staged：回答率 100%，澄清解决率 100%correction：回答率 100%，澄清解决率 100%topic_switch：回答率 100%，澄清解决率 100%handoff：handoff 率 100%
-
前后台产品拆分
User Chat 服务用户低认知交互，Trace Console 服务团队可观测和优化。
-
多轮澄清闭环
对模糊问题不急于检索，先收集产品、任务类型、故障现象、页面/功能等槽位。
-
路由前范围收缩
在正式检索前先根据目录级召回、产品候选和上下文 source hint 缩小知识范围。
-
混合检索与轻量 rerank
基于 Milvus 同时使用 BM25 和向量检索，并根据来源、结构化上下文、关键词覆盖做轻量重排。
-
可观测检索
返回命中 source、chunk 数量、top 片段、fallback 状态，便于复盘和调优。
-
降级与转人工
多轮无效补充后不继续猜测，进入 handoff 状态。
- 多模态链路目前重点支持图片输入和图片返回，视觉理解效果取决于所配置模型能力。
- 合成评测集不能替代真实客服数据，需要后续补充人工标注真实样例。
- LangGraph 暂未承担完整 Agent 工作流图编排，主流程仍以自研 pipeline 和状态机为主。
- detailed results 的 JSON 可解析性仍需继续增强，便于失败样例自动分析。