← Pi Agents

测试随机软件

单元测试、结构化测试和评估,回答关于包含模型的代码的三个不同问题;本章针对那个论断检查器把三者都构建出来,并展示为什么平均成功率掩盖了要紧的那个数字。

第 36 到第 40 章的测试全都通过了。它们告诉你的比你可能希望的要少,而把这一点准确地说清楚是值得的。

它们表明,当模型做了你脚本化的那些事情之一时,你的代码表现得正确。它们不能表明模型将会做什么。一个脚本化的 provider 从不拒绝、从不跑题、从不调用错误的工具。如果你停在全绿的测试上,那么除了那个随机的部分,你已经验证了一切。

有三种不同的活动在这里都被叫作"测试",而它们回答不同的问题。把它们区分开,就是本章的全部。

1. 脚本化测试         我的代码正确处理这个响应了吗?
2. 结构化测试         不论措辞如何,对的事情发生了吗?
3. 评估               在反复运行中,整个东西多久成功一次?

这三级,以及各自能触及什么

    flowchart TD
  subgraph L1["第 1 级 — 脚本化"]
    S1["脚本化一个响应<br/>断言你对它的处理"] --> R1["免费、确定性、在 CI 中"]
  end
  subgraph L2["第 2 级 — 结构化"]
    S2["运行真正的循环<br/>对事件断言"] --> R2["在脚本之下依然免费<br/>容忍措辞变化"]
  end
  subgraph L3["第 3 级 — 评估"]
    S3["k 次独立运行<br/>在真实任务上"] --> R3["花费请求、金钱、时间<br/>不确定"]
  end
  L1 -->|"一个你想到了的情形"| L2
  L2 -->|"一个你需要的比率"| L3
  L3 -.->|"绝不向上或向下替代"| X1["第 1 和第 2 级永远不会变成第 3 级"]
  

那些实线箭头是升级路径,而它们只朝一个方向走。那条虚线是那个值得说出口来的错误:一套全绿的第 1 级测试套件经常被报告成"智能体能工作",而这两句话说的是不同的事。

第 1 级:脚本化

第 36 章那个 faux provider 重放你写下的响应。测试完全控制模型,所以结果是精确且可复现的:

faux.setResponses([fauxAssistantMessage([fauxToolCall("submit", { severity: "high" })], { stopReason: "toolUse" })]);
assert.deepEqual(await step(models, model, "Triage.", "x", Triage), { severity: "high" });

这一级是针对碰巧包含一次模型调用的代码所做的单元测试。它是回答这些问题的正确工具:assess() 会拒绝一个破坏 schema 的东西吗,step() 会停在 maxAttempts 上吗,这条流水线会拒绝一个编造出来的引用吗。这些是你的代码的性质,而一次脚本化的运行证明它们,不需要网络、密钥或账单。它属于每一次 CI 运行。

它的极限是内建的。模型说的正是你让它说的东西。所以一个通过的脚本化测试,是关于你对那个响应的处理的证据,而对于模型会产出它,则完全没有证据。

一个响应也可以是一个函数。fauxProvider 接受一个工厂,它接收送给那个 provider 的转录记录;第 39 章检查 transformContext 改变了被送出去的东西,用的就是这个。用它来对请求断言,而不只是对回复。

有一个陷阱:不要写那些只是把脚本重述一遍的断言。一个脚本化 "supported" 然后断言 "supported" 的测试,测试的是那个 faux provider。要对你的代码拿那个答案做了什么断言。

对于那个 faux provider 能为你制造什么、不能制造什么,要同样清楚。它很乐意脚本化一次拒绝、一段跑题的答案、一次错误的工具调用或一次畸形的提交——那些是值得放进一套测试里的情形,而它们全都是你选定的情形。它无法产出一个自发的意外。一次脚本化测试所锻炼到的一切,都是你预料到并写下来的行为,这使这些测试极擅长在你对响应的处理里找出回归,而在结构上无法找出一个你没想到的失败模式。第 3 级就是为那个而存在的,而第 1 和第 2 级永远不能替代它。

