文章类型技术长文 所属专栏Agent 观测 预计阅读55 分钟 文档状态已发布

第 8 篇：从生产 Trace 构造 Agent 评测数据集

从生产 Trace 的候选发现、准入门槛、Failure Taxonomy 与样本重建，走到去重切分、血缘版本和持续更新的评测数据流水线。

开始阅读全文10998 字 · 55 分钟 查看系列目录Agent 观测

作者Jupiter 发布日期2026/08/06 最近更新2026/08/06 正文规模10998 字

关键词 AgentEvaluationTraceDataset数据血缘

栏目 AgentObservability；专栏 Agent 观测；标签 Agent、Evaluation、Trace、Dataset、数据血缘

文章目标#

生产环境是 Agent 失败模式最丰富的数据源，但生产 Trace 不是天然的 Benchmark。

一条原始 Trace 可能包含：

用户真实目标；
多轮模型请求；
检索、记忆和 Tool Call；
权限审批；
网络重试与故障恢复；
文件、数据库或浏览器状态变化；
用户反馈；
最终回答。

这些信息让 Trace 看起来很“完整”，但从评测角度看，它仍然可能：

没有明确任务边界；
缺少初始环境；
缺少可验证 Outcome；
无法复现当时的工具和外部服务；
包含大量偶然上下文；
与其他 Trace 高度重复；
带有无权用于评测的数据；
已经泄漏到训练或调试流程。

因此，从生产 Trace 构造评测数据集不是一次简单导出，而是一条有门槛的数据工程与评测工程流水线：

1
Production Signals
2
→ Candidate Discovery
3
→ Privacy / Authorization Gate
4
→ Trace Completeness Gate
5
→ Failure Classification
6
→ Deduplication & Clustering
7
→ Evaluation Case Reconstruction
8
→ Ground Truth & Rubric
9
→ Human Calibration
10
→ Split & Leakage Control
11
→ Versioned Dataset
12
→ Experiment / Regression Gate
13
→ Drift Monitoring

本篇解决的核心问题是：

如何把一次不可控、不可重复的生产运行，改造成一个可复现、可标注、可版本化、可长期维护的 Evaluation Case？

本文继续使用一个 Coding Agent 场景作为贯穿案例：

用户要求 Agent 修复订单模块中的折扣计算 Bug，只允许修改 orders/ 和 tests/orders/，不得修改 payments/。生产运行中 Agent 搜索代码、修改文件、运行测试，并在一次网络断流后恢复执行。

我们将把这条生产 Trace 逐步转化为一个 Evaluation Case：

1
输入：
2
用户目标 + 冻结仓库快照 + 工具集合 + 权限 + 预算
3

4
期望结果：
5
目标测试通过 + 原有测试不退化 + 只修改允许目录
6

7
评测规则：
8
Outcome Grader + Forbidden Action Grader
9
+ Trajectory Rubric + Recovery Grader
10

11
血缘：
12
Source Trace → Case Version → Dataset Version → Experiment Run

Anthropic 将生产监控、用户反馈和 Transcript Review 视为 Agent Eval 的重要样本来源，但同时强调 Task 必须具有明确输入、环境、成功标准和可验证 Outcome。¹ Langfuse 的 Dataset Item 数据模型也将 input、expectedOutput、metadata、sourceTraceId 和 sourceObservationId 分开，说明生产 Trace 与可执行 Dataset Item 是两个不同层次的对象。²

1. 生产 Trace 为什么不能直接作为评测集#

为什么生产 Trace 不能直接作为评测集

1.1 大量重复和低信息任务#

真实流量通常呈现明显的头部集中。

例如客服 Agent 的生产请求可能大量重复：

1
查询订单状态
2
重置密码
3
取消未发货订单
4
解释退款政策

Coding Agent 也可能反复收到同一模板：

1
修复一个测试失败
2
补充 README
3
修改一个配置项
4
更新依赖版本

如果直接将 Trace 全量导出：

高频简单任务会占据绝大多数样本；
稀有失败和边界场景被淹没；
Dataset 分数接近生产流量平均值，却无法暴露系统脆弱点；
Experiment 成本被大量低信息样本消耗；
模型或 Agent 只需优化头部模板就能显著提高总分。

低信息不等于简单#

某些 Trace 虽然很长，却没有新的评测信息：

1
同一 Tool 重试十次
2
相同用户问题重复提交
3
Agent 输出不同措辞但路径完全一致
4
同一根因生成多个事故 Trace

应把“样本长度”和“样本信息量”分开。

一个候选样本的信息量可以粗略理解为：

I(x) = \alpha \cdot Novelty(x) + \beta \cdot FailureSeverity(x) + \gamma \cdot CoverageGain(x) + \delta \cdot Uncertainty(x) - \lambda \cdot Redundancy(x)

它不是必须精确实现的数学公式，而是一条筛选原则：

一个新样本是否补充了新的任务、工具组合、失败机制、环境状态或判定边界？

代表样本而不是随机保留#

对同一近重复簇，代表样本应优先选择：

证据链最完整；
Outcome 最可验证；
环境最容易重建；
边界更困难；
对用户影响更大；
能区分 Agent 版本；
隐私风险更低。

语义去重研究表明，仅去掉完全相同文本无法消除大规模数据中的语义冗余，嵌入与聚类可以识别表面不同、含义高度相似的样本。³ 但去重也可能误删长尾和少数群体，因此必须在类别、语言、租户、失败模式和风险层内执行，而不是用一个全局相似度阈值粗暴裁剪。⁴

1.2 成功样本远多于失败样本#

成熟 Agent 的线上流量通常以成功为主。

假设：

1
Verified Success：96%
2
Partial / Failure：4%

随机抽取 10,000 条 Trace，只会得到约 400 条失败，而且失败内部还可能高度集中在：

同一个 Provider 事故；
某个版本的 Tool Schema Bug；
一个大客户的特殊工作流；
同一类权限配置错误。

如果评测集按生产自然分布构造：

1
永远回答正常路径

就可能得到很高总分。

生产分布集与挑战集分开#

建议至少保留两套视图。

Production Representative Set#

目标：

1
估计真实线上平均质量

采样接近生产分布，保留真实任务频率。

Risk / Challenge Set#

目标：

1
暴露失败、长尾、安全和恢复能力

对以下样本过采样：

用户差评；
人工接管；
高风险写操作；
网络恢复失败；
安全策略触发；
新 Tool 组合；
版本回归；
Judge 与规则冲突；
多 Trial 不稳定。

两者不能合成一个总分后失去语义。

推荐同时报告：

1
Production-weighted Score
2
Macro Score by Failure Type
3
Worst-group Score
4
Safety Failure Count
5
Recovery Rate

成功样本仍然必要#

失败过采样不意味着只保留失败。

成功样本用于：

建立正常轨迹基线；
识别不应触发的工具；
比较 Success Trace 与 Failure Trace；
防止修复某个失败后破坏正常路径；
构造正负成对样本；
评估成本与效率。

1.3 Trace 缺失或链路不完整#

生产 Trace 经常不是完整事实。

常见缺失：

1
根 Agent Span 缺失
2
第一轮 Prompt 未采集
3
Tool Result 被截断
4
子 Agent Trace 未关联
5
网络断流后没有结束事件
6
CLI 退出前未 Flush
7
环境 Diff 未保存
8
人工审批只在外部系统有记录

一条 UI 中“看起来有很多节点”的 Trace，仍可能无法形成 Evaluation Case。

完整性需要按必需边定义#

推荐为不同样本粒度建立完整性规则。

Task 级 Trace#

至少需要：

1
Task Input
2
Root Agent / Run
3
模型与 Prompt 版本
4
Tool Call 与 Tool Result 配对
5
最终回答
6
Environment Outcome

Tool Call 级样本#

至少需要：

1
调用前上下文摘要
2
Tool Name 与 Schema Version
3
Raw / Validated Arguments
4
Tool Result
5
执行状态
6
后续消费位置

Recovery 样本#

至少需要：

1
故障注入或错误事件
2
Attempt Tree
3
恢复动作
4
副作用状态
5
最终 Outcome

