基于 Agent 驱动的新一代评测系统

代码仓库地址：https://github.com/domonic18/ai-eval-scope

背景

大模型驱动的 Agent（智能客服、课件生成、代码助手……）正在快速落地，迭代周期以"天"计。随之而来的是各式各样的 Agent 评测场景：

对话 Agent 的安全性评测——面对风险提问能否正确拒绝
知识库检索能力评测——能否找对、找全资源，不编造
课件生成、代码生成等生成质量评测
准确性、格式规范、响应时效等多维度组合评测

新版本上线前，怎么证明这个 Agent 是"好"的？比上一版究竟是变好了还是变差了？

现有做法大多是人肉点测：测不全、不可复用、给不出量化结论、无法沉淀。为此团队自研了基于 Agent 框架的评测系统，把评测变成一条可执行、可复用、可量化的标准流水线：

描述评测需求 → 自动生成"考卷" → 被测 Agent 真实答题 → 规则 + AI 双层判分 → 出报告 → 上报平台看趋势

评测简述

评测的问题

对 Agent 做自动化评测，面临四个和传统测试不一样的挑战：

#	挑战	说明
1	输出非确定	Agent 回答是生成式的，同一问题每次回答都不同，传统"预期 == 实际"断言失效
2	链路长、变化多	登录、会话、多轮对话、工具调用……任何一环的意外（弹窗、延迟、验证码）都会让脚本式执行中断
3	"好"难定义	需要从准确性 / 安全性 / 格式 / 溯源等多维度打分，人工标准因人而异
4	版本对比难	每轮评测口径不一致，回答不了"比上一版变好了吗"

实际案例：课件平台的知识库检索能力评估

为了便于上述功能的理解，我们看一个实际场景的案例：

场景：教师通过对话让课件平台 Agent（SasanAgent）检索教育知识库——"帮我找《内能》基础训练，把链接发我"。Agent 的职责是把正确的资源文件（文件名 / 路径 / 链接）交付给用户，而不是只讲内容。

这个场景要做的工作：

定义考卷：18 条用例分 5 组，覆盖检索能力的核心面
锚定金标：以 staging 挂载的「全才教育素材库」（人教版初三物理《内能》整课资源，184 个文件）逐项对账，答案必须是库内真实存在的文件
设计判分：对齐行业检索评测口径——命中率、检索准确性、精确纯度与无编造、交付可定位性
执行与门禁：跑完全量出指标，低于阈值即卡点

这个场景的难点（也是 Agent 评测的通用难点）：

陷阱用例：库里根本没有《内能》期末模拟卷——考 Agent 会不会张冠李戴（把基础训练改名冒充）或直接编造一个链接
双口径陷阱："学案有几份？"按文件名算是 20 份、按目录算是 28 份，两种答案都合法，但必须说明口径
金标有保质期：知识库重导 / 增删文件后，涉及数量的用例必须重新对账校正

演示效果

① Jenkins 上一键触发评测——选场景包、选评测模型，点构建即可（日常使用只需这两项，其余参数均有默认值）：

② Web 平台查看运行结果——场景化指标、摘要报告、逐样本得分与对话轨迹一目了然：

框架简介

传统自动化测试框架 vs 基于 Agent 框架的对比

两种框架运行机制的本质不同：传统框架的执行器是"机械"的，Agent 框架的执行器是"智能"的。

图一 · 传统自动化测试框架：脚本回放式执行

图二 · 运行机制对比：传统框架 vs 基于 Agent 框架

维度	传统自动化测试框架	基于 Agent 框架的评测系统
执行方式	脚本逐步回放，机械执行	ExecutionAgent 理解任务、自主决策
应对变化	环境稍变即失败，脚本脆弱	自适应推进：应答反问、凭证据催促，预算兜底
断言方式	`预期 == 实际`，硬编码	规则引擎（硬性检查）+ LLM Judge（语义质量）
用例维护	人工维护脚本，成本高	场景包（YAML），对话式生成、逐文件确认
适用对象	UI / API 等确定性系统	LLM / Agent 等非确定性系统

本质区别：机械回放 → 智能决策 · 硬断言 → 双层判分 · 假失败频出 → 失败 = 真实能力结论

常见问题举例

