前言

        真正的生产环境中，从来都不是风平浪静的。显存溢出、延迟飙升、服务卡死、网关超时等等，这些问题都可能会出现，但这并不是模型不行，而是资源分配和调度策略不合理导致的。本文就对常见的问题制定一套合理的方案，从排查报错的顺序和对应的解决指令来一一拨开迷雾。

显存相关报错

• CUDA out of memory 错误

        这是一个最典型的报错了，可能导致的原因先列出来，然后再一一排查：

可能原因	本质
max-model-len 过大	KV Cache 预留爆炸
并发太高	同时生成的 token 过多了
gpu-memory-utilization 过于激进	没给系统留有余量
模型太大	权重将显存占满

• 排查顺序

        1、检查模型大小

#通过指令查看模型加载后显存占多少？如果一上来就 90%+，后面必炸。
nvidia-smi

        2、检查KV Cache的配置

#检查这几个参数的配置
--max-model-len
--max-num-batched-tokens
--max-num-seqs

• 解决方案

        可以参考以下列表分别降低对应参数的配置

方式	建议幅度
↓ max-model-len	4096 → 2048
↓  max-num-batched-tokens	8192 → 4096
↓  max-num-seqs	256 → 128
↓  gpu-memory-utilization	0.95 → 0.8
开启 --swap-space 4	给 CPU 做缓冲

        一般情况下，出现OOM问题80%的概率都是上下文长度调太大导致。

启动时报 NCCL 错误（多卡会出现）

• NCCL错误：

        可能会报：RuntimeError: NCCL error in: ...

        这也是一个常见的报错，可能导致的原因先列出来，然后再逐一排查：

可能原因	本质
GPU 之间不能够通信	没 NVLink / PCIe 拓扑异常
驱动 与 CUDA 不匹配	版本不一致导致的冲突
Docker 没有开启权限	缺少 --ipc=host

• 排查顺序

        1、检查多卡之间的拓扑结构

#展示 GPU 拓扑连接矩阵，判断多卡通信方式
nvidia-smi topo -m

        2、检查多卡环境变量的取值

# 查看变量值
echo $NCCL_P2P_DISABLE

• 解决方案

             临时禁用多卡通信，确认是否通信导致的错误 

#设置变量为禁用
export NCCL_P2P_DISABLE=1
export NCCL_IB_DISABLE=1

        Docker的环境可以增加以下参数，开启权限来校验

#开启权限,使用宿主机IPC命名空间
--ipc=host

请求无响应

• 请求无响应的问题，一直没有返回

        可能导致的原因先列出，再逐一排查：

可能原因	本质
批处理队列塞满	请求排队过久
max-num-seqs 过小	新请求进不来
输出 token 过长	一个请求霸占 GPU 过久

• 排查顺序

        检查日志有无：Waiting for free blocks in KV cache

• 解决方案       

方案	作用
增大 max-num-seqs	提升并发能力
限制 max_tokens	防止单请求一直占用资源
增大 max-num-batched-tokens	提高吞吐能力

启动时报‘Torch not compiled with CUDA enabled’

        这种错误比较直观，可以很快做出判断

• 原因

        很明显PyTorch安装为CPU版本，不支持CUDA

• 解决方案

        卸载CPU版本PyTorch，直接安装CUDA版本的PyTorch，指令如下

#卸载CPU版本的PyTorch
pip uninstall torch

#安装GPU版本的PyTorch
pip install torch==2.9.1 torchvision==0.24.1 torchaudio==2.9.1 --index-url https://download.pytorch.org/whl/cu128

加载模型卡住不动

这也是经常出现的一个问题，就是下载模型无响应。

• 原因

        以下列出常见原因

问题	说明
HuggingFace 下载慢	网络问题，国内限制，可以寻找国内镜像
权限不足	cache 目录不可写
safetensors 校验	大模型加载慢是正常的

• 解决方案

        1、网络问题导致的下载慢

        可以使用国内加速，修改HuggingFace为国内镜像,以下为对应指令

# HF镜像配置
export HF_ENDPOINT=https://hf-mirror.com

        2、cache权限不足

        可以找到对应目录增加权限，以下为对应指令

# 给当前用户赋予该目录的读写权限（最常用）
sudo chown -R $USER:$USER ~/.cache/huggingface

总结

        以上是几个常见的错误，其实是提供一个思路。总结下来就是先看显存，再看并发，再看 batch，最后看驱动。整理下来就是如下列表：

现象	第一怀疑对象
OOM	max-model-len
慢	batched-tokens
卡住	seqs / KV cache
多卡报错	NCCL
启动失败	CUDA / Torch

        这是遇到vLLM错误排查的一些思路，以供参考，当然也欢迎在评论区补充。