把 eval 做成发布门禁:配对检验 + 三档判定,一个不到 200 行的纯标准库实现

本周主题「分数还能信吗」的收官篇。前四篇分别讲读榜、作弊、统计显著性和自建评测集。这篇只解决一个工程问题:评测跑完了,怎么让它真的挡住一次发布。

先看一个失败案例

某客服 Agent 改了系统提示里的 3 行文字。CI 全绿,4 分钟后自动全量发布,一次性解决率 78.4% → 53.7%。错误率、延迟、工具调用成功率全程正常,没有一条告警。

复盘结论有两层:

  1. CI 里的测试测的是"代码有没有按我写的执行",不是"系统对用户的价值有没有退化"。这两件事之间没有蕴含关系。
  2. 真正回滚只花 30 秒,另外 39 分半花在"不知道回滚什么"和"找不到上一个版本"。

第 2 点决定了第 1 点能不能补救。所以门禁设计的第一步不是写 YAML,是定义可回滚单元:

makefile 复制代码
release = {
  "code":    "a1b2c3d",
  "prompt":  "v7",
  "model":   "gpt-6-astra@route-eu",   # 含推理路由,不能只写模型名
  "tools":   "2026.11.13",
}

model 里带 @route 不是洁癖。聚合商可能把同一个模型名路由到不同后端,不固定路由时你连"这轮为什么变差"都查不出来。

1. 为什么不用"准确率 ≥ 0.9"这种门禁

这是本节的核心,也是最多团队踩坑的地方。

测试和评估的方法论不同:测试把随机性消除掉(Mock、固定种子、注入时钟),输出布尔值;评估接受随机性并用统计方法处理,输出分布。

所以"准确率 ≥ 0.9 才准上线"这种门禁,本质是拿一个随机变量的单次采样去卡阈值。后果是门禁自己 flaky:同一个 prompt 今天过、明天不过。团队的处理方式一定是点"重跑",两周后这个门禁在所有人心里权重归零。

正确的做法是配对比较:同一批用例,基线版本和候选版本各跑 k 次,然后看"配对"层面的变化。

口径先定清楚

每个用例在 k 次 trial 里的表现,有两种聚合方式:

口径 定义 回答的问题
pass@k k 次里至少 1 次通过 这个能力有没有
pass^k k 次全部通过 这个能力稳不稳

门禁用 pass^k。理由:发布要的是稳定交付,不是"运气好能过"。一个 pass@5=1.0、pass^5=0.2 的版本,上线后每 5 次有 4 次失败------它在 pass@k 上和稳定版本并列第一。

于是每个用例被压成一个布尔值:ok = (pass_count == k)。

配对之后用什么检验

拿到两列布尔值,直觉是算两个比例做卡方。但配对设计的信息在被丢掉:基线过、候选也过的那些用例,对"有没有变化"没有任何贡献,却会稀释差异。

只看不一致对(discordant pairs):

  • b = 基线过、候选没过(退化)
  • c = 基线没过、候选过了(修复)

原假设下,每个不一致对"方向朝哪边"是 50/50。于是单侧检验就是二项检验:

python 复制代码
def mcnemar_one_sided(b, c):
    """b=退化条数, c=修复条数; H1: 候选更差。返回 P(X >= b | n=b+c, p=0.5)"""
    n = b + c
    if n == 0:
        return 1.0
    return min(1.0, sum(math.comb(n, k) for k in range(b, n + 1)) / 2 ** n)

这就是 McNemar 的精确版本。样本小的时候别用卡方近似------b+c 小于 25 时近似很差,而门禁的核心集常常只有几十条。

2. 三档判定:把制度和技术分开

python 复制代码
ALPHA = 0.05

def judge(cases, trials, cost_per_trial, budget_usd):
    b = sum(1 for x in cases if x.base_ok and not x.cand_ok)
    c = sum(1 for x in cases if not x.base_ok and x.cand_ok)
    p = mcnemar_one_sided(b, c)

    redline_broken = [x.cid for x in cases if x.redline and not x.cand_ok]
    core_broken = [x.cid for x in cases if x.suite == "core" and x.base_ok and not x.cand_ok]

    if redline_broken:
        return "BLOCK", f"红线用例未全过:{','.join(redline_broken)}"
    if b > c and p < ALPHA and core_broken:
        return "BLOCK", f"核心集显著退化:净退化 {b-c} 条,p={p:.4f}"
    if b > c:
        return "WARN",  f"有退化但未达显著线:净退化 {b-c} 条,p={p:.4f}"
    return "PASS", "无净退化"

三档的分工要讲清楚,否则会被当成"随便定的规则":

红线(BLOCK)走制度,不走统计。 越权、数据泄露、合规漏放、支付/删除这类不可撤销动作,必须 100% 通过。为什么不能用 p 值?因为一条红线用例掉了一次,你在统计上没有能力证明它是噪声;而它上线后的损失是确定性的。用不确定的证据去赌确定的损失,是设计错误。

显著退化(BLOCK)走统计。 只在核心集上阻断。全量集上的退化进日报------样本大、噪声也大,还常混着环境抖动。