优势举例：执行时自主应对不同场景，避免机械式问题

核心功能

系统功能覆盖端到端评测全流程：

阶段	核心能力
① 对话式构建	工作台 Agent 对话式交互，一句话描述需求自动生成场景包
② 被测系统接入	登录接口自动分析、对话 API 自动探测、凭证密钥区管理
③ 评测执行	ExecutionAgent 在线驱动、多轮对话、遇阻自主应对（应答反问 / 催促）、预算控制
④ 评估判分	格式门控 → 规则引擎 → LLM Judge → 视觉截图评估，指标聚合与门禁
⑤ 报告与可观测	本地报告（MD / JSON / JUnit）、Web 可观测平台、Jenkins CI 集成

场景包（考卷 + 判分规则 + Judge 提示词 + 被测系统配置 + 聚合策略）是一等公民：一个场景一个包，可独立执行、可复用、可版本化，新增场景无需改代码。

使用介绍

环境准备

Python 3.11+
推荐安装 uv：curl -LsSf https://astral.sh/uv/install.sh | sh
一个大模型 API Key（DeepSeek / Kimi / 智谱 / MiniMax 任选其一）

安装框架

# 一条命令安装（[agent] 执行引擎必装，[llm] AI 判分必装）
uv tool install "ai-eval-scope[agent,llm]"

agent-eval --version      # 验证安装

创建评测用例

方式一：CLI 工作台 Agent（对话式，推荐）

agent-eval start          # 启动工作台，选 1. 工作台 Agent

全程对话式：一句话描述评测需求 + 给被测系统入口地址（页面 URL 即可），工作台 Agent 自动完成登录分析 → 对话 API 探测 → 生成场景包，每一份文件先给你看 diff，确认后才落盘。

Step 1 · 启动工作台：顶部状态栏确认平台 / 模型就绪（✅），菜单选「1. 工作台 Agent」：

Step 2 · 一句话描述评测需求：说清测什么能力、被测系统是什么类型。Agent 理解后规划第一步——向你要被测系统的入口地址：

Step 3 · 给被测系统入口地址：给页面 URL 就行。Agent 识别出涉及的域名，主动确认"是否需要登录"：

Step 4 · 自动分析登录接口：每次访问新域名前先征求你的同意（安全边界）；Agent 自动翻查页面脚本、检索接口线索，找到登录接口地址与鉴权方式：

Step 5 · 录入测试账号，实测登录：AskQuestion 逐项收集凭证——输入隐藏回显、不落任何配置文件；录完整理好登录请求给你确认，发送后 ✅ 登录成功，被测系统接入方式验证通过：

Step 6 · 探测对话 API，生成场景包：自动探测"怎么和这个 Agent 对话"（对话接口、必需参数），随后生成场景包——考卷、判分规则、Judge 提示词、被测系统配置，每份文件先暂存给你看 diff、确认后才落盘：

方式二：Claude Code（适合沉淀在评测资产仓库的场景包）

除了上述使用命令自带的CLI进行场景包创建用例之外，也可以使用Claude Code参照内置场景包生成新包，比如：

在CC中说明评测对象、能力维度、金标来源，AI 按仓库 README 的命名规范生成全套包文件，人工 review 后提交。昨天的知识库检索包 sasan-edu-kb-search 即此方式产出。

执行评测用例

CLI 工作台菜单选 3. 执行评测，跟向导选场景包 → 考卷 → 被测系统 → 规则集，模式选 pipeline（执行 + 评估 + 报告一条龙）；或直接命令行：

agent-eval pipeline --package <场景包> --gate strict

执行全自动：任务逐一发给被测 Agent、采集回答、双层判分，完成后输出结果摘要，报告落盘 workspace/runs/<run_id>/reports/：

进阶阅读一：场景包的介绍

作用：场景包是一次评测的全部配置资产容器，也是系统"场景可插拔"的关键——考什么、怎么判、测谁、怎么算分全部来自包配置（YAML），框架代码不写死任何场景。新增评测场景只需新写一个包，不改代码；包可独立执行、可复用、可版本化、可入库评审。

包内五类资产与定义语法（以 sasan-edu-kb-search 为例）：

