gqt
94 lines
4.5 KiB
Markdown
94 lines
4.5 KiB
Markdown
# 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)。
|
||
报告不包含任何密钥。
|