# 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)。
报告不包含任何密钥。