Pocket Guide to AI Evals

@HamelHusain 把自己「Applied AI Evals」课程重要概念浓缩成了 13 张信息卡，做成了口袋指南，这个好，方便随时查看！

信息卡：https://hamel.dev/notes/llm/evals/flashcards/

1. 误差分析：流程为收集 100+ 条多样 trace → 开放式编码写非结构化笔记 → 聚类归类 → 按频次排优先级，循环直到"理论饱和"（新数据不再带来新失败模式）。与邮件版相比，这张卡补充了一个实操细节：trace 需标注 pass/fail 和 失败模式。

2. 何时写评估：这是最容易被跳过的决策卡。先问"误差分析中是否观察到该失败"，没观察到就别写。观察到后看修复需要多少迭代：需要大量迭代的才值得投入昂贵评估（如 LLM 裁判）；小问题考虑用代码断言，或者干脆修掉就继续前进。评估是有成本的，ROI 为正才写。

3. 拒绝通用指标：ROUGE、BLEU、"有用性/忠实度/语气"分数这类通用指标应替换为应用专属指标，如"日历排期失败""邮件收件人错误""未升级转人工"。好指标的五条标准：对应观察到的错误、涉及值得迭代的非平凡问题、范围聚焦于具体失败、结果是二元的（pass/fail 而非 1-5 分）、可验证（LLM 裁判需有人类标签对照）。

4. 常见错误：三条，迷信"自动评估魔法"而不先看数据（off-the-shelf 指标因此失效）；用 LLM 裁判却不对照人类标签测量裁判本身，得到不可信的错位指标；全绿（100% 通过）不是好消息，往往说明评估已饱和或太简单，应持续补充困难用例。

5. 自动化评估的三种类型：代码断言（关键词匹配、确认工具执行等，快、便宜、确定性、可解释，能用则用）；LLM 裁判（处理代码无法覆盖的主观/细微标准，慢、贵、需验证校准，留给重要失败）；护栏 Guardrails（运行在请求/响应通路上，在失败触达用户前拦截，要求低误报率以免拦截正常响应，通常是小分类器或代码检查）。

6. 拒绝 Likert 量表：LLM 裁判用二元 pass/fail 优于 1-5 打分。理由：量表与领域专家对齐的成本高；标注者倾向选中间值逃避艰难判断；还容易诱发"总体质量"这种大而不当的范围。二元评分强迫做出明确决定，这恰好对应现实中的发布决策（够好/不够好），且在误差分析中更易应用。示例中把"is_polite / scheduling / human_handoff"拆成三个独立的 pass/fail 判定。

7. 如何信任 LLM 裁判：唯一办法是对照人类标签测量裁判。人类标注数据切三份：Train（~20%，从中挑选 few-shot 示例进提示词）、Dev（~40%，优化裁判）、Test（~40%，防过拟合的最终检查）。切分比例与 ML 不同，因为"训练"的只是提示词。报告指标时不要用 accuracy，在不均衡数据上有误导性，应分别报告 TPR 和 TNR，目标都在 90% 以上。

8. trace 采样策略：两个维度。探索方向，随机采样（永远与其他策略并行，用于发现未知问题）、聚类（按语义相似度分组，看是否暴露新错误）、数据分析（对延迟、轮次、工具调用数、token 数等做统计找离群点）、分类筛选（用现有评估或 LLM 预测性筛选问题 trace，需谨慎）。利用信号方向，用用户的显式反馈过滤 trace。

9. 合成数据：关键是结构化生成而非零样本生成。"生成 50 个测试用例"这种提示词只会产出雷同、泛化的输入。正确做法：定义关键维度（功能、用户画像、场景）作为提示词变量保证多样性；尽量用真实日志做种子，让模型显式注入变化（新约束、修改变量）制造贴近现实的边界情况；定义输出 schema 并大量生成后过滤；从简单查询起步，迭代增加约束和格式复杂度。

10. 用 trace 构造测试用例：阅读 trace 时在第一个（最上游的）错误处停下，上游失败通常更重要，这样才可控。针对主要失败收集 trace，做最小化复现（尽量少的轮次和复杂度）。核心技巧是 N-1 切分：收集最小化复现的错误 trace 数据集，用错误发生前 N-1 轮作为测试用例（前提是系统没有剧烈变动）。进阶：用 LLM 对用例做有效变形（改写用户提问）扩大覆盖；或用另一个 LLM 模拟用户（做好很难）。

11. 转移矩阵定位 agent 失败：多步 agent（Plan → Search → Code → Finalize）难以判断哪一步最常出错。做法：列出所有状态；以"From 状态"为行、"To 状态"为列建网格；每次失败归因于错误前最后一次成功转移，计入对应格子。网格会直观呈现失败热点（示例中 GenSQL→ExecSQL 转移积了 12 次失败，一眼可见）。源自 Bryan Bischof 的演讲。

12. 部署评估：按目标分三档。CI/CD（pre-merge，用精选测试用例 + 单元测试/LLM 裁判，失败则阻止合并）防止回归；在线监控（post-response 异步，对采样生产流量跑评估，失败触发告警）发现新失败、跟踪表现；护栏（pre-response 同步，覆盖 100% 实时流量，用单元测试/小分类器，失败则拦截响应、重试或降级）保障安全、拦截高影响错误。