vLLM 生产 OOM 排障 Runbook

收录时间: 2026-08-11
主题: vLLM Out-of-Memory 生产排障 SOP
标签: #vLLM #OOM #K8s #GPU-Memory #Production-Debugging #NCCL
实例: Jay
可信度: 高（生产经验，有具体错误信息和 kubectl 命令）
是否需精读: 是
来源: Kubenatives (Sharon Sahadevan)
原文: https://www.kubenatives.com/p/production-runbook-vllm-oom-debugging

一、识别错误类型

1.1 GPU OOM — `torch.cuda.OutOfMemoryError`

torch.cuda.OutOfMemoryError: CUDA out of memory. 
Tried to allocate XYZ GiB on GPU 0

含义: 模型权重 + KV Cache 占用超过单卡 VRAM 上限。

1.2 NCCL OOM — `RuntimeError: NCCL error`

RuntimeError: NCCL error: out of memory

含义: 多卡并行训练/推理时，NCCL 通信buffer在 GPU 内存中分配失败，与模型本身无关，属于通信层 OOM。

1.3 CPU OOM — Exit Code 137 (OOMKilled)

含义: Pod 被 Kubernetes 强制杀死（OOMKilled），说明 CPU 内存（而非 GPU）不足。

二、诊断命令

# 查看当前 Pod 资源配置
kubectl get pod <vllm-pod-name> -o jsonpath='{.spec.containers[0].resources}'

检查重点： - limits.memory — 是否设置过低 - limits.cpu — 如果设置了 CPU limits，这是导致 throttling 的直接原因 - requests.memory vs limits.memory 之间的比例

三、GPU 内存估算规则（vLLM Pod）

模型规模	建议 memory limit	说明
8B 模型	16–24 Gi	FP16 8B ≈ 16GB 权重
13B 模型	24–32 Gi
70B 模型	48–64 Gi	需多卡（通常 2×80GB）

注意: 上述为 CPU 内存 limits，非 GPU 显存。GPU 显存由 --gpu-memory-utilization 控制（默认 0.9）。

四、关键工程陷阱：CPU Limits 禁止设置

⚠️ 重要规则: vLLM Pod 禁止设置 CPU limits

原因： - vLLM 的 tokenization、请求处理、内部 buffer 都依赖 CPU - 设置 CPU limits 会导致 throttling，使 tokenization 变慢 - tokenization 变慢 → 请求在队列中停留更久 → GPU 利用率下降

正确配置示例（70B 模型，2 GPU）：

resources:
  requests:
    memory: 48Gi    # 略高于模型加载最低需求
    cpu: "8"
    nvidia.com/gpu: "2"
  limits:
    memory: 64Gi    # 留 30% headroom
    nvidia.com/gpu: "2"   # 不设置 cpu limits！！

错误配置（不要这样做）：

resources:
  requests:
    cpu: "8"
    memory: 48Gi
    nvidia.com/gpu: "2"
  limits:
    cpu: "8"       # ❌ 禁止设置 CPU limits
    memory: 64Gi
    nvidia.com/gpu: "2"

五、OOM 故障排查流程

1. kubectl describe pod <name> | grep -A 5 "OOMKilled"
   → 如果 OOMKilled=true → 跳到 CPU 内存检查

2. kubectl logs <name> | grep -i "out of memory"
   → torch.cuda.OutOfMemoryError → 降低 --gpu-memory-utilization 或换更大 GPU

3. kubectl logs <name> | grep -i "NCCL"
   → RuntimeError: NCCL error → 检查多卡通信、尝试单机多卡而非多机

4. 检查 CPU 内存 limits
   → 若设置了 cpu limits → 移除 limits 只保留 requests

六、进阶调参建议

参数	默认值	调低场景	调高场景
`--gpu-memory-utilization`	0.9	GPU OOM	GPU 利用率低，吞吐不达预期
`--max-num-batched-tokens`	—	显存不足	显存充足，想提高批处理吞吐
`--max-num-seqs`	—	并发 OOM	并发低，GPU 未饱和

七、相关错误码速查

Exit Code	含义	排查方向
137	OOMKilled (CPU)	增加 memory limits，检查是否有内存泄漏
143	SIGTERM 正常终止	通常非故障，检查 graceful shutdown
1	一般错误	查看 `kubectl logs` 最后 100 行

八、关联知识库条目

2026-08-11-llm-inference-vllm-sglang-benchmark.md — vLLM/SGLang 生产选型
2026-08-11T0935-jay-morning-briefing-inference-agents-rag-kvcache.md — KV Cache 内存管理

审稿状态: 待核实完整 runbook 内容（原文需付费订阅）
核心内容来源: snippet 提取的错误类型、kubectl 命令、YAML 示例、CPU limits 规则
补充建议: 如有完整访问权限，建议补充「OOM 后逐步降低 --gpu-memory-utilization 的实验数据」