Skip to Content

第 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 或 traceRunResult.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 区间,并和正态近似对比。