ROCm 环境下 vLLM 部署 llama3 时 CUDA_VISIBLE_DEVICES 失效的替代方案

在 ROCm 环境下用 vLLM 部署 llama3 时，CUDA_VISIBLE_DEVICES 失效不是个例。ROCm 运行时主要通过 HIP_VISIBLE_DEVICES 决定应用能看到哪些 GPU，而 vLLM 在 ROCm 下调用的是 HIP 访问路径，所以原来在 CUDA 生态里用 CUDA_VISIBLE_DEVICES 选卡的方式，需要换成 HIP 侧的环境变量。实际操作时，在启动 vLLM 之前设置 HIP_VISIBLE_DEVICES，再用 rocm-smi 核对设备编号，即可替代原方案。

判断：ROCm 下 vLLM 选卡应使用 HIP_VISIBLE_DEVICES，而不是 CUDA_VISIBLE_DEVICES。先设置该变量再启动 vLLM，并用 rocm-smi 核对设备编号；若变量未生效，再补充 ROCR_VISIBLE_DEVICES。设置后要通过 vLLM 启动日志确认实际加载的 GPU，避免多卡并行与设备数量不匹配。

为什么 CUDA_VISIBLE_DEVICES 会失效

CUDA_VISIBLE_DEVICES 是 NVIDIA CUDA 生态约定的变量，ROCm 的 HIP 层不会主动解析。vLLM 在 ROCm 环境里调用的底层 API 是 HIP，所以 GPU 可见性由 HIP 自己的环境变量控制。某些 ROCm 版本或容器镜像可能对这个变量做了兼容，但依赖这个变量来选择 GPU 仍然不可靠，尤其在多卡机器上，容易导致 vLLM 把所有 GPU 都当成可用资源。

替代方案：用 HIP_VISIBLE_DEVICES 指定 GPU

适用场景是需要把 vLLM 限定到指定一块或多块 AMD GPU 上。在启动 vLLM 的同一个 shell 中先设置环境变量，再执行 vllm serve。例如只使用 0 号卡：

export HIP_VISIBLE_DEVICES=0
vllm serve /models/llama3-8b-instruct `--tensor-parallel-size` 1

使用多张卡时，卡号列表和 tensor-parallel-size 要一致，否则模型并行初始化会出错：

export HIP_VISIBLE_DEVICES=0,2
vllm serve /models/llama3-8b-instruct `--tensor-parallel-size` 2

如果设置 HIP_VISIBLE_DEVICES 后 vLLM 仍然看到全部 GPU，可以追加设置 ROCR_VISIBLE_DEVICES，两个变量都写成同样的卡号。ROCR_VISIBLE_DEVICES 更接近硬件层，部分 ROCm 驱动版本会优先读取这个变量：

export HIP_VISIBLE_DEVICES=1
export ROCR_VISIBLE_DEVICES=1
vllm serve /models/llama3-8b-instruct `--tensor-parallel-size` 1

需要结合当前环境测试哪一个变量真正生效。HIP_VISIBLE_DEVICES 的编号是 ROCm 侧的设备序号，不一定对应物理插槽的 PCIe 顺序，所以先执行 rocm-smi `--showuniqueid` 或 rocminfo 确认目标卡对应的编号。

验证 GPU 是否按预期加载

设置完成后，不能只看环境变量内容。vLLM 启动时会打印类似 “GPU 0” 或 “GPU 0,1” 的日志，这里的编号是 vLLM 内部重新整理后的顺序，不是物理编号。要判断 vLLM 是否只看到指定卡，可以观察启动日志中的设备数量，再用 rocm-smi 查看这些 GPU 是否真的被占用。

ROCm 环境下 vLLM 部署 llama3 时 CUDA_VISIBLE_DEVICES 失效的替代方案

也可以用 Python 做更直接的确认。在设置环境变量后执行 torch 的可见设备检查，ROCm 下 torch 仍沿用 CUDA 风格的 API 名称，但底层已经走 HIP：

import os
os.environ['HIP_VISIBLE_DEVICES'] = '0,2'
import torch
print(torch.cuda.device_count())
print(torch.cuda.get_device_name(0))

如果输出数量与 HIP_VISIBLE_DEVICES 中的卡数一致，说明环境变量对 torch/vLLM 生效。如果 vLLM 启动时报找不到 GPU，先用 rocm-smi 确认驱动和设备状态，再检查环境变量是否被子进程覆盖。

常见问题

不设置 HIP_VISIBLE_DEVICES 会怎样？ 默认情况下 vLLM 会尝试使用所有在线 GPU。只想用部分卡时，才需要显式设置。

设置这个变量能控制显存占用吗？ 不能。HIP_VISIBLE_DEVICES 只控制设备可见性，单卡显存用量需要通过 `--gpu-memory-utilization` 参数单独设置。

多卡并行时 tensor-parallel-size 必须等于卡数吗？ 建议保持一致。vLLM 会按这个参数切分模型，设置值大于可见卡数时进程会失败；小于可见卡数时剩余卡不会参与负载。