第 2 级:结构化

第二级对发生了什么断言,而不对说了什么断言。模型的措辞会变,而事件结构不会。一次结构化测试在脚本之下运行那个真正的循环,并检查那些事件。注意它在这里演示了什么、没有演示什么:在脚本之下,措辞按构造就是固定的,所以这个测试表明的是那些断言是关于事件的,而不是当真实模型的措辞变化时事件会保持稳定。第二个论断需要第 3 级。下面的示例驱动一个内联构建的小 submit 智能体,而不是那个论断检查器;而一次结构化测试擅长的另外两件事——断言没有调用允许集合之外的任何工具,以及一次拦下之后什么都没有运行——是本书提出的用途,本书对它们没有测试(第 39 章那道闸门的测试直接测量第二件):

assert.ok(events.includes("tool:submit:ok"));
assert.equal(faux.state.callCount, 1, "terminate must save the follow-up request");
assert.equal(events.filter((e) => e === "turn_start").length, 1);

断言正确的工具运行了、循环花了预期的轮次数、没有调用允许集合之外的任何工具、一次拦下之后什么都没有运行。如果你换掉模型,那些陈述依然为真,而它们是当你把同样的检查指向一个真实 provider 时要带进第 3 级的那一些:那些话每次运行都会不同,而结构不应该。

请求数是一个格外好的结构化断言,因为它同时是一个成本和一种行为。“那条便宜路径恰好发出两次请求"是对一条流水线经济性的回归测试。

第 3 级:评估

现在问题变了。你不再问代码是否正确。你在问一个带有随机成分的系统多久产出一个可接受的结果。那是被测量出来的,而不是被断言出来的,而单独一次运行什么也测量不到。

// Level 3 of chapter 41: evaluation. A scripted provider cannot tell you how
// often a real model gets it right. Repeated runs can, and the number to read
// is not the average.

export interface Task<T> {
	id: string;
	run: () => Promise<T>;
	passes: (result: T) => boolean;
}

export interface EvalResult {
	tasks: number;
	k: number;
	/** Mean single-run success rate. What a demo reports. */
	passAt1: number;
	/** Fraction of tasks that succeeded on ALL k independent runs. What a service needs. */
	passPowK: number;
}

export interface EvalOptions {
	/** Wall-clock budget for the whole evaluation. Per-run, not per-task, so a
	 *  task that hangs cannot hang the evaluation past its share of the budget. */
	timeoutMs?: number;
	/** Injected for tests; defaults to the platform timer. */
	timeout?: (fn: () => Promise<unknown>, ms: number) => Promise<unknown>;
}

const defaultTimeout = (fn: () => Promise<unknown>, ms: number) =>
	new Promise((resolve, reject) => {
		const t = setTimeout(() => reject(new Error(`timed out after ${ms}ms`)), ms);
		fn().then(resolve, reject).finally(() => clearTimeout(t));
	});

// An empty task list divides by zero and reports NaN for both rates, which reads
// as a result. A non-positive k makes pass^k vacuously 0 and pass@1 meaningless.
// Both are caller mistakes, and the numbers they produce look like measurements.
export async function evaluate<T>(tasks: Task<T>[], k: number, options: EvalOptions = {}): Promise<EvalResult> {
	if (!Number.isInteger(k) || k < 1) throw new Error(`k must be a positive integer, got ${k}`);
	if (!tasks.length) throw new Error("evaluate needs at least one task; an empty list has no rate to report");
	const guard = options.timeout ?? defaultTimeout;
	const budget = options.timeoutMs;
	// Spread the budget over the runs, with a floor, so one run cannot consume the
	// whole evaluation's allowance.
	const perRun = budget ? Math.max(1, Math.floor(budget / (tasks.length * k))) : undefined;

	let single = 0;
	let allK = 0;
	for (const task of tasks) {
		let wins = 0;
		for (let i = 0; i < k; i++) {
			try {
				const result = perRun ? await guard(() => task.run(), perRun) : await task.run();
				if (task.passes(result as T)) wins++;
			} catch {
				// A step that throws, or times out, is a failed run. Not a crashed
				// evaluation: the point of pass^k is that a run which did not work
				// counts against the task, and a timeout is exactly that.
			}
		}
		single += wins / k;
		if (wins === k) allK++;
	}
	return { tasks: tasks.length, k, passAt1: single / tasks.length, passPowK: allK / tasks.length };
}

