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

Benchmark 开发说明

所属模块：Knowledge / Retrieval Core（后端，负责人 yxx）。RAG 与标准Agent Benchmark均已实现，前端入口/benchmarks。真实验收结果与范围见第二阶段收尾记录。

定位

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的POST /api/benchmarks/agent/runs已实现并注册OpenAPI，使用正式Agent Runtime与Trace；请求/Case见契约§9。默认只接受真实Provider，显式offline才允许mock，不自动批准工具权限。

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。

• RAG创建时校验索引兼容性：索引非空、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 参数、Reranker、索引元数据、App 版本与环境、Python 版本。local_embedding 记录本地基线 model/version/dim；embedding.policy = per_case 表示实际来源以逐样本结果为准，不能把本地基线当作本次使用的模型。

每个 RAGCaseResult.embedding（同时出现在报告 cases 和 CaseCompleted SSE 中）记录 source（api/local/not_used/unavailable）、实际 model_id 空间标识、dimensions、本地 version、fallback_reason。远程路由还记录请求时的 route_version 和 requested_route（provider_id/model/endpoint/dimensions，不含凭据）、成功生成查询向量后的 attempted_space。FTS 标记 not_used；调用失败而未完成向量检索时标记 unavailable。API 不可用或远程索引缺失时，实际模型仍记录最终使用的本地基线。配置允许在样本间改变，逐样本记录对应实际调用；汇总指标可能包含多种空间，比较实验时需检查 cases。记录使用任务局部上下文隔离，并发评测不会相互覆盖。

测试

cd backend
uv run pytest -q

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

2026-09-07 数据与复现补充

agent-core-v1.json为四例标准任务；rag-phase2-v1.json对应独立测试语料，不对应任意用户Vault，运行前必须用phase2-quality.py准备语料及真实索引。语料源、配置、逐例结果和冷暖缓存说明见收尾验收记录。UI支持RAG/Agent切换、Provider/模型、融合/TopK/RRF/rerank配置、取消、报告JSON与Trace入口。

Agent成功判定包含终态完成、预期工具及声明参数一一匹配、无额外调用、工具结果成功、输出子串、引用和任务数量；并非由另一个LLM主观打分。失败/取消报告保留total_cases与evaluated_cases，不能当成完成的质量测量。报告注册表最多100条且不跨进程恢复，重要结果须下载保存；持久Agent Trace独立保留。工具选择/参数准确率和无效调用率在无分母时返回null。