评测与基准

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

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

已落地能力（Admin 后台）

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

1. 在 Evaluation -> Datasets 创建评测数据集（平台共享）
2. 在数据集详情页导入 CSV 样本
3. 在数据集详情页冻结数据集生成不可变快照版本
4. 在数据集详情页选择目标 chat Agent 发起异步测评 Run
5. 跳转到 Agent 详情页查看 Run 聚合指标与样本级结果
6. 在 Agent 详情页评估并查看 Run 级质量门禁结论（Gate）

首期范围：

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

评测数据集 CSV 模板

CSV Header 要求：

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

示例：

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

导入规则：

• 文件编码必须为 UTF-8（支持 UTF-8 BOM）
• 空 input 或空 expected 会返回 400 错误
• 导入动作会覆盖该数据集原有样本（replace 语义）
• 冻结数据集（is_frozen=true）不可导入，需先创建或冻结新的版本
• 发起 Run 仅允许选择冻结数据集快照（is_frozen=true）

执行链路

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

指标说明

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

• 规则评分：
• exact_match：归一化后完全一致记 1，否则 0
• token_f1：基于分词重叠的 F1
• pass_rate：当前实现等价于 EM（EM=1 则通过）
• LLM Judge：
• score：0 到 1 的语义匹配分
• reason：模型给出的简短理由
• raw_response_text：Judge 原始响应

Run 级聚合指标：

• score_em
• score_f1
• score_pass_rate
• score_llm_judge（Judge 可用时计算均值）
• gating_status（pass / fail / not_evaluated）
• gating_policy（本次 Gate 评估使用的阈值快照）
• failed_criteria（未通过时的具体失败条件）

分片指标：

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

相关端点

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

前端入口与迁移说明

• 新入口（主路径）：
• Evaluation -> Datasets
• /evaluation/datasets
• /evaluation/datasets/:datasetId
• 迁移兼容：
• AgentDetailPage 仍保留 Run 启动与结果查看能力。
• 数据集管理能力（创建/导入/冻结）已迁移到 Evaluation -> Datasets。

回归验证

1. 代码回归

uv run pytest

2. 文档回归

uv run mkdocs build

后续演进方向

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

最后更新

• 2026-03-04