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 的字段
这些东西补齐后，出事时团队会稳定很多。