失败样例分桶专题

版本：v1.2

最后更新：2026-07-08

适用对象：正在做 AI 评测、线上复盘、用户反馈治理和 Agent / RAG / 工具工作流改进，需要把“坏样例堆积”转成“问题排序、owner 指派、回归闭环”的平台、评测、产品和运营同学

很多团队做 AI 评测、线上复盘或用户反馈治理时，都会积累一堆失败样例。但真正的问题往往不是：

• 样例不够多

而是：

• 样例堆着没人看
• 看了也不知道先修哪类
• 同类问题一遍遍重复出现
• 不同团队对“这算哪类错误”口径不一致

OpenAI 当前 Evaluation best practices、Trace grading、Evaluate agent workflows，以及 LangSmith 当前 annotation queues、evaluation concepts、online evaluations 等官方资料，在 2026-07-08 复核时都强调了一个非常关键的事实：

• 失败样例的价值，不在于数量，而在于能否被结构化归因、被分派给正确 owner、并沉淀成下一轮回归资产。

这也是为什么需要做失败样例分桶。分桶的目标不是做一张更漂亮的报表，而是把失败样例转成：

• 可排序的问题清单
• 可分派的工程动作
• 可回归验证的评测资产

---

1. 什么是失败样例分桶

更实用的理解通常是：

• 把失败样例按可行动的维度分组

重点不是单纯贴标签，而是帮助团队回答：

• 这批问题本质上属于哪一类
• 应该由谁来修
• 修完后怎么回归

它在评测闭环里的位置更像：

collect bad runs
 -> review traces / outputs
 -> bucket failures
 -> assign owners
 -> fix prompts / tools / retrieval / workflows
 -> add to regression sets
 -> rerun evals

---

2. 为什么分桶比“收集失败样例”更关键

如果只有失败样例集合，没有分桶，团队通常会遇到：

• 优先级混乱
• owner 不明确
• 修复动作彼此打架
• 评测结论难以转成工程任务

而分桶之后，失败样例才能真正进入改进闭环。

一个常见现象是：

• 团队说“最近错误挺多”

但只要没有分桶，你通常回答不了：

• 哪类错误最多
• 哪类错误影响最大
• 哪类错误反复出现
• 哪类错误最值得先修

---

3. 为什么不能只按表面现象分桶

很多问题表面上都像：

• 回答不对
• 没解决问题
• 用户不满意

但根因可能完全不同：

• 没召回到文档
• 召回到了，但证据不够
• 工具顺序错了
• 参数填错了
• guardrail 误拦
• 审批链漏拦
• 知识版本过旧
• 输出结构解析失败

如果只按现象分桶，后续修复很容易南辕北辙。

举个简单例子：

• 现象：回答错了

可能根因是：

• query rewrite 把问题改坏了
• retrieval 没命中
• rerank 把正确证据排掉了
• 模型没有忠实使用上下文
• 输出引用错了

这五类问题修法完全不同。

---

4. 一个更实用的分桶视角：三层并行

更推荐同时做三层分类，而不是只做单标签。

4.1 业务场景桶

回答：

• 哪类任务出问题

例如：

• FAQ 问答
• RAG 检索问答
• 代码生成
• 工单审批
• 多智能体协作
• 高风险执行

4.2 根因桶

回答：

• 是哪一层出了问题

例如：

• query rewrite
• retrieval
• rerank
• context assembly
• prompt / instruction
• tool selection
• tool args
• workflow state
• output validation
• approval policy
• permission / safety

4.3 风险等级桶

回答：

• 这类失败影响有多大

例如：

• P0：越权、错误执行、敏感泄漏
• P1：高价值任务失败、关键业务错误
• P2：质量退化、体验下降
• P3：样式、措辞、低影响问题

这三层组合起来，才能同时支持：

• 看问题分布
• 看修复优先级
• 看谁来处理

---

5. symptom bucket 和 root-cause bucket 最好分开

很多团队一开始就把这两层混在一起，后面很快会失真。

例如一个样例：

• 现象：答错退款政策

根因可能是：

• knowledge_stale
• retrieval_noise
• context_ignored

所以更好的结构通常是：

层	示例
symptom bucket	wrong_answer
root-cause bucket	knowledge_stale
severity bucket	P1

这样做的好处是：

