源码篇第11章 每次考试换新考场——pi-evals ​

小A在摆有参考书的评测工位完成任务,老Z在旁核对另一张结果卡片。

本章导读: 源码路线第 ⑩ 站(评测层)。看 pi-evals 包,读 src/harness.ts、src/plan.ts、src/report.ts 和 evals/ 下的用例。这一站要泼一盆冷水:“跑通了”不等于“改对了”,看看评测 harness 怎么用临时环境和 artifact 留下可复查的证据,faux 测试和真实模型测试的证据等级差在哪,以及“有文档和没文档”的对照实验怎样避免把偶然当成结论。

小A终于把自己的 Agent 改到了能跑,长舒一口气:“跑通了!这次应该没问题了吧?”

“跑通一次,和改得好不好,是两回事。”老Z说,“协议和远程状态可以被测试,但‘模型改得好不好’不能只靠一次成功运行。这一章我们跟着 pi-evals 的 harness,看环境怎么隔离、模型怎么选择、judge 到底能证明什么。别把评测分数当普适能力排名。”

本章源码证据均来自上游 pi 标签 v1.0.0(提交 a13d35a7,packages/evals/,包版本 1.0.0,private: true)。v1.0.0 重新组织了这个包:运行器代码在 src/,用例和夹具在 evals/,镜像构建文件在 docker/。README.md 把用例分成两类:*.docs.eval.ts 是文档增益评测,其余 *.eval.ts 是在本机跑的普通 host 评测。

harness 建立一次隔离运行 ​

“先看运行环境。”老Z打开 packages/evals/src/harness.ts:“createPiCodingAgentHarness 用 vitest-evals/harness 的 createHarness 包出一个 harness,run 回调进入 runPiCodingAgent。每次运行都用 mkdtemp(join(tmpdir(), "pi-eval-")) 建临时根目录,再在里面放独立的 workspace、home、agent 目录和 session 目录。”

ts
// packages/evals/src/harness.ts,runPiCodingAgent(v1.0.0,节选)
const root = await mkdtemp(join(tmpdir(), "pi-eval-"));
const workspace = join(root, "workspace");
const isolatedHome = join(root, "home");
const agentDir = join(isolatedHome, ".pi", "agent");
// ……
const restoreEnvironment = applyIsolatedEnvironment(isolatedHome, agentDir);

比喻:每次考试换新考场

临时 cwd 像每次换新考场,上一次的草稿纸不会留在桌上。

“applyIsolatedEnvironment 把 HOME、USERPROFILE 和 PI_CODING_AGENT_DIR 临时指向这个根目录,并先删掉所有 PI_EVAL_ 开头的环境变量,运行结束再全部还原。”老Z说,“用例还能用 workspaceFiles 预先放入夹具文件;seedWorkspace 拒绝绝对路径和跳出 workspace 的相对路径。”

小A猜:“那临时目录把模型服务也关进去了吧?测试期间什么都不碰外面?”

“模型服务恰好在名单之外。”老Z指着 try 块,“它先从宿主 agent 目录的 auth.json 读出所选 provider 的已存凭据,放进一个 InMemoryCredentialStore,再用它 ModelRuntime.create。也就是说,临时目录隔离的是工作区、配置和会话;凭据是有意从宿主带进来的,模型请求照样走真实网络。这套隔离压住的是测试之间共享工作目录的污染,不等于运行绝对无副作用。”

“还有一道更严的隔离只在容器里启用。”老Z接着说,“设置了 PI_EVAL_SANDBOX_UID 和 PI_EVAL_SANDBOX_GID 时,runPiCodingAgent 先删掉宿主的 auth.json,把凭据环境变量从 process.env 里藏起来,然后 enterToolSandbox:要求进程以 root 启动,把临时根目录 chown 给沙箱用户,再 setgid/setuid 永久降权,最后自检降权后读不到 Vitest 转译过的用例模块。注释和 README 的说法一致:降权之后,用例定义、评判辅助代码和夹具对 Agent 不可读。”

小A:“cleanup 呢?按什么顺序删?”

“顺序固定,而且要和 artifact 收集的顺序对上。”老Z顺着源码往下读。finally 块里先读 sessionManager.getSessionFile():没有会话文件本身就算一条 cleanup 错误,‘Pi eval produced no session file.’;有就把整份 JSONL 通过 setArtifact(PI_SESSION_SNAPSHOT_ARTIFACT, ...) 存下。之后才 session?.dispose(),再 rm(root, { recursive: true, force: true }),最后还原环境变量和藏起来的凭据变量。artifact 读取必须排在 rm 之前,JSONL 一删就再读不到了。每一步各自 try/catch,错误全部推进 cleanupErrors,即使 dispose 抛错,rm 仍会执行。

