调优归因与实验方法

一句话：调优的第一原则是先归因再动手：环境 → Harness → 模型，改模型永远是最贵的一步。没有固定条件的比较不算实验，没有回归门禁的优化只是把错误换了一种表现。

为什么需要

Agent 出问题时，团队的第一反应通常是"换个模型"或"改 Prompt"。但生产环境的失败大部分不来自模型能力，而来自执行环境抖动、Harness 配置缺项、上下文被截断。先归因，能把修复成本压到最低层。

另一个常见事故是"优化"缺乏方法：改了 Prompt，现场跑两个例子感觉变好了就上线。没有黄金集、没有配对检验、没有回归门禁，上线后旧问题复发、新问题混入，谁也说不清到底变好还是变坏。

核心机制

一、三层归因：环境 → Harness → 模型

层	典型失败	验证方法	修复成本
执行环境	工具超时 / 网络抖动 / 权限变更 / 依赖服务降级	查 Trace 的工具耗时分布、错误码、重试记录	最低：改配置、加重试
Harness	上下文截断丢关键事实 / 工具描述缺参数 / 压缩改变任务事实 / 终止条件误判	对比 Manifest 与预期上下文清单；回放同轨迹	中：改编排策略，要过回归
模型	能力不足 / 知识过时 / 推理偏差 / 指令遵循退化	固定 Harness 跑同一黄金集；人工评审分歧样本	最高：换模型或微调，影响面最大

看图抓两处：三道判定按成本从低到高串行，每一道"否"才允许进入下一道；模型层的判据只有"固定 Harness 跑黄金集仍失败"这一条，其余结论都不足以动模型。

归因纪律：一次 Badcase 必须归到"相邻事实"——具体是哪条上下文缺失、哪个工具返回异常、哪条规则未生效——而不是"模型不行"这种无法行动的结论。

二、Agent 轨迹数据：Trace / Session / Trajectory

三个对象不能混用：

• Trace：一次执行的完整因果链（从用户输入到最终输出），关联同一 trace_id
• Session：交互边界，同一会话可能含多个 Trace
• Trajectory：行为序列视角，关注"Agent 做了哪些决策"，可跨 Trace 聚合（长任务）

Trace 最小字段集：trace_id · step · span_type · prompt_hash · context_ref · token_breakdown（输入/输出/缓存命中分开） · tool_calls · duration · outcome。

轨迹诊断三类：

1. 工具调用链异常：同一工具连续失败仍重试、参数漂移、结果未消费
2. 上下文溢出：prompt_hash 变化点附近的 token 数突增，关键事实被挤出
3. 目标漂移：Trajectory 后期动作与初始目标语义距离变大——常见于长任务压缩后丢失验收标准

三、黄金数据集：验收标准不是训练素材

五阶段建设闭环：

图里只有一条虚线，其余四步都是单向：候选、标准、复核、使用、留档一旦建成就不再回看老题，失效样本靠这条回边重新进池。缺了回边，黄金集会停在建库那天，之后测的都是旧分布。

选题五类（缺一不可）：

类别	目的	占比建议
高频	覆盖主流量路径	40%
高风险	资金/发布/删除类动作	20%
边界	空输入/超长上下文/并发冲突	15%
回归	历史 Badcase 固化	15%
对抗	注入/绕过/误导样本	10%

硬约束：黄金集不参与任何训练或 Prompt 调优的数据回路；调优用的样本与验收用的黄金集物理隔离，否则指标虚高。

四、实验方法论

• 固定条件比较：同一黄金集、同一模型版本、同一 Harness 配置、同一随机种子（可复现时）；只改一个变量
• 配对显著性检验：同一题跑 A/B 两版，配对比较；样本 n 时 95% 置信半宽约 3/√n，n<100 的"提升 5%"通常不显著
• A/B 分桶按 Session 不按请求：同一用户的多轮请求进同一桶，避免上下文污染交叉
• 影子验证先行：新配置先在影子流量跑（不影响用户），对比在线指标再决定灰度

五、Badcase 48 小时闭环

五个方框是 48 小时内必须走完的动作顺序，实线箭头表示交接；虚线是沉淀回边，把案例送回告警与抽检的入口。看这张图只需盯一件事：归因是否落到相邻事实——落不下去，后面的修复与回归都会退化成试错。

修复优先级（从便宜到贵）：知识补 > Prompt 改 > 工具补 > 流程改 > 模型换。每例修复必须同时产出"共享字段 + 回归样本"，让修复对象从单份报告扩展到模块间一致性。

六、运行时数据 Pipeline

从 Trace 到训练/评测数据集的 ETL 链路，七类处理能力：

解析 · 校验 · 脱敏 · 切片 · 标注 · 聚合 · 分发

数据质量门禁四项：完整性（必填字段齐全）· 一致性（跨源口径对齐）· 时效性（窗口内更新）· 可溯源（每条样本能回链到原始 trace_id）。

实战场景

场景：三层归因实例——“客服答非所问”最终定位在 Harness 发布回退未生效

现象：客服 Agent 一周内“答非所问”失败率从 2.1% 升至 7.8%（生产采样口径）。团队第一反应是“新模型版本指令遵循退化”，准备回滚模型。

排除顺序与每层判据：

层	检查项	判据	结果
环境	Trace 工具耗时分布、错误码、重试记录	无超时聚集、错误码零增长、重试率正常	排除
Harness	失败样本 prompt_hash 对照预期清单；回放同轨迹	失败样本 system prompt 哈希全部指向旧版本，“多轮追问时不复述已答内容”规则缺失	定位
模型	固定 Harness 跑同一黄金集	恢复预期 prompt 版本后，同一模型每例 3 次取中位数全部答对	排除