// Deterministic pseudo-randomness, so an evaluation of a *simulated* model is repeatable.
export function seeded(seed: number): () => number {
	let a = seed >>> 0;
	return () => {
		a = (a + 0x6d2b79f5) >>> 0;
		let t = a;
		t = Math.imul(t ^ (t >>> 15), t | 1);
		t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
		return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
	};
}

出来两个数字,而它们之间的差距就是教训。

passAt1 是单独一次运行的平均成功率。它是一个演示所报告的东西:“它大约 86% 的时候能用”。

passPowK,写作 pass^k,是在 k 次独立运行的每一次上都成功的那些任务所占的比例。它是一个服务所需要的东西:对于一个给定输入,当我调用它时它能工作,当我再次调用它、然后又调用它时,它也能工作吗?

那个测试模拟一个在每个任务上都有 85% 的时候为对的模型,跨 40 个任务、每个任务 5 次运行,用一个带种子的生成器,好让这个模拟可复现:

pass@1 = 0.86
pass^5 = 0.45

第一个数字读起来是健康的。第二个数字说的是,在过半的任务上,五次相同运行中至少有一次失败了。它们并不矛盾。如果每次运行都以概率 0.85 独立地为对,那么连续五次约为 0.85⁵,接近 0.44,这正是那个模拟产出的结果。平均值掩盖了可靠性是向下复合的。

要清楚这演示了什么、没有演示什么。那个"模型"是一个从带种子的随机生成器里抽样的脚本化函数。这个测试演示的是那个算术和那个测试骨架。它对于任何真实模型的比率什么都没告诉你。一次真实的评估把那个模拟的 run 换成对一个真实 provider 的调用,并且没有种子。

对着一个真实模型运行它

变化在于 run 如何被构建,而那个测试骨架里别的什么都不动:

import { builtinModels } from "@earendil-works/pi-ai/providers/all";

const models = builtinModels();
const model = models.getModel("anthropic", "claude-sonnet-5")!;

const tasks = cases.map((c) => ({
	id: c.id,
	run: () => assess(models, model, c.claim, c.evidence),
	passes: (r) => r.verdict === c.expected,
}));

const result = await evaluate(tasks, 5);

有文档记载的 API,本书的测试套件没有运行它,因为它需要一个凭据,而且要花钱。有四条规则让这个数字有意义:

  • **记录你测量了什么。**模型标识符和版本、日期、k、任务数量,以及被锁定的 Pi 发布版本。一个没有附带模型的 pass^k 是一个没有意义的数字。
  • **用你没有在其上调过参的情形。**如果你编辑提示词,直到你那二十个例子通过,那么你测量到的是你的提示词对那二十个的拟合。
  • **把要紧的那些失败包含进来。**那个编造出来的引用、那份矛盾的证据、那条根本没有相关证据的论断。一个只由容易情形构成的集合,测量不到任何会伤害到你的东西。
  • 把一个抛出的步骤算作一次失败的运行。evaluate() 就是这么做的,而一个测试现在锻炼那个分支:一次抛出的运行被算作一次失败,而评估继续下去。(第一个版本的模拟模型从不抛出,所以那个分支未经测试,这是一次独立评审抓住的。)一个引发 StepFailed 的步骤是一个结果,而不是一次崩溃,而 StepFailed.kind 让你能把 provider 失败和一个不照办的模型分开计数。
  • 对那些输入做校验,因为失败是静默的。evaluate() 现在拒绝一个空的任务列表和一个不是正整数的 k。两者否则都会产出数字:一个空列表会除以零,并为两个比率都报告 NaN,而 k = 0 会让 pass^k 空洞地为 0,同时 pass@1 失去意义。结果表里的一个 NaN 很容易被一眼扫过,而一个空洞的 0 看着像一次测量。还有两个测试覆盖这些。
  • **给这次评估一个截止期限。**一次 pass^k 运行是对着一个真实模型发出 tasks × k 个请求,而一个无界运行的失败模式,是一次永远不结束、什么也不报告的运行。evaluate() 接受 timeoutMs,把它摊到那些运行上,并把一次超时算作一次失败的运行——它确实是。这是本书的模式,不是 Pi 的。

