79 lines
4.7 KiB
Markdown
79 lines
4.7 KiB
Markdown
# 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` 为终止事件，收到后断流。
|
||
|
||
## 错误码
|
||
|
||
```text
|
||
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。记录使用任务局部上下文隔离，并发评测不会相互覆盖。
|
||
|
||
## 测试
|
||
|
||
```powershell
|
||
cd backend
|
||
uv run pytest -q
|
||
```
|
||
|
||
`tests/test_benchmark.py` 覆盖数据集注册与校验、指标纯函数、端到端运行、取消、索引兼容、容量与失败样本聚合；`tests/test_retrieval.py` 覆盖 FTS 阈值与分页 total 一致性。
|