test: verify real kbqa workflow

2026-07-13 14:23:06 +08:00
parent 52184aa00e
commit 2361d62867
32 changed files with 656 additions and 12 deletions
@@ -0,0 +1,93 @@
+# 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：
+
+```text
+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
+```
+
+显式开启的真实模型黑盒测试：
+
+```text
+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 窄屏证据抽屉：
+
+- [文档索引状态](screenshots/documents-indexing.png)
+- [文档详情抽屉](screenshots/document-detail-drawer.png)
+- [文档窄屏布局](screenshots/documents-narrow.png)
+- [历史对话与桌面引用](screenshots/chat-history-citation.png)
+- [对话窄屏布局](screenshots/chat-mobile.png)
+- [窄屏可点击引用抽屉](screenshots/chat-mobile-citation.png)
+- [浏览器上传与后台索引中](screenshots/browser-upload-indexing.png)
+- [真实问答研究阶段](screenshots/browser-live-researching.png)
+- [真实回答与引用](screenshots/browser-live-answer.png)
+- [失败文档重试](screenshots/browser-retry.png)
+- [不支持格式的页面错误](screenshots/browser-upload-error.png)
+- [文档删除后的空状态](screenshots/browser-delete-empty.png)
+- [会话删除后侧栏同步](screenshots/browser-session-deleted.png)
+
+## 真实环境问题与修复
+
+- 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`](https://smith.langchain.com/o/3b9cd927-6db9-411f-b6af-19b38f36a387/projects/p/6b719950-c885-405f-addb-1bd86ac3cf83/r/019f5a18-28fb-7f80-b252-b436e2567e1d?trace_id=019f5a18-28fb-7f80-b252-b436e2567e1d&start_time=2026-07-13T06:09:20.635570)。
+报告不包含任何密钥。