跳转至

评测与基准

本页描述当前仓库已经落地的 Agent 后台测评能力，以及通用回归验证方式。

建议先阅读《评测架构蓝图 v1》，该文档定义了统一数据模型、Trace Schema 与阶段性路线。

已落地能力（Admin 后台）

当前已支持在 Admin 后台完成完整测评闭环：

  1. 在 Evaluation -> Datasets 创建评测数据集（平台共享）
  2. 在数据集详情页导入 CSV 样本，并持久化当前生效的 source CSV
  3. 在数据集详情页冻结数据集生成不可变快照版本，并复制当前 source CSV 到快照
  4. 在数据集详情页选择目标 chat Agent 发起异步测评 Run
  5. 跳转到 Agent 详情页查看 Run 聚合指标与样本级结果
  6. 在 Agent 详情页评估并查看 Run 级质量门禁结论（Gate）
  7. 在数据集详情页查看 source CSV 元数据并直接下载原始导入文件
  8. 在数据集列表或详情页删除不再使用的数据集（受引用保护规则约束）

首期范围：

  • Agent 类型：仅 chat
  • 数据集导入：仅 CSV
  • 评分策略：规则评分 + LLM-as-a-Judge
  • 模型参数：默认继承 Agent 配置，支持 Run 级可选覆盖

评测数据集 CSV 模板

CSV Header 要求：

  • 必填：input, expected
  • 可选：metadata, accepted_answers

示例：

input,expected,accepted_answers,metadata
请介绍一下Incoterms 2020,Incoterms 2020 是国际贸易术语规则,"[""Incoterms 2020 是 ICC 发布的国际贸易术语规则""]","{""domain"": ""trade"", ""difficulty"": ""easy""}"
你们的服务覆盖哪些地区,服务覆盖全球主要港口与航线,,"{""domain"": ""company_profile""}"

导入规则：

  • 文件编码必须为 UTF-8（支持 UTF-8 BOM）
  • 空 input 或空 expected 会返回 400 错误
  • accepted_answers 支持 JSON 字符串数组；若填普通字符串，会被当作 1 个备选答案
  • 导入动作会覆盖该数据集原有样本（replace 语义）
  • 导入成功后会持久化原始 source CSV 文件，并保留 filename/content_type/size/uploaded_at 元数据
  • 冻结数据集（is_frozen=true）不可导入，需先创建或冻结新的版本
  • 冻结动作会把当前 source CSV 一起复制到快照版本，保证后续复跑仍能取回当时的原始输入文件
  • 发起 Run 仅允许选择冻结数据集快照（is_frozen=true）
  • 对历史遗留数据集，如果当前已有 items 但没有已持久化的 source CSV，冻结会返回 400；需要重新导入 CSV 后再冻结
  • 删除数据集时，若存在评测 Run 引用或子快照（parent_dataset_id 依赖）会返回冲突错误
  • 若因评测 Run 引用删除失败，409 detail 会包含引用明细（referencing_agents），可在前端直接展示“被哪个 Agent 引用”

Source CSV 持久化与下载

数据集详情页现在会显示一个 Source CSV 区域，直接展示当前生效原始 CSV 的：

  • 文件名
  • content_type
  • 文件大小
  • 上传时间

下载行为说明：

  • 优先使用后端返回的下载入口，不要求管理员打开对象存储后台或手工拼接 URL
  • 当对象存储公网下载不可用时，前端会透明回退到同域 API 代理下载
  • 现有 Evaluation Run Results CSV 导出保持不变，仍可在 Agent 详情页的 Evaluation 面板使用

Conversations 历史导出补充：

  • Admin Conversations 页面导出的 CSV 也保持同一 input,expected,metadata 契约，可以直接作为评测数据集 CSV 的原始素材。
  • Conversations 导出的行仍保持单个 Turn 的 input + expected 结构，不会把整段多轮会话折叠成一行。
  • 导出范围已扩展到 Selected Turns、Current Session、Selected Sessions、Filtered Sessions，因此多 turn / 多 session 的历史样本现在可以直接批量生成数据集原始素材。
  • 导出 metadata 会补充会话/Turn provenance 与导出范围信息，但不会内联完整原始观测 payload。

执行链路

