故障模式与排障手册

排障的本质是用系统化方法缩短定位路径，而不是靠经验“拍脑袋”。分层收敛、证据链、最小修复，是高效排障的核心。

排障的总原则：先分层，再收敛

GPU 平台的故障排查难点在于，同一现象可能源自不同系统层级。例如，Pod Pending 既可能由于配额不足，也可能因为设备插件未上报资源；推理延迟抖动既可能是同卡邻居干扰，也可能是 CPU 或网络瓶颈。

本章旨在提供一套可操作的排障顺序，将排障过程从“凭经验试错”转变为“分层收敛”，让你把时间花在最可能的根因上。

你可以将本章视为 GPU 平台的“诊断树”：先判定控制面与数据平面，再区分工作负载与运维配置，最后深入具体组件细节。

快速分诊：四个问题决定排障路径

遇到任何故障时，建议先用以下四个问题进行快速分诊，通常只需 2–5 分钟：

1. 现象类型是什么？

   • Pod Pending / 调度失败
   • Pod Running 但不使用 GPU / GPU 不可见
   • GPU 使用异常：OOM / 掉卡 / Xid 错误
   • 性能异常：吞吐下降 / P99 抖动
   • 资源“穿透”：声明与实际不一致（超用/偷用/配额不兑现）

2. 影响范围多大？

   • 单 Pod / 单节点 / 单队列 / 全集群
     范围越大，越倾向于数据平面或运维问题（驱动、runtime、device-plugin）。

3. 最近是否发生变更？

   • 驱动/CUDA/容器运行时升级
   • MIG 重配置
   • HAMi/Volcano/Kueue 版本变更或参数调整
   • 节点增删/标签变更
     大多数生产故障都与变更强相关，优先回滚或对比变更前后差异。

4. 是否可复现？

   • 可复现：走“定位—验证—修复”闭环
   • 不可复现：先补齐观测与采样，把现象固化成证据链

快速分诊决策树——通过现象类型、影响范围、变更历史和可复现性四个维度，在 2–5 分钟内快速锁定排障路径。

总体排障路径：四段式收敛流程

排障流程建议分为四步，帮助你高效定位问题：

确定是控制面还是数据平面

• 控制面问题：通常表现为“规则导致的不可用”，如 Pending 原因是配额、队列、优先级、准入、抢占等。
• 数据平面问题：表现为“资源本体不可用或不一致”，如节点上看不到 GPU、device-plugin 异常、容器无法访问设备。

判断依据：

• kubectl describe pod 的 Events 是否明确说明“资源不足/准入拒绝/队列等待”。
• kubectl describe node 是否仍然有 GPU capacity/allocatable（或对应的设备资源）。
• 相关组件是否健康：scheduler、device-plugin、runtime。

在选定层内，判定是“配置/运维”还是“工作负载行为”

• 配置/运维：版本不匹配、驱动/runtime 错误、MIG 重配、权限/安全策略、镜像环境不完整等。
• 工作负载行为：显存激增、KV cache 膨胀、batch 配置不当、训练通信/拓扑瓶颈等。

用最少命令拿到证据链

排障时应避免“到处翻日志”，优先获取以下三类证据：

• 资源视角：节点 GPU 是否存在、分配是否兑现（Pod 注解、GPU UUID 映射）。
• 调度视角：Pending 原因、准入/队列/抢占事件。
• 运行时视角：容器是否能看到 GPU，是否出现 OOM/Xid。

最小修复与回归验证

修复建议遵循“最小改动”原则：

• 先恢复可用性，再追求最优。
• 每次改动都要有回归用例（建议复用本书 Lab 的 YAML）。

四段式收敛流程——从确定控制面/数据平面，到判定配置/工作负载问题，再到获取证据链，最后最小修复与回归验证，形成闭环的排障方法论。

五大故障模式概览

GPU 平台五大常见故障模式——涵盖调度失败、GPU 不可见、显存 OOM、性能异常和 MIG 配置问题，以及对应的控制面与数据平面根因分类。

