feat(backend): RAG Benchmark 检索评测（含两轮评审修复） #12

2026-09-03T22:25:15+08:00

yxx commented

2026-09-03 22:25:15 +08:00

概述

在 feat/knowledge-retrieval-core 上交付 RAG Benchmark 检索评测，并落实 PR #9 与 PR #11 两轮评审意见。

本轮（PR #11 第二轮评审）修复

Benchmark 容量淘汰只删终态 run，满容量且全活动时返回 BENCHMARK_CAPACITY_EXCEEDED
创建 run 前校验索引兼容性（BENCHMARK_INDEX_INCOMPATIBLE）
取消 run 补发 RunCancelled 终止事件；失败分支脱敏（BENCHMARK_RUN_FAILED）
失败样本计入汇总分母，报告输出 total_cases/successful_cases/failed_cases/failure_rate
load_dataset 按文件名隔离无关损坏文件，顶层非对象拒绝
FTS score_threshold 先于计数/分页，total 与 items 一致
Benchmark SSE 支持 Last-Event-ID 游标
移除 Agent Benchmark 501 占位接口
同步第二阶段接口契约与开发说明文档

测试

cd backend && uv run pytest -q → 120 passed

🤖 Generated with Claude Code

## 概述在 `feat/knowledge-retrieval-core` 上交付 RAG Benchmark 检索评测，并落实 PR #9 与 PR #11 两轮评审意见。 ## 本轮（PR #11 第二轮评审）修复 - Benchmark 容量淘汰只删终态 run，满容量且全活动时返回 `BENCHMARK_CAPACITY_EXCEEDED` - 创建 run 前校验索引兼容性（`BENCHMARK_INDEX_INCOMPATIBLE`） - 取消 run 补发 `RunCancelled` 终止事件；失败分支脱敏（`BENCHMARK_RUN_FAILED`） - 失败样本计入汇总分母，报告输出 `total_cases`/`successful_cases`/`failed_cases`/`failure_rate` - `load_dataset` 按文件名隔离无关损坏文件，顶层非对象拒绝 - FTS `score_threshold` 先于计数/分页，`total` 与 `items` 一致 - Benchmark SSE 支持 `Last-Event-ID` 游标 - 移除 Agent Benchmark 501 占位接口 - 同步第二阶段接口契约与开发说明文档 ## 测试 `cd backend && uv run pytest -q` → 120 passed --- 🤖 Generated with [Claude Code](https://claude.com/claude-code)

yxx added 5 commits 2026-09-03 22:25:15 +08:00

feat: 完成benchmark后端功能 9b50b8f0ce

feat: benchmark功能开发完成 866febec21

chore(backend): 移除误提交的验收笔记 0006e91e67

验收笔记此前被误纳入 benchmark 提交，现摘除跟踪，文件保留在本地磁盘。

Co-Authored-By: Claude Code <noreply@anthropic.com>

fix(backend): 落实 PR #9 评审意见 c6cde2500b

- 检索调优参数(rrf_k/rerank/rerank_candidates/score_threshold)透传到引擎实际执行
- Recall 去重，避免同一 Note 多 Block 重复导致 Recall 超 1
- RAG 运行改为后台异步执行：创建即 queued + 202，支持取消与 SSE 实时事件
- 数据集元数据校验，坏文件隔离跳过；citation_required 语义修正
- modes 空/重复校验；配置快照记录模型版本与索引元信息

Co-Authored-By: Claude Code <noreply@anthropic.com>

fix(backend): 落实 PR #11 第二轮评审意见 fcc601fcf3

- Benchmark 容量淘汰只删终态 run，满容量且全活动时返回 BENCHMARK_CAPACITY_EXCEEDED
- 创建 run 前校验索引兼容性（BENCHMARK_INDEX_INCOMPATIBLE）
- 取消 run 补发 RunCancelled 终止事件；失败分支脱敏（BENCHMARK_RUN_FAILED）
- 失败样本计入汇总分母，报告输出 total/successful/failed/failure_rate
- load_dataset 按文件名隔离无关损坏文件，顶层非对象拒绝
- FTS score_threshold 先于计数/分页，total 与 items 一致
- Benchmark SSE 支持 Last-Event-ID 游标
- 移除 Agent Benchmark 501 占位接口
- 同步第二阶段接口契约与开发说明文档

Co-Authored-By: Claude Code <noreply@anthropic.com>

yxx requested review from Kronecker 2026-09-03 22:26:13 +08:00

yxx added 1 commit 2026-09-03 22:36:23 +08:00

docs: 补齐 PR #11 评审要求的文档同步 3898530585

- 技术栈说明实施状态：RAG Benchmark 标记为已完成、Agent Benchmark 暂缓
- 新增 Benchmark 开发说明，并登记到文档索引
- README 回归基线更新为后端 157 / 前端 29

Co-Authored-By: Claude Code <noreply@anthropic.com>

Kronecker commented

2026-09-03 22:56:10 +08:00

审阅结论

暂不建议合并。基于提交 3898530，发现 1 个 P1、3 个 P2，均已复现，需要修复后再次审阅。

[P1] Benchmark 阻塞事件循环，运行中取消与实时进度失效

位置：backend/app/benchmarks/rag.py:48–57

当前检索调用虽然使用 async/await，但 FTS、默认 Embedding 和向量查询内部同步执行，逐样本循环没有实际让出事件循环。

复现：第 1 个样本完成后调度取消回调，直到全部 20 个样本执行完毕，取消回调才获得执行机会。

影响：较大数据集会阻塞其他 API 请求，运行中的取消请求无法及时处理，SSE 进度也无法实时发送。

建议：隔离同步检索计算，并在样本边界让出执行权；增加运行中取消、实时进度和并发请求的回归测试。

