Debugging & Incident Playbook
Debugging 与 Incident Playbook
LLM system 出问题时，最怕的不是 error 本身，而是团队不知道该先看哪里。因为 AI incident 往往不是单点故障，它可能同时牵涉 model、retrieval、prompt、tool、provider、queue，甚至只是某次配置变更把坏行为悄悄放大了。没有 playbook，排障会很像摸黑撞墙。
所以这页的重点不是“出事再看日志”，而是 AI engineer 该怎么把 debugging 和 incident response 做成一套能复用的生产流程。
先说结论：先分型，再排障
AI incident 最容易犯的错，是一上来就盯模型输出。
更有效的顺序通常是：
- 先判断是哪类事故
- 再缩小到哪一层
- 最后才做 prompt / model 级定位
如果不先分型，排障会被大量噪音拖住。
AI Incident 常见的 5 类类型
| 类型 | 常见表现 |
|---|---|
| provider / infra | 401、403、429、5xx、timeout |
| quality drift | 突然更会乱答、乱引、乱格式 |
| retrieval failure | 找不到 source、citation 空了 |
| tool failure | tool timeout、schema 不对、执行失败 |
| cost / latency spike | token 激增、fallback 过多、P95 爆掉 |
先把事故归到这类里面，后面定位速度会快很多。
第一轮 Triage 该看什么
更实用的 triage 顺序：
| 问题 | 你先看什么 |
|---|---|
| 有没有刚发过配置 / prompt / model 变更 | deploy / config timeline |
| 错误是不是集中在某 provider / region | provider dashboard / route log |
| 是全量都坏，还是某一类请求坏 | request segment / tenant / feature flag |
| 是 deterministic error，还是质量漂移 | logs + samples + metrics |
AI incident 最怕一上来只盯单个 bad sample。先看面，再看点。
一个更像生产系统的排障分层
| 层 | 你要排什么 |
|---|---|
| request layer | 哪类用户、哪个 feature、哪个 tenant 出问题 |
| routing layer | 走了哪个 provider / model / fallback |
| context layer | prompt、history、retrieval chunk 有没有异常 |
| execution layer | tool、queue、worker、timeout、retry 是否异常 |
| outcome layer | 质量、cost、latency、schema 是否失控 |
这样分层后，incident 讨论会比“模型是不是变笨了”更有效。
常见事故怎么快速处理
| 事故 | 更快的动作 |
|---|---|
| 401 / 403 | 先查 key、permission、env 是否变更 |
| 429 | 降并发、开 backoff、检查流量 spike |
| 5xx / timeout | 看 provider health，必要时切 fallback |
| schema fail | 先加 repair path 或切回旧 prompt |
| hallucination surge | 先收温度、收 scope、加强 source guard |
Incident response 里，“先把伤口止住”通常比“立刻找全根因”更重要。
Trace 和 Log，最少要记到什么程度
没有 trace ID 的 AI debugging，后面几乎都会很痛。
建议每个 request 至少关联：
- trace_id
- model / provider
- prompt or config version
- retry count
- retrieval source IDs
- tool call summary
- latency
- token usage
不是让你把敏感内容全记下来，而是让你能把一次坏请求在系统里串起来。
Quality Incident 和 Infra Incident 不一样
这是很多 team 会混淆的一点。
| Infra incident | Quality incident |
|---|---|
| 明显报错、超时、失败 | 看起来成功，但内容明显变差 |
| 更容易用系统指标发现 | 往往要靠 sample review 才发现 |
| 通常先看 provider / worker | 通常先看 prompt / retrieval / policy |
如果你把 quality incident 当成普通 5xx 事故来处理，往往会漏掉真正的问题。
Runbook 不该只是文档存档
一个能用的 runbook，至少要写清：
- 症状
- 快速诊断入口
- 临时止损动作
- 根因排查路径
- 回滚方法
- 责任人和升级路径
没有这些，runbook 很容易变成“事后复盘材料”，而不是现场工具。
Postmortem 最有价值的部分
AI incident 的 postmortem 不该只写“问题已修复”。
更该补的是：
- 哪个监控本来应该更早报警
- 哪个 bad case 应该进入 eval set
- 哪个 rollback 开关不够快
- 哪条 guardrail 本来可以提前挡住
真正好的 postmortem，是把 incident 转成未来的系统能力。
Practice
拿你现在一个线上 AI feature，先补这 4 样：
- 一页 incident 分类表
- 一页 triage 顺序
- 最常见 3 类故障的 runbook
- 一组必须进 trace 的字段
这些东西补齐后，出事时团队会稳定很多。
📚 相关资源
❓ 常见问题
关于本章主题最常被搜索的问题，点击展开答案
AI incident 排障的正确顺序是什么？
先分型，再排障，最后才看模型。3 步：(1) 判断是哪类事故（provider/infra、quality drift、retrieval failure、tool failure、cost/latency spike 5 类）；(2) 缩小到哪一层（request / routing / context / execution / outcome）；(3) 才做 prompt / model 级定位。一上来盯单条 bad sample 会被噪音拖死。
AI incident 第一轮 triage 应该看什么？
4 个问题，从面到点：最近有没有发过配置 / prompt / model 变更（看 deploy timeline）、错误是不是集中在某 provider / region（看 provider dashboard）、是全量都坏还是某一类请求坏（按 segment / tenant / feature flag 切）、是 deterministic error 还是质量漂移。先看面再看点，否则容易陷入个例。
Quality incident 和 infra incident 怎么区别处理？
完全两套打法。Infra incident：明显报错 / 超时 / 失败，靠系统指标发现，先看 provider 和 worker。Quality incident：看起来成功但内容明显变差，要靠 sample review 才发现，先看 prompt / retrieval / policy。把 quality incident 当 5xx 处理是常见误判 —— 你会盯 retry 但根本不在 retry 上。
AI 请求至少要 trace 哪些字段才好排障？
至少 8 项：trace_id、model / provider、prompt 或 config 版本、retry count、retrieval source IDs、tool call summary、latency、token usage。不是要你把敏感内容全记下来，是让你能把一次坏请求在系统里串起来 —— 没有 trace_id 的 AI 排障基本都很痛。
AI runbook 应该写什么才在现场真正能用？
6 件事缺一不可：症状描述、快速诊断入口、临时止损动作、根因排查路径、回滚方法、责任人和升级路径。常见 3 类故障必须各有 runbook：401/403 先查 key/permission，429 先降并发开 backoff，hallucination surge 先收温度收 scope 加 source guard。Runbook 不能只当事后存档。