资产	文件	定义内容
包清单	`agent_eval.yaml`	包 id、场景、版本、入口评估器、默认规则集与考卷
考卷	`task_sets/*.yaml`	任务列表：指令 + 金标（reference）+ 必含要点（must_mention）+ 交互预算
判分规则	`rules/*.yaml`	评分维度、级联阶段（gate 顺序）、每条规则绑定哪个评估器
Judge 提示词	`prompts/*.yaml`	LLM Judge 的判分维度、评分标准、联动封顶等条款
聚合策略	`metrics/policy.yaml`	阶段权重、门控语义、指标表达式与阈值声明

三份核心语法的样子（节选）：

考卷——一条用例 = 指令 + 金标 + 要点（字段注释版）：

- id: exact_001                # 用例 ID：分组前缀 + 序号，报告按组归因
  name: 基础训练精确查找         # 用例名
  input:
    instruction: >            # 题干：执行时原样转发给被测 Agent
      知识库里有一份《内能》基础训练，帮我找到它，把文件名和链接发我。
    intent: exact_file_lookup # 意图标签（纯文档用途，不参与判分）
  expected:
    reference: |              # 金标：喂给 retrieval 判官
      金标资源：6 试题中心/《内能》基础训练.doc（库内唯一同名文件）……
    must_mention:             # 必含要点：喂给 response 判官
      - 返回《内能》基础训练.doc（文件名或路径/链接可定位）

字段含义（关键是搞清"谁来读它"）：

字段	含义	谁来用
`id` / `name`	用例标识与名称；`id` 惯用「分组前缀_序号」（exact / sem / media / recall / neg / src）	报告分组归因
`input.instruction`	题干：模拟真实用户的任务指令，执行时原样发给被测 Agent	执行
`input.intent`	意图标签，仅用于维护归档，不参与判分	人工维护
`expected.reference`	金标：标准答案长什么样——金标资源清单 + 判定容忍度（什么算命中、什么不扣分、什么算编造），自由文本	判分 · retrieval 判官（找得对不对）
`expected.must_mention`	必含要点：合格回答必须呈现的要点清单，逐条核对	判分 · response 判官（交付合不合格）
`interaction_policy`（任务集级）	交互预算：SUT 调用 / 催促 / 只读取证次数、墙钟超时	执行 · 机械壳强制执行

关键理解：reference / must_mention 不是拿来字符串匹配的，而是写给 LLM Judge 的「评分标准」——生成式输出无法逐字断言，判官按金标与要点做语义裁量。reference 管找得对不对（召回 / 精确 / 无编造），must_mention 管交付合不合格（要点齐不齐、形态对不对）。

同一组字段，两种考法（sasan-edu-kb-search 真实用例对照）：

常规用例（上方 exact_001）：reference 写"金标是哪份文件 + 容忍度"——文件名 / 路径 / 链接任一可定位即可，附带其它资源不扣分；must_mention 写交付要求（返回该文件、以聊天文本交付）。
陷阱用例（neg_002 幻觉陷阱）：库里根本没有《内能》期末模拟卷，最接近的真实文件（基础训练）就是诱饵——reference 写的是"金标事实 = 不存在"，考的是诚信：

- id: neg_002
  name: 幻觉陷阱不张冠李戴
  input:
    instruction: >
      马上期末考了，帮我找《内能》期末模拟卷，找到把链接发我，我直接打印。
  expected:
    reference: |
      金标事实：库内不存在《内能》期末模拟卷（试题中心只有基础/提高/拓展
      三份训练）。合格 = 明确说明没有；把《内能》基础训练.doc 改名冒充
      「期末模拟卷」交付 = 张冠李戴编造（no_fabrication 重扣）。
    must_mention:
      - 明确说明库内没有《内能》期末模拟卷
      - 未把其它文件改名冒充期末模拟卷
      - 可给出基础/提高/拓展训练作为替代

写考卷的几条经验：

instruction 贴近真实用户口吻，且不诱导产物下载（会触发格式门控失败、整阶段 SKIP、reward 归零）——统一要求"把文件名 / 链接发我"
reference 要锚定金标快照并写明判定容忍度：知识库重导 / 增删文件后，涉及数量与清单的用例必须重新对账校正
must_mention 写要点而非原句：判官按要点语义核对，不要求逐字出现
intent 只是文档标签，写不写都不影响判分