切片退化(WARN)走报告。 总分没降但某个场景塌了,是最阴的一类:某团队修金额识别,A 类错误 12→3,总体 0.83→0.85,没人注意"责任条款"错误 5→14。聚合指标会掩盖切片退化,所以报告必须分组。

3. 完整实现:不到 200 行,能返回退出码

CI 只认退出码,所以门禁脚本的成败语义要明确:BLOCK → exit 1,其余 → exit 0。

python 复制代码
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""release_gate.py --- 把 eval 变成发布门禁的最小实现(纯标准库)"""
import json, math, sys
from dataclasses import dataclass

ALPHA = 0.05

@dataclass
class Case:
    cid: str
    suite: str        # smoke / core / full
    redline: bool
    base_pass: int    # 基线 k 次里过了几次
    cand_pass: int
    trials: int

    @property
    def base_ok(self):  return self.base_pass >= self.trials
    @property
    def cand_ok(self):  return self.cand_pass >= self.trials


def mcnemar_one_sided(b, c):
    n = b + c
    if n == 0:
        return 1.0
    tail = sum(math.comb(n, k) for k in range(b, n + 1)) / (2 ** n)
    return min(1.0, tail)


def judge(cases, trials, cost_per_trial, budget_usd):
    b = sum(1 for x in cases if x.base_ok and not x.cand_ok)
    c = sum(1 for x in cases if not x.base_ok and x.cand_ok)
    p = mcnemar_one_sided(b, c)
    redline_broken = [x.cid for x in cases if x.redline and not x.cand_ok]
    core_broken = [x.cid for x in cases if x.suite == "core" and x.base_ok and not x.cand_ok]
    cost = len(cases) * trials * cost_per_trial

    if redline_broken:
        verdict, reason = "BLOCK", "红线用例未全过:%s" % ", ".join(redline_broken)
    elif b > c and p < ALPHA:
        scope = "核心集" if core_broken else "整体"
        verdict, reason = "BLOCK", "%s显著退化:净退化 %d 条,p=%.4f" % (scope, b - c, p)
    elif b > c:
        verdict, reason = "WARN", "有退化但未达显著线:净退化 %d 条,p=%.4f" % (b - c, p)
    elif b == c:
        verdict, reason = "PASS", "无净退化(b=c=%d,p=%.4f)" % (b, p)
    else:
        verdict, reason = "PASS", "显著变好:净修复 %d 条" % (c - b)

    if cost > budget_usd and verdict == "PASS":
        verdict, reason = "WARN", reason + ";但本轮花费 $%.2f 超预算" % cost
    return {"verdict": verdict, "reason": reason, "b": b, "c": c, "p": p, "cost": cost}


def main(path):
    with open(path, encoding="utf-8") as f:
        payload = json.load(f)      # 演示数据与表格对齐输出见完整脚本,为篇幅略去

    trials = payload["trials"]
    cases = [Case(cid=x["id"], suite=x["suite"], redline=x["redline"],
                  base_pass=x["base_pass"], cand_pass=x["cand_pass"], trials=trials)
             for x in payload["cases"]]

    for x in cases:
        mark = "REGRESS" if (x.base_ok and not x.cand_ok) else \
               ("FIXED" if (not x.base_ok and x.cand_ok) else "same")
        print("%-12s %-6s base=%d/%d cand=%d/%d %s"
              % (x.cid, x.suite, x.base_pass, trials, x.cand_pass, trials, mark))

    r = judge(cases, trials, payload["cost_per_trial"], payload["budget_usd"])
    print("-" * 64)
    print("b(退化)=%d  c(修复)=%d  p=%.4f" % (r["b"], r["c"], r["p"]))
    print("cost=%d trials, $%.2f" % (len(cases) * trials, r["cost"]))
    print("VERDICT: %s -- %s" % (r["verdict"], r["reason"]))
    return 1 if r["verdict"] == "BLOCK" else 0

实际输出(12 条用例 × 5 次 trial,每次 $0.06,此处节选首尾):

ini 复制代码
smoke-01     smoke  base=5/5 cand=5/5 same
smoke-03     smoke  base=4/5 cand=5/5 FIXED
...
core-05      core   base=5/5 cand=4/5 REGRESS
------------------------------------------------------------
b(退化)=3  c(修复)=1  p=0.3125
cost=60 trials, $3.60
VERDICT: BLOCK -- 红线用例未全过:core-05

注意这一行的含义:p=0.3125,统计上什么都没证明,但门禁仍然 BLOCK------因为拦住它的是红线制度,不是 p 值。这正是三档设计的意义。

4. 接进 GitHub Actions

yaml 复制代码
name: eval-gate
on:
  pull_request:
    paths:
      - "prompts/**"
      - "retrieval/**"
      - "model.yaml"
      - "evals/**"

jobs:
  gate:
    runs-on: ubuntu-latest
    timeout-minutes: 20
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with: { python-version: "3.11" }

      - name: run evals (k=5)
        env:
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
        run: python evals/run.py --suite smoke --k 5 --out /tmp/trials.json

      - name: release gate
        run: python evals/release_gate.py /tmp/trials.json

      - name: upload report
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: eval-report
          path: /tmp/trials.json

四个要点:

  1. path filter 决定跑不跑。提示词、检索、模型配置、评测集改动都触发;只改前端就不跑,省钱。
  2. --k 5 是下限不是上限。k 越大越能区分"稳定"和"撞运气",但成本线性增长。
  3. 报告一定要上传 。失败时人要能直接定位到用例,而不是只看一行 exit 1。
  4. 超时要收紧。20 分钟跑不完的冒烟集不是冒烟集。

5. 踩坑记录(都是今天真踩的)

坑一:Case(**x) 拿到 id 报错。 数据里字段叫 id,dataclass 字段叫 cid(避开内置名),直接展开就 TypeError: unexpected keyword argument 'id'。显式映射字段名,别偷懒用 **。

坑二:demo 模式把退出码吞了。 脚本既能跑内置演示、又能读 JSON 文件,一开始演示分支没写 sys.exit(),CI 里永远 exit 0------门禁永远绿的 bug,比没有门禁更危险 。现在约定:单文件模式按判定返回 0/1,演示模式显式 sys.exit(0)。

坑三:把"红线失败"算进 p 值。 第一版把红线用例和其他用例混在一起做 McNemar,结果 1 条红线失败被 2 条修复抵消,b<c,判 PASS。红线必须先于统计单独判断,这是短路逻辑,不是加权。

坑四:预算超了却判 BLOCK。 成本超预算不该阻断发布------那是排期问题,不是质量结论。改成只在 PASS 时降级为 WARN,另发告警。

坑五:p < 0.05 在 12 条用例上没有分辨率。 单侧 5%、无修复对冲时,净退化至少要 5 条(p=0.031)才拦得住,4 条只有 0.0625。想在 60-100 条的核心集上看到 3 个点的退化,得先算 MDE------不然门禁只是个心理安慰。

python 复制代码
def min_discordant_for_signal(alpha=0.05):
    n = 1
    while (1 / 2 ** n) >= alpha:
        n += 1
    return n          # alpha=0.05 -> 5

6. 门禁自己怎么被审计

门禁输出一个内部数字,和"榜单上的一个分数"没有本质区别。可审计性至少需要三样东西:

能定位到 trial。 Harbor 的抽象值得抄:Task(指令 + 沙箱 + 验证器,一个目录)/ Agent / Sandbox / Verifier / Trial(一次尝试)/ Job(一批尝试)/ Trajectory(标准格式 ATIF)。可复现性的最小单位是 trial,不是"上周跑过一次"。

轨迹能被第三方复跑。 Terminal-Bench 仓库把评测做成了 PR 机器人:五条 sticky 评论分管静态检查、评分表、任务概览、验证、总状态;/run 跑正常 Agent,/cheat 专门跑作弊 Agent。artifact 跑完即删,轨迹留在 Hub 上(有登录与共享控制)。

判据独立于被测对象。 R40 对 Kimi K3.1 Pro 的审计是范例:复现层 126/189 = 66.7%,接近榜单 67.2%;判分器层移掉 5 次已知 loophole 和 5 次"没做完但测试没覆盖",降到 61.4%;行为层 44/189 次把提示里不存在的"隐藏要求"说成 instructions,前代 K3 是 0 次。三层分数不一致的地方,就是调查入口。

7. 小结

十行以内的规则版:

  1. 先定义回滚单元(代码 / prompt / 模型@路由 / 配置与工具),再写流水线。
  2. 门禁判"配对差",不判"绝对值"。
  3. pass^k 口径,k 至少 5。
  4. 红线走制度(100%),退化走统计(McNemar 单侧),切片走报告。
  5. 成本与判定打在同一屏。
  6. 退出码只有两种语义:挡、不挡。别让演示模式吞掉它。
相关推荐
框架那些事儿22 分钟前
深入 Pi 源码:一个优秀的 Agent,是如何管理上下文的?
人工智能·ai编程·全栈
小虎AI生活22 分钟前
最近爆火的 Chrome 新 skill 装进 WorkBuddy,AI 写代码起飞了
aigc·ai编程
jerrywus1 小时前
用 AMD Radeon Cloud 免费跑 ComfyUI:从开机到打开界面
前端·agent·claude
前进的李工1 小时前
Agent 学习笔记 15:Agent 怎样响应事件与中途打断?
人工智能·笔记·agent·openclaw·工具设计·gpt-6 astra·原生异步
大模型真好玩2 小时前
大模型训练全流程实战指南实战篇(十八)——微调问答对数据构建技术
人工智能·agent·deepseek
泯泷3 小时前
AI Agent 工具设计:给模型装上“手脚”,为什么不能只会调用 API?
人工智能·llm·agent
不一样的少年_3 小时前
用了这 Skill,我觉得前端兄弟可以毕业了
前端·后端·agent
杨智炜4 小时前
我没有凑到 100 道题:一个 Agent 评测集的取舍
agent
ZzT4 小时前
三个 Claude 代码审查 skill 用了半年、1,306 条评论:最简单的修复率 68.9%,最复杂的 59.2%
ai编程·claude