text
try 块结束
 → 读 session JSONL 注入 artifact(没有文件也记一条错误)
 → session.dispose()
 → rm(root, recursive)
 → 还原环境变量与凭据变量
 → 合并 runError 与 cleanupErrors,决定 throw 或返回

“runId 在会话创建后立刻通过 setArtifact("runId", sessionManager.getSessionId()) 记下。”老Z补充,“失败的 run 也会留下 runId 线索,不会因为 rm 就完全断链。”

小A:“cleanup 出错和 run 失败撞到一起,报告怎么合并?”

“分两种,别混。”老Z回到尾部,“run 成功但 cleanup 出错:一个错误直接 throw,多个包成 AggregateError("Agent cleanup failed.")。run 失败且 cleanup 也出错:和 run 的错误一起包成 AggregateError("Agent run failed and cleanup also failed.")。如果失败前已经收集到 transcript 和 usage,还会用 attachHarnessRunToError 把这份部分结果挂到错误上。run 失败的原因永远是第一手证据,cleanup 失败只是附加信息。”

text
createPiCodingAgentHarness → createHarness(vitest-evals)
   │ run 回调
   v
runPiCodingAgent
   ① signal.throwIfAborted / resolveModelSelection / mkdtemp / 隔离环境变量
   ② 宿主凭据 → InMemoryCredentialStore → ModelRuntime.create → getModel / getAuth
   ③ (容器内)删 auth.json、藏凭据变量
   ④ createAgentSessionServices → SessionManager.create → setArtifact(runId)
   ⑤ createAgentSessionFromServices → 检查没有意外扩展
   ⑥ (容器内)enterToolSandbox 降权
   ⑦ 逐步 prompt / reload;signal abort 桥接到 session.abort()
   ⑧ toTranscriptEvents → usage → verifySystemPrompt → output()
   ⑨ finally: 读 JSONL → dispose → rm(root) → 还原环境
   ⑩ 合并错误,或返回结果与 timings

fake 与真实模型的边界 ​

小A:“测试用哪个模型?随便挑一个?”

“不能随便。”老Z说,“resolveModelSelection 要求显式模型,或同时设置 PI_PROVIDER、PI_MODEL;之后找不到模型、或模型没有配置认证,都直接失败。”

ts
// packages/evals/src/harness.ts,resolveModelSelection(v1.0.0)
const provider = (explicitModel?.provider ?? environment.PI_PROVIDER)?.trim();
const id = (explicitModel?.id ?? environment.PI_MODEL)?.trim();
if (!provider || !id) {
	throw new Error("Select a harness model explicitly or set both PI_PROVIDER and PI_MODEL as defaults.");
}
return { provider, id };

小A抢着接话:“那 faux 呢?我猜就是个假模型,装装样子,不用真跑?”

“不跑。”老Z翻开 packages/ai/src/providers/faux.ts,“createFauxCore 维护一个 pendingResponses 队列,stream 被调用时 shift() 出一条预先装好的响应,再用 streamWithDeltas 切成小块模拟流。withUsageEstimate 按字符长度除以 4 估算 token,所以 usage 是估算的,不是真计费。队列空了,它会产一条错误消息,文本是 ‘No more faux responses queued’。faux 测的是控制流和事件序列,模型推理它碰都没碰。”

小A:“那为什么 harness 不干脆默认用 faux?”

“因为 faux 跑过不代表真模型跑过。”老Z说,“resolveModelSelection 不接受隐式默认,它宁可让测试失败,也不让你误以为测了真模型。faux 用在 pi-coding-agent 的单元测试里,例如 test/suite/harness.ts;packages/evals 里没有任何 faux 引用,走的都是 ModelRuntime.create() 加真实 getModel(provider, id)。两条路径对应两种证据等级:单元测试证明控制流,pi-evals 证明真实链路。”

要点:两种证据等级

真实模型会受服务端版本、采样、限流和价格影响;faux provider 可为确定性单测提供替身,但不能证明真实 API 兼容或质量。反过来,真实模型 smoke 能证明一次实际链路可用,却不能证明所有 prompt 的正确性。

本章其余小节为付费内容

登录后可购买;已购 Pi Cookbook Pro?登录即解锁完整章节。