排障手册¶

先保护用户与作业，再定位根因：必要时限流、回滚、隔离坏节点或暂停扩散，随后保全指标、事件、日志和 profile 证据。

通用流程¶

flowchart TD
    A[确认影响与时间线] --> B[检查最近变更]
    B --> C[从 SLI 分层下钻]
    C --> D{单实例 / 单节点?}
    D -- 是 --> E[隔离对比健康实例]
    D -- 否 --> F[检查共享依赖与负载]
    E --> G[提出可证伪假设]
    F --> G
    G --> H[一次改变一个变量]
    H --> I[验证恢复并记录]

先收集¶

• 时间范围、受影响模型/租户/作业、错误样本与 request/job ID。
• 代码、模型、配置、镜像、驱动或节点最近变更。
• 请求/step 分解、队列、GPU、网络、存储与 Kubernetes events。
• 健康对照组：同版本其他副本、同节点其他卡、同工作负载旧版本。

场景一：CUDA OOM¶

先区分：启动即 OOM、运行一段时间 OOM、特定长请求 OOM，还是并发上升 OOM。

检查：

1. 模型权重、激活/KV、临时 workspace 的理论预算。
2. framework allocated 与 reserved，是否存在碎片或缓存增长。
3. batch、sequence、并发、数据类型、CUDA Graph 或编译配置变更。
4. 是否有其他进程占卡，容器设备隔离是否正确。
5. 推理是否缺少最大 token/并发/admission limit。

缓解可以是降低 batch/并发/序列上限、回滚配置、清理异常进程；长期修复依根因选择 checkpointing、sharding、量化、KV 管理或内存泄漏修复。

场景二：NCCL hang / timeout¶

症状可能是 collective timeout，但根因也可能是某 rank 更早 OOM、数据加载卡住或代码控制流不一致。

检查顺序：

1. 找到第一个异常 rank 和第一条错误，不要只看最后的 watchdog timeout。
2. 验证所有 rank 是否执行相同 collective 序列、tensor shape/count 一致。
3. 检查进程存活、节点/NIC/GPU Xid、网络错误与路由。
4. 单机与跨机分别复现，用 nccl-tests 隔离模型代码。
5. 核对 NCCL、CUDA、驱动、容器库及环境变量，检查 GPU/NIC 拓扑。

不要把盲目调大 timeout 当修复；它只可能延迟故障暴露。

场景三：GPU utilization 低¶

按时间线分类：

• 大段空白：数据、CPU、调度、同步或存储等待。
• 大量小 kernel：launch overhead、算子碎片、shape 太小。
• kernel 持续但 SM/带宽低：kernel 实现、分支、访存或资源占用问题。
• collective 占主导：通信量、拓扑、straggler 或 overlap 不足。
• 推理请求少：正常容量空闲，不应为了指标人为制造工作。

场景四：TTFT P99 突增¶

检查：

• queue time 是否上升；请求到达率与长 prompt 比例是否变化。
• prefill batch/chunk 和调度优先级是否改变。
• 是否发生扩缩、模型冷加载、缓存未命中或滚动发布。
• 某副本/节点是否明显慢，路由是否不均。
• 网络入口、鉴权、网关和下游是否在 GPU 之前已耗时。

如果 TPOT 正常而 TTFT 变差，优先看排队与 prefill；如果二者都变差，检查过载、GPU 性能与共享依赖。

场景五：Pod Pending / 看得到节点但调度不了¶

kubectl describe pod <pod>
kubectl get nodes -o custom-columns=NAME:.metadata.name,GPU:.status.allocatable.nvidia\.com/gpu
kubectl get events --sort-by=.lastTimestamp

检查 GPU allocatable、requests/limits、node affinity、taint/toleration、配额、优先级，以及 gang 中是否必须一次满足多个 Pod。Device Plugin 未上报时再检查其 DaemonSet 与 kubelet 日志。

场景六：模型发布后错误或延迟上升¶

• 对比 revision、模型 tokenizer/config、量化、引擎参数与镜像 digest。
• 检查 readiness 是否真的覆盖模型加载和 warmup。
• canary 是否代表生产请求长度与租户结构。
• 新旧副本同时存在时路由、缓存与协议是否兼容。
• 先停止扩散或回滚，再保留坏版本样本做离线复现。

事故记录最小模板¶

# 事故：<标题>
- 影响：
- 开始 / 检测 / 缓解 / 恢复时间：
- 用户症状与 SLO：
- 最近变更：
- 关键证据：
- 根因（技术 + 系统性）：
- 临时缓解：
- 长期行动项（owner / deadline / 验证方式）：
- 哪个监控或流程本可更早发现：