AI 评估（AI evals）
评估（eval）是一种可重复的测试，用于衡量 AI 系统是否完成了其任务。此技能使你能够按照 aievals.co 指南所教授的方式工作：在测量任何内容之前先查看真实输出，测量你实际发现的失败，在信任任何 LLM 评判之前先用人工标签进行校准，并对每个数字都给出区间。
指南位于 https://www.aievals.co 。当你向用户解释某个选择时，应引用其页面。末尾列出的参考文件包含详细信息和来源。
基本规则
在每个评估任务中都遵循以下规则，无论用户要求什么。
- 在编写指标之前先查看轨迹。 无法为未观察过的系统指定失败模式。如果用户没有轨迹，先获取一些：生产日志，或者在 100 个真实输入上运行系统。然后阅读它们。
- 人工标注；你提出建议。 切勿自己编写真实标签并将其作为人类判断呈现。你可以起草标记为
"provisional": true的标签供人确认。切勿让模型同时编写输入及其正确答案，除非代码计算出答案（如 SQL 结果、测试、计算器等）。 - 代码检查优于评判。 任何字符串匹配、解析器、模式检查、正则表达式或单元测试能决定的内容都是代码检查。在构建任何评估之前，先通过提示词编辑修复可修复的问题。将 LLM 评判保留给剩余的主观失败。
- 每个失败模式一个二值评判。 PASS 或 FAIL 加上一句批评。不使用 1-5 等级。多个质量维度意味着多个二值评判，报告为总通过率并附带每个检查的明细。
- 在信任评判之前先校准。 将其与人工标签进行比较，并分别报告 PASS 召回率和 FAIL 召回率，每个都带上 N 值。原始一致性永远不是重点：一个总是回答 PASS 的评判在 5% 的输出失败时，能有 95% 的一致性。
- 训练集、开发集、测试集。 少量示例仅来自训练集。在开发集上迭代。只读一次测试集，在最后。在更多编辑后再次读取测试集会使其变成第二个开发集。
- 固定评判配置。 模型 ID、effort、评判文本、输出模式以及少量示例的顺序都是测量工具的一部分。将它们与每个结果一起记录，并在其中任何一项发生变化时重新校准。不要假设确定性：对开发集运行两次并统计标签翻转次数。
- 每个数字都附带 N 和区间。 对于比率，使用威尔逊区间（Wilson interval），切勿使用正态近似。将两个版本在相同输入上作为配对数据进行比较。
- 回归集 100% 通过。 它包含复现的生产错误和策略边界。一次失败就阻止发布，而一次不稳定情况则是流程错误。
- 在差异上设门控，而不是绝对比率。 使用 references/ci-and-release-gates.md 中的四个等级。
- 在运行器中限制开销。 评判运行需要花钱。通过代码强制执行预算 (
EVAL_BUDGET_USD)，而不是作为打印警告。 - 构建最小的可用方案。 断言和大约 30 个标注示例优先于评判，校准过的评判优先于仪表板或评判集成。
选择工作流程
| 用户想要 | 执行 | 阅读 |
|---|---|---|
| 为没有评估的功能添加评估 | 工作流程 A | error-analysis, judges, datasets |
| 编写或修复 LLM 评判提示 | 工作流程 B | judges, templates |
| 判断现有评估是否可信 | 工作流程 C | judges, statistics |
| 判断版本 B 是否优于版本 A | 工作流程 D | statistics, ci-and-release-gates |
| 在 CI 中运行评估 | 工作流程 E | ci-and-release-gates, datasets |
工作流程 A：为功能添加评估
- 收集轨迹。 拉取至少 100 个多样化的轨迹，如果系统尚未上线，则在真实输入上运行它。将它们存储为 JSONL，每行带有稳定的
id。应记录的轨迹字段请参考 references/templates.md。 - 与用户一起进行错误分析（详细信息见 references/error-analysis.md）。一个人阅读轨迹，并在每个轨迹中首先出现问题的位置写下一行注释。一旦此人标注了至少 30 条，你可以构建一个简单的查看器，并将这些注释聚类为 4 到 7 个命名失败模式。对每个模式计数，并按频率乘以严重程度排序。
- 修复廉价的失败。 首先进行提示词和代码修复。重新运行并重新计数。
- 为每个规则能检测到的剩余模式编写代码检查。
- 为每个剩余的主观模式编写一个评判（工作流程 B）。
- 获取人工标签：每个失败模式的目标是 100 到 200 个标签，在开发集和测试集中各包含 30 到 50 个 PASS 和 30 到 50 个 FAIL。100 行的 40% 开发集划分可能无法容纳每类 30 个样本，并且在低失败率下，你必须对失败案例进行过采样以填充 FAIL 侧。从现有数据开始，并说明区间有多宽。
- 校准 每个评判在开发集上运行一次，然后在测试集上确认一次。
- 从复现的失败中构建回归集，并将测试套件集成到 CI（工作流程 E）。
交付物位于用户仓库中，除非他们已有布局：
evals/
data/ labeled.jsonl (human labels), regression.jsonl, traces/
rubrics/ 每个失败模式一个文件
codebook.md 标签、定义、2 个 PASS 和 2 个 FAIL 示例、最后 kappa 值
checks.* 代码检查
judge.* 评判调用、固定配置
calibrate.* 划分、评分、报告、分歧
run_eval.* 对输出评分、与基线比较、CI 退出代码
runs/ 每次运行一个文件夹：摘要、预测、评判副本
Python 和 TypeScript 的入门代码位于 https://github.com/ombharatiya/ai-evals-skills/tree/main/starters。复制一份而不是从头编写框架。
工作流程 B：编写或修复 LLM 评判
- 确认失败模式来自错误分析，并且代码检查无法捕获它。
- 编写由四部分组成的提示词（模板见 references/templates.md）：角色和精确定义；二值标准（"如果 X 则 PASS。如果 Y 则 FAIL，即使响应的其余部分正确。如有疑问，FAIL 并说明原因。"）；来自训练集的 2 或 3 个少量示例，包括一个看似通过的 FAIL 示例；以及一个严格的输出模式
{"label": "PASS" | "FAIL", "critique": "..."}，如果 API 支持，使用结构化输出强制执行。解析器必须在格式错误时失败并报错。 - 校准：在开发集上运行，计算 PASS 召回率、FAIL 召回率和 Cohen's kappa，并阅读每个分歧。分别阅读假通过和假失败。如果人工标签错误，则修复标签，而不是评判文本。
- 每次迭代更改一件事，按典型影响顺序：评判文本的特定性、少量示例、输出模式，最后是模型交换。
- 预计在第二或第三次迭代时达到平台期。然后为边缘情况添加少量示例：两个在粗心阅读时看起来像 FAIL 的 PASS 示例，以及两个看起来像 PASS 的 FAIL 示例。如果 FAIL 召回率仍然没有变化，那么评判模型可能是天花板：在再次更改评判文本之前尝试更强的模型，并将新模型视为从头校准的新工具。
- 当 PASS 和 FAIL 召回率在开发集上都达到标准时停止（本指南默认为 0.90；根据错过失败的代价与误报的代价来设定），然后读取一次测试集。
工作流程 C：审计现有评估
检查每个项目并报告哪些失败，附上文件和行号：
- 指标可追溯到有人在真实轨迹中观察到的失败模式。
- 代码检查覆盖了代码可以决定的内容；评判是二值的，每个失败模式一个。
- 每个评判都有校准记录：PASS 和 FAIL 召回率，附带 N 和区间，基于评判从未见过的测试集划分。仅靠一致性不算数。
- 少量示例不包含在开发集或测试集中。
- 评判配置（模型、effort、评判文本、模式、少量示例）已固定，并与校准时的配置匹配。
- 每个报告的比率都有 N 和区间；比较是配对的。
- 存在回归集，在每个 PR 上运行，并且 100% 通过。
- 发布决策读取配对差异及其区间，而不是绝对阈值。
- 数据集已版本化（内容哈希），结果指名了哈希值。
- 一个已 100% 通过几个月的测试套件实际上没有测试任何东西。回归集是唯一的例外。
工作流程 D：比较两个版本
在相同的输入上运行两个版本。报告每个通过率及其威尔逊区间，以及配对差异及其区间：对于二值结果，使用 McNemar 检验或配对自举。首先确定值得检测的最小差异，然后确定样本大小（references/statistics.md）。在必要时按细分进行切片，并在进行多种切片时校正多重比较。来自低能力运行的“无显著差异”并非无差异的证据：说明该运行能够检测到多大的变化。
工作流程 E：CI 中的评估
三个层级：每次推送时运行 10 到 50 个确定性断言的烟雾层（无评判），在更改提示词或模型的 PR 上运行带有校准评判的完整层，以及运行扩展回归集和鲁棒性集的夜间层。在 PR 上发布基线与候选版本的对比表，包含差异、95% 区间以及“发布”、“暂缓”、“调查”或“阻止”的判定。在“调查”、“阻止”、回归集失败或测量损坏（无判定行、任一侧缺失行、使用非校准评判）时使任务失败，并报告“暂缓”由指定人员阅读：“暂缓”意味着区间无法判断变化与否。 从相同系统无变化的 A/A 运行中确定不关心窗口的大小，而不是零噪声下限。不允许静默覆盖：覆盖需要指定人员和书面原因。Fork PR 不获取 API 密钥。详细信息见 references/ci-and-release-gates.md。
如何报告结果
报告表格，而不是句子：
| 指标 | 值 | 95% 置信区间 | N | 评判 | 数据集 |
|---|---|---|---|---|---|
| FAIL 召回率，退款策略评判（测试集） | 0.92 | [0.80, 0.97] | 48 | claude-opus-5-5, medium, rubric a1b2c3 | labeled.jsonl @ 9f8e7d |
说明这些数字不能支持什么。写作“区间较宽；标注更多 FAIL 示例”，而不是将弱结果四舍五入成结论。当提到 TPR 或 TNR 时指明正类：一些文献（包括 Hamel Husain 的常见问题解答）将 FAIL 视为正类，因此其 TPR 是捕获到的真实失败的比例。简单的“PASS 召回率”和“FAIL 召回率”避免了混淆。
默认值
除非用户的情况需要其他值，否则使用这些默认值。“网站默认值”指的是 aievals.co 自身的常用数字，而非公开标准。
| 决策 | 默认值 | 来源 |
|---|---|---|
| 首次错误分析通过 | 100+ 条轨迹，仅第一个失败（Hamel 和 Shankar 常见问题解答）；每条 15 到 45 秒 | FAQ，以及 aievals.co 的节奏说明 |
| 失败模式类别 | 轴向编码后 4 到 7 个 | aievals.co 开放编码指南 |
| 每个失败模式的标签数 | 100 到 200 | Hamel 和 Shankar 常见问题解答 |
| 划分 | 15% 训练集，40% 开发集，45% 测试集，分层（入门代码使用每个 id 的哈希值进行划分，因此一行永远不会改变划分；比例仅平均匹配） | aievals.co 校准配方 |
| 开发集和测试集中每类样本 | 30 到 50 个 PASS 和 30 到 50 个 FAIL | Hamel 和 Shankar 常见问题解答 |
| 评判召回率标准 | PASS 和 FAIL 召回率在开发集上至少为 0.90，并在测试集上确认 | 网站默认值 |
| 自动化前的人类一致性 | kappa 至少 0.6 才继续，0.8 才作为黄金集或门控 | 团队策略，依据指南 |
| 比率的区间 | 威尔逊区间，95% | aievals.co 统计章节 |
| 发布门控窗口 | 主指标的 1 点不关心窗口；2 点轻微回归窗口 | aievals.co 发布门控章节 |
| 回归集 | 每个 PR 100% 通过 | aievals.co 回归集章节 |
参考资料
加载与任务匹配的文件：
- references/error-analysis.md：开放编码、轴向编码和结构化编码、饱和度、优先级排序、轨迹查看器、维度抽样。
- references/judges.md：评判设计、校准、偏见及其测试方法、直接对比与成对对比、重新校准触发条件。
- references/datasets.md：按目的划分的规模、来源、合成数据规则、回归集、覆盖网格、版本控制。
- references/statistics.md：威尔逊区间、配对检验、聚类错误、样本量、多重比较、纠正评判评分比率。
- references/ci-and-release-gates.md：CI 层级、发布门控等级、在线评估、抽样、漂移。
- references/templates.md：评判提示、编码簿条目、注释记录、轨迹模式、PR 结果评论。