gqt
4.5 KiB
4.5 KiB
KBQA MVP 真实链路验收报告
- 验收时间：2026-07-13（Asia/Shanghai）
- 分支：
feature/kbqa-mvp - 模型：
qwen3.5-flash、text-embedding-v4（1024 维） - 数据库：SQLite + Milvus Lite
- 运行约束：单 Uvicorn worker
版本
- Python 3.12.12
- LangChain 1.3.13（仅使用 1.x API）
- FastAPI 0.139.0
- SQLAlchemy 2.0.51
- PyMilvus 2.6.16
- Node.js 24.17.0 / npm 11.13.0
自动验证
普通测试未调用 Chat/Embedding：
ruff format --check: 48 files already formatted
ruff check: All checks passed
pytest unit + integration: 5 passed
ESLint: passed
Vitest: 1 file / 3 tests passed（含任意 UTF-8 网络分片的增量 SSE）
Vite production build: passed
显式开启的真实模型黑盒测试：
KBQA_RUN_LIVE_TESTS=1 uv run pytest tests/live/test_live_pipeline.py -v -s
1 passed in 69.77s
黑盒测试使用隔离的临时 SQLite、Milvus Lite 和原始文件目录，完成以下流程：上传真实 Markdown、UTF-8 TXT、带文本层 PDF；等待真实 Embedding 索引；三轮真实双 Agent 问答； 校验严格 SSE 子序列、答案语义、拒答边界、来源 chunk 可读取；重启 Uvicorn 后再次执行真实 检索；验证文档、会话和消息仍存在；删除数据；直接确认原始文件、SQLite 六张业务表及 Milvus 向量均清空。
用户真实文件验收
使用用户授权的 test.txt（6,158,012 字节）执行了额外的大文件验收：
- 后台真实 Embedding 完成 5,037 个片段的索引。
- 首轮问题经 Research Agent 检索后进入 Main Agent，SSE 依次产生
researching、sources、answering、多个token和done。 - 同一会话追问“佩罗和奥克斯对伊南娜做了什么？”，准确召回第 1 章相关片段并生成 S3/S4/S5 引用。
- 多次停止并重启后端后，文档、5,037 个片段、会话和历史消息均可读取。
- 删除会话后，该会话及消息记录均为 0。
- 删除文档后，文档、索引任务、片段、消息来源记录及原始副本均为 0；Milvus
row_count为 0。用户提供的源文件未被改动。
首个宽泛问题的向量召回偏离了开篇片段，因此系统严格返回了证据不足；更具体的多轮追问 召回正确。这属于可接受的模型/向量检索波动，测试只断言事件结构、来源真实性和证据边界， 不锁定模型措辞。
浏览器验收
使用 agent-browser 检查了文档状态、详情抽屉、历史会话恢复、可点击引用、桌面右栏及 390px 窄屏证据抽屉：
- 文档索引状态
- 文档详情抽屉
- 文档窄屏布局
- 历史对话与桌面引用
- 对话窄屏布局
- 窄屏可点击引用抽屉
- 浏览器上传与后台索引中
- 真实问答研究阶段
- 真实回答与引用
- 失败文档重试
- 不支持格式的页面错误
- 文档删除后的空状态
- 会话删除后侧栏同步
真实环境问题与修复
- DashScope 单次 Embedding 上限为 10，索引器已固定分批上限并验证大文件成功。
qwen3.5-flash默认思考模式不支持强制tool_choice；按官方兼容接口关闭思考模式， 保留双 Agent 的必经工具约束。- Milvus Lite 重启后集合需要重新 load，启动流程已补齐。
- 自定义主键搜索结果从
entity.chunk_id读取，避免依赖不存在的默认id字段。 - Research Agent 完成一次真实检索后强制进入证据总结，避免模型重复调用工具直到图递归上限。
- 修复新会话首问完成回调的导航竞态，SSE 完成后按实际会话 ID 刷新历史与侧栏。
LangSmith tracing 已按本地 .env 开启并写入既有项目。代表性 Main Agent trace：
019f5a18-28fb-7f80-b252-b436e2567e1d。
报告不包含任何密钥。