把这三级放在一起

脚本化 结构化 评估
问题 我的代码处理这个响应吗? 对的事情发生了吗? 它多久成功一次?
模型 faux,完全脚本化 faux 或真实 真实
确定性 是 在脚本之下是 否
花费 无 在脚本之下无 请求、金钱、时间
运行 每次提交 每次提交 按计划,以及当模型或提示词改变时
一次失败意味着 你代码里的一个 bug 一个 bug,或一次行为改变 系统不那么可靠了,或模型变了
一次通过意味着 你的代码处理了那个情形 结构守住了 一个被测量出来的比率,带着你必须自己提供的误差范围

常见的失败是替代:把第 1 级当作第 3 级。一套全部通过的脚本化测试说的是"那个管路是正确的”,而团队听到的是"智能体能工作"。这两句话说的是不同的事,而只有第二句是关于模型的。

那些数字没有说什么

四十个任务乘五次运行是 200 个请求,并给出一个误差很大的 pass^5。在本章的模拟里,那"四十个任务"是一个任务重复四十次,所以那 200 个请求是对一枚 85% 的硬币的 200 次抛掷,而所引用的那些数字(0.86 和 0.45,在测试里被精确锁定)描述的是那枚硬币,而不是四十个不同的问题。对于真正互不相同的任务,那个分布会不同,通常更分散。两个提示词之间几个百分点的差异,在那个规模上大概是噪声。如果一个决定取决于那个差异,就跑更多任务,并且不要把单独一次评估读成一次精确的测量。

一次通过也意味着"答案与你标为正确的东西相匹配"。那只有标签那么好。在有多个答案可接受的地方,passes 必须说出这一点。

而一个结果描述的是某一个时刻的一个模型。provider 在一个稳定的名字背后更换模型。上个月的一个 pass^k 是一个关于上个月的陈述,这就是为什么上面第一条规则里那份记录不是记账。

那个外部的想法

pass^k 作为一种测量智能体可靠性的方式,不是本书的发明。参考文献在附录 A 里,它也标示出从那个工作里引用的数字没有在这里被独立验证。上面使用的那个定义独立成立:它是 eval.ts 里的代码,而那个算术可以手工核对。

你能和不能论断什么

*有文档记载:*那个 faux provider 及其响应工厂(pi-ai README 与声明,1.0.4)。

已观察:examples/ch41-testing/ 里的那四个测试。尤其是那个模拟的 85% 模型在 40 个任务上、以种子 42、在 1.0.4 上给出 pass@1 为 0.86、pass^5 为 0.45。**那个数字是这个模拟的一个性质。**它不是对任何真实模型的测量。

*本书提出:*这三级的区分、一次有意义的评估的那些规则,以及表里那个时间安排。这些是实践,不是 Pi 的契约。

下一章

你有了一个带类型、经过组合、被守护且被测量过的论断检查器。你还没有问过的是,它被允许影响什么。它读一个语料库。如果它也能写一个、发一条消息或运行一条命令,那么前面那五章没有一章会告诉你它应不应该。

最后一章讲的是一个智能体能做什么和它可以做什么之间的区别。