Feat/knowledge retrieval core #9

2026-09-01T23:44:00+08:00

yxx commented

2026-09-01 23:44:00 +08:00

概述

为 Knowledge Core / Retrieval Core 增加一套可复现的 RAG 检索评测能力，量化检索质量并提供可复现基线，为后续检索调优（embedding / reranker / RRF 参数）提供依据。

功能点

受控数据集：backend/data/benchmarks/*.json 目录注册（dataset_id / kind / version / cases），加载时校验，内容 sha256 哈希保证可复现。
纯函数指标：Hit@1 / Hit@5、Recall@K、MRR、CitationHit、P50/P95 延迟分位数，无副作用、可独立单测。
RAG Runner：复用 app.retrieval.engine.search()，不旁路检索链路；逐 (mode, case, repeat) 采样，按 mode 聚合；单样本失败不中断整体。
运行注册表：内存态 run 注册、进度推进、SSE 事件流（RunStarted / CaseCompleted / RunCompleted / RunFailed）、报告组装与取消接口。
配置快照：记录 embedding / reranker 模型、检索参数、环境信息，报告可解释、可复现。
REST 端点：/api/benchmarks/* 共 8 个（数据集列表、RAG 运行、Agent 运行占位、运行列表/详情/取消/事件/报告）。

文件清单

新增 backend/app/benchmarks/：metrics.py、datasets.py、rag.py、service.py
修改：backend/app/contracts.py（Benchmark 契约）、backend/app/routes.py（端点）、backend/app/config.py（数据集路径）
新增种子数据集 backend/data/benchmarks/rag-core-v1.json（5 个中文检索 case）
新增 backend/tests/test_benchmark.py（13 个测试）

测试

cd backend
pytest tests/test_benchmark.py -v

## 概述为 Knowledge Core / Retrieval Core 增加一套可复现的 RAG 检索评测能力，量化检索质量并提供可复现基线，为后续检索调优（embedding / reranker / RRF 参数）提供依据。 ## 功能点 - **受控数据集**：`backend/data/benchmarks/*.json` 目录注册（dataset_id / kind / version / cases），加载时校验，内容 sha256 哈希保证可复现。 - **纯函数指标**：Hit@1 / Hit@5、Recall@K、MRR、CitationHit、P50/P95 延迟分位数，无副作用、可独立单测。 - **RAG Runner**：复用 `app.retrieval.engine.search()`，不旁路检索链路；逐 (mode, case, repeat) 采样，按 mode 聚合；单样本失败不中断整体。 - **运行注册表**：内存态 run 注册、进度推进、SSE 事件流（RunStarted / CaseCompleted / RunCompleted / RunFailed）、报告组装与取消接口。 - **配置快照**：记录 embedding / reranker 模型、检索参数、环境信息，报告可解释、可复现。 - **REST 端点**：`/api/benchmarks/*` 共 8 个（数据集列表、RAG 运行、Agent 运行占位、运行列表/详情/取消/事件/报告）。 ## 文件清单 - 新增 `backend/app/benchmarks/`：`metrics.py`、`datasets.py`、`rag.py`、`service.py` - 修改：`backend/app/contracts.py`（Benchmark 契约）、`backend/app/routes.py`（端点）、`backend/app/config.py`（数据集路径） - 新增种子数据集 `backend/data/benchmarks/rag-core-v1.json`（5 个中文检索 case） - 新增 `backend/tests/test_benchmark.py`（13 个测试） ## 测试 ```bash cd backend pytest tests/test_benchmark.py -v

yxx added 3 commits 2026-09-01 23:44:01 +08:00

feat: 完成benchmark后端功能 9b50b8f0ce

feat: benchmark功能开发完成 866febec21

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

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

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

Kronecker commented

2026-09-02 00:11:33 +08:00

本次 PR 已完成 RAG Benchmark 的基础 Dataset、Runner、指标、报告和接口结构，整体模块拆分清晰，现有测试也全部通过。但审阅中发现部分问题会直接影响 Benchmark 指标可信度及接口契约，当前暂不建议合并。

需要修复

Benchmark 检索配置未实际生效（P1）

rrf_k、rerank、rerank_candidates 和 score_threshold 目前只写入配置快照，实际执行时仅使用了 top_k。

这会造成报告记录的配置与真实执行过程不一致，也无法完成以下实验对比：

Hybrid + RRF
Hybrid + RRF + Reranker
不同 RRF 参数
不同候选数量和阈值

建议接入统一的 RetrievalProfile；暂未支持的参数应明确拒绝，不能记录后静默忽略。配置快照还需要补充接口契约要求的索引版本。

Recall@K 可能大于 1（P1）

检索结果是 Block 级别，同一 Note 可能通过多个 Block 重复出现。当前 Recall 逐项计数，重复 Note 会被多次计算。

已复现：

retrieved = ["note-a", "note-a"]
expected = {"note-a"}
Recall@2 = 2.0

建议改为：

len(set(retrieved[:k]) & expected) / len(expected)

并补充重复 note_id 的单元测试。

202、SSE 和取消接口与实际行为不一致（P1）

POST /api/benchmarks/rag/runs 会等待整个 Benchmark 执行完成后才返回，因此：

返回的通常是 completed，不是契约中的 queued；
客户端无法在运行期间订阅 SSE；
取消接口无法有效取消正在运行的任务；
大型 Dataset 会长时间占用请求和事件循环。

建议创建 Run 后立即返回 202 queued，由受管理的后台 Task 执行。Runner 应在 Case 之间检查取消状态，SSE 实时输出进度。

损坏 Dataset 会导致列表接口返回 500（P2）

当前只跳过无法解析的 JSON，没有校验合法 JSON 的字段结构。例如：

{
  "dataset_id": "bad",
  "kind": "rag",
  "cases": 42
}

会在 len(cases) 处抛出 TypeError，导致整个 Dataset 列表失败。

建议使用统一的 Dataset 元数据模型逐文件校验，并将单个损坏文件隔离处理。

citation_required 未参与 Citation Hit Rate 计算（P2）

当前只要存在 expected_block_ids 就会计入 Citation Hit Rate，即使 Case 设置：

{
  "citation_required": false
}

仓库自带 Dataset 已存在这种情况，会造成引用指标分母不准确。

建议：

以 citation_required 判断是否计入指标；
当 citation_required=true 时，强制要求存在 expected_block_ids。

空 modes 会生成无效报告（P2）

当前允许：

{
  "dataset_id": "rag-core-v1",
  "modes": []
}

运行会直接完成并返回空的 metrics。建议给 modes 添加 min_length=1，同时拒绝重复模式。

验证结果

Backend tests: 105 passed
Frontend tests: 27 passed
TypeScript type-check: passed
Frontend production build: passed
Python compileall: passed
git diff --check: passed
Merge conflict check: passed

现有测试均通过，但尚未覆盖上述指标正确性和运行生命周期问题。

审阅结论

Request changes / 暂不建议合并。

建议优先修复三个 P1 问题：

让检索配置真正进入执行链路；
修正 Recall 去重计算；
将 Benchmark 改为可观察、可取消的后台运行。

完成后再进行一次合并前审阅。

本次 PR 已完成 RAG Benchmark 的基础 Dataset、Runner、指标、报告和接口结构，整体模块拆分清晰，现有测试也全部通过。但审阅中发现部分问题会直接影响 Benchmark 指标可信度及接口契约，当前暂不建议合并。 ### 需要修复 1. **Benchmark 检索配置未实际生效（P1）** `rrf_k`、`rerank`、`rerank_candidates` 和 `score_threshold` 目前只写入配置快照，实际执行时仅使用了 `top_k`。这会造成报告记录的配置与真实执行过程不一致，也无法完成以下实验对比： - Hybrid + RRF - Hybrid + RRF + Reranker - 不同 RRF 参数 - 不同候选数量和阈值建议接入统一的 `RetrievalProfile`；暂未支持的参数应明确拒绝，不能记录后静默忽略。配置快照还需要补充接口契约要求的索引版本。 2. **Recall@K 可能大于 1（P1）** 检索结果是 Block 级别，同一 Note 可能通过多个 Block 重复出现。当前 Recall 逐项计数，重复 Note 会被多次计算。已复现： ```text retrieved = ["note-a", "note-a"] expected = {"note-a"} Recall@2 = 2.0 ``` 建议改为： ```python len(set(retrieved[:k]) & expected) / len(expected) ``` 并补充重复 `note_id` 的单元测试。 3. **202、SSE 和取消接口与实际行为不一致（P1）** `POST /api/benchmarks/rag/runs` 会等待整个 Benchmark 执行完成后才返回，因此： - 返回的通常是 `completed`，不是契约中的 `queued`； - 客户端无法在运行期间订阅 SSE； - 取消接口无法有效取消正在运行的任务； - 大型 Dataset 会长时间占用请求和事件循环。建议创建 Run 后立即返回 `202 queued`，由受管理的后台 Task 执行。Runner 应在 Case 之间检查取消状态，SSE 实时输出进度。 4. **损坏 Dataset 会导致列表接口返回 500（P2）** 当前只跳过无法解析的 JSON，没有校验合法 JSON 的字段结构。例如： ```json { "dataset_id": "bad", "kind": "rag", "cases": 42 } ``` 会在 `len(cases)` 处抛出 `TypeError`，导致整个 Dataset 列表失败。建议使用统一的 Dataset 元数据模型逐文件校验，并将单个损坏文件隔离处理。 5. **`citation_required` 未参与 Citation Hit Rate 计算（P2）** 当前只要存在 `expected_block_ids` 就会计入 Citation Hit Rate，即使 Case 设置： ```json { "citation_required": false } ``` 仓库自带 Dataset 已存在这种情况，会造成引用指标分母不准确。建议： - 以 `citation_required` 判断是否计入指标； - 当 `citation_required=true` 时，强制要求存在 `expected_block_ids`。 6. **空 `modes` 会生成无效报告（P2）** 当前允许： ```json { "dataset_id": "rag-core-v1", "modes": [] } ``` 运行会直接完成并返回空的 `metrics`。建议给 `modes` 添加 `min_length=1`，同时拒绝重复模式。 ### 验证结果 ```text Backend tests: 105 passed Frontend tests: 27 passed TypeScript type-check: passed Frontend production build: passed Python compileall: passed git diff --check: passed Merge conflict check: passed ``` 现有测试均通过，但尚未覆盖上述指标正确性和运行生命周期问题。 ### 审阅结论 **Request changes / 暂不建议合并。** 建议优先修复三个 P1 问题： 1. 让检索配置真正进入执行链路； 2. 修正 Recall 去重计算； 3. 将 Benchmark 改为可观察、可取消的后台运行。完成后再进行一次合并前审阅。

Kronecker closed this pull request

2026-09-02 00:11:33 +08:00

yxx referenced this issue from a commit

2026-09-02 23:21:45 +08:00

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

yxx referenced this pull request

2026-09-02 23:27:23 +08:00

feat(backend): RAG Benchmark 检索评测（含 PR #9 评审修复） #11

yxx referenced this pull request

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

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