第 8 章：如何为自己的 Agent 设计 Golden Data 和 Eval
第 8 章：如何为自己的 Agent 设计 Golden Data 和 Eval
本章核心
黄金数据集是评估的"源代码"，其质量决定了评估信号的信噪比。构建黄金数据集不是"收集数据"，而是"定义正确性"。
这是全书的实践章——把前 7 章的方法、框架、信号全部串成一套可落地的流程。读完这一章，你应该能为自己的 Agent 从零搭建一套完整的评估体系。
这一章回答三个问题：
- 黄金数据集怎么定义、怎么构建、怎么版本化？
- Eval 驱动的开发工作流怎么落地到团队流程？
- 一个端到端案例长什么样？
8.1 黄金数据集的定义与核心原则
什么是黄金数据集
黄金数据集（Golden Dataset） 是包含参考输出（ground truth）的数据集，作为性能基准，提供可靠的标准来衡量和比较 Agent 在不同迭代中的输出。
每个数据条目应包含三要素：
- 输入（query）：用户请求或任务描述
- 期望输出（reference output）：正确的输出/行为
- 元数据（metadata）：标签、错误类型、难度、领域
数据集应包含的样本类型
| 类型 | 说明 | 作用 |
|---|---|---|
| 正常案例 | 典型用户交互 | 覆盖主路径 |
| 边缘案例 | 历史上 Agent 表现不佳的场景 | 捕捉边界 |
| 标记的失败运行 | 从日志/反馈/tracing 提取的失败模式 | 驱动修复 |
黄金集/影子集/对抗集/合成集
一个完整的评估数据体系通常由四类数据集分工（来自 AI Agent Evaluation Pipeline）：
- 黄金集（Golden）：人工挑选 + 人工标注，作为主门禁，决定能否 release
- 影子集（Shadow）：生产流量的影子回放，离线评测生产 case
- 对抗集（Adversarial）：专门为难 Agent 构造的用例
- 合成集（Synthetic）：LLM 生成的变体，用于规模扩展
8.2 构建流程：从错误分析到版本化
第一步：错误分析驱动
从生产 trace 中挖掘真实失败案例，而非套用通用指标。这是构建黄金集的起点——先看真实世界哪里出错，再决定测什么。
第二步：种子集构建
手工构造约 20 个高信号用例，然后从生产 trace 和合成生成中扩展。黄金集典型规模为 50-200 条人工挑选 + 人工标注的案例，作为主门禁决定能否 release。
一个务实的建议（来自 evaluation-first 博客）："80% 公共 Benchmark + 20% 私有黄金集"——公共集负责覆盖面和横向对比，私有集保证对齐内部真实需求。私有黄金集不要搞太大，100 道高质量 case 已经足够抓住 90% 的回归。
第三步：标注纪律
- 领域专家以"仁慈独裁者"模式主导标注（一个人做最终裁决，避免众口难调）
- 验证每条 LLM 建议的标签
- 测量标注者间一致性（inter-annotator agreement）——标注者都不一致的条目，评估信号就是噪声
第四步：样本量与统计严谨性
- ±5% margin 需要约 250 个用例
- 关键路径用 pass^k（连续 k 次成功）而非 pass@k（k 次内至少一次成功）——前者保证稳定性，后者可能靠运气
第五步：版本化与防过拟合
- 版本控制（
my-bench@1.0、my-bench@2.0，升级时保留旧版本，分数跨版本可比） - 保留 held-out split
- 持续刷新（防数据污染：私有黄金集任何人不能把 case 放进训练数据）
将 evals 视为 first-class artifacts，与代码一同版本化。
第六步：合成数据扩增
人工标注成本高，2025 年的主流是用强模型造评测数据，但要防止污染与质量失控：
- seed task 扩写：从 20 个人工种子用例出发，让强模型生成同分布变体，人工抽检
- 仿真环境生成轨迹：在 τ-bench 式固定 API 环境中运行 Agent，收集真实轨迹作为 eval 集
- 蒸馏大基准子集：从公开大基准中挑选与自家场景相关的高信号子集
- 去污染与人工校验：合成数据必须去重（防与训练集重叠）并经过人工/半人工抽检
数据托管与版本化工具
- Opik Datasets / LangSmith Datasets：数据集版本化、curation、实验对照
- HuggingFace Hub Datasets：公开评测数据与结果的托管、浏览、多 split 管理
- Arize Phoenix 实验：数据集 + 运行实验 + 对比，沉淀为可追溯的评估资产
8.3 Agent 评估的特殊设计考量
轨迹标注
不仅标注最终答案，还标注期望的工具调用序列（expected trajectory）。
ADK 的 golden-path 方法：捕获 golden session → 定义 expected tool trajectory → 配置指标 → 运行评估。（详见第 2 章 2.3 与第 5 章 5.4。）
多轮对话设计
使用 ADK 的 ConversationScenario 替代硬编码脚本——定义 starting_prompt 和 conversation_plan，让 LLM 驱动的模拟用户动态生成对话。这使测试对 Agent 的对话风格变化具有鲁棒性。
中间步骤评估
捕获推理轨迹（reasoning trace）以区分"Agent 自己编造了数字"和"工具实际返回了该数字"。（经典案例：GPU 使用率 87% 来自 nvidia-smi 还是模型编造，见第 2 章 2.3。）
运行时 Schema 集成
通过 /agent-info 端点暴露实时工具定义，使评估器在运行时获取最新 schema，避免测试套件与实际代码漂移。评估器应该测试"现在的 Agent"，而不是"上周的 Agent"。
8.4 Eval 驱动的开发工作流
四阶段工作流
Claude Code EDD 实践的核心原则：先定义 evals，再编码。
- 定义阶段：编写 capability evals 和 regression evals 的检查清单
- 实现阶段：运行 evals 频繁捕获回归
- 验证阶段：track pass@k 趋势，监控可靠性变化
- 发布阶段：黄金集作为主门禁，决定能否 release
持续评估与 CI 门禁
把评估接进开发流水线：
- PR Gate：任何改 Agent 的 PR 触发小型 smoke benchmark（10-20 tasks，10 分钟内跑完），Smoke 分数下降超过阈值（如 -3%）直接阻止合并
- Nightly Gate：每晚跑完整 benchmark，连续两天下降就开 Issue 跟进
- Release Gate：正式发布前必须过 Full benchmark + Safety suite + Cost audit
工具支撑：
- Opik PyTest 集成：每次 commit 跑 LLM 管线评估，失败即阻止合并
- curiocity / coding-agent-evals：用真实 CLI transcript 驱动并在 CI gate 编码 Agent 变更
- 注意成本与噪音：在线评估需设计阈值、抽样率与告警，避免判官抖动触发无效告警
发布后的在线评估闭环
离线黄金集管"发布前"，在线评估管"发布后"：
- 线上流量转 eval 集：把生产 trace 中高价值/失败样本回流成新 eval 用例，形成 data flywheel
- 漂移检测：监控 prompt 分布、工具调用模式、反馈分数的漂移，及时发现"环境变了"
- 灰度对比与 trace 回放：新版本上线前用历史 trace 回放对比，灰度期用 A/B 观察真实用户反馈
- 工具支撑：LangSmith/Langfuse/Opik 的 trace 查询与在线评估器，Arize Phoenix 的 drift 检测
8.5 评分器的选择策略
优先使用代码评分器
确定性检查优于概率性检查。 代码评分器的典型场景：文件包含期望模式、测试通过、构建成功。
代码评分器为什么优先？因为它是确定性的——同一输入永远给同一结果，不存在判官偏差。这是第 2、3 章反复强调的原则在选型上的落地。
LLM 评分器处理开放式输出
使用 1-5 分制，附带推理说明。判官 prompt 应包含四要素：评估量表、上下文、具体标准、输出格式。（详见第 3 章 3.1。）
人工审查用于安全关键变更
永远不要完全自动化安全相关的评估。（呼应第 4 章铁律一。）安全相关变更的放行必须有强制人工审查环节。
混合策略
| 输出类型 | 评分方式 |
|---|---|
| 结构化输出 | 代码评分器 |
| 开放式输出 | LLM 判官 |
| 安全相关 | 人工审查 |
| 高风险评估 | 多判官共识 + 人工 |
8.6 选型决策矩阵
当评估需求（对象、规模、资源）明确后，按以下矩阵快速定位工具：
| 场景 | 推荐起点 | 备选 |
|---|---|---|
| 单模型/开源模型对比 | lighteval + Open LLM Leaderboard | evaluate |
| RAG 系统评估 | RAGAS | Opik 内置判官指标 |
| 通用 Agent 观测 + 评估 + CI | Opik | Langfuse / LangSmith |
| 编码 Agent（Claude Code/Codex）评估 | Harbor | ECC Eval Harness / coding-agent-evals |
| 多轮对话模拟与轨迹评估 | Google ADK | 自建 ConversationScenario + LLM judge |
| 判官质量与校准 | RewardBench / Judge Arena | Agent-as-a-Judge |
| Agent 安全评估 | Inspect AI + AgentDojo | Garak / ASB-2025 |
| Skill 优化 | SkillOpt / SkillEvaluator | MUSE-Autoskill / skill-creator |
8.7 端到端案例：为一个带工具的 RAG + 浏览器 Agent 搭建评测
用一个真实案例串起全书所有章节（从 0 到 1 的 walkthrough）。
背景：你有一个带工具的 RAG + 浏览器 Agent——它检索文档、调用工具、浏览网页来回答用户问题。现在要给它搭建完整评估体系。
第 1 步：数据采集
接入 Opik/LangSmith，对生产 Agent 打 trace，导出失败轨迹与用户反馈 → 形成错误分析原料。
对应章节：第 2 章（观测）、第 5 章（Opik）。
第 2 步：Golden 集构建
从错误分析挑 20 个种子用例，人工标注期望输出 + 期望工具调用序列，扩到 50-200 条。
对应章节：8.1-8.2。
第 3 步：合成数据扩增
用强模型扩写同分布变体，去重 + 人工抽检。
对应章节：8.2 第六步。
第 4 步：评分器校准
- 代码评分器：必调工具检查（比如"回答前必须调用检索工具"）
- LLM 判官：回答质量 1-5 分，提示含四要素
- RewardBench 式对齐测试：确认判官与人类判断一致
对应章节：8.5 / 第 3 章。
第 5 步：CI 接入
Opik PyTest / promptfoo 在每次 commit 跑评估，黄金集作为发布门禁。
对应章节：8.4。
第 6 步：成本与效率统计
记录 $/task、token/task、延迟，纳入看板。
对应章节：第 2 章 2.5（成本与效率指标）。
第 7 步：优化闭环
把失败样本喂给 GEPA / SkillOpt，用评估反馈迭代 prompt 与技能文档，held-out 验证通过才接受。
对应章节：第 6、7 章。
第 8 步：在线监控
上线后跑 online evaluation rules，trace 回流成新 eval 用例。
对应章节：8.4 发布后闭环。
这套 walkthrough 展示了本书的核心主张：评估不是终点，而是 Agent 持续进化的燃料。
30 条落地 Checklist（从 0 到 1）
基础设置（第 1-2 周）
- 选好 1 个主公共 Benchmark（和你的任务类型对应）
- 采集 50-100 条内部真实 case 做私有黄金集，每条都写确定性 Verifier
- 定好
dataset@version命名规则，版本不可变 - 选好 Harness：代码 Agent → Harbor Framework；其他 → 按推荐表选
- 沙箱环境跑通（本地 Docker 即可，并发先 4）
- 定义 5 维度度量表（score/cost/latency/reliability/safety）
- 跑一次 Baseline，把 5 维度数字 + CI 存进中心存储
迭代机制（第 3-6 周）
- Prompt 模板代码化并纳入 git
- 元数据 10 项（commit/harness/model/prompt-sha/image-sha/seed/…）自动记录
- Ablation 模板：任何改动 PR 附消融表
- PR Smoke Gate：<10 分钟小子集评测，> -3% 降分拒绝
- Nightly Full Benchmark：自动贴结果到群聊
- 分桶分析：难度桶、任务类型桶、失败原因桶
- Pareto 前沿图定期生成
- 每周一次 Failure Review（固定议程、固定节奏）
数据闭环（第 7 周起）
- Harness 支持导出 ATIF 轨迹
- SFT 导出命令：
harbor traces export --fmt sft - SFT 数据集清洗：MinHash 去重 + 死步骤过滤
- 建立独立 Hold-out Set（至少和训练集不重叠）
- RL 训练管线打通（Flow-GRPO / GRPO / PPO 三选一）
- 每个训练 checkpoint 自动过 Hold-out + 成本审计
- Reward hacking 监控：Hard 子集分数变化
- 训练产出 Agent 重新建立 Baseline，进入下一循环
团队与流程（持续）
- 角色分工到位：Engineer/TrainEng/ResEng/TL/QA 各自职责明确
- 发布 Release Gate 三条线过（Full/Safety/Cost）
- Benchmark 相关性每季度审计一次（和线上 A/B 比）
- 私有黄金集每季度新增 10-20 条（从生产 bad case 回灌）
- 中心存储至少保留 90 天历史，支持多维查询
- 新成员入职第一课：怎么读评测报告、怎么跑 baseline
- 年度大版本：重新过一遍 Harness / Benchmark / Verifier 三件套是否依然合适
常见陷阱与反模式
陷阱 1：只追一个 Benchmark 的分数，上线翻车
征兆：团队把 Benchmark 分数作为单一 KPI，分数涨了 20 分但线上用户反馈没变好。 解药：20% 私有黄金集 + 定期生产 case 回灌 + 线上 A/B 测试和离线分数的相关性审计。相关系数 < 0.7 就该换 Benchmark。
陷阱 2：数据泄露 / Test Set Contamination
征兆：新模型从 60 分直接跳到 90 分，换个任务集立刻掉回 60 分。 解药：私有黄金集权限隔离、公共数据集定期换版本、训练前 n-gram overlap 检查。
陷阱 3：用 LLM-as-judge 做主 reward
征兆：同一个任务跑两次，reward 0.9 和 0.5 都出现，方差巨大。 解药：LLM-as-judge 最多用于失败原因聚类 / 开放式内容辅助检查，主 reward 用代码化、确定性 verifier。
陷阱 4：改 Prompt 不存版本
征兆："上周这个 case 明明过的"——但没人知道上周 Prompt 是啥。 解药：Prompt 模板代码化，每次改都进 git，sha256 记录进评测元数据。
陷阱 5：RL 过拟合训练分布
征兆：训练 reward 一路飙升，但 hold-out 分数不涨甚至下降。 解药：每个 checkpoint 必过独立 hold-out；KL penalty 调大；多任务混合训练；self-play 定期 reset 采样池。
陷阱 6：把"更聪明的模型"当万能药
征兆：分数低就换更大的模型，不做进一步分析。 解药：任何模型升级都要做分桶 + 成本审计。很多时候 7B + 评测 + RL 训练出来的 Agent，在 (score, cost) 组合上比 Opus 级别模型更优。
陷阱 7：没人看失败 case，只看总分
征兆：团队只讨论总分变化曲线，没人点进失败 case 看一眼。 解药：每周一次 30 分钟 Failure Review——随机抽 5 个失败 case 看轨迹，讨论 Verifier 是否误判、Prompt 该补什么、环境缺什么。坚持 8 周，分数会自己涨。
本章小结
- 黄金数据集是评估的"源代码"，每个条目含输入/期望输出/元数据三要素
- 构建六步：错误分析 → 种子集 → 标注纪律 → 统计严谨性 → 版本化 → 合成扩增
- EDD 工作流四阶段 + CI 三级门禁（PR/Nightly/Release）+ 发布后在线闭环
- 评分器策略：代码优先、LLM 判官补开放式、人工审安全、混合全覆盖
- 选型决策矩阵覆盖 8 大场景
- 端到端案例 + 30 条 Checklist + 7 个常见陷阱
参考资料
官方文档
- Defining the Dataset That Powers Your Experiments（Arize Phoenix 文档）
- Claude Code Eval Harness SKILL.md（ECC 项目）— EDD 原则、评分器类型、pass@k
- Google ADK Evaluation 文档 — golden path、用户模拟、轨迹评估
- From "Vibe Checks" to Continuous Evaluation（Google Cloud Blog, 2026）— 推理轨迹捕获、运行时 Schema 集成
GitHub 与工具
- AI Agent Evaluation Pipeline（GitHub）— 黄金集/影子集/对抗集/合成集四种数据集的分工
- METR AgentEvals / RE-Bench — 82 名人类专家对照实验，人类标注参考标准
- promptfoo / DeepEval / Inspect AI 文档 — CI 门禁与在线评估实践
博客与文章
- 基于 Evaluation 的 AI Agent 开发实践全景指南（本项目博客 2026-08-28）— 构建流程、Checklist、陷阱的数据来源
- Reliable Evaluations for LLMs and AI Agents（Springer, 2026）