完整性不是字段数量#

一个 Trace 可能有 300 个字段，却缺少最关键的：

1
state_before
2
state_after

因此应使用“证据边完整性”，而不是简单字段覆盖率。

示例：

1
model_call → tool_call
2
tool_call → tool_result
3
tool_result → next_model_call
4
write_tool → state_diff
5
trace → verified_outcome

如果任一必需边缺失，候选样本应进入：

1
QUARANTINED

而不是直接进入 Dataset。

1.4 缺少可验证 Outcome#

原始 Trace 最常见的问题是：

1
Agent 最终回答存在
2
但环境结果不存在。

例如：

1
Agent：
2
“退款已经成功。”
3

4
Trace：
5
有 process_refund Tool Result。
6

7
缺失：
8
数据库是否真的产生 Refund Record。

或：

1
Agent：
2
“测试全部通过。”
3

4
Trace：
5
有 run_tests Tool Call。
6

7
缺失：
8
测试报告、Exit Code 和最终工作区状态。

Final Response 不能替代 Outcome#

必须区分：

1
Claimed Outcome
2
Verified Outcome

1
{
2
  "claimed_outcome": {
3
    "task_status": "success",
4
    "tests_passed": true
5
  },
6
  "verified_outcome": {
7
    "task_status": "failure",
8
    "tests_passed": false
9
  }
10
}

Outcome 的来源#

可验证 Outcome 可以来自：

数据库 State Assertion；
文件系统 Snapshot；
Git Diff；
单元测试或集成测试；
浏览器 DOM / Backend State；
外部服务查询；
Delivery Ledger；
人工专家确认。

Anthropic 的 Agent Eval 定义明确区分 Transcript 与 Outcome：Agent 可以声称完成，但真正 Outcome 取决于环境终态。¹

无 Outcome 的 Trace 如何处理#

三种选择：

补建 Outcome
通过日志、数据库、Artifact 或人工取证重建。
降粒度
无法构造 Task-level Case，但可以构造 Tool Call 或 Response-level Case。
拒绝入选
如果评测目标是端到端任务成功，缺少 Outcome 就不能进入 Gold Dataset。

1.5 生产环境不断变化#

线上运行时，以下对象都可能变化：

1
Agent Code
2
模型 Revision
3
Prompt
4
Tool Schema
5
MCP Server
6
Retriever Index
7
数据库 Schema
8
业务政策
9
网页 DOM
10
第三方 API
11
权限
12
当前时间

同一 Trace 在一个月后重新执行，可能得到不同结果。

Trace 记录的是历史事实，不是可复现环境#

要把 Trace 转成 Case，必须把动态依赖冻结或替换为 Fixture。

例如：

1
生产 Trace：
2
读取 GitHub Issue #482
3
搜索 main 分支
4
调用实时 CI
5
读取当前依赖文档
6

7
Evaluation Case：
8
冻结 Issue 内容
9
固定 Repository Commit
10
固定 CI 容器
11
固定依赖文档 Snapshot

环境漂移的两类影响#

Case 无法复现#

原 API 已下线，原页面已变化，原仓库 Commit 不存在。

Ground Truth 失效#

政策变化后，旧的正确回答变成错误回答。

因此 Dataset 必须记录：

1
environment_revision
2
valid_from
3
valid_until
4
retirement_reason

SWE-bench-Live 通过持续收集新 GitHub Issue、为任务构建独立容器环境并周期更新，说明动态、可执行 Benchmark 需要同时解决“新鲜度”和“可复现性”。⁵ LiveBench 通过持续加入基于近期信息的新问题和客观 Ground Truth，降低静态测试集污染和过时风险。⁶

1.6 隐私、授权和敏感内容#

生产 Trace 可能包含：

1
用户个人信息
2
客户业务数据
3
源代码
4
数据库记录
5
访问 Token
6
邮件
7
合同
8
医疗或金融信息
9
内部 Prompt
10
Tool Result
11
浏览器页面

“系统已经采集了 Trace”不等于：

1
可以将其用于评测
2
可以分享给标注员
3
可以进入长期 Dataset
4
可以导出到第三方 Judge

需要独立的数据使用授权#

每个候选 Trace 应有：

1
collection_purpose
2
evaluation_use_allowed
3
human_annotation_allowed
4
external_judge_allowed
5
retention_policy
6
tenant_scope
7
data_residency
8
deletion_link

目的限制与最小化#

GDPR 第 5 条要求个人数据具有明确合法目的，并且仅保留与目的相关、必要的数据；这意味着评测数据不能沿用“生产观测”作为无限制的二次使用授权。⁷

分层内容策略#

原始层#

仅限受控生产存储：

1
raw_trace
2
raw_prompt
3
raw_tool_result

脱敏候选层#

1
pseudonymized_user_id
2
redacted_content
3
normalized_entity
4
artifact_hash

Evaluation Case 层#

只保留复现和评分所需的最小信息。

不可逆匿名化并不总能实现#

代码、自然语言和轨迹可能通过上下文重新识别用户或组织。

因此要同时采用：

删除直接标识符；
对 ID 做租户级 HMAC；
替换业务实体；
删除无关内容；
访问控制；
保留期限；
标注员最小权限；
Judge 数据边界；
删除请求传播。

2. 数据来源#

从生产信号发现高价值评测样本

2.1 生产 Trace#

生产 Trace 提供最真实的：

任务分布；
工具组合；
用户表达；
环境差异；
网络故障；
成本和延迟；
未预期路径。

但它的偏差也最复杂：

1
没有完整 Ground Truth
2
成功任务多
3
低信息任务多
4
不同用户和租户混合
5
环境持续漂移

生产 Trace 适合作为：

1
Candidate Pool

不适合直接作为：

1
Frozen Test Set

2.2 用户反馈#

用户反馈包括：

1
点赞 / 点踩
2
问题是否解决
3
投诉
4
重新打开工单
5
撤销 Agent 操作
6
重复提问
7
人工纠正

优点：

直接反映用户价值；
容易发现自动 Grader 未覆盖的问题；
能揭示表达、信任和产品体验问题。

偏差：

反馈稀疏；
用户只在极好或极坏时反馈；
负反馈未必来自 Agent；
用户可能误判环境结果；
不同用户标准不同。

用户反馈不是最终标签#

应作为：

1
discovery_signal

再通过：

1
Trace Review
2
Environment Verification
3
Failure Classification

确定是否进入 Dataset。

2.3 人工接管记录#

人工接管通常是高价值样本。

触发原因：

1
Agent 低置信度
2
权限不足
3
多次恢复失败
4
用户要求人工
5
安全策略升级
6
Agent 路径过长

需要记录：

1
handoff_reason
2
handoff_step
3
human_action
4
human_corrected_output
5
environment_before
6
environment_after

人工接管可以产生两类 Case：

何时应该升级人工；
升级前 Agent 做错了什么。

不要只保存人工最终答案，否则会丢失升级决策的上下文。

2.4 线上事故#

线上事故具有高影响、低频率和强因果价值。

可转成：

1
Safety Case
2
Recovery Case
3
Regression Case
4
Fault Injection Case

事故 Trace 应同时关联：

1
incident_id
2
root_cause
3
first_anomaly
4
blast_radius
5
mitigation
6
missing_observability

从事故构造样本#

不要只复制事故输入。

需要重建：

1
事故前初始状态
2
触发条件
3
故障注入点
4
期望恢复动作
5
禁止副作用
6
最终安全状态

例如：

1
工具已完成写操作，但 Tool Result 丢失。

Evaluation Case 应检查：

1
Agent 是否查询执行状态
2
是否使用 Idempotency Key
3
是否避免重复写入

2.5 客服和 Bug 报告#

客服、Issue Tracker 和 Bug Report 提供：

用户自然语言描述；
复现步骤；
影响范围；
人工诊断；
修复结果。

它们适合补充生产 Trace 中缺失的：

1
用户真正意图
2
预期行为
3
问题严重度
4
正确处理方式

关联方法#

1
support_ticket_id
2
bug_id
3
incident_id
4
source_trace_ids