根因：system prompt 走灰度发布，配置缓存失效失败，实例长期跑旧版本；发布监控只看“发布事件成功”，没校验“机器实际加载的 prompt_hash”。

修法：

• 发布验收指标从“发布成功”改为“集群 prompt_hash 达到目标版本的占比”，比例不符自动告警并阻止后续放量。
• 该失败 case 按“输入 + 期望约束 + 失败层=Harness”写入对抗集，只增不删。
• 归因文档记录“模型层为何被排除”：若当时直接回滚模型，配置缓存 bug 仍潜伏，下次发布照样复发。

一句话判据：模型层的判据是“固定 Harness 跑黄金集仍失败”，前提是 Harness 真的固定到了预期版本——观测字段不补齐，三层归因就只是流程口号。

场景：离线涨在线跌——评测集被 Prompt 迭代自身污染

现象：黄金集 QS 两周内从 0.78 涨到 0.83，但灰度在线的任务成功率不动，追问率反升。离线与在线第一次出现持续背离。

排查：调优期间是同一批人既改 Prompt 又修 Badcase。两个月里黄金集新增 20 余条，全部来自当前 Prompt 的失败案例，参考答案还顺手改成“当前能答对的形式”。指标涨幅是真的，但测的是“题目跟着 Prompt 走”，不是“Prompt 跟着用户走”。

修法（按黄金集五阶段闭环收口）：

• 候选 → 标准 → 复核 → 使用 → 留档各自设权限：参与调优的人不得担任双人复核，分歧样本交第三方仲裁。
• hold-out 纪律：留出题目永不进入任何调优回路，发布前只在留出集上做一次独立验证；调优样本与验收黄金集物理隔离。
• 评测集版本化：黄金集独立版本号并与模型 / Harness Release 绑定；实验前置断言“评测集版本一致”，跨版本对比只作趋势参考、不作放行依据。
• 新案例先进对抗集（只增不删），经一个复核周期毕业入黄金集，避免“调优即污染验收集”。

判据：离线提升可信，须同时满足——同版本评测集、hold-out 同步提升、影子或灰度在线指标同向。三者缺一，按噪声处理。

场景：黄金集 +0.8% 该不该发布——成对显著性的真实判读

现象：新 Prompt 版黄金集 QS 0.802，基线 0.794，每例 3 次取中位数后差值 +0.8%，且“连续两周正向”，团队申请发布。

判读：

• n=100、配对差值标准差 σ_d≈6 个百分点（QS 口径历史经验），95% 置信半宽 ≈1.96×6/√100 ≈1.2%。+0.8% 落在噪声区间内，配对检验 p 值远达不到 0.05——与正文“n<100 的提升 5% 通常不显著”及 3/√n 的宽松上界同向。
• 结论是“+0.8% 与 0 统计上不可区分”，不是“大概是正的”。
• 对照组：同样 σ_d 下 n=400 半宽 ≈0.6%，+0.8% 即显著。要稳定检出 1% 级改进，要么扩题量到数百，要么靠成对设计压低 σ_d——同一题跑 A/B 两版能消掉用例本身难度的公共方差。

门禁条件	阈值	本次	处置
绝对底线	QS ≥ 0.75	0.802	通过
相对显著性	配对检验 p < 0.05	不显著	不满足
护栏	P95 延迟 / 成本 / 安全拦截率不退化	均持平	通过

最终决策：不放行，样本扩到 n=400 后重跑。“噪声区间内不发布”的代价是多等一轮回归；收益是每个发布版本都能归因为真实提升，评测趋势线才有解读价值。放行一个不可区分的版本，等于给基线加噪，让下一次归因更难。

最小上手

attribution_order: [environment, harness, model]   # 改模型永远是最后一步
badcase: {sla_hours: 48, priority: [knowledge, prompt, tool, flow, model], output: [fix, regression_sample]}
golden_set:
  buckets: [high_freq:40, high_risk:20, boundary:15, regression:15, adversarial:10]
  isolation: 不参与任何调优数据回路
experiment: {single_variable: true, test: paired_significance, threshold: p<0.05, bucket_by: session, shadow_before_canary: true}
trace_fields: [trace_id, step, span_type, prompt_hash, context_ref, token_breakdown, outcome]

验收判据：能对一个线上失败说出具体的"相邻事实"；黄金集有版本和五类分布；任何"优化"都有配对检验数据。

生产动作

• 失败样本先查环境和 Harness，把"换模型"作为最后选项记录进归因文档
• 黄金集按版本管理，与模型/Harness Release 绑定，防止"题目漂移"
• 每次调优实验只改一个变量，改动前后跑同一回归集
• 48 小时闭环从告警触发计时，超时升级到人工评审
• 数据集分发前过脱敏与可溯源门禁

边界

• 没有独立验证集的调优不可信：调优数据和验收数据同源时，指标提升大概率是过拟合
• 单变量原则在小样本下更难：n<50 时任何多变量改动都无法归因，先扩样本
• 轨迹数据有隐私与成本约束：全量 Trace 存储成本随会话长度平方增长，分层采样（异常全采、正常聚合）是常态
• 归因本身可能出错：三层判据依赖观测质量，观测缺失时宁可先补观测再做调优决策

讲清楚

调优是归因驱动的闭环：先按环境→Harness→模型三层找"相邻事实"，改最便宜的那层；黄金集是验收标准不是训练素材，五类题配齐、与调优数据物理隔离；实验必须固定条件单变量，配对检验 p<0.05 才算提升；每例 Badcase 在 48 小时内走完"归因—修复—回归—入库"，修复同时产出回归样本。没有这套纪律，所有"优化"都只是换了一种错误。

适用：Agent 质量调优与评测体系建设 | 2026-10