flowchart LR
  Admin[Admin Evaluation->Datasets] --> Dataset[选择或创建数据集]
  Dataset --> Import[上传 CSV]
  Import --> Freeze[冻结数据集快照]
  Freeze --> Run[在数据集详情页创建 evaluation run]
  Run --> Queue[queued]
  Queue --> Running[running]
  Running --> Completed[completed 或 failed]
  Completed --> Review[Agent 详情页查看聚合分数和逐条结果]

状态机：

  • Run 状态：queued → running → completed / failed
  • Result 状态：succeeded / failed

执行可靠性：

  • POST /agents/{agent_id}/evaluation-runs 只负责创建 queued Run，不再在请求线程里直接执行
  • API 启动后会启动后台 evaluation supervisor；supervisor 会尽力立即执行一次 stale recovery，但即使首次巡检瞬时失败也不会放弃后台 loop，后续周期仍会继续保活 dispatcher 并重试恢复
  • dispatcher 从数据库队列中依次领取 Run；worker 心跳与 stale recovery 完全在后台进行
  • 当单个 dataset item 执行时间较长时，runner 会在 item 执行期间持续刷新 worker_heartbeat_at，避免把仍在执行中的慢样本误判为 stale worker 并错误重试
  • 若单条样本中的模型或 Judge 请求卡住，统一的 timeouts.model_request_seconds 会让该请求超时失败，避免 fresh heartbeat 把整个 Run 无限期留在 running
  • 若服务重启前存在 queued Run，它会在启动后继续执行
  • 若服务重启前存在心跳超时的 running Run，它会被自动回退到 queued 后重试
  • 前端轮询只负责刷新列表、详情、结果和切片展示，不负责触发恢复；关闭页面不会暂停后台评测
  • Run 续跑以已落库的 agent_evaluation_results 为准：已完成样本会跳过，不会整批从 0 重算
  • agent_evaluation_runs.completed_at 是 Run 级规范结束时间：终态 completed / failed 会在收敛时写入，queued / running 必须保持为空
  • worker_heartbeat_at 只反映 worker liveness，不等价于 Run 结束时间；控制面展示 End Time 时必须使用 completed_at
  • 若历史异常终态数据缺少 completed_at，展示层应输出 Unknown 一类容错占位，而不是伪造时间
  • Dataset Detail 的 Recent Runs 必须调用 dataset-scoped 列表接口（GET /evaluation-datasets/{dataset_id}/runs）；不要先拉取每个 agent 的 capped run 列表再在前端按 dataset_id 过滤，否则会静默漏掉较老但仍属于该数据集的 Run
  • API 响应会基于原始 status/attempt_count/worker_heartbeat_at 派生 execution_state，用于前端直接展示 recovering、heartbeat_expired 等后台执行态

指标说明

每条样本会产出两类评分：

  • 规则评分：
  • exact_match：归一化后完全一致记 1，否则 0
  • token_f1：基于分词重叠的 F1
  • pass_rate：当前实现等价于 EM（EM=1 则通过）
  • matched_expected_answer_index：命中的标准答案索引；0 代表主 expected，其余索引对应 accepted_answers
  • LLM Judge：
  • score：0 到 1 的语义匹配分
  • reason：模型给出的主评语
  • issues：识别出的主要问题点
  • improvement_suggestions：修改建议列表
  • suggested_better_answer：建议改写答案
  • confidence：Judge 自评置信度
  • rubric_version：Judge rubric / prompt 版本快照
  • raw_response_text：Judge 原始响应

Run 级聚合指标：

  • score_em
  • score_f1
  • score_pass_rate
  • score_llm_judge（Judge 可用时计算均值）
  • judge_prompt_version（本次 Run 冻结的 Judge prompt 版本）
  • gating_status（pass / fail / not_evaluated）
  • gating_policy（本次 Gate 评估使用的阈值快照）
  • failed_criteria（未通过时的具体失败条件）
  • started_at（Run 首次进入执行态的时间）
  • completed_at（Run 规范结束时间，供列表/详情/Review 展示 End Time）
  • generation_usage_rollup / judge_usage_rollup（分别聚合 generation 与 Judge 的 token 使用量）
  • combined_total_tokens（当 generation/judge 两侧总量都可用时返回合计）