一个 Bug 可能对应多个生产 Trace。

建议先聚类到：

1
Failure Episode

再选代表 Trace，而不是每条都变成 Case。

2.6 专家构造样本#

专家样本用于：

覆盖生产中极少出现的风险；
构造清晰边界；
补齐类别；
建立 Gold；
校准 Judge；
验证政策。

优势：

目标明确；
Ground Truth 强；
可控；
容易隔离。

风险：

语言不自然；
环境过于干净；
路径过于理想；
与真实用户分布不一致。

因此专家集不能替代生产集，两者应分层报告。

2.7 合成边界与故障样本#

合成样本适合系统性覆盖组合空间：

1
工具 × 权限 × 故障 × 任务类型

例如：

1
read-only tool + timeout
2
write tool + ack lost
3
MCP tool + reconnect
4
compaction + pending approval

合成不是让 LLM 自由生成#

应由模板和约束生成：

1
template:
2
  task_type: refund
3
  amount_bucket:
4
    - low
5
    - boundary
6
    - over_limit
7
  identity_status:
8
    - verified
9
    - unverified
10
  fault:
11
    - none
12
    - timeout_after_commit

再由专家抽样审核。

合成样本的角色#

1
覆盖边界
2
验证恢复
3
压力测试安全

不适合估计真实生产平均质量。

3. Trace 入选门槛#

Trace 从候选到 Gold 的入选门槛

建议将 Candidate 生命周期设计为状态机：

1
DISCOVERED
2
→ QUARANTINED
3
→ ELIGIBLE
4
→ CURATED
5
→ ANNOTATED
6
→ GOLD
7
→ ACTIVE
8
→ ARCHIVED

任何硬门槛失败都应记录：

1
rejection_reason

而不是静默丢弃。

3.1 执行链完整#

最低要求取决于样本粒度。

Task-level#

1
用户目标
2
Root Run
3
模型调用
4
Tool Call / Result
5
最终回答
6
环境 Outcome

Trajectory-level#

1
Step 顺序
2
每步 Action
3
每步 Observation
4
终止原因

Tool-level#

1
调用上下文
2
Tool Schema
3
Arguments
4
Execution
5
Result
6
Downstream Use

推荐完整性清单：

1
{
2
  "root_present": true,
3
  "task_input_present": true,
4
  "model_calls_complete": true,
5
  "tool_pairs_complete": true,
6
  "environment_outcome_present": true,
7
  "artifact_references_resolvable": true
8
}

内容被截断时#

不能将：

1
output_truncated = true

默认为完整。

处理：

从 Artifact Store 恢复；
降粒度；
标记 insufficient_evidence；
拒绝进入 Gold。

3.2 模型、工具和环境版本明确#

必须能回答：

1
哪个 Agent 版本
2
哪个模型和 Provider
3
哪个 Prompt
4
哪个 Tool Schema
5
哪个 Retriever
6
哪个环境

版本不明确的风险#

同一个失败可能来自：

1
Agent 逻辑
2
Tool Schema 变更
3
模型升级
4
环境变化

无法归因的 Trace 不适合作为长期回归样本。

3.3 Tool Input 与 Tool Result 完整#

每个 Tool Call 必须配对：

1
tool_call_id
2
tool_name
3
schema_version
4
raw_arguments
5
validated_arguments
6
execution_status
7
result
8
error
9
attempts

写工具还需要#

1
state_before
2
state_after
3
state_diff
4
idempotency_key

Result 完整不等于 Result 被使用#

如果评测目标是“模型是否正确使用工具结果”，还需记录：

1
attached_to_state
2
injected_into_model
3
downstream_action

3.4 环境 Outcome 可验证#

入选端到端 Dataset 的 Trace 必须有至少一种独立 Outcome 证据：

1
state assertion
2
test result
3
database diff
4
browser backend state
5
external service query
6
human verified artifact

Outcome 验证等级#

1
L0：仅 Agent 声明
2
L1：Tool Result 声明
3
L2：环境读取验证
4
L3：独立 Grader 验证
5
L4：多源一致 + 人工 Gold

3.5 可以复现或重建#

入选前运行：

1
Reconstruction Dry Run

步骤：

从 Snapshot 恢复初始环境；
注入 Task Input；
启用冻结工具；
运行 Reference Solution；
运行 Grader；
验证 Case 可重复。

复现状态#

1
REPRODUCIBLE
2
RECONSTRUCTABLE_WITH_MOCK
3
PARTIALLY_REPRODUCIBLE
4
NON_REPRODUCIBLE

只有前两类适合核心 Dataset。

非复现样本可以保留在：

1
Forensic Archive

用于事故研究，但不应进入稳定 Benchmark。

3.6 不包含无法授权使用的数据#

硬门槛：

1
evaluation_use_allowed = true

还要分别检查：

1
human_annotation_allowed
2
third_party_judge_allowed
3
long_term_retention_allowed
4
cross_region_transfer_allowed

自动扫描#

1
PII
2
Secret
3
Credential
4
Source Code Classification
5
Tenant Policy
6
Data Residency
7
Copyright / License

数据删除传播#

如果源数据需要删除，应能够沿血缘删除：

1
Source Trace
2
→ Dataset Item
3
→ Derived Artifact
4
→ Annotation Copy
5
→ Export

这也是为什么 source_trace_id 和 Provenance 不是可选装饰。

4. 样本粒度#

4.1 Session 级#

一个 Session 包含多个 Trace 或 Turn。

适合：

多轮一致性；
长期目标；
记忆；
人工接管；
用户满意度；
跨 Turn 恢复。

风险：

样本过大；
Ground Truth 难定义；
初始状态复杂；
多个子任务混合。

Session-level Case 应先切分逻辑 Task，再决定是否保留全 Session。

4.2 Task 级#

Task 是最常用的 Agent Eval 粒度。

适合：

1
端到端任务完成
2
环境 Outcome
3
成本
4
恢复
5
安全

一个 Task 可以跨多个 Turn 和多个模型请求。

推荐默认：

1
一个 Dataset Item = 一个可复现 Task

4.3 Turn 级#

Turn 适合评价：

单次用户请求；
澄清问题；
最终回复；
一个对话阶段；
Prompt / Model 版本。

它不一定包含完整任务 Outcome。

例如：

1
用户补充“不要修改支付模块”

可以构造 Constraint-following Turn Case。

4.4 Step 级#

Step 级适合：

1
规划质量
2
局部决策
3
是否使用证据
4
是否产生进展

输入：

1
当前状态 + 可见上下文

目标：

1
合理的下一步动作集合

难点是不能假设唯一最佳动作。

Ground Truth 应是：

1
acceptable_actions
2
forbidden_actions
3
required_properties

4.5 Tool Call 级#

适合：

Tool Selection；
Arguments；
Approval；
Result Parsing；
Retry Decision；
Side Effect。

Tool-level Case 可以快速运行，适合 PR Gate。

示例：

1
{
2
  "input": {
3
    "task": "只允许修改 orders/",
4
    "state": {
5
      "target_file": "payments/service.py"
6
    },
7
    "tools": ["read_file", "edit_file"]
8
  },
9
  "expected": {
10
    "forbidden_tool_calls": [
11
      {
12
        "tool": "edit_file",
13
        "path_prefix": "payments/"
14
      }
15
    ]
16
  }
17
}

4.6 如何根据评测目标选择粒度#

评测目标	推荐粒度
任务是否完成	Task
多轮一致性	Session
最终回复质量	Turn / Generation
下一步决策	Step
Tool 参数	Tool Call
网络恢复	Operation / Attempt + Task
记忆污染	Session / Task
权限与安全	Tool Call + Task Outcome
成本与延迟	Task / Trace
Judge 校准	对应被评分对象

一个 Dataset 可以包含多种粒度，但必须在 Manifest 中显式标记：

1
sample_granularity

不要把 Tool-level 和 Task-level 分数直接平均。

5. 样本发现与智能采样#

5.1 用户差评#

优先发现：

1
thumbs_down
2
low_rating
3
ticket_reopened
4
user_correction
5
repeat_request

但差评要经过 Root Cause Review。

标签：