[P2] SSE 历史回放期间收到终止事件后可能无法关闭

位置：backend/app/routes.py:966–977

历史回放直接遍历持续追加的事件列表。如果运行在回放期间完成，终止事件会通过历史列表输出；随后进入实时队列，同一终止事件被序号去重跳过，流便永久等待下一条事件。

复现：客户端已经收到 RunCompleted，但事件流仍不结束。

建议：历史回放和实时消费都必须识别终止事件；将订阅后的整个回放与消费过程纳入 try/finally，确保正常结束和断连时均清理订阅。

[P2] FTS 搜索结果被新增的 5000 条上限截断

位置：backend/app/retrieval/engine.py:150–168

实现丢弃数据库返回的真实总数，只取前 5000 条命中，再计算 total 和分页。默认 score_threshold=0 的普通搜索同样受影响。

复现：建立 5010 个匹配块后，返回 total=5000；请求 offset=5000、limit=10 得到空页，剩余结果无法访问。

建议：无阈值过滤时保留数据库计数与分页；有阈值过滤时实现完整的统计和分页，不应通过固定截断静默丢失结果。

[P2] 仅标注块 ID 的合法样本被错误计为零分

位置：backend/app/benchmarks/rag.py:109–114

数据集校验允许只提供 expected_block_ids，但 Hit、Recall 和 MRR 仅使用 expected_note_ids 计算。

复现：第一条结果精确命中期望块，citation_hit=True，其余质量指标仍全部为零，并被计入汇总。

建议：统一校验与评分契约。可以明确要求笔记 ID，或根据期望块解析所属笔记后评分，避免把标注缺失误判为检索失败。

合并冲突

与审阅时最新 main（78e8e3e）存在以下文件冲突，Gitea 当前也显示不可自动合并：

README.md
backend/app/routes.py
docs/architecture/AI笔记软件技术栈说明-团队版-v2.3.md
docs/development/Knowledge与Retrieval-Core开发说明.md

解决冲突时需要保留 main 已合入的 MCP 功能与文档更新，并重新验证合并后的版本。

验证情况

PR 分支后端测试：120 项通过。
上述 4 个问题通过补充验证复现，现有测试未覆盖。
尚未验证解决冲突后的合并版本。

请修复上述问题、补充回归测试并解决与 main 的冲突后，再次提交审阅。

## 审阅结论暂不建议合并。基于提交 `3898530`，发现 1 个 P1、3 个 P2，均已复现，需要修复后再次审阅。 ### [P1] Benchmark 阻塞事件循环，运行中取消与实时进度失效位置：`backend/app/benchmarks/rag.py:48–57` 当前检索调用虽然使用 async/await，但 FTS、默认 Embedding 和向量查询内部同步执行，逐样本循环没有实际让出事件循环。复现：第 1 个样本完成后调度取消回调，直到全部 20 个样本执行完毕，取消回调才获得执行机会。影响：较大数据集会阻塞其他 API 请求，运行中的取消请求无法及时处理，SSE 进度也无法实时发送。建议：隔离同步检索计算，并在样本边界让出执行权；增加运行中取消、实时进度和并发请求的回归测试。 ### [P2] SSE 历史回放期间收到终止事件后可能无法关闭位置：`backend/app/routes.py:966–977` 历史回放直接遍历持续追加的事件列表。如果运行在回放期间完成，终止事件会通过历史列表输出；随后进入实时队列，同一终止事件被序号去重跳过，流便永久等待下一条事件。复现：客户端已经收到 RunCompleted，但事件流仍不结束。建议：历史回放和实时消费都必须识别终止事件；将订阅后的整个回放与消费过程纳入 try/finally，确保正常结束和断连时均清理订阅。 ### [P2] FTS 搜索结果被新增的 5000 条上限截断位置：`backend/app/retrieval/engine.py:150–168` 实现丢弃数据库返回的真实总数，只取前 5000 条命中，再计算 total 和分页。默认 score_threshold=0 的普通搜索同样受影响。复现：建立 5010 个匹配块后，返回 total=5000；请求 offset=5000、limit=10 得到空页，剩余结果无法访问。建议：无阈值过滤时保留数据库计数与分页；有阈值过滤时实现完整的统计和分页，不应通过固定截断静默丢失结果。 ### [P2] 仅标注块 ID 的合法样本被错误计为零分位置：`backend/app/benchmarks/rag.py:109–114` 数据集校验允许只提供 expected_block_ids，但 Hit、Recall 和 MRR 仅使用 expected_note_ids 计算。复现：第一条结果精确命中期望块，citation_hit=True，其余质量指标仍全部为零，并被计入汇总。建议：统一校验与评分契约。可以明确要求笔记 ID，或根据期望块解析所属笔记后评分，避免把标注缺失误判为检索失败。 ## 合并冲突与审阅时最新 main（`78e8e3e`）存在以下文件冲突，Gitea 当前也显示不可自动合并： - README.md - backend/app/routes.py - docs/architecture/AI笔记软件技术栈说明-团队版-v2.3.md - docs/development/Knowledge与Retrieval-Core开发说明.md 解决冲突时需要保留 main 已合入的 MCP 功能与文档更新，并重新验证合并后的版本。 ## 验证情况 - PR 分支后端测试：120 项通过。 - 上述 4 个问题通过补充验证复现，现有测试未覆盖。 - 尚未验证解决冲突后的合并版本。请修复上述问题、补充回归测试并解决与 main 的冲突后，再次提交审阅。

Kronecker closed this pull request

2026-09-03 22:56:13 +08:00

yxx referenced this issue from a commit

2026-09-03 23:57:44 +08:00

fix(backend): 落实 PR #12 评审意见

yxx referenced this pull request

2026-09-04 00:00:59 +08:00

Feat/knowledge retrieval core #14