评估套件与夹具任务:pass@1 与 pass@k

评估套件与夹具任务:pass@1 与 pass@k

本节摘要:编程 Agent 只和你度量它的任务套件一样好。本节建一个评估套件:吃一个夹具任务文件夹,把每个跑过候选 Agent,用确定性验证器打通过或失败,聚合成 pass@1、pass@k、均值延迟、均值成本。这套件是让你把回归从重构里分出来的真相源。三类失败困扰无套件的基准:未验证通过(Agent 说修了,人瞥一眼 diff 标绿,三周后回归测试冒出同一 bug)、未察觉回归(改提示模板让响亮任务好 4%、安静任务坏 14%)、每任务漂移(周一 100 任务、周五 95,因有人重命名了五个夹具)。套件把这三类失败变成可复现顺序里的可验证事实。

对应原课程:Phase 19 · Lesson 27 · eval-harness-fixture-tasks(原英文 phases/19-capstone-projects/27-eval-harness-fixture-tasks/docs/en.md)。本节属「Agent Harness 深度构建赛道」第八节。

学习目标

阅读完本节,你应当能够:

1. 把夹具任务定义为(目标、setup、验证器)三元组。
2. 每任务跑多个样本,算 pass@1 与 pass@k。
3. 把延迟与成本聚合成均值与 95 分位指标。
4. 把确定性验证器(文件 diff、退出码、正则匹配)接成可复用函数。
5. 发可被回归追踪脚本摄取的结构化 JSON 报告。

一、问题与直觉

无评估套件的 Agent 基准被三类失败困扰。第一,未验证通过:Agent 说修了 bug,人瞥一眼 diff,套件标绿,三周后回归测试冒同一 bug——Agent 推理得头头是道却啥也没修。第二,未察觉回归:改提示模板让 Agent 在响亮任务上好 4%、安静任务上坏 14%,无金集与每任务分,回归溜进主干,客户投诉才冒头。第三,每任务漂移:评估周一跑 100 任务、周五 95,因为有人重命名了五个夹具,通过率看着像提升 5%,其实不是。

套件是把这三类失败变成事实的程序。它每次、以可复现顺序、跑每个夹具,对一个返回 true/false 的确定性检查的验证器。

二、从零实现

FixtureTask 是小 JSON 文件加可选 expected/ 目录。JSON 声明 id、goal(喂 Agent 的提示)、setup 块(放进 scratch 目录的文件)、verifier 块(命名套件验证器注册表里的函数并供参数)。

三种验证器形状覆盖多数有用任务:

VERIFIERS = {
    "file_equals":    lambda scratch, expected: read(scratch/x) == expected,  # "精确这样修"
    "regex_match":    lambda scratch, pattern: pattern.search(read(scratch/x)),# "函数得存在且返回 X"
    "shell_exit_zero": lambda scratch, cmd: sandbox.run(cmd).exit_code == 0,  # "测试得过"(经第 26 节沙箱)
}
​

套件每任务跑 k 次。pass@k 是 1 - (1 - p)^k,其中 p 是经验通过率;套件也报原始计数让你看出方差。延迟是每样本墙钟,成本是 Agent 自报(token 数、美元或两者),套件跨样本求和并呈每任务与聚合数。

三、为何 pass@k 而非只 pass@1

真 LLM Agent 是随机的。pass@1=0.6 看着像失败;pass@5=0.95 说 Agent 多数时候答对但早样本选错。解法是采样与排序,不总是更多训练——pass@k 让这显形。但 pass@k 与 pass@1 并报,因为 pass@k 会盖过真失败:模型二十次里答对一次,你没有一个有用的 Agent。套件两个都显。

四、可复用产物

main.py 发:FixtureTask、SampleResult(success_self_reported/latency_ms/cost_units/edits)、TaskReport/EvalReport(带 to_dict())、VerifierRegistry(验证器名 → 函数,内置 file_equals/regex_match/shell_exit_zero)、EvalHarness 类(跑任务目录对候选,返回 EvalReport)。tasks/ 里五个夹具(fizzbuzz 差一、factorial 缺 return、错误消息拼写错、空函数体、链表遍历差一)。一个确定性参考候选 apply_known_fixes 演示干净 pass@1=1.0。demo 打印 EvalReport JSON、退出零。候选是 Callable[[FixtureTask, str], SampleResult],套件用 tempfile.mkdtemp() 建 scratch 目录并以纯字符串传路径——套件不在乎候选怎么工作,候选可是确定性 patch 施加器(套件自测用)、真 LLM Agent、模糊器,契约是 SampleResult。

五、与赛道其余组合

第 25 节产出门链,第 26 节产沙箱,套件对任何 shell_exit_zero 验证器用沙箱,第 28 节把每次套件运行包进 OTel trace,第 29 节端到端 demo 对一个捆绑夹具跑并断言参考候选 pass@1=1.0。

六、练习

1. 加验证器:加一个 unit_tests_pass 验证器,跑 pytest 并按退出码判。
2. 方差检测:让一个随机候选在五任务上跑 k=10,确认套件报原始计数让你看出高方差任务。
3. 漂移守门:加一个夹具 ID 哈希校验,若有人重命名夹具,套件拒绝跑并报漂移。
4. pass@k 数学:用 p=0.6 验证 pass@5 ≈ 0.99,确认公式实现正确。
5. 回归对照:跑两版候选,确认 EvalReport 能让你一眼看出哪版在哪任务上回归。

本节要点回顾

1. 三类失败:未验证通过、未察觉回归、每任务漂移——套件把这三变可验证事实。
2. 夹具三元组:目标 + setup + 验证器,验证器是确定性 true/false。
3. 三种验证器:file_equals(精确修)/regex_match(存在且返回)/shell_exit_zero(测试得过,经沙箱)。
4. pass@k = 1-(1-p)^k:与 pass@1 并报,前者显采样能力,后者显单次有用性。
5. 候选是可调用对象:套件不在乎候选怎么工作,契约是 SampleResult。
6. 延迟与成本:均值与 p95,每任务与聚合。

下一节,我们建「可观测性与 OpenTelemetry 追踪」——把循环、门、沙箱、套件全部接到 trace 上。