1
USER_DISSATISFACTION
2
AGENT_FAILURE
3
PRODUCT_LIMITATION
4
ENVIRONMENT_FAILURE
5
USER_ERROR
6
UNKNOWN

只有确认与 Agent 可评测行为相关时，才构造 Case。

5.2 人工接管#

高价值条件：

1
handoff_reason = low_confidence
2
handoff_reason = policy_conflict
3
handoff_reason = repeated_failure
4
handoff_reason = unsafe_action

优先保存：

接管前最后状态；
Agent 建议动作；
人工实际动作；
最终 Outcome；
差异。

这类样本特别适合：

1
Escalation Decision Eval
2
Recovery Eval
3
Human Correction Dataset

5.3 高成本和长链路任务#

候选条件：

1
cost > p95 / p99
2
latency > p95 / p99
3
tool_calls > threshold
4
model_calls > threshold
5
no_progress_steps > threshold

高成本 Trace 不一定失败。

它可以构造：

1
Trajectory Efficiency Case
2
Loop Detection Case
3
Tool Result Compression Case

与正常 Trace 配对#

同一个任务模板中选择：

1
Low-cost Success
2
High-cost Success
3
Failure

有利于分析成本差异来自哪里。

5.4 网络恢复失败#

筛选：

1
429
2
5xx
3
stream_disconnect
4
tool_timeout
5
mcp_disconnect
6
retry_exhausted

候选必须具备：

1
Attempt Tree
2
Retry Policy
3
Side-effect Status
4
Final Outcome

否则只能构造故障分类样本，不能构造恢复能力样本。

5.5 稀有工具组合#

工具组合可以表示为：

1
tool_set
2
tool_order
3
dependency_graph

例如：

1
search_code → read_file → edit_file → run_tests

稀有组合不等于高价值。

优先保留：

1
低频 + 高影响
2
低频 + 新能力
3
低频 + 失败
4
低频 + 安全敏感

可以对 Tool N-gram 或 Tool Graph 做频率统计。

5.6 新版本回归#

对比：

1
旧版本成功
2
新版本失败

相同：

1
Task Template
2
Environment
3
Tool Set

差异 Case 优先级很高，因为它直接进入 Regression Set。

推荐保存：

1
baseline_trace_id
2
candidate_trace_id
3
changed_components
4
trace_diff

5.7 高不确定性和评分冲突样本#

优先抽取：

1
LLM Judge 低置信度
2
多个 Judge 不一致
3
规则与 Judge 冲突
4
用户反馈与 Outcome 冲突
5
人工标注分歧

这些样本最适合改进：

1
Rubric
2
Judge
3
Task Contract
4
Grader

不一定是 Agent 最难样本。

5.8 Hard Case Mining#

Hard Case 不是简单选低分。

建议结合：

1
低成功率
2
多 Trial 方差高
3
版本间翻转
4
高 Judge 不确定性
5
高人类分歧
6
新 Failure Cluster
7
高成本
8
高安全风险

优先级函数：

P(x) = w_i I(x) + w_u U(x) + w_n N(x) + w_c C(x) + w_r R(x) - w_d D(x) - w_p P_{\text{privacy}}(x)

其中：

$I$ ：业务影响；
$U$ ：不确定性；
$N$ ：新颖度；
$C$ ：覆盖缺口；
$R$ ：风险；
$D$ ：重复度；
$P_{\text{privacy}}$ ：隐私处理成本。

主动学习式采样#

可以先用当前 Agent 在候选池上多 Trial 运行：

1
接近决策边界
2
版本间分歧
3
Judge 不稳定

的样本优先人工标注。

但 Test Holdout 不应参与持续 Hard Mining，否则会被反复优化。

6. Failure Taxonomy#

Failure Taxonomy 的目标不是给每条 Trace 贴一个唯一标签，而是区分：

1
root_cause
2
symptoms
3
contributing_factors

推荐记录：

1
{
2
  "primary_failure": "RETRIEVAL_ERROR",
3
  "secondary_failures": [
4
    "PLANNING_ERROR",
5
    "RECOVERY_ERROR"
6
  ],
7
  "first_anomaly_observation_id": "obs_12",
8
  "confidence": 0.86
9
}

6.1 Planning Error#

定义：

1
任务分解、依赖、停止条件或计划选择错误。

例子：

跳过必要验证；
计划修改错误模块；
过早锁定旧方案；
无进展循环；
子任务 Contract 不完整。

证据：

1
plan
2
step sequence
3
task contract
4
missing required actions

6.2 Tool Selection Error#

定义：

1
在当前状态选择了不合适的工具。

例子：

应查询却直接写入；
应使用专用 API 却调用 Shell；
选择已下线工具；
使用高风险工具而有低风险替代。

要先排除：

1
正确工具未被 Discovery 暴露
2
Tool Description 错误
3
权限过滤

这些是系统配置原因。

6.3 Tool Argument Error#

定义：

1
工具正确，但参数语法、语义、权限或状态不合法。

子类：

1
SYNTAX
2
SCHEMA
3
SEMANTIC
4
POLICY
5
STALE_STATE

示例：

1
edit_file(path="payments/service.py")

Schema 合法，Policy 违规。

6.4 Retrieval Error#

阶段：

1
Query Rewrite
2
Recall
3
Filter
4
Rerank
5
Selection
6
Injection
7
Citation

子类：

1
LOW_RECALL
2
WRONG_HIGH_RANK
3
STALE_INDEX
4
ACL_OVERFILTER
5
SELECTION_DROP
6
UNSUPPORTED_CLAIM

必须记录最早失败阶段。

6.5 Memory Error#

子类：

1
STALE_MEMORY
2
CONFLICT
3
SCOPE_LEAK
4
CROSS_USER
5
INCORRECT_SUMMARY
6
OVERDOMINANT_MEMORY

评测需要：

Memory-disabled Replay；
候选与过滤记录；
Injection 记录；
下游动作差异。

6.6 State Error#

定义：

1
Agent Runtime 状态机、Checkpoint、Pending Action 或版本状态不一致。

例子：

Tool 已执行但状态未提交；
Resume 使用旧 Checkpoint；
已完成动作重复执行；
子 Agent Result 未汇合；
错误 Parent 关系。

6.7 Recovery Error#

定义：

1
故障检测或恢复策略错误。

例子：

429 无退避；
Stream 中断后执行半截 Tool Call；
写工具 Outcome 未知却直接重试；
Retry Budget 失效；
Fallback 不兼容。

6.8 Safety Error#

子类：

1
PERMISSION_BYPASS_ATTEMPT
2
UNAUTHORIZED_MUTATION
3
SECRET_EXPOSURE
4
CROSS_TENANT_ACCESS
5
PROMPT_INJECTION_COMPLIANCE
6
IRREVERSIBLE_UNAPPROVED_ACTION

区分：

1
attempted
2
blocked
3
committed

被 Sandbox 阻止不代表 Agent 决策安全。

6.9 Outcome Verification Error#

定义：

1
任务可能完成，但验证逻辑错误，或 Agent 声明与环境不一致。

例子：

只看 Tool Success，不看业务状态；
测试覆盖不足；
Grader 误拒合法方案；
Final Response 声称成功但环境失败；
旧 Ground Truth 已失效。

这类错误属于评测系统本身，不能直接计为 Agent Failure。

7. 去重、聚类与覆盖率#

7.1 文本语义近重复#

推荐多级去重。

L0：Exact Hash#

1
hash(normalized_input)

L1：Lexical Near-duplicate#

1
Shingling
2
MinHash / LSH
3
Jaccard

L2：Semantic Near-duplicate#

1
Embedding
2
ANN Search
3
Cosine Similarity

L3：Task-equivalence Review#

由规则或人工判断：

1
是否测试同一能力和同一边界

规范化要保留重要变量#

可以替换：

1
user_id
2
order_id
3
timestamp

不能替换：

1
金额边界
2
权限状态
3
错误码
4
工具组合

否则不同 Case 会被错误合并。

7.2 轨迹近重复#

两个用户输入不同，Agent 可能走完全相同轨迹。

构造 Trajectory Fingerprint：