• 可以统计“答错”的总量
• 也可以统计“知识过期”占了多少

---

6. 分桶标签应该满足什么条件

好的分桶标签通常有四个特点。

6.1 稳定

同类问题不要今天一个名字、明天一个名字。

6.2 互相尽量可区分

不要让标签之间大量重叠，否则统计没有意义。

6.3 能映射到 owner

标签不能只是描述现象，还要能对应改动团队。

例如：

• retrieval_miss -> 检索 / 知识库团队
• tool_arg_invalid -> 工具 / 后端团队
• policy_guardrail_false_block -> 安全 / 策略团队

6.4 能映射到回归测试

一个桶一旦形成，就应该能不断吸纳样例，最终变成稳定回归集。

---

7. 一个可落地的最小分桶 schema

建议每条失败样例至少保存这些字段：

{
  "case_id": "fail-20260708-001",
  "task_type": "rag_answer",
  "symptom_bucket": "wrong_answer",
  "root_cause_bucket": "retrieval_miss",
  "severity_bucket": "P1",
  "owner_team": "search_platform",
  "user_impact": "high",
  "reproducible": true,
  "regression_required": true,
  "trace_id": "tr_abc123",
  "model": "example-model",
  "prompt_version": "rag-answer-v7",
  "notes": "query rewrite 漏掉了产品线条件"
}

如果没有这些最小字段，后面通常很难做到：

• 统计
• 分派
• 回归
• 复盘

---

8. 一套更实用的根因桶起步清单

下面这套清单很适合做第一版，既不算太粗，也不至于细到没人维护。

8.1 输入与理解类

• intent_misread
• query_rewrite_error
• missing_context_resolution

8.2 检索类

• retrieval_miss
• retrieval_noise
• rerank_error
• knowledge_stale
• permission_filter_error

8.3 生成与推理类

• context_ignored
• unsupported_claim
• reasoning_error
• citation_mismatch
• format_violation

8.4 工具与 workflow 类

• tool_selection_error
• tool_arg_error
• tool_result_misuse
• workflow_state_error
• handoff_error

8.5 安全与审批类

• guardrail_false_block
• guardrail_miss
• approval_missing
• permission_violation
• sensitive_leak

注意：

• 这套桶不是标准答案
• 它是适合大多数 Agent / RAG / tool-use 系统的工程起点

---

9. 分桶之后最关键的动作：不是统计，而是指派

失败样例分桶最怕变成“做完标签就结束”。

真正应该继续推进的是：

1. 定 owner
2. 定优先级
3. 定修复手段
4. 定回归样例

例如：

root cause	owner	常见动作
query_rewrite_error	检索 / LLM 应用团队	调整 rewrite prompt / query schema
retrieval_miss	搜索平台团队	调整索引、chunk、混合检索、召回策略
knowledge_stale	知识运营 / 数据团队	修同步链路、补版本治理
tool_arg_error	工具平台团队	收紧 schema、加参数校验
approval_missing	workflow / safety 团队	补审批节点和运行时拦截

---

10. annotation queues 和人工分桶为什么重要

LangSmith 当前 annotation queues 官方文档明确说明：

• single-run queues 可以逐条审阅 run
• pairwise queues 可以对比两条结果优劣
• 还可以配 assertions 和 rubric

这对失败分桶特别有价值，因为它让人工审查不是“聊天式看日志”，而是：

• 用统一标准看一批样例
• 给出结构化结论
• 把反馈沉淀进数据集

尤其在这些场景里，人工分桶仍然非常重要：

• 高风险样例
• 多根因交叠样例
• 输出主观质量问题
• 新出现、还没定义好桶的新问题

---

11. 失败样例怎么和 online evaluators 联动

LangSmith 当前 online evaluations 文档说明：

• 可以对生产 traces 持续打分

这件事对分桶的价值在于：

• 线上检测可以先把“疑似坏样例”筛出来
• annotation queues 再做人工确认和精细分桶

一个更稳的组合通常是：

online evaluator flags suspicious runs
 -> send to annotation queue
 -> human bucket symptom / root cause / severity
 -> assign owner
 -> add to regression set

这样团队不会把所有线上流量都拉来人工看，而是：

• 先用自动评分缩小范围
• 再用人工提高归因质量

---

12. 失败分桶怎么和 eval 数据集联动

