NotesAgentic/docs/development/Benchmark开发说明.md

Benchmark 开发说明

所属模块：Knowledge / Retrieval Core（后端，负责人 yxx）。RAG Benchmark 已交付；Agent Benchmark 暂缓，待 Agent Runtime 完成后在同一契约下补齐。

定位

Benchmark Service 用受控 Dataset 对检索引擎做可复现评测：创建即返回 queued、后台 asyncio.Task 执行、SSE 实时推送进度、结束后产出结构化报告。CLI、测试与前端报告页复用同一 Service，不各自实现指标。

接口

方法	路径	用途
GET	/api/benchmarks/datasets?kind=rag	枚举受控目录下的 Dataset 元信息
POST	/api/benchmarks/rag/runs	创建 RAG Benchmark（202）
GET	/api/benchmarks/runs?kind=&status=&limit=&offset=	分页获取运行记录
GET	/api/benchmarks/runs/{run_id}	状态与指标摘要
GET	/api/benchmarks/runs/{run_id}/events	SSE 进度与 Case 结果
POST	/api/benchmarks/runs/{run_id}/cancel	取消运行
GET	/api/benchmarks/runs/{run_id}/report	结构化完整报告

Agent Benchmark 的 /api/benchmarks/agent/runs 未暴露（暂缓），不在 OpenAPI 注册占位接口。

Dataset

Dataset 来自 settings.benchmark_datasets_path（默认 backend/data/benchmarks），API 不接受调用方提交任意路径。按文件名 stem 精确匹配 {dataset_id}.json，与请求无关文件的损坏（JSON 语法错误、UTF-8 解码错误、顶层非对象）不会阻断加载；只有目标文件本身损坏才返回 BENCHMARK_DATASET_INVALID。

RAG Case 结构：case_id、query、expected_note_ids、expected_block_ids、citation_required、tags。citation_required=true 时必须声明 expected_block_ids，否则无法计算 Citation Hit Rate。

运行生命周期

queued → running → completed | failed | cancelled。

• 创建时校验索引兼容性：索引非空、Embedding model/dim 与当前引擎一致、vector/hybrid 时向量索引非空；不满足返回 BENCHMARK_INDEX_INCOMPATIBLE（409），避免把环境/索引错误误判为检索质量差。
• 内存注册表上限 MAX_RUNS=100，超限只淘汰终态 run；满容量且全为活动 run 时返回 BENCHMARK_CAPACITY_EXCEEDED（429）。
• 失败/取消只向公开响应暴露项目错误码与安全消息，详细异常进入日志，不通过 HTTP/SSE 返回。

指标

RAG 按 (mode, case, repeat) 逐样本计算，再按 mode 聚合：

• 质量：hit_at_1、hit_at_5、recall_at_k、mrr、citation_hit_rate；
• 延迟：p50_latency_ms、p95_latency_ms（仅统计成功样本）；
• 样本构成：total_cases、successful_cases、failed_cases、failure_rate。

失败样本按零分计入质量指标分母，报告据此可知实际分母，避免把执行失败误判为检索质量差。

事件与 SSE

事件流：RunStarted → CaseCompleted* → RunCompleted | RunFailed | RunCancelled。

GET /api/benchmarks/runs/{run_id}/events 支持 Last-Event-ID 与 ?after_sequence= 游标恢复（复用 Agent SSE 的解析逻辑），RunCompleted / RunFailed / RunCancelled 为终止事件，收到后断流。

错误码

BENCHMARK_DATASET_NOT_FOUND
BENCHMARK_DATASET_INVALID
BENCHMARK_INDEX_INCOMPATIBLE
BENCHMARK_CAPACITY_EXCEEDED
BENCHMARK_RUN_NOT_FOUND
BENCHMARK_RUN_FAILED
BENCHMARK_CASE_EVALUATION_FAILED

配置快照

报告与运行记录保存 config_snapshot：dataset hash/version、modes、retrieval 参数、Embedding model/version/dim、Reranker、索引元数据、App 版本与环境、Python 版本，保证不同实验结果可复现。

测试

cd backend
uv run pytest -q

tests/test_benchmark.py 覆盖数据集注册与校验、指标纯函数、端到端运行、取消、索引兼容、容量与失败样本聚合；tests/test_retrieval.py 覆盖 FTS 阈值与分页 total 一致性。