1
tool_name sequence
2
normalized argument schema
3
error sequence
4
state transition
5
termination reason

示例：

1
SEARCH → READ → EDIT → TEST_FAIL → EDIT → TEST_PASS

可以使用：

Sequence Edit Distance；
N-gram Jaccard；
Graph Embedding；
Dynamic Time Warping；
Canonical Tool DAG Hash。

轨迹去重用于保留不同失败机制，而不仅是不同文本。

7.3 任务模板重复#

将任务抽象为 Template：

1
intent
2
entity_type
3
operation
4
constraint_pattern
5
environment_type

示例：

1
intent = update
2
entity = order
3
constraint = approval_required

同一模板有大量实例时，保留：

典型；
边界；
失败；
不同工具路径；
不同语言；
不同权限。

7.4 同一仓库或业务实体泄漏#

随机切分会让同一实体跨 Train / Dev / Test。

Coding 场景：

1
同一 Repository
2
同一文件
3
同一 Issue Family
4
同一历史 PR

客服场景：

1
同一用户
2
同一订单
3
同一产品
4
同一政策模板

模型或 Agent 可能记住实体结构，产生虚高。

应构造 Group Key：

1
repository_id
2
business_entity_id
3
task_template_id
4
incident_cluster_id

并按 Group 切分。

7.5 类别、难度和工具组合均衡#

覆盖张量可以定义为：

1
Task Type
2
× Difficulty
3
× Failure Type
4
× Tool Set
5
× Risk
6
× Language
7
× Environment

不是每个 Cell 都要等量，但应明确目标权重。

难度信号#

1
Baseline Success
2
Human Time
3
Trajectory Length
4
Tool Count
5
Environment Complexity
6
Constraint Count

不要只用 Token 长度定义难度。

7.6 失败模式覆盖率#

定义：

Coverage(F) = \frac{ \sum_{f \in F} \mathbb{1}[\text{dataset contains qualified case for } f] }{ |F| }

更有用的是加权覆盖：

WeightedCoverage = \frac{ \sum_f w_f \cdot covered(f) }{ \sum_f w_f }

权重可由：

事故严重度；
生产频率；
业务影响；
检测难度；

确定。

还应统计：

1
每个 Failure Type 的样本数
2
有效环境数
3
工具组合数
4
多 Trial 结果

7.7 长尾场景覆盖率#

长尾不应只按频率最低定义。

高价值长尾：

1
低频 + 高风险
2
低频 + 新工具
3
低频 + 新租户配置
4
低频 + 恢复失败

监控：

1
uncovered production clusters
2
new tool graph
3
new failure code
4
new environment revision

去重研究提醒我们，强裁剪可能损害少数分布；长尾层应设置最小保留量。⁴

8. 从 Trace 重建 Evaluation Case#

从生产 Trace 重建可复现 Evaluation Case

8.1 重建用户目标#

生产用户表达可能包含：

多轮补充；
隐含目标；
无关内容；
身份信息；
生产偶然状态。

目标重建应输出：

1
goal
2
must
3
must_not
4
allowed_scope
5
completion_definition

示例：

1
user_goal:
2
  objective: >
3
    修复 quantity=0 时折扣计算错误。
4
  must:
5
    - 相关测试通过
6
    - 其他折扣行为不变
7
  must_not:
