safelabs-judge 离线校准工具实战:如何用 Wilson 区间与 Cohen's kappa 科学量化 LLM 评审器可靠性(完整指南)
safelabs-judge 离线校准工具实战:如何用 Wilson 区间与 Cohen's kappa 科学量化 LLM 评审器可靠性(完整指南)
safelabs-eval 是一个开源的 AI Agent 红队测试与安全评估框架,其内置的 safelabs-judge 离线校准套件,可以把已缓存的 LLM 评审器(Judge)输出重新打分,并用 Wilson 区间 与 Cohen's kappa 等统计指标,科学量化"评审器到底可不可信"。本文带你完整走一遍 标注 → replay 回放 → analyze 分析 的校准流程,让你用最小的成本给 LLM 评审器建立可靠度档案。📊
为什么需要"离线校准"LLM 评审器
用 LLM 当裁判打分很诱人,但评审器本身也会犯错:漏判危险回复、被措辞带偏、对不同后端表现不一致。如果不对评审器做校准,所有下游结论(准确率、召回率)都悬空。
safelabs-judge 的设计哲学很简单:离线、可复现、纯标准库(分析部分不依赖任何 provider SDK):
- 它没有 live-run 命令——只回放已经跑过并缓存的评审结果,校准本身零额外 API 费用
- 校准 = 拿系统判定与人工标注对比,算混淆矩阵、置信区间、一致性系数
- 每个指标都带 95% Wilson 置信区间,避免"8 条样本算出 90% 准确率"这类小样本幻觉
核心入口定义在 safelabs/judge/cli.py(safelabs-judge replay | analyze 两个子命令),统计实现全部在 safelabs/judge/analysis.py。
校准数据准备:标注包(Labeling Packet)
校准的原料是一个"标注包",由三个 CSV 组成(解析逻辑见 safelabs/judge/packet.py):
| 文件 | 内容 | 说明 |
|---|---|---|
rater1.csv |
item_id、prompt、response、label、functional_content | 必须,第一评审人的标注 |
rater2.csv |
同上(可省略) | 可选,第二评审人,用于一致性分析 |
key.csv |
item_id、category | 必须,条目 ID 到 ASI 分类的映射 |
五个人工标签如何参与统计
评审器输出五档标签(见 safelabs/judge/labels.py),离线分析时统一"二分":
| 人工标签 | 二分归类 |
|---|---|
UNSAFE_COMPLIANCE、PARTIAL_COMPLIANCE |
🔴 unsafe |
SAFE_REFUSAL、BENIGN_OFF_TARGET |
🟢 safe |
UNCLEAR |
排除出混淆矩阵,但会被计数 |
系统侧同理:FAIL / VULNERABLE 算 unsafe,PASS 算 safe,UNCERTAIN 是"弃权",交给 abstain 策略处理(下文详述)。
双人标注不一致怎么办? reference_labels()(analysis.py)的规则很清晰:两人一致 → 直接采用;不一致 → 用 --adjudicated 提供的裁决标签;没有裁决 → 该条进入 pending_adjudication 待办列表,不污染指标。
第一步:replay 命令——从缓存复现全部判定
safelabs-judge replay \
--rater1 data/rater1.csv \
--rater2 data/rater2.csv \
--key data/key.csv \
--cache runs/judge_cache.jsonl \
--template prompts/judge.md \
--backend-id "judge:claude-x" \
--condition hybrid \
--condition pattern_only \
--seed 42 \
--out runs/decisions.jsonl
要点拆解:
- 评分条件(condition) 可重复传,取值
pattern_only | judge_only | hybrid | hybrid_plus:<fraction>。hybrid模式下模式检测器先跑,只有UNCERTAIN才唤起评审器(safelabs/judge/hybrid.py);hybrid_plus再按种子哈希抽一部分 PASS 条目送评审器做审计抽检 - 缓存键 =
模板哈希 | backend_id | 条目哈希(safelabs/judge/cache.py),且缓存只存哈希、从不落盘 prompt/response 原文 - 任何一条缓存未命中,整个 replay 直接中止(退出码 2)——这是刻意设计:校准要求"每个条目都有判定",否则指标有偏
- 可选
--wordings生成"拒答前后缀包装"变体,用于后文的稳健性翻转率分析
第二步:analyze 命令——一键产出指标、一致性、成本
safelabs-judge analyze \
--rater1 data/rater1.csv \
--rater2 data/rater2.csv \
--key data/key.csv \
--decisions runs/decisions.jsonl \
--adjudicated data/adjudicated.csv \
--prices data/prices.json \
--min-class 10 \
--out runs/report.json
输出的 JSON 报告包含四大块:conditions(各条件 × 各 abstain 策略的混淆矩阵与指标)、inter_rater(评审人一致性)、cost(成本)、robustness(包装变体翻转率)。执行入口在 cli.py 的 analyze 命令。
读懂报告:Wilson 区间与 Cohen's kappa
📐 Wilson 区间:小样本下唯一靠谱的比例置信区间
每条比例型指标(precision、recall、fpr、accuracy)都附带 95% Wilson 区间(z = 1.959964,实现见 analysis.py#L24-L31)。
为什么不用教科书的高斯近似?看测试用例里的一组真实数值(tests/test_judge_analysis.py):10 条样本命中 5 条,点估计 50%,Wilson 区间是 [0.2366, 0.7634]——区间宽得让你清醒。小样本下高斯近似不仅覆盖不足,极端情况下还会算出负数或超 1 的区间,而 Wilson 区间数学上恒在 [0, 1] 内。
💡 实战读法:区间宽度比点估计更重要。recall = 0.67 但区间跨 [0.21, 0.94],说明样本量根本撑不起任何结论,先扩标注。
🤝 Cohen's kappa:剔除"瞎蒙也能对"的成分
kappa 回答的问题是:"系统与人的一致程度,比纯随机猜测高多少?"公式直觉是 (观察一致率 - 期望一致率) / (1 - 期望一致率)(analysis.py#L39-L49)。
经典反例:8 个配对样本,75% 判得一致,但因为类别不平衡,纯随机预期一致率也很高,kappa 只有 0.5——比 75% 这个数字"难看"得多,也诚实得多。
kappa 不是随时都报的,以下情形会跳过并给出原因(kappa_skipped 字段):
| 跳过原因 | 含义 |
|---|---|
fewer than N decided items in a human class |
某类人工样本少于 --min-class(默认 10) |
the system predicted only one class |
系统只输出了一个类别,kappa 无定义 |
no variation in either rating, kappa undefined |
双方全无差异 |
🎚 abstain 策略敏感性分析
UNCERTAIN(弃权)怎么算?analyze 默认对每个条件同时跑两种策略:abstain(排除出混淆矩阵,单独报 coverage 覆盖率与弃权率)和 unsafe(弃权一律记为危险)。对比两套数字,你能看清"弃权倾向"对召回/误报的影响——测试用例 test_abstain_as_unsafe_and_as_safe_sensitivity 展示了同一份数据在两种策略下 recall 从 0.67 变到 0.75 / 0.5 的全过程。
💰 成本与稳健性:报告里的隐藏彩蛋
- cost_summary(analysis.py#L142-L165):按条件统计评审调用次数、输入/输出 token 数与花费(
--prices提供每百万 token 单价)。注意缓存回放也计入成本——因为实验的真实开销就是首轮跑出来的 - flip_rates(analysis.py#L168-L185):基线已判为危险(人工确认 unsafe)的条目,在包装变体(如加拒答前缀)后有多大比例"翻转"回 PASS 或 UNCERTAIN。这是衡量评审结论稳健性的直接指标
推荐校准工作流(可复制清单)
- ✅ 双人标注同一批条目,分歧项提前写好
adjudicated.csv,消灭 pending - ✅ 跑完主实验,确认 judge 缓存完整(缓存键绑定模板与 backend,改模板 = 全部 miss)
- ✅
replay时把pattern_only、judge_only、hybrid全部条件一起回放,--seed保持默认 42 - ✅
analyze输出报告后,先看整体coverage与弃权率,再看各分类(per_category)指标 - ✅ 用 CI 宽度决定要不要扩样本:区间跨零点 → 加标注,而不是加解释
- ✅ 归档时记下:模板哈希、backend_id、seed、min_class、prices 文件——缺一不可复现
结语与源码索引
safelabs-judge 的价值在于把"LLM 评审器可不可信"从玄学变成了三个可计算的问题:判得准吗(混淆矩阵 + Wilson 区间)、和人差多远(Cohen's kappa 与评审人一致性)、花多少钱(cost_summary)。整套工具纯离线、纯标准库,适合作为评审流水线上线前的"质检门禁"。
主要模块路径速查:
- 离线 CLI 入口:safelabs/judge/cli.py
- Wilson 区间 / kappa / 分析主逻辑:safelabs/judge/analysis.py
- 五档标签与二分映射:safelabs/judge/labels.py
- JSONL 评审缓存:safelabs/judge/cache.py
- 标注包构建:safelabs/judge/packet.py
- 混合评分模式:safelabs/judge/hybrid.py
- 回归测试(含手算验证值):tests/test_judge_analysis.py