OpenAI 的评测最佳实践和 LangSmith 的 evaluation concepts 都在强调一件事：

• 失败样例应该进入未来评测

所以一个成熟闭环通常是：

线上失败样例
 -> 人工审查 / annotation queue
 -> symptom / root-cause / severity 分桶
 -> 进入 dataset
 -> 绑定 evaluator / grader
 -> 下次变更自动回归

如果分桶后的样例没有回流到数据集里，团队就会反复修同一类问题，却永远难以证明它是否真的被修好了。

---

13. 一个更实用的优先级视角

分桶之后，不建议只按“出现次数最多”排序。

更稳妥的优先级通常由三件事共同决定：

• 发生频率
• 业务影响
• 风险等级

可以粗略理解成：

priority = frequency * impact * risk

举例：

• 高频低风险格式错误
• 低频高风险越权调用

很多时候应该优先修第二种。

---

14. 怎样避免 taxonomy 越做越乱

很多团队做分桶，半年后会遇到一个问题：

• 桶越建越多，最后没人知道该怎么选

更稳的治理做法通常包括：

14.1 先小后大

先用少量高区分度桶，不要一开始追求几百个标签。

14.2 定期合并重复桶

如果两个桶总是一起出现、owner 也一样，通常应该考虑合并。

14.3 给每个桶写定义和边界

例如：

• 什么叫 retrieval_miss
• 什么不算 retrieval_miss

14.4 桶变更也做版本化

否则前后统计口径会失真。

---

15. 失败分桶最常见的反模式

15.1 所有失败样例放在一个列表里

这会让团队只有“失败很多”的感觉，没有行动方向。

15.2 标签很多，但没有可执行含义

例如：

• 感觉不太好
• 回答怪怪的

这类标签很难映射到工程动作。

15.3 一开始就按十几个维度过度精细分类

维护成本会很快压垮团队。

15.4 分桶后不绑定 owner 和回归

这会让分桶只剩统计价值，没有治理价值。

15.5 只在线下评测分桶，不纳入线上问题

真正的问题分布往往在真实流量中更明显。

---

16. 一个更稳的落地顺序

建议按下面顺序做第一版失败分桶：

1. 先定义 symptom、root cause、severity 三层最小分类。
2. 先选 30 到 50 条真实失败样例做人工试标。
3. 统一口径，删掉含糊和重叠标签。
4. 为每个根因桶绑定 owner。
5. 把高风险桶和高频桶先拉入回归集。
6. 再接 annotation queue、online evaluators 和自动报表。

这个顺序通常比“一上来建一套完美 taxonomy”更稳。

---

17. 推荐搭配阅读

• 模型输出漂移检测专题
• 评测基准与基线管理专题
• 评测样例治理专题
• 业务指标回放专题
• AI项目复盘案例专题
• 企业知识纠错闭环专题

---

18. 重点官方资源

以下入口已按 2026-07-08 的官方资料重新整理：

• OpenAI Evaluation best practices：https://developers.openai.com/api/docs/guides/evaluation-best-practices
• OpenAI Working with evals：https://developers.openai.com/api/docs/guides/evals
• OpenAI Trace grading：https://developers.openai.com/api/docs/guides/trace-grading
• OpenAI Evaluate agent workflows：https://developers.openai.com/api/docs/guides/agent-evals
• LangSmith Annotation queues：https://docs.langchain.com/langsmith/annotation-queues
• LangSmith Evaluation concepts：https://docs.langchain.com/langsmith/evaluation-concepts
• LangSmith Set up LLM-as-a-judge online evaluators：https://docs.langchain.com/langsmith/online-evaluations-llm-as-judge
• W&B Weave monitor using built-in signals：https://docs.wandb.ai/weave/guides/evaluation/monitors

---

19. 落地检查清单

• 是否已经把 symptom、root cause、severity 三层拆开，而不是只做一个笼统标签
• 是否为高频和高风险样例建立了稳定桶，而不是每次临时起新名字
• 是否保证每个根因桶都能映射到明确 owner 和修复动作
• 是否把线上可疑 traces 通过 online evaluators 或人工队列持续送入分桶流程
• 是否把分桶后的高价值样例回流到回归数据集和 evaluator
• 是否定期治理重叠、模糊和无人维护的桶