故障模式一：Pod Pending / 调度失败

本节介绍 Pod Pending 或调度失败的常见现象、根因及排查方法。

现象与高频根因

• 控制面根因

  • Kueue：未准入（配额不足、队列拥塞、ResourceFlavor 不匹配）
  • Volcano：队列/公平/抢占/Gang scheduling 条件不满足
  • 原生调度：节点选择、污点容忍、亲和性冲突

• 数据平面根因

  • device-plugin 未上报 GPU（节点上 Capacity 没有设备资源）
  • HAMi scheduler 未生效（schedulerName 未指向 HAMi）
  • 节点标签缺失（如 GPU 节点未被纳入管理）

最短诊断命令

以下命令可快速定位 Pending 原因、调度器及节点资源状态：

# 查看 Pending 原因（最重要）
kubectl -n <ns> describe pod <pod> | sed -n '/Events/,$p'

# 查看调度到哪个 scheduler（防止跑错调度器）
kubectl -n <ns> get pod <pod> -o=jsonpath='{.spec.schedulerName}{"\n"}'

# 查看节点资源是否存在
kubectl describe node <node> | egrep -n "Capacity:|Allocatable:|nvidia|gpu" -n

典型修复动作

• schedulerName 错误：修正为 hami-scheduler 或 volcano 对应名称。
• 节点未上报 GPU：重启 device-plugin，确认 runtime/driver 链路。
• 准入失败：调整配额/队列策略，或解释为“策略拒绝（符合预期）”。
• 资源请求写错：如 gpumem 与 gpumem-percentage 混用（互斥），或单位不正确。

故障模式二：Pod Running 但 GPU 不可见 / CUDA 初始化失败

本节聚焦于容器运行但无法使用 GPU 的排查思路。

现象信号

• 容器内 nvidia-smi 不存在或报错。
• CUDA 报错 CUDA driver version is insufficient 或 no CUDA-capable device is detected。
• 框架侧报“torch.cuda.is_available() = False”。

最短诊断命令

以下命令可帮助你快速定位 GPU 链路问题：

# 宿主机 GPU 是否正常
ssh <node> nvidia-smi

# 容器内能否看到 GPU
kubectl -n <ns> exec -it <pod> -- nvidia-smi

# 节点 runtime 侧最小验证（如有节点操作权限）
docker run --rm --gpus all nvidia/cuda:12.4.1-base-ubuntu22.04 nvidia-smi

高概率根因

• 节点未正确安装/配置 nvidia-container-toolkit（runtime 没有 GPU hook）。
• 镜像缺少用户态库（只装了框架但没有匹配的 CUDA runtime）。
• 驱动与容器内 CUDA 版本组合不兼容（尤其在升级驱动后）。

修复策略

• 更换已知可用的 CUDA base 镜像验证链路。
• 修复 runtime 配置（containerd/docker）并重启运行时。
• 回滚驱动或统一驱动版本（生产环境建议做驱动“金镜像”）。

故障模式三：显存 OOM / “看起来还有显存但还是 OOM”

本节分析显存 OOM 的常见场景及排查方法。

现象信号

• vLLM / PyTorch 报 CUDA out of memory。
• nvidia-smi 显示显存剩余但仍 OOM（碎片化或临时峰值）。

核心判断：OOM 属于“工作负载行为”还是“配额/隔离问题”

• 工作负载行为：batch、并发、KV cache、activation checkpoint 等导致峰值超出预期。
• 配额/隔离问题：共享场景下邻居抢占显存、配额未兑现、显存策略不生效。

最短诊断命令

以下命令有助于定位 OOM 发生时的显存使用情况及同卡进程：

# 查看 OOM 发生时间与 GPU 显存曲线（如有 DCGM/Prometheus 更佳）
nvidia-smi --query-gpu=timestamp,memory.used,memory.total --format=csv -l 1