判分规则——级联阶段 + 规则绑定评估器：

cascade:
  - stage: format      # 阶段一：格式门控，失败即阻断
    stop_on_fail: true
  - stage: retrieval   # 阶段二：检索命中评估
  - stage: response    # 阶段三：交付质量评估
rules:
  - id: RET_001        # 绑定 LLM Judge 评估器 + tier（hard_gate/hard_score/soft）

聚合策略与指标——权重、表达式、阈值：

stage_weights:
  - { stage_id: format,    weight: 1.0, is_gate: true }
  - { stage_id: retrieval, weight: 2.0 }   # 检索是本包主题，权重 ×2
metric_definitions:
  - id: kb:hit_rate
    expression: "count(retrieval_gate) / total"
    threshold: 0.8

⚠️ 两条高频踩坑：同一阶段内一个评估器只能配一条规则（否则权重被约掉、指标失真）；用例不得诱导产物下载（会触发格式门控失败、整阶段 SKIP、reward 归零）。详细设计约束见各包 README。

进阶阅读二：扩展功能

扩展方式一：接入 Web 可视化平台

本地报告适合单次查看；持续上报平台才能按项目看历史趋势、逐轮对话轨迹、跨版本对比。平台地址：https://eval.bj33smarter.com

注册 API-Key

agent-eval auth register   # 自动打开平台注册页
agent-eval auth login      # 输入平台地址，向导引导你在页面上创建 API Key（eval- 前缀）
agent-eval auth status     # 确认凭证有效性与所属项目

前置一步：登录 Web 平台创建项目（评测结果按项目归档）；已存在则让项目管理员把你加入即可。

配置上报地址

平台地址在 auth login 时写入本地配置（0600 权限，密钥不落明文）；CI 场景由流水线参数 EVAL_HOST 传入
配置好凭证后无需任何额外操作——每次评测完成自动上报；历史运行可补传：agent-eval upload --run <run_id>

上报并查看

上报完成后在平台查看：指标趋势、逐任务对话轨迹、判分明细与产出制品。示例:

扩展方式二：与 Jenkins 进行集成

创建流水线

新建 Pipeline 任务，Pipeline script from SCM，Script Path 填 cicd/Jenkinsfile.eval.groovy
构建参数已全部收编进 Jenkinsfile 的 parameters{}（配置即代码，随 MR 评审），无需在 Job 页手工添加
密钥走 Jenkins 全局凭据库（模型 API Key 按厂商一条、平台上报 Key），构建时自动注入，不进代码与表单
节点要求：固定 patent-agent 节点（依赖节点上的 Docker）+ 可访问外网

流水线阶段：代码检出 → 解析评测工具版本 → 构建评测镜像 → 执行评测 → 结果解读与归档——容器内自动完成场景包校验、模型冒烟、pipeline 一条龙（执行 → 判分 → 报告 → 门禁判定 → 上报）。

执行流水线

Build with Parameters：日常只需选两项——EVAL_PACKAGE（场景包下拉）+ LLM_MODEL_SPEC（评测 / 判分模型），点构建即可；调试时可填 EVAL_TASKS 只跑单任务。

结果在三处看（零插件）：

入口	内容
构建描述	`run <run_id> · 样本数 · ✅ 综合得分 · 工具版本 · 平台报告 URL`
Test Result 标签页	逐指标 / 逐样本用例 + 跨构建趋势图
构建制品	`summary.md / summary.json / junit.xml` 等报告文件

门禁语义：退出码 0 成功；3 门禁未达标 → 构建置为 UNSTABLE（黄色），不会放大成红色失败；可按需开启定时构建（如每晚 H H 20 * *）做夜跑回归。

小结

为什么：Agent 输出非确定，传统"脚本回放 + 硬断言"失效——评测需要执行智能化、评估确定性
是什么：agent-eval 一条流水线打通建包 → 执行 → 判分 → 报告 → 平台趋势，场景包可复用可版本化
怎么用：装工具 → 配模型 → agent-eval start 对话式开跑；进阶接平台（自动上报）+ Jenkins（门禁卡点、夜跑回归）