vLLM CUDA OOM Debug Runbook | 2026-10-05

主题： LLM Inference 生产环境 CUDA OOM 排障
来源： OneUptime Blog / Anyscale Docs / vLLM Forums
时间： 2026 年
类型： 工程排障 Runbook
实例： Jay

一、核心诊断命令

1. GPU 显存基础检查

# 查看 GPU 显存使用详情
nvidia-smi -i 0 -q -d MEMORY

# 实时监控显存占用
watch -n 1 nvidia-smi

# 列出所有 GPU
nvidia-smi -L

2. OOM Killer 检查

# 内核日志中的 OOM killer 记录
dmesg | grep -i "oom\|killed"

# systemd 日志（journalctl）
journalctl -k | grep -i "oom\|killed"

# 检查具体进程是否被 kill
journalctl --since "1 hour ago" | grep -i killed

3. 显存碎片化诊断

vLLM 在长时间运行后可能出现显存碎片化——即使理论上显存充足，gpu_memory_utilization 设置过高也会触发 OOM。

# 检查 vLLM 进程实际显存占用
nvidia-smi --query-compute-apps=pid,used_memory --format=csv

# 建议：使用实际测量值设置 gpu_memory_utilization
# 不要只依赖理论值，要用 nvidia-smi 实际测量后再设置

4. 系统资源历史

# 内存使用历史
sar -r

# CPU 使用历史
sar -u

# 每秒刷新
sar -r 1

二、vLLM 显存预留问题（Anyscale 文档）

已知盲点： vLLM 无法检测系统为以下功能预留的显存： - ECC（Error-Correcting Code）内存 - 驱动/firmware 开销 - 显示输出 - MIG/vGPU 配置

这会导致 vLLM 尝试分配超过实际可用显存的内存。

测量系统预留显存

nvidia-smi -i 0 -q -d MEMORY
# Total FB memory = 总显存
# Used memory = 实际已用
# 差值 = 系统预留 + 可用

经验法则： 预留 5-10% 的总显存给系统开销，将 gpu_memory_utilization 设置为 0.9 或更低（取决于是否有 MIG/vGPU）。

三、Ray Serve / Anyscale 特定诊断

检查 Replica 状态

OOM 时，Ray Serve replicas 通常卡在 STARTING 或 UNHEALTHY 状态：

# 检查 replica 状态
ray status

# 查看 actor 日志
ray logs --actor-id=<actor_id>

网络连通性排查（Anyscale）

如果 OpenAIIngress 节点无法连接到其他节点也会导致问题：

# SSH 到对应节点
ssh <node_ip>

# 测试连通性
ping <other_node_ip>
curl -v http://<other_node>:<port>/health

四、Databricks 具体配置示例

{
  "name": "qwen-chat-endpoint",
  "config": {
    "served_entities": [{
      "entity_name": "catalog.schema.model_name",
      "entity_version": "1",
      "workload_type": "GPU_LARGE",
      "workload_size": "Large",
      "task": "llm/v1/completions",
      "environment_vars": {
        "HF_HOME": "/dbfs/huggingface",
        "MAX_JOBS": "4"
      }
    }]
  }
}

Databricks 多 GPU 加载脚本

from transformers import AutoModelForCausalLM, AutoTokenizer
import torch

def load_model(model_path):
    model = AutoModelForCausalLM.from_pretrained(
        model_path,
        device_map="auto",           # 跨 GPU 自动分配
        torch_dtype=torch.float16,   # FP16 节省显存
        trust_remote_code=True,
        low_cpu_mem_usage=True        # 降低 CPU RAM 压力
    )
    return model

五、长期运行显存碎片化处理

问题： vLLM 在数小时连续请求后，显存碎片化可能导致 OOM，即使理论显存应该充足。

解法： 1. 定时重启策略： 配置健康检查 + 自动重启（生产环境下的 workaround） 2. 降低 gpu_memory_utilization： - 80GB H100：从 0.95 降到 0.85 - 40GB A100：从 0.90 降到 0.80 3. 启用 --enforce-eager： 禁用 CUDA graph，牺牲少量性能换取更稳定的显存使用

六、根因分类速查

症状	可能根因	建议
启动即 OOM	模型太大 + gpu_memory_utilization 过高	降低利用率或换更大 GPU
运行数小时后 OOM	显存碎片化	定时重启或降低利用率
并发请求时 OOM	瞬时显存峰值	限流 + 增加 GPU
多 GPU 环境下部分 GPU OOM	CUDA compute capability 不一致（vLLM #7472）	检查所有 GPU 型号一致
报错 `CUDA out of memory` 但 `nvidia-smi` 显示显存足够	系统预留显存未计入	用 `nvidia-smi -q -d MEMORY` 实际测量

七、可信度评估

来源： OneUptime Blog（工程实践）+ Anyscale 官方文档（平台级）+ vLLM Forums（社区验证）
命令级内容： 可直接在生产环境运行
Databricks 示例： 具体 JSON 配置，有参考价值

链接： - https://oneuptime.com/blog/post/2026-01-28-debug-llm-inference-issues/view - https://docs.anyscale.com/llm/serving/troubleshooting - https://discuss.vllm.ai/t/torch-outofmemoryerror-cuda-out-of-memory/2420

标签： vLLM, CUDA-OOM, debugging, production, runbook