8
    - 修改 payments/**

不要由失败结果反推目标#

Case 的 Task Contract 只能包含用户当时可合理知道的要求，不能把：

1
生产事故后发现的内部根因

写进 Agent-visible Prompt。

8.2 冻结初始环境#

需要恢复到 Agent 开始前的状态：

1
state_before

Coding Agent：

1
Repository Commit
2
Working Tree
3
Dependencies
4
Container
5
Environment Variables

客服 Agent：

1
Database Snapshot
2
Ticket State
3
User Verification State
4
Policy Version

Browser Agent：

1
DOM / Backend State
2
Cookie
3
Account
4
Clock

Snapshot 必须验证#

1
snapshot_hash
2
reference_solution_pass
3
original_failure_reproduced

8.3 确定可用工具#

不要直接使用当前生产 Tool Set。

应恢复 Trace 当时的：

1
tool_name
2
schema
3
description
4
implementation
5
permission
6
timeout

如果旧工具无法运行：

保存兼容 Mock；
建立 Version Adapter；
退役 Case。

工具可见性是任务条件#

正确工具如果未被暴露，失败属于 Tool Discovery / Harness，而不是模型能力。

8.4 删除生产环境偶然信息#

需要删除：

1
真实用户 ID
2
真实订单号
3
当前时间噪声
4
无关聊天
5
内部 Ticket 链接
6
Trace ID 提示
7
生产错误标签
8
人工结论
9
Gold Patch

但不能删除决定任务难度的变量：

1
权限状态
2
金额边界
3
错误码
4
环境版本

偶然信息与必要上下文#

使用反事实检查：

1
删除这个字段后，任务仍定义清楚吗？
2
删除后会改变正确答案吗？

8.5 构造可复现 Fixture#

Fixture 类型：

1
Static File
2
Database Seed
3
HTTP Mock
4
Record-and-replay
5
MCP Fixture
6
Clock Fixture
7
Fault Injector

Fixture Manifest：

1
{
2
  "fixture_id": "fx_order_discount_03",
3
  "version": "1.2.0",
4
  "source_trace_id": "trace_prod_123",
5
  "repository_commit": "abc123",
6
  "http_recording_hash": "sha256:...",
7
  "clock": "2026-08-01T00:00:00Z"
8
}

Record-and-replay 的请求匹配#

不要只按 URL。

可以包括：

1
method
2
normalized_path
3
body_hash
4
selected_headers
5
sequence

同时删除 Secret。

8.6 记录禁止行为和预算#

Evaluation Case 需要显式：

1
forbidden_actions
2
max_wall_time
3
max_model_calls
4
max_tool_calls
5
max_cost
6
max_retries

完整 Case Manifest：

1
case:
2
  id: fix-discount-zero-quantity
3
  version: 3
4
  granularity: task
5

6
  source:
7
    trace_id: trace_prod_123
8
    observation_id: obs_root
9
    incident_id: null
10

11
  input:
12
    user_goal: >
13
      修复 quantity=0 时折扣计算错误。
14
    allowed_paths:
15
      - orders/**
16
      - tests/orders/**
17
    forbidden_paths:
18
      - payments/**
19

20
  environment:
21
    fixture_id: fx_order_discount_03
22
    container_image: coding-eval@sha256:...
23
    repository_commit: abc123
24

25
  tools:
26
    schema_set_hash: sha256:...
27
    names:
28
      - search_code
29
      - read_file
30
      - edit_file
31
      - run_tests
32

33
  budgets:
34
    wall_time_seconds: 600
35
    model_calls: 20
36
    tool_calls: 60
37
    cost_usd: 2.0
38

39
  forbidden_actions:
40
    - modify: payments/**
41
    - tool: git_push
42

43
  graders:
44
    - outcome-v4
45
    - forbidden-path-v2
46
    - recovery-v3

9. Ground Truth 与 Rubric#

9.1 最终正确环境状态#

最强 Ground Truth 是环境性质，而不是一个文本答案。

1
tests_passed
2
database_state
3
file_state
4
browser_state
5
external_object

示例：

1
{
2
  "tests": {
3
    "required": {
4
      "test_zero_quantity": "passed",
5
      "test_discount_boundaries": "passed"
6
    },
7
    "regression_suite": "passed"
8
  },
9
  "filesystem": {
10
    "changed_paths_subset_of": [
11
      "orders/**",
12
      "tests/orders/**"
13
    ]
14
  }
15
}

9.2 必须完成的动作#

只有当动作本身是业务要求时，才设为必须。

例如：

1
必须验证身份
2
必须取得审批
3
必须运行安全测试

不要把实现细节写成必须动作：

1
必须先调用 search_code

除非缺少该动作会导致不可审计或不安全。

9.3 禁止执行的动作#

禁止动作通常是硬门禁：

1
修改禁止资源
2
绕过审批
3
重复不可逆写入
4
外泄 Secret
5
调用生产 Endpoint

记录：

1
attempted
2
blocked
3
committed

9.4 可接受的多种轨迹#

Ground Truth 可以表示为约束图：

1
必须满足：
2
read evidence before write
3
write before final verification
4

5
允许：
6
search → read → edit
7
read → test → edit
8

9
禁止：
10
push before tests

Trajectory Grader 检查：

1
partial order

而不是唯一完整序列。

9.5 部分成功和分级得分#

复杂任务可能分成：

1
定位根因
2
修复代码
3
补充测试
4
通过回归
5
输出说明

分级：

1
partial_credit:
2
  root_cause_identified: 0.15
3
  patch_applies: 0.20
4
  target_tests_pass: 0.30
5
  regression_tests_pass: 0.20
6
  explanation_correct: 0.15

但硬门禁仍单独执行。

1
修改 payments/
2
→ Final Pass = false

无论软分多高。

9.6 成本和时间边界#

可以是：

1
硬预算
2
软评分

硬预算：

1
超过 30 分钟自动终止
2
超过 5 美元自动终止

软评分：

EfficiencyScore = \exp( -\alpha \cdot Cost -\beta \cdot Latency )

实际可以使用分桶：

1
excellent
2
acceptable
3
expensive
4
unacceptable

更容易解释。

9.7 恢复能力评分#

恢复 Grader 不只看最终成功。

维度：

1
检测故障
2
选择正确策略
3
尊重 Retry-After
4
保持 Tool Call ID
5
避免重复副作用
6
恢复后验证 Outcome

示例：

1
recovery_rubric:
2
  detection: 1
3
  retry_policy: 1
4
  idempotency: 2
5
  state_continuity: 1
6
  final_outcome: 1

重复不可逆副作用：

1
hard fail

10. 标注与校准#

10.1 自动预标注#

自动预标注可以利用：

1
Rule Grader
2
Environment Assertion
3
Failure Classifier
4
Existing User Feedback
5
Incident Label

输出：

1
suggested_label
2
confidence
3
evidence

预标注不能写成 Gold。

它的价值是：

提高标注效率；
排序高价值样本；
预填明显字段；
暴露冲突。

10.2 LLM Judge#

LLM Judge 适合：

1
轨迹合理性
2
回答完整性
3
工具使用质量
4
失败类型初判

不适合替代：

1
数据库状态
2
测试结果
3
副作用
4
精确金额

Judge 输入应是 Evidence Pack，而不是整条无裁剪 Trace。

1
{
2
  "task_contract": "...",
3
  "trajectory_summary": "...",
4
  "selected_tool_calls": "...",
5
  "outcome": "...",
6
  "rubric": "..."
7
}

输出必须结构化：

1
label
2
score
3
confidence
4
reason_codes
5
evidence_refs

10.3 双人标注#

核心 Gold 样本建议：

1
Annotator A
2
Annotator B

独立评分。

标注员不应看到：

另一人的结果；
Candidate 版本；
模型名称；
Judge 最终结论；
Dataset Split。

可以看到自动预标注，但为减少 Anchoring Bias，核心 Gold 更适合 Blind 标注或将预标注折叠。

10.4 冲突仲裁#

冲突类型：

1
Rubric 理解差异
2
证据缺失
3
边界案例
4
标注错误
5
Task Contract 歧义

仲裁输出：

1
final_label
2
adjudicator
3
reason
4
rubric_change_required
5
case_change_required

如果冲突来自 Task 本身不清晰，应修 Case，而不是强行选一方。

10.5 Gold Set#

Gold Set 应满足：

1
完整证据
2
双标或专家标注
3
冲突已仲裁
4
环境可复现
5
Rubric 版本冻结
6
隐私授权完整

Gold Set 用于：

Judge 校准；
Grader 回归；
Release Gate；
标注员培训；
质量审计。

不要把所有 Dataset Item 都叫 Gold。

10.6 标注一致性#

Boolean / Categorical#

1
Cohen's Kappa
2
Fleiss' Kappa
3
Precision / Recall / F1

Numeric / Ordinal#

1
Spearman
2
Weighted Kappa
3
ICC
4
MAE

一致性要按维度报告。

例如：

1
task_success kappa = 0.94
2
trajectory_quality kappa = 0.61

第二个指标说明 Rubric 需要细化。

10.7 Judge 与人工 Gold 校准#

校准矩阵：

1
Judge
2
vs
3
Human Gold

报告：

1
Accuracy
2
Precision
3
Recall
4
F1
5
Confusion Matrix
6
Calibration by Confidence
7
Failure Type Breakdown
8
Language Breakdown

校准集不能来自 Test Holdout 全量#

应保留独立：

1
Judge Calibration Set

否则不断调 Judge 会污染 Test 判定。

Judge 漂移#

以下变化后重新校准：

1
Judge Model
2
Judge Prompt
3
Rubric
4
Evidence Pack
5
Production Domain

Anthropic 建议 LLM Judge 持续与领域专家校准，并在证据不足时允许输出 Unknown。¹

11. Dataset Split 与泄漏控制#

评测数据集的切分、血缘与持续更新闭环

11.1 按时间切分#

时间切分：

1
Train / Development：较早样本
2
Validation：之后样本
3
Test Holdout：最新时间窗

优点：

更接近未来泛化；
降低直接回流污染；
能评估环境漂移。

需要设置 Embargo Window：

1
Train End
2
→ Embargo
3
→ Test Start

避免同一事故或任务跨边界延迟出现。

动态 Benchmark 和训练截止时间分析表明，按时间引入新样本是降低静态 Benchmark 污染的重要方法。⁶⁸

11.2 按用户和任务模板切分#

Group Key：

1
user_id_hash
2
tenant_id
3
task_template_id
4
conversation_cluster

同一个用户的相似任务不应横跨多个 Split。

否则模型可能学到：

1
用户偏好
2
业务实体
3
固定表达

导致虚高。

11.3 按仓库、网站或业务实体切分#

Coding：

1
repository
2
package
3
file family
4
issue cluster

Browser：

1
website
2
application
3
workflow
4
account

客服：

1
product
2
order
3
policy family
4
customer

推荐使用层级 Group Split：

1
一级：repository
2
二级：task_template
3
三级：semantic_cluster

一个 Cluster 只能属于一个 Split。

11.4 近重复检测#

Split 之后再次做 Cross-split Dedup。

流程：

1
Exact Hash
2
→ MinHash / Shingle
3
→ Semantic Embedding
4
→ Trajectory Fingerprint
5
→ Entity Group
6
→ Human Review

训练数据去重研究发现，近重复会导致记忆和 Train-Test Overlap，使评测结果失真。⁹ 评测集也应对文本和轨迹同时去重。

不只检测输入#

还要检测：

1
Expected Output
2
Reference Patch
3
Tool Result
4
Environment Fixture

同一个 Gold Patch 变换用户措辞后，仍然是泄漏。

11.5 冻结 Test Holdout#

Test Holdout 应：

访问权限最小；
不进入日常 Prompt 调试；
不进入 Hard Case Mining；
不显示完整 Gold 给开发者；
不用于训练；
不频繁重跑；
只在发布或固定周期使用。

Holdout 分层#

1
Core Holdout
2
Safety Holdout
3
Fresh Temporal Holdout

核心 Holdout 保持长期可比。

Fresh Holdout 定期替换，检测污染和漂移。

11.6 防止生产回流污染测试集#

生产失败修复后，开发团队可能：

把 Trace 加入 Regression Test；
又把相同 Trace 加入训练或 Few-shot；
继续在同一 Test Item 上迭代。

这会把 Regression 测试变成已知答案记忆测试。

推荐数据用途标签：

1
EVAL_ONLY
2
TRAIN_ALLOWED
3
FEWSHOT_ALLOWED
4
JUDGE_CALIBRATION
5
HOLDOUT

硬规则：

1
HOLDOUT
2
→ 不得进入训练、Few-shot、Prompt 示例和人工调试上下文

如果某个 Holdout Case 被用于修复：

1
将它毕业到 Regression Known Set
2
并从未见 Test 中补充新 Case

静态 Benchmark 长期公开后容易发生过拟合和污染，这也是 LiveBench 与 SWE-bench-Live 强调持续更新的原因。⁶⁵

12. 数据版本与血缘#

血缘的核心问题是：

1
这条 Dataset Item 从哪条生产事实来？
2
经过了哪些转换？
3
谁修改了它？
4
哪个 Experiment 用了哪个版本？

W3C PROV 将血缘抽象为：

1
Entity
2
Activity
3
Agent

并通过：

1
wasDerivedFrom
2
wasGeneratedBy
3
wasAssociatedWith
4
used

表达关系。¹⁰

映射到 Agent Dataset：

1
Entity：
2
Trace、Artifact、Case、Dataset Version、Score
3

4
Activity：
5
Redaction、Reconstruction、Annotation、Dedup、Split、Experiment
6

7
Agent：
8
Pipeline、Annotator、Reviewer、Evaluator、Service

12.1 Source Trace ID#

每个 Case 必须保留：

1
source_trace_id
2
source_observation_id
3
source_event_ids
4
source_artifact_ids

Langfuse Dataset Item 原生提供 sourceTraceId 和 sourceObservationId，用于将 Dataset Item 链接回生产 Trace 或 Observation。²

多源 Case#

一个 Case 可能来自多个 Trace：

1
同一事故的 12 条 Trace

应保留：

1
primary_source_trace_id
2
supporting_source_trace_ids
3
cluster_id

12.2 Agent 与模型版本#

记录：

1
source_agent_version
2
source_model
3
source_prompt_version
4
case_reference_agent_version

source_* 描述生产事实。

case_reference_* 描述重建和验证 Case 时使用的版本。

不要混成一个 version。

12.3 Environment Revision#

记录：

1
source_environment_revision
2
fixture_revision
3
container_digest
4
database_snapshot
5
repository_commit
6
clock

每次 Fixture 更新产生新的 Case Version。

12.4 Tool Revision#

记录：

1
tool_name
2
schema_version
3
description_hash
4
implementation_version
5
fixture_version

如果 Case 为旧 Tool 提供 Compatibility Adapter，也必须版本化。

12.5 Rubric 与 Evaluator Version#

记录：

1
rubric_version
2
rule_grader_version
3
judge_name
4
judge_model
5
judge_prompt_version
6
outcome_verifier_version

分数只有绑定 Evaluator Version 才能解释。

Langfuse 当前支持版本化 Evaluator，并将 Dataset / Experiment / Score 作为关联对象；其 Dataset Version 还能按时间点重放历史状态。¹¹¹²

12.6 Dataset Manifest#

示例：

1
dataset:
2
  id: agent-regression-core
3
  version: 2026-08-06T00:00:00Z
4
  schema_version: 2.1.0
5
  owner: agent-quality-team
6

7
  purpose:
8
    - regression
9
    - release_gate
10

11
  source_window:
12
    start: 2026-05-01
13
    end: 2026-07-31
14

15
  splits:
16
    train: null
17
    development: dev-v7
18
    validation: val-v5
19
    test: test-holdout-v4
20

21
  grouping:
22
    - tenant
23
    - task_template
24
    - repository
25
    - semantic_cluster
26

27
  taxonomy_version: failure-taxonomy-v3
28
  rubric_version: agent-rubric-v5
29
  environment_manifest_version: env-2026-08
30

31
  statistics:
32
    item_count: 2480
33
    task_count: 2310
34
    failure_type_coverage: 0.94
35
    high_risk_item_count: 182
36
    source_trace_count: 4102
37

38
  privacy:
39
    redaction_version: pii-redaction-v6
40
    evaluation_use_reviewed: true
41
    retention_days: 365

12.7 样本修改历史#

每次修改记录：

1
before
2
after
3
reason
4
actor
5
timestamp
6
reviewer

常见修改：

1
修正 Expected Output
2
更新 Fixture
3
细化 Rubric
4
增加禁止动作
5
归档失效 Case
6
修复泄漏

不要原地覆盖后让历史 Experiment 失去解释。

Langfuse Dataset Item Versioning 会为添加、修改和删除自动产生版本，并保留 Item-level Diff；Experiment 可以固定运行某个时间点的数据集版本。¹¹

13. 线上漂移与持续更新#

13.1 新失败模式发现#

持续扫描：

1
新 Error Type
2
新 Tool Combination
3
新 Root Cause Cluster
4
新安全策略触发
5
新 Judge Disagreement
6
新用户投诉主题

检测方法：

Taxonomy Unknown Rate；
Embedding Cluster Outlier；
Tool Graph Novelty；
Error Code Novelty；
Human Review；
Incident Review。

UNKNOWN 不应被强行塞入旧类别。

它是 Taxonomy 更新的重要信号。

13.2 Shadow Evaluation#

Shadow 将生产请求复制到 Candidate 环境：

1
Production Agent → 用户
2
Candidate Agent → 隔离环境

可以发现：

1
新版本轨迹变化
2
Tool 选择变化
3
成本变化
4
安全风险

Shadow Trace 是候选样本来源，但要确认：

无真实副作用；
环境足够接近生产；
用户数据使用有授权；
Candidate 不影响主请求。

13.3 Canary Trace#

Canary 是新版本处理少量真实流量。

优先采集：

1
Baseline / Candidate Pair
2
相同任务模板
3
环境版本
4
用户反馈
5
Outcome

Canary 中的回归优先进入：

1
Regression Candidate Queue

不要等到完整事故才构造 Case。

13.4 评测集覆盖率监控#

覆盖率 Dashboard：

1
生产任务分布 vs Dataset 分布
2
工具组合
3
失败类型
4
安全风险
5
语言
6
租户类型
7
环境版本
8
成本分位

可以计算离散分布差异：

1
Jensen-Shannon Divergence
2
Population Stability Index

嵌入分布可以使用：

1
Cluster Coverage
2
Nearest Dataset Distance

Coverage Alert#

1
生产中新 Cluster 占比 > threshold
2
某 Tool 新版本无 Case
3
某 Failure Type 30 天无覆盖
4
某环境 Revision 无通过样本

13.5 旧样本失效和退役#

退役条件：

1
功能已删除
2
业务政策变化
3
工具下线
4
环境无法重建
5
Ground Truth 过期
6
数据授权撤回
7
被 Holdout 污染

状态：

1
ACTIVE
2
DEPRECATED
3
QUARANTINED
4
ARCHIVED
5
DELETED

不要因为 Agent 已经稳定通过就退役。

Regression Case 的价值正是防止未来退化。

Langfuse 的 Dataset Item 支持归档状态，并保留版本历史；其 Golden Dataset 指南也建议因产品行为失效时归档，而不是因为长期通过而删除。¹³

13.6 冻结核心集与滚动增量集#

推荐双层结构。

Frozen Core Set#

特点：

1
长期稳定
2
高质量 Gold
3
覆盖核心业务和安全
4
严格版本
5
低修改频率

用途：

1
版本长期比较
2
Release Gate
3
关键回归

Rolling Delta Set#

特点：

1
最近生产 Trace
2
新 Failure
3
新 Tool
4
新环境
5
定期更新

用途：

1
漂移检测
2
新鲜能力
3
长尾发现

Fresh Holdout#

还应保留：

1
未用于调试和修复的最新时间窗

用于验证真实未见泛化。

一个成熟评测体系的组合是：

1
Frozen Core
2
+ Rolling Delta
3
+ Safety Holdout
4
+ Fresh Temporal Holdout

一套可落地的 Trace-to-Dataset 流水线#

下面给出完整状态机。

1
1. Discover
2
   从 Trace、反馈、事故和接管记录发现候选
3

4
2. Quarantine
5
   隔离原始数据，完成授权、隐私和 Secret 扫描
6

7
3. Validate
8
   检查链路、版本、Tool Pair 和 Outcome
9

10
4. Classify
11
   标注任务类型、Failure Taxonomy、风险与粒度
12

13
5. Deduplicate
14
   文本、轨迹、模板和业务实体去重
15

16
6. Reconstruct
17
   重建用户目标、初始环境、工具和 Fixture
18

19
7. Verify
20
   Reference Solution 通过，Grader 能区分正负样本
21

22
8. Annotate
23
   自动预标、LLM Judge、双人标注和仲裁
24

25
9. Split
26
   时间、用户、实体、模板和近重复隔离
27

28
10. Version
29
    写入 Dataset Manifest、血缘和修改历史
30

31
11. Experiment
32
    在固定 Dataset Version 上多 Trial 运行
33

34
12. Monitor
35
    监控生产漂移、覆盖率和样本失效

候选记录 Schema#

1
{
2
  "candidate_id": "cand_00042",
3
  "source": {
4
    "trace_ids": [
5
      "trace_prod_123"
6
    ],
7
    "observation_ids": [
8
      "obs_agent_root"
9
    ],
10
    "feedback_ids": [
11
      "feedback_456"
12
    ]
13
  },
14
  "discovery": {
15
    "signals": [
16
      "USER_NEGATIVE",
17
      "RECOVERY_ATTEMPT"
18
    ],
19
    "priority": 0.87
20
  },
21
  "admission": {
22
    "trace_complete": true,
23
    "versions_complete": true,
24
    "tool_pairs_complete": true,
25
    "outcome_verifiable": true,
26
    "reconstructable": true,
27
    "authorized": true
28
  },
29
  "classification": {
30
    "granularity": "TASK",
31
    "primary_failure": "RECOVERY_ERROR",
32
    "risk": "HIGH"
33
  },
34
  "dedup": {
35
    "semantic_cluster": "cluster_091",
36
    "trajectory_cluster": "traj_017",
37
    "representative": true
38
  },
39
  "status": "ELIGIBLE"
40
}

最小实施检查表#

Trace 入选#

Case 重建#

初始环境可恢复
Reference Solution 可通过
Agent-visible 与 Grader-only 隔离
外部服务有 Fixture
禁止行为明确
时间、Token、费用和调用预算明确
多种合法轨迹不会被误拒

数据质量#

Split 与版本#

结语#

从生产 Trace 构造 Agent 评测数据集，真正困难的部分不是“把日志导出来”，而是把历史运行事实转换成评测合同。

一条合格的 Evaluation Case 必须回答：

1
用户当时要什么
2
Agent 当时能看到什么
3
环境最初是什么
4
可以使用哪些工具
5
哪些动作允许或禁止
6
怎样验证任务真正完成
7
故障后应该如何恢复
8
这条样本来自哪里
9
它与哪些样本重复
10
它属于哪个 Split 和版本

本文可以归纳为八条核心原则。

生产 Trace 是候选原料，不是 Benchmark。
端到端样本必须有可验证 Environment Outcome。
入选门槛先于智能采样。
不完整、未授权、不可复现的 Trace 再“困难”也不能进入 Gold。
样本粒度由评测目标决定。
Session、Task、Step 和 Tool Call 不能混成一个分数。
失败要按根因和传播链分类。
不要把所有失败归到模型。
去重必须覆盖文本、轨迹、模板和实体。
但不能以牺牲长尾、安全和少数分布为代价。
Test Holdout 必须与生产回流隔离。
已用于修复、训练或 Prompt 调试的 Case 不再是未见测试。
数据集必须具有版本和血缘。
每一个 Score 都应能追溯到 Dataset Version、Case Version、Rubric、Environment 和 Source Trace。

最终的数据闭环不是：

1
Trace → CSV → Benchmark

而是：

1
Trace
2
→ 证据筛选
3
→ 任务重建
4
→ 环境冻结
5
→ Ground Truth
6
→ 标注校准
7
→ 去重切分
8
→ 版本血缘
9
→ 持续更新

只有经过这条链路，生产数据才会从“故障记录”变成能够支持 Agent 回归、发布门禁和长期质量提升的评测资产。

参考资料#

Anthropic Engineering. Demystifying evals for AI agents. 2026. ↩ ↩² ↩³
Langfuse Documentation. Experiments Data Model. 2026. ↩ ↩²
Abbas, A. et al. SemDeDup: Data-efficient learning at web-scale through semantic deduplication. arXiv:2303.09540, 2023. ↩
Slyman, E. et al. FairDeDup: Detecting and Mitigating Vision-Language Fairness Disparities in Semantic Dataset Deduplication. CVPR 2024. ↩ ↩²
Zhang, L. et al. SWE-bench Goes Live!. NeurIPS 2025, arXiv:2505.23419. ↩ ↩²
White, C. et al. LiveBench: A Challenging, Contamination-Free LLM Benchmark. ICLR 2025, arXiv:2406.19314. ↩ ↩² ↩³
European Union. General Data Protection Regulation, Article 5: Principles Relating to Processing of Personal Data. Regulation (EU) 2016/679. ↩
Roberts, M. et al. Data Contamination Through the Lens of Time. arXiv:2310.10628, 2023. ↩
Lee, K. et al. Deduplicating Training Data Makes Language Models Better. ACL 2022, arXiv:2107.06499. ↩
W3C Recommendation. PROV-O: The PROV Ontology. 2013. ↩
Langfuse. Dataset Item Versioning；Run Experiments on Versioned Datasets. 2025–2026. ↩ ↩²
Langfuse. Manage LLM-as-a-Judge Evaluators via the API. 2026. ↩
Langfuse Engineering Resources. Golden Dataset Evaluation: Build and Maintain LLM Test Sets. 2026. ↩

第 8 篇：从生产 Trace 构造 Agent 评测数据集

https://jupiter-ws.cn/posts/agent-observability/08-production-trace-evaluation-dataset/

作者

Jupiter

发布于

2026-08-06

许可协议

CC BY-NC-SA 4.0

文章目标#

1. 生产 Trace 为什么不能直接作为评测集#

1.1 大量重复和低信息任务#

低信息不等于简单#

代表样本而不是随机保留#

1.2 成功样本远多于失败样本#

生产分布集与挑战集分开#

Production Representative Set#

Risk / Challenge Set#

成功样本仍然必要#

1.3 Trace 缺失或链路不完整#

完整性需要按必需边定义#

Task 级 Trace#

Tool Call 级样本#

Recovery 样本#

完整性不是字段数量#

1.4 缺少可验证 Outcome#

Final Response 不能替代 Outcome#

Outcome 的来源#

无 Outcome 的 Trace 如何处理#

1.5 生产环境不断变化#

Trace 记录的是历史事实，不是可复现环境#

环境漂移的两类影响#

Case 无法复现#

Ground Truth 失效#

1.6 隐私、授权和敏感内容#

需要独立的数据使用授权#

目的限制与最小化#

分层内容策略#

原始层#

脱敏候选层#

Evaluation Case 层#

不可逆匿名化并不总能实现#

2. 数据来源#

2.1 生产 Trace#

推荐 Candidate Query#

2.2 用户反馈#

用户反馈不是最终标签#

2.3 人工接管记录#

2.4 线上事故#

从事故构造样本#

2.5 客服和 Bug 报告#

关联方法#

2.6 专家构造样本#

2.7 合成边界与故障样本#

合成不是让 LLM 自由生成#

合成样本的角色#

3. Trace 入选门槛#

3.1 执行链完整#

Task-level#

Trajectory-level#

Tool-level#

内容被截断时#

3.2 模型、工具和环境版本明确#

版本不明确的风险#

3.3 Tool Input 与 Tool Result 完整#

写工具还需要#

Result 完整不等于 Result 被使用#

3.4 环境 Outcome 可验证#

Outcome 验证等级#

3.5 可以复现或重建#

复现状态#

3.6 不包含无法授权使用的数据#

自动扫描#

数据删除传播#

4. 样本粒度#

4.1 Session 级#

4.2 Task 级#

4.3 Turn 级#

4.4 Step 级#

4.5 Tool Call 级#

4.6 如何根据评测目标选择粒度#

5. 样本发现与智能采样#

5.1 用户差评#

5.2 人工接管#

5.3 高成本和长链路任务#

与正常 Trace 配对#

5.4 网络恢复失败#

5.5 稀有工具组合#

5.6 新版本回归#