第 2 章
评测方法论术语地图
一个 92% 的三种理解
设想一场复盘会。值班助手的评测报告显示:50 条任务通过 46 条,92%。负责数据集的人认为可以发布。负责线上的人问:这是每条任务只跑一次的结果吗?改生产配置的任务要每次都过才算数。写工作流的人接着问:一共只跑了 50 条,这个 92% 的误差有多大?
三个人看的是同一个数字,对“通过”和“分数”的理解却各不相同。本章给后面各章反复用到的词定一个统一口径。第 1 章确定了评测对象是 harness 和 model 组成的端到端系统,这一章给出描述这个系统所需的词汇,每个词配一段值班场景里能运行的最小代码。
评测的基本单位
先定义评测流程里的几个名词。命名沿用 Anthropic 的 Demystifying evals for AI agents,右列是它们在本书评测层 harness-lab(第 5 章)里对应的代码:
| 术语 | 含义 | 在 harness-lab 里 |
|---|---|---|
| 任务(task) | 一条有明确输入和成功标准的测试 | EvalTask |
| 试验(trial) | 对一个任务的一次运行。模型输出每次不同,所以同一任务要跑多次 | 一次 adapter.run(task) |
| 运行记录(transcript) | 一次试验的完整记录:输出、工具调用、推理和中间结果,也叫 trajectory 或 trace | RunResult.steps、RunResult.trace |
| 结果状态(outcome) | 试验结束时环境里的最终状态,不是 agent 自己声称完成了什么 | RunResult.finalState |
| 评分器(grader) | 给试验的某个方面打分的逻辑,一个任务可以挂多个 | Mastra 的 scorer |
| 评测集(eval suite) | 为衡量某类能力或行为收集的一组任务 | 第 6 章的任务集 |
| 评测 harness | 端到端运行评测的基础设施 | harness-lab |
“评测 harness”和第 1 章说的 agent harness 都叫 harness,前者是跑评测的设施,后者是被评的系统。本书单说 harness 时,指后者。
用这几个词,可以把两条基本要求说清楚:
- 每次试验都从干净、隔离的环境开始。试验之间共享状态,会让失败彼此相关,或者让分数虚高。第 5 章的适配器每次运行都会重建
world,就是为了满足这一条。 - 优先给结果状态打分,不要把步骤顺序卡死。agent 换一条同样合理的路径完成任务,卡死顺序的测试就会误判。运行记录仍然要读:不读运行记录,就无法确认评分器本身判得对不对。
三种评分器
评分器按判定方式分三种,各有长处和代价:
| 评分器 | 长处 | 代价 | 值班场景里评什么 |
|---|---|---|---|
| 代码评分器 | 快、便宜、客观、可复现 | 对“换个写法也对”的情况很脆 | 配置改没改对、该升级时有没有升级 |
| 模型评分器(LLM judge) | 灵活,能评开放式输出 | 结果有随机性,更贵,要用人工评分校准 | 升级说明写得清不清楚 |
| 人工评分 | 质量的金标准 | 贵、慢,规模上不去 | 抽样校准模型评分器 |
选择的原则是:能用代码判的,就不用 LLM 判。值班助手的评测里,凡是有客观终态的判断都用代码评分器,只有措辞清晰度这类主观质量才用 judge,并定期抽一批让人复评,检查 judge 有没有跑偏。第 7 章算整体分时,骨架是代码评分器对结果状态的比对,judge 只是附加的一维。
Mastra 两种评分器都提供。代码评分器在 packages/evals/src/scorers/code/ 下,如 keyword-coverage、tool-call-accuracy,以及按动作序列比对的 trajectory;另有一组不调用 LLM 的 Quick Checks(checks.calledTool、checks.didNotCall 等)。模型评分器在 packages/evals/src/scorers/llm/ 下,如 answer-relevancy、faithfulness。两种都用 createScorer 构造,区别在于有没有 judge 字段。下面是本章示例里评升级说明清晰度的 judge 评分器:
import { createScorer } from '@mastra/core/evals';
import { z } from 'zod';
const JUDGE_INSTRUCTIONS = `
你是评估值班升级说明清晰度的裁判。给定一段升级说明,判断它是否清楚说明了:
1) 改动了什么 2) 为什么有风险 3) 需要人确认什么。
三点都清楚给高分,含糊或缺失给低分。
`;
/** 造一个评升级说明清晰度的 LLM judge scorer;model 由调用方注入 */
export function createEscalationClarityScorer(model: unknown) {
return createScorer({
id: 'escalation-clarity-scorer',
name: 'Escalation Clarity Scorer',
description: '质量判定:升级说明写得清不清楚(LLM judge,有方差)',
judge: {
model: model as never, // 换成你实际在用的模型 id,如 'openai/gpt-4.1'
instructions: JUDGE_INSTRUCTIONS,
},
type: 'agent',
})
.analyze({
description: '让 judge 给清晰度打 0~1',
outputSchema: z.object({ clarity: z.number().min(0).max(1) }),
createPrompt: ({ run }) => {
const note = String((run as { input?: unknown }).input ?? '');
return `请给下面这段升级说明的清晰度打 0 到 1 的分,只返回 { "clarity": 数字 }:\n${note}`;
},
})
.generateScore(({ results }) => results.analyzeStepResult?.clarity ?? 0);
}同一段说明交给它打两次分,结果可能不同;把 judge 去掉、在 generateScore 里写确定的比较逻辑,就得到一个代码评分器。完整的对照见本章 examples/src/code-vs-quality.ts。
下面按“你想问系统什么”把其余术语分成四组。
第一组:整体分 Φ(H)
第一个问题是:这套值班助手整体行不行?本书把整体效果指标记作 Φ(H):让 harness 配置 H 跑完整个评测集,按某种口径聚合出的总分,最常见的是任务成功率。后面讨论“某个改动让系统好了多少、坏了多少”,比较的都是不同 H 的 Φ。
Φ(H) 怎么算是第 7 章的内容:并发回放评测集,用代码评分器比对每条任务的结果状态,再聚合。这里只需要记住一点:Φ(H) 是统计量,不是真值。同样 50 条任务再跑一遍,或者换 50 条,数字都会变。报 Φ 时必须带上它的不确定性,见本章后面的“置信区间”一节。
第二组:模块归因
整体分回答不了“靠的是哪个模块、哪个模块在拖后腿”。最直接的办法是消融实验(ablation):关掉模块 i 重新跑,看整体分掉了多少。这个差值就是模块 i 的消融贡献:
Δi = Φ(H) − Φ(H−i)
H−i 表示从完整 harness 里去掉模块 i 后的配置。第 5 章的适配器提供 withConfig({ disable: [...] }) 来构造这种变体,第 9 章用它做消融。
各模块的 Δi 不能相加:
ΣΔi ≠ Φ(H) − Φ(空)
原因是模块之间有交互。查 runbook 的工具和升级判断可能是协同关系,单独留哪个都不管用,两个都在才有效;也可能是冗余关系,两个都能独立兜底,去掉任意一个分数都不掉,各自的 Δ 都是 0,但同时去掉系统就会垮。下面的玩具函数里,book 和 flow 带一个协同项:
// Φ:开启哪些模块返回成功率;book 和 flow 有协同项,是不可加的根源
function phi(on: Set<string>): number {
let s = 0.3; // 空配置也能蒙对一些
if (on.has('logs')) s += 0.2;
if (on.has('book')) s += 0.05; // 单独贡献很小
if (on.has('flow')) s += 0.05; // 单独贡献很小
if (on.has('book') && on.has('flow')) s += 0.25; // 协同项:俩一起才兜得住
return Math.min(1, s);
}
const ALL = ['logs', 'book', 'flow'];
const full = new Set(ALL);
const phiUp = phi(full) - phi(new Set()); // 整体提升 Φ(H)−Φ(空) = 0.550
// 逐一消融:Δi = Φ(H) − Φ(H−i)
const sumDelta = ALL.reduce((acc, i) => {
const minusI = new Set(full); minusI.delete(i);
return acc + (phi(full) - phi(minusI));
}, 0);
// ΣΔi = 0.800 ≠ phiUp = 0.550:协同项在 book 和 flow 的 Δ 里各算了一次因为消融差值不可加,本书把贡献度归因分成三档,分三章讲:
| 档位 | 回答的问题 | 代价与局限 | 章节 |
|---|---|---|---|
| 消融差值 Δ | 这个模块平均值不值得留 | 算得快,但不可加,处理不了模块交互 | 第 9 章 |
| Shapley 值 | 公平地说,每个模块各占多少功劳 | 对所有加入顺序的边际贡献取平均,可加;模块一多就要用蒙特卡洛近似 | 第 10 章 |
| 反事实根因 | 这一次失败具体栽在哪一步 | 针对单条失败的运行记录,不给模块级结论 | 第 11 章 |
第 10、11 章引用的 ShapleyFlow、AgentSHAP 等工作是 2026 年的预印本,本书标为“前沿探索”,并用最小代码自己复现近似算法。
第三组:稳定性
agent 和传统软件测试最大的不同,是同一条任务、同一套 harness,跑十次可能成八次、败两次。来源包括模型采样的随机性、工具返回的不确定性、并发时的顺序变化和外部依赖。同一输入多次试验结果不一致的程度,本书叫 flakiness(抖动),是第 12 章的主题。
衡量抖动要分清两个指标,k 指同一条任务的试验次数:
- pass@k:k 次试验里至少成功一次的概率,衡量能力上界。
- pass^k:k 次试验全部成功的概率,衡量可靠性。
一条单次成功率 0.9 的任务,pass@3 = 1 − 0.1³ ≈ 0.999,pass^3 = 0.9³ = 0.729。也就是说,同一条任务连跑三次,三次都成功的概率只有七成出头。
生成多个候选、挑一个对的就行的场景(例如代码生成),看 pass@k。值班助手改生产配置,要求每次都对,看 pass^k。
在评测集上算 pass^k 还有一个细节:每条任务有自己的单次成功率,要逐任务算 p^k 再取平均,不能先把成功率平均再乘方。两条任务成功率分别是 1.0 和 0.8,平均都是 0.9,但评测集的 pass^3 是 (1.0³ + 0.8³) / 2 ≈ 0.756,不是 0.729。抖动集中在哪些任务上,决定了这个数。
/** pass@k:k 次试验里至少成功一次的概率。乐观,衡量能力上界 */
export function passAtK(p: number, k: number): number {
return 1 - Math.pow(1 - p, k);
}
/** pass^k:k 次试验全部成功的概率。悲观,衡量可靠性 */
export function passHatK(p: number, k: number): number {
return Math.pow(p, k);
}
/** 评测集上的 pass^k:每条任务有自己的单次成功率,先逐任务算 p^k 再平均 */
export function suitePassHatK(taskRates: number[], k: number): number {
return taskRates.reduce((sum, p) => sum + passHatK(p, k), 0) / taskRates.length;
}另一个容易和 pass^k 混淆的现象是多步任务的成功率累积:一次运行要连做 3 步,每步成功率 0.9,整条成功的概率也是 0.729。数值相同,含义不同:pass^k 是同一任务重复 k 次试验,累积是一次试验内部的 k 步。开头那位写工作流的人担心的是后者,负责线上的人要求的是前者。
第四组:人在回路
最后一类问题只有 agent 才有:多步任务里,值班助手该不该在某一步停下来问人?该停没停(漏升级),可能直接改坏生产;不该停却停了(过度打断),用的人会不再理它。这两类错误不在任何一条输出里,而在“要不要停”的决策上。
本书把它建模成逐步的二分类:每一步,系统要么停下来问人或升级,要么继续。于是可以用分类指标衡量,本书定义为 Ask-F1:
- precision(精确率):系统选择问人的时刻里,真正该问的比例。偏低说明它经常无谓打断。
- recall(召回率):真正该问人的时刻里,系统实际问了的比例。偏低说明它该问时不问,第 1 章的故障就属于这一类。
- Ask-F1:precision 和 recall 的调和平均。
两类错误的代价通常不对称:漏升级一次可能搞挂生产,过度打断只是烦人。实践中可以调权重,偏向保住 recall。判定依据来自任务的 oracle:mustEscalate 标记这条任务该不该升级,评分器拿系统的实际选择(RunResult.askEvents)和它比。第 13 章给出 Ask-F1 的完整计算,并用 Mastra workflow 的 suspend / resume 实现“停下来问人”。这一组引用的 HiL-Bench 同样是 2026 年的预印本,第 13 章和附录 B 会标明出处和复现情况。
置信区间
上面每一组报出来的都是统计量,所以都离不开置信区间(confidence interval,CI),也叫误差棒。
50 条任务成功 46 条,得到 92%。这是真实成功率的一个估计,换一批任务或者重跑一遍,数字会变。置信区间给这个估计配上范围:46/50 的 95% 置信区间约为 [81%, 97%]。按这种方法构造的区间,在反复抽样中约有 95% 会覆盖真实成功率。
开头那场会上,有人想用“92% 高于上一版的 88%”来拍板。88% 对应 44/50,区间约为 [76%, 94%]。两版差 4 个百分点,在 50 条样本下,这点差异可能只是噪声。判断两版是否真有差别,要对差值做检验,只看两个区间重不重叠是偏保守的粗略判断,第 4 章会展开。
成功率这种二项比例,样本少或者比例接近 0、1 时,教科书上的正态近似 p ± 1.96·√(p(1−p)/n) 会失真,上界甚至会超过 100%。这时应该用 Wilson 区间,依据见 Evan Miller 的 How Not To Sort By Average Rating(附录 B 收录):
// Wilson 区间:n 次试验成功 success 次,返回 95% 置信下/上界
// 比正态近似 p±1.96·√(p(1-p)/n) 在小样本/极端比例下稳健得多
function wilsonInterval(success: number, n: number): { lower: number; upper: number } {
if (n === 0) return { lower: 0, upper: 1 };
const z = 1.96; // 95% 置信水平
const p = success / n;
const denom = 1 + (z * z) / n;
const center = (p + (z * z) / (2 * n)) / denom;
const margin = (z * Math.sqrt((p * (1 - p)) / n + (z * z) / (4 * n * n))) / denom;
return { lower: center - margin, upper: center + margin };
}
// 46/50 → 约 [0.81, 0.97]LLM judge 自身打分的波动是另一种噪声,要靠对同一输入多次打分来估计,也在第 4 章讲。
能力评测与回归评测
同一组指标可以服务两种目的,数据集和通过标准都不一样:
| 能力评测(capability eval) | 回归评测(regression eval) | |
|---|---|---|
| 目的 | 找到系统做不好的事,给团队一个往上爬的目标 | 保证已有行为不退化 |
| 通过率 | 起点应该低 | 应该接近 100% |
| 数据集 | 持续加入新的难题 | 相对固定的保留集 |
| 运行节奏 | 阶段性摸底 | 每次提交都跑,作为变更门禁 |
| 值班场景举例 | 连改三处配置、中途监控报警、还要判断是否升级 | 以前稳定通过的查日志、单项改配置任务 |
能力评测里的任务,通过率稳定在高位之后,就可以“毕业”转入回归评测集。拿能力评测的难题做回归门禁,会天天误报;拿回归任务衡量能力,分数永远好看。Mastra 的 runEvals 支持 gates 和 thresholds,可以直接把回归评测接进 CI。第 6 章构建任务集、第 16 章做防劣化闭环时,都会用到这个区分。
术语在评测流水线里的位置
这些词对应同一条流水线上的不同位置。一条任务进来,适配器把它跑成一个 RunResult,其中的结果状态、运行记录和问人事件分别交给不同的评分器,最后聚合成带误差棒的分数,决定这版 harness 能不能放行。数据流向如图 2-1 所示。
图 2-1:一次评测的数据流向。各组术语分别对应流水线上的一段。
图 2-1 里,finalState 交给代码评分器比对;升级说明从 askEvents.payload 取出交给 judge;askEvents 和 oracle 的 mustEscalate 比对得到 Ask-F1;同一任务重复试验才能估 pass^k。这些分数聚合成 Φ(H) 之后,一边按 withConfig 关模块做归因,一边套上置信区间,用来判断两版之间的差异是否显著。
图 2-2 换一个角度,按归属关系把本章的术语摆成一张地图。
图 2-2:harness 评测术语地图。各节点展开的章节见下一节的导航表。
术语导航表
第 1 章末尾的表按“要装什么能力”组织,这张表按“你想问系统什么”组织,两张对照着用:
| 术语 | 回答什么问题 | 主要评分方式 | 展开章节 |
|---|---|---|---|
| 任务 / 试验 / 运行记录 / 结果状态 | 评测流程里的基本对象分别是什么 | — | 本章、第 5 章 |
| 代码 / 模型 / 人工评分器 | 这项判断该用代码、LLM 还是人 | — | 本章、第 4 章 |
| Φ(H) 整体效果指标 | 这套 harness 整体行不行 | 代码为主 | 第 7 章 |
| 消融 Δi = Φ(H) − Φ(H−i) | 某个模块值不值得留 | 代码 | 第 9 章 |
| 贡献不可加 ΣΔi ≠ 总提升 | 为什么不能把 Δ 加起来 | — | 第 9 章 |
| Shapley 值 | 每个模块公平地占多少功劳 | 代码 | 第 10 章(前沿) |
| 反事实根因 | 这一次失败栽在哪一步 | 代码 | 第 11 章(前沿) |
| pass@k | 最好情况下够不够得着 | 代码 | 第 12 章 |
| pass^k | 能不能每次都成功 | 代码 | 第 12 章 |
| flakiness 抖动 | 同一输入多次试验有多不一致 | 代码 | 第 12 章 |
| Ask-F1 | 该不该停下来问人,问得准不准 | 代码 | 第 13 章 |
| 能力评测 / 回归评测 | 是在探上限还是守底线 | — | 第 6、16 章 |
| 置信区间 / Wilson 区间 | 这个分数的误差有多大 | — | 第 4 章 |
后面各章用到这些词时,口径都和这里一致。
小结
- 评测的基本单位是任务、试验、运行记录和结果状态。每次试验从干净环境开始,优先给结果状态打分,同时要读运行记录。
- 评分器有代码、模型、人工三种。能用代码判的不用 LLM 判,LLM judge 要用人工评分校准。
- 模块的消融差值 Δi = Φ(H) − Φ(H−i) 不可加,模块间的交互要靠 Shapley 值分账,单次失败要靠反事实定位。
- 衡量可靠性看 pass^k。它指同一任务 k 次试验全部成功,和一次运行里多步成功率的累积是两回事;评测集上要逐任务计算再平均。
- 任何评测分都要带置信区间,小样本用 Wilson 区间;两版比较要做差异检验。
- 能力评测从低通过率起步,回归评测要求接近 100%,任务稳定通过后从前者转入后者。
配套代码
本章 examples/ 下有四个脚本,除 judge 打分外都不需要 API key:
npm run code-vs-quality:同一个值班场景,用代码评分器判“配置改对没有”,用 LLM judge 评“升级说明清不清楚”。judge 需要配置模型 key 才会真正打分。npm run passk:计算 pass@k 和 pass^k,用蒙特卡洛验证,并演示评测集上逐任务计算和先平均再乘方的差别。npm run ablation:三个模块逐个消融,对比 ΣΔi 和整体提升。npm run wilson:对 46/50 等样本计算 Wilson 区间,并和正态近似对比。