端到端 Eval 与数据集设计

1. 为什么这组知识要一起学

本章刻意区分 Observability、Testing、Evaluation：三者共享数据但回答不同问题，不能互相替代。

这几个知识点处在同一条工程链上。如果只记单个名词，很容易在真实系统里把责任放错层：例如让模型管理程序事实、让数据库 transaction 承担外部 API 原子性，或把一个 provider SDK 的行为误认为 Agent 的通用规律。

2. Mental Model

Observability 解释“发生了什么”，Testing 验证软件契约，Evaluation 衡量 Agent 效果；三者共享 trace/data 但目的不同。

Run → Spans/Events/Metrics → Trace Store → Test Assertions / Eval Dataset → Graders → Regression Decision

3. 核心机制

End-to-End Evaluation

Component eval 定位 retriever/tool/planner/context 子系统；end-to-end eval 看真实任务是否完成。只做后者很难定位回归来源。

Eval Dataset Design

数据集应覆盖代表任务、边界、对抗/注入、失败/超时、权限、长期恢复，并版本化输入和期望。

Deterministic Grader

文件是否存在、JSON schema、DB state、调用次数、trajectory constraint 等可程序判断的，应优先 deterministic grader。

4. 最小实现 / 伪代码

下面代码只表达边界和生命周期，不要求照抄到项目中：

with tracer.start_as_current_span("tool.execute") as span:
    span.set_attribute("tool.name", tool.name)
    result = await tool.execute(args)
    metrics.tool_latency.record(timer.elapsed)
    return result

真正实现时应把 I/O、状态持久化、错误翻译和策略注入拆成可测试组件，而不是把示例扩成一个巨型函数。

5. 在 Shadow Harness 中怎么落地

统一 trace_id/run_id/node_id/tool_call_id；支持 OTEL 兼容 export；Fake/Scripted Model 测 Runtime，真实 provider 留给 integration/eval。

建议为本章涉及的行为留下明确的 domain object、interface 和 trace event；只要一个关键行为只能通过读日志猜测，就说明 Runtime contract 仍不够清晰。

6. Production Engineering 检查项

• 敏感 prompt/tool payload 默认最小采集
• 确定性可判定就不用 model judge
• eval set 要覆盖失败/边界
• 基准必须重复试验控制噪声

7. Failure Modes

7.1 只看最终答案

当出现「只看最终答案」时，用 trace 定位组件，再选择 deterministic assertion 或 eval rubric；不要用 model judge 掩盖软件 contract bug。 这类问题通常需要修改 contract、policy、state 或 adapter，而不是只追加 Prompt。

7.2 把日志当 trace

当出现「把日志当 trace」时，用 trace 定位组件，再选择 deterministic assertion 或 eval rubric；不要用 model judge 掩盖软件 contract bug。 这类问题通常需要修改 contract、policy、state 或 adapter，而不是只追加 Prompt。

7.3 model judge 评所有东西

当出现「model judge 评所有东西」时，用 trace 定位组件，再选择 deterministic assertion 或 eval rubric；不要用 model judge 掩盖软件 contract bug。 这类问题通常需要修改 contract、policy、state 或 adapter，而不是只追加 Prompt。

7.4 benchmark 只跑一次

当出现「benchmark 只跑一次」时，用 trace 定位组件，再选择 deterministic assertion 或 eval rubric；不要用 model judge 掩盖软件 contract bug。 这类问题通常需要修改 contract、policy、state 或 adapter，而不是只追加 Prompt。

7.5 trace 泄露 secret/PII

当出现「trace 泄露 secret/PII」时，用 trace 定位组件，再选择 deterministic assertion 或 eval rubric；不要用 model judge 掩盖软件 contract bug。 这类问题通常需要修改 contract、policy、state 或 adapter，而不是只追加 Prompt。

8. Trade-offs

全量 payload 易 debug 但隐私/成本高；结构化 metadata 安全但信息少；生产需要采样与可配置敏感字段。

设计记录最好明确：当前约束是什么、备选方案有哪些、为什么现在选这个、未来什么条件出现时需要重构。 这样 ADR 才能随着模型和基础设施变化被重新审视。

9. Experiment / Evaluation

建立 golden traces、fault injection、trajectory grader 和 regression suite；比较版本前后 success/latency/token/step count。

实验应固定数据集、版本和环境，至少记录 success、latency、token/cost、attempt/step 数以及失败类型；涉及随机模型时需要重复运行而不是只看一次结果。

10. 常见问题

基础：End-to-End Evaluation 最容易被误解的点是什么？

Component eval 定位 retriever/tool/planner/context 子系统；end-to-end eval 看真实任务是否完成。只做后者很难定位回归来源。

机制：这些能力在一次 Run 的哪个生命周期阶段生效？

沿着 Run → Spans/Events/Metrics → Trace Store → Test Assertions / Eval Dataset → Graders → Regression Decision 找位置，并明确它的输入、输出、持久化事实和失败传播。

工程：如果这一层失败，应该由谁恢复？

先区分 transient failure、invalid input、permission、semantic failure 与 irreversible side effect。恢复策略属于拥有该状态与副作用的 Runtime/adapter，而不是交给模型自由决定。

设计：规模扩大 10 倍后，哪个假设最先失效？

优先检查 context/token、并发/连接池、catalog 大小、持久化吞吐、trace 体积、身份与租户隔离。不要默认“多加机器”能解决语义和一致性问题。

11. Sources

• OpenAI Agents SDK — Tracing
• OpenAI Agents SDK — Testing
• OpenTelemetry — GenAI semantic conventions
• LangGraph — Persistence

12. 本文结论

掌握本文的标准不是能背定义，而是能画出数据流、写出最小 contract、解释失败恢复，并用测试或 benchmark 证明设计没有只停留在概念层。