vLLM多卡部署时自动检测GPU数量失败改用显式CUDA_VISIBLE_DEVICES

文章导读
vLLM多卡部署时自动检测GPU数量失败,优先考虑CUDA_VISIBLE_DEVICES环境变量与容器/驱动环境不一致。vLLM的显卡探测走的是CUDA API,CUDA只枚举CUDA_VISIBLE_DEVICES中可见的设备。如果这个变量没设置,vLLM会尝试从系统层读取全部GPU;但在Docker、Kubernetes或部分虚拟化环境中,系统层设备列表和当前进程可见设备列表可能对不上,导致
📋 目录
  1. 一 先做四个检查点
  2. 二 直接改用显式CUDA_VISIBLE_DEVICES
  3. 三 如果还是失败,走分支排查
  4. 四 验证信号:看启动日志和显存分布
A A

vLLM多卡部署时自动检测GPU数量失败,优先考虑CUDA_VISIBLE_DEVICES环境变量与容器/驱动环境不一致。vLLM的显卡探测走的是CUDA API,CUDA只枚举CUDA_VISIBLE_DEVICES中可见的设备。如果这个变量没设置,vLLM会尝试从系统层读取全部GPU;但在Docker、Kubernetes或部分虚拟化环境中,系统层设备列表和当前进程可见设备列表可能对不上,导致自动检测到0卡或1卡,而不是实际分配的4卡/8卡。显式设置CUDA_VISIBLE_DEVICES能跳过这一层探测,让vLLM直接面对你想让它用的设备集合。

先确认现象,再动手改。典型现象是:nvidia-smi能看到多张卡,但vLLM启动日志只有0卡或1卡;或者启动后只占用单卡显存;也可能直接报类似“No available GPUs”的错误。如果你在容器里跑,还可能看到vLLM识别到的GPU编号与容器内nvidia-smi不一致,比如宿主机是4卡、容器里只映射了2卡,但vLLM用了宿主机编号导致越界。

先做四个检查点

  • 运行 nvidia-smi -L 查看当前进程可见的GPU列表,记下设备编号。
  • 运行 echo $CUDA_VISIBLE_DEVICES 看环境变量是否已存在,是否被错误设置成只有一个ID。
  • 查看vLLM启动命令里的 `--tensor-parallel-size` 参数,不要让它大于可见GPU数。
  • 如果是Docker,检查运行命令是否带 `--gpus` all 或 `--gpus` device=0,1;只设置环境变量但容器没映射GPU,照样没用。

直接改用显式CUDA_VISIBLE_DEVICES

最直接的处理方式是在启动vLLM前,把环境变量设置成你实际要用的GPU编号列表。以4卡启动OpenAI兼容API服务为例:

vLLM多卡部署时自动检测GPU数量失败改用显式CUDA_VISIBLE_DEVICES
export CUDA_VISIBLE_DEVICES=0,1,2,3
python -m vllm.entrypoints.openai.api_server `--model` meta-llama/Llama-2-7b-chat-hf `--tensor-parallel-size` 4

也可以在不改shell环境的情况下,直接在命令前加变量:

vLLM多卡部署时自动检测GPU数量失败改用显式CUDA_VISIBLE_DEVICES
CUDA_VISIBLE_DEVICES=0,1,2,3 python -m vllm.entrypoints.api_server `--model` /path/to/model `--tensor-parallel-size` 4

这里有两处需要根据实际情况替换:`--model` 换成你的模型路径或HuggingFace模型名;`--tensor-parallel-size` 换成与GPU数量一致的数字。如果你是其他入口(比如vllm serve),同样把环境变量放在最前面即可。

如果还是失败,走分支排查

  1. 设置后启动仍然只看到1卡:先运行 CUDA_VISIBLE_DEVICES=0,1,2,3 python -c 'import torch; print(torch.cuda.device_count())',如果用PyTorch都只看到1卡,说明CUDA层没有正确读取环境变量,检查驱动和CUDA版本;如果PyTorch看到4卡而vLLM只看到1卡,考虑升级vLLM版本。
  2. 报“Invalid device ordinal”之类的错误:你设置的编号超出了当前可见设备范围,比如容器内只有2张卡,却写成了 0,1,2,3。先用 nvidia-smi -L 确认实际编号。
  3. 容器里nvidia-smi都看不到卡:这是容器化问题,先检查NVIDIA Container Toolkit是否安装,以及docker run是否带了 `--gpus` 参数。不要指望在容器内设置CUDA_VISIBLE_DEVICES能解决宿主机透传问题。
  4. 多用户共享宿主机时,别人占用了GPU显存:你可以只指定空闲卡的编号,但要注意编号可能随时间变化;建议在业务启动前先通过 nvidia-smi `--query-gpu`=index,memory.free `--format`=csv 确认。

验证信号:看启动日志和显存分布

设置成功后,vLLM启动日志中应该能看到类似‘GPU 0, 1, 2, 3’或‘tensor_parallel_size=4’的字样,并且进程会占用所有指定GPU的显存。你可以同时运行 watch -n 1 nvidia-smi,看这4张卡的显存使用是否同时上涨。另一个更严格的验证是直接在服务端调用推理接口,看单次请求是否同时利用多卡计算。如果日志里只有0号卡,或者显存只有一张卡在涨,说明显式设置没有生效,回到检查点重新排查。

vLLM多卡部署时自动检测GPU数量失败改用显式CUDA_VISIBLE_DEVICES

还需要注意的是,显式指定CUDA_VISIBLE_DEVICES只是绕开自动检测的一种稳妥做法,不等于vLLM一定能填满多卡。如果模型本身很小,或者推理时batch太小,多卡利用率可能不高。自动检测失败如果和驱动版本强相关,请先升级NVIDIA驱动和vLLM版本,再考虑用环境变量做长期固定方案。