评测与基准

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

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

已落地能力（Admin 后台）

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

1. 创建评测数据集（平台共享）
2. 导入 CSV 样本
3. 对指定 chat Agent 发起异步测评 Run
4. 查看 Run 聚合指标与样本级结果

首期范围：

• 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 语义）

执行链路

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

状态机：

• 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 可用时计算均值）

相关端点

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

回归验证

1. 代码回归

uv run pytest

2. 文档回归

uv run mkdocs build

后续演进方向

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

最后更新

• 2026-02-28