Token 统计约定：

  • 每条 evaluation result 都会分别持久化 generation_usage 与 judge_usage
  • provider 未返回 usage 时，写入路径会直接使用本地 tokenizer 估算，而不是依赖离线回填
  • 如果单条样本只拿到部分 provider usage，则该样本的对应 usage 会整体降级成 tokenizer_estimated，避免把 partial total 当成完整 provider 统计
  • deterministic / no-model 路径会显式写入 0 token，并标记 no_model_invocation
  • 若样本在 generation 阶段失败、Judge 从未调用，则 judge_usage 会写成 0 + no_model_invocation
  • 若 provider usage 缺失且 tokenizer 估算也失败，则会写入 unavailable，避免 silent null
  • Run 级 rollup 会同时记录四类来源计数：provider_reported、tokenizer_estimated、no_model_invocation、unavailable

分片指标：

  • 支持按 domain、difficulty、source 聚合查看各分片 EM/F1/PassRate/Judge。

Agent 详情页审阅工作台

Agent 详情页的 Evaluation 面板现在支持：

  • 在 Configuration 页签编辑 Agent 级 LLM Judge Prompt。留空时回退到内置默认 Judge prompt；保存后，新创建的 evaluation run 会冻结当时的 prompt 文本与派生版本号。
  • 当 Agent 级 judge_prompt 为空时，Run 快照会持久化展开后的内置默认 Judge prompt 文本，因此即使后台服务稍后升级了默认 prompt，排队中的历史 Run 仍优先使用创建时冻结的快照。
  • 新创建的 evaluation run 还会绑定一份不可变 agent_version 快照，并在 Review 面板返回 agent_snapshot；worker 执行时优先使用这份快照中的 system_prompt、orchestrator_key、mcp_runtime_config 与其他运行时配置，而不是回读后续变更后的 live Agent。
  • 在 Run 列表和 Review 摘要里显示 Started At、End Time 与可选 Duration；其中 End Time 固定来自 completed_at
  • 在 Run 列表和 Review 摘要里分别显示 generation/judge token rollup 与来源 breakdown
  • 编辑并提交 Gate policy（minimum_items、score_pass_rate_min、score_f1_min、max_failed_item_ratio、llm_judge_min）
  • 查看本次 Gate 评估实际使用的 policy 快照与 failed_criteria
  • 样本结果分页（每页 50 条）
  • 结果过滤：all、failed、low_signal
  • 导出当前选中 Run 的全量样本结果为 CSV（后端直接返回下载文件）
  • Sample inspector 查看：
  • 输入 / 期望 / 备选答案 / 预测
  • 规则评分细项
  • Judge 评语、问题点、修改建议、推荐改写答案
  • generation / judge token 使用量与来源
  • 分片聚合指标（domain / difficulty / source）

CSV 导出说明：

  • 导出入口位于 Agent 详情页的 Evaluation 面板
  • 导出范围覆盖当前选中 Run 的全部已落库样本级结果，而不是仅当前分页
  • 下载文件编码为 UTF-8（含 BOM），便于 Excel 等工具直接打开中文内容
  • 导出响应采用流式返回，避免大 Run 在服务端一次性拼接整份 CSV
  • 为降低表格软件公式注入风险，导出时会自动转义以 =, +, -, @ 开头的文本单元格
  • 导出列包含运行标识、输入/期望/预测、规则评分、Judge 评分细项、generation/judge token 数值与来源、错误信息与时间戳

相关端点

已上线端点详见 API 端点总览 的“评测数据集端点”和“Agent 测评运行端点”章节。

前端入口与迁移说明

  • 新入口（主路径）：
  • Evaluation -> Datasets
  • /evaluation/datasets
  • /evaluation/datasets/:datasetId
  • 迁移兼容：
  • AgentDetailPage 仍保留 Run 启动与结果查看能力。
  • 数据集管理能力（创建/导入/冻结）已迁移到 Evaluation -> Datasets。
  • Dataset Detail 现在额外提供 Source CSV 元数据与下载入口。

回归验证

1. 代码回归

uv run pytest

2. 文档回归

uv run --group docs mkdocs build

后续演进方向

  • 支持 document_extraction / etl 专项测评器
  • 增加离线评测脚本（批量回放 + 报告导出）
  • 增加历史对比视图与阈值告警

最后更新

  • 2026-03-31