# 查看同卡有哪些进程（定位邻居）
nvidia-smi pmon -c 1

修复策略

• 降低并发、最大 tokens、batch（立即止血）。
• 通过调度与隔离减少同卡干扰（强隔离/MIG 或治理共享）。
• 将“显存峰值”纳入验收指标：不仅关注平均占用，还要关注峰值与抖动。

故障模式四：性能异常（吞吐下降 / P99 抖动）

本节介绍性能异常的排查思路，帮助你快速定位瓶颈。

先排除“假性能问题”

许多“GPU 性能问题”实际根因在 CPU、网络或存储：

• CPU 饱和导致 GPU 喂不饱。
• 网络/存储瓶颈导致数据加载卡住。
• NUMA/PCIe 拓扑导致跨 socket 访问变慢。

最短诊断命令

以下命令可在 3 分钟内完成初步性能排查：

# GPU 利用率与功耗是否明显下降
nvidia-smi dmon -s pucm -c 5

# 是否出现大量 CPU wait / IO wait
top -H  # 或 iostat/vmstat（视工具链而定）

# 查看同卡邻居（共享场景必查）
nvidia-smi pmon -c 1

用“干扰系数”收敛问题域

将当前性能与“独占基线”对比：

• 吞吐下降但 P99 稳定：更可能是资源配额/cores 限制或 CPU 瓶颈。
• P99 明显变差：优先怀疑共享干扰、显存抖动、调度共址策略。

没有对照组或基线，性能排障会变得极为困难。

故障模式五：MIG 相关问题（重配置、实例不可用、资源不一致）

本节聚焦于 MIG（Multi-Instance GPU）相关的常见故障与排查顺序。

典型现象

• 节点上 MIG 实例与 Kubernetes 资源视图不一致。
• 重配置后 Pod 仍调度到旧的实例视图。
• MIG 实例无法创建或创建后不可用。

排障顺序

• 节点侧确认 MIG 状态与实例列表。
• device-plugin 是否识别新实例。
• 集群侧资源是否刷新（必要时重启相关插件）。
• 避免在高峰期做 MIG 重配（重配本身属于运维事件，需纳入变更管理）。

HAMi 特有排障：配额兑现与“治理共享”的证据链

当你使用 HAMi 进行细粒度共享时，排障的关键不只是“能否运行”，而是以下三点：

1. Pod 是否走了正确的 scheduler。
2. 分配结果是否写入可对账信息（如 Pod 注解）。
3. 超配是否被稳定阻断且可解释。

建议将 Lab 3 中用于验证的命令，作为本章的“HAMi SOP”长期固化：

• 查看 schedulerName
• 查看分配注解
• 提交超配 Pod 验证阻断

这样无论对外演示还是内部评审，都更具说服力。

最小化的“排障工具箱”

建议你长期维护一个最小化的排障工具箱，做到随时可用：

• 集群视角：kubectl get/describe/events/logs
• 节点视角：nvidia-smi（含 pmon/dmon）、dmesg（查看 Xid）
• 观测视角（进阶）：DCGM Exporter + Prometheus + Grafana
• 回归用例：本书的 Lab YAML（独占/共享/超配/负载压测）

排障的最终交付：把一次事故沉淀成资产

每次排障结束，建议沉淀以下三类资产，这将直接提升你在平台治理中的影响力：

1. 触发条件与证据链：事件、日志、指标、YAML。
2. 根因分类：控制面、数据平面、工作负载、运维配置。
3. 防复发措施：告警阈值、准入策略、验收项、回归用例。

这样可以让平台治理从“靠专家”转向“靠系统”。

总结

排障的核心不是更懂某个组件，而是能在多层系统中快速收敛。先分层（控制面 vs 数据平面），再分因（工作负载 vs 运维配置），用最少命令拿证据链，做最小修复并回归验证。只要你将这套流程固化为 SOP，GPU 平台的可用性将实现阶跃式提升。