vLLM 安装教程：Linux、NVIDIA GPU 与 AMD GPU 怎么装

木木夕技术创作者 2026-11-04 147 阅读

vLLM 是用于大语言模型推理和部署的开源引擎，这篇教程按 Linux、NVIDIA GPU、AMD GPU 和 Docker 四种路径给出可复制的安装步骤。安装完成后，可通过 vllm --help、启动本地服务或检查容器状态来确认是否成功。

先确定安装路径：原生 Python 还是 Docker

截至 2026-10-09，vLLM Quickstart 页面列出的基础环境是 Linux、Python 3.11–3.14；页面同时说明，macOS 可以通过 vLLM-Metal 使用 Apple Silicon GPU 加速。安装方式应根据硬件和用途选择：普通 NVIDIA GPU 优先使用 Python 环境；AMD GPU 需要选择对应的 ROCm 后端；多台机器部署或需要隔离依赖时，Docker 更省事；Windows 原生环境则应改用 WSL。

使用场景	推荐路径	安装前重点确认	安装后验证
Linux + NVIDIA GPU	`uv` 创建虚拟环境后安装	NVIDIA 驱动、CUDA 兼容关系、Python 版本	`vllm --help`
Linux + AMD GPU	使用 AMD 对应的安装命令	GPU 型号、ROCm 环境、Python 版本	`vllm --help`
macOS + Apple Silicon	vLLM-Metal	Apple Silicon GPU、对应文档标签页	`vllm --help`
多节点部署或隔离环境	Docker	NVIDIA Container Toolkit、镜像与驱动匹配	`docker ps`
Windows	WSL	兼容的 Linux 发行版、WSL 内 GPU 支持	在 WSL 中执行 `vllm --help`

这里的“容器”指把 vLLM、Python 依赖和运行时打包运行的 Docker 镜像；“ROCm”是 AMD GPU 的计算平台；WSL 是 Windows Subsystem for Linux，即 Windows 中运行 Linux 的兼容环境。

vLLM 官方首页当前展示的是“latest developer preview”文档，并提供稳定版文档入口。安装前应优先选择稳定版文档，不要把开发预览版与生产环境的依赖混用。官方仓库还提供 Releases 页面，可用于核对版本和变更记录。

NVIDIA GPU：用 uv 建立隔离环境

准备环境

先确认系统、Python 和显卡驱动：

uname -a
python3 --version
nvidia-smi

如果使用官方 Quickstart 当前列出的 Python 3.11–3.14，先创建虚拟环境。官方安装文档给出的完整命令是：

uv venv --python 3.12 --seed
source .venv/bin/activate

这里的 uv 是 Python 环境和包管理工具，--seed 会为新环境安装基础包。执行后确认当前解释器来自 .venv：

which python
python --version

路径应指向项目目录下的 .venv/bin/python。如果 uv 尚未安装，应先按照官方文档安装 uv，不要直接把系统 Python 改成虚拟环境。

安装 vLLM

NVIDIA GPU 可直接通过 pip 安装 vLLM。官方文档给出的自动选择 PyTorch CUDA 后端的命令为：

uv pip install vllm --torch-backend=auto

--torch-backend=auto 会根据已安装的 CUDA 驱动版本选择合适的 PyTorch 索引。若机器上的驱动和 CUDA 环境已经明确，可以指定后端；官方文档示例使用 cu126：

uv pip install vllm --torch-backend=cu126

不要在没有核对驱动版本的情况下盲目替换后端版本。安装后先检查命令是否已经进入当前环境：

vllm --help

看到帮助信息并且命令没有回到“command not found”，说明 Python 包已经安装到当前虚拟环境。此时再准备模型目录或模型下载权限。

不想创建长期环境

如果只是临时查看 CLI，或者需要一次性运行服务，可以使用 uv run。官方 Quickstart 页面给出的命令是：

uv run --with vllm vllm --help

这种方式不会创建长期保留的虚拟环境，适合快速确认安装是否可用，但它不适合需要反复调参、锁定依赖或部署服务的生产环境。

AMD GPU：安装命令必须匹配 ROCm

AMD GPU 不应直接照搬 NVIDIA 的 CUDA 安装命令。官方 Quickstart 说明，AMD GPU 可以使用 uv 安装 vLLM，并建议使用 uv，因为它能优先使用高于默认索引的额外索引。页面同时给出针对 AMD 平台的依赖条件：Python 3.12、ROCm 7.0，以及 glibc 不低于 2.35。

先在目标 Linux 机器执行：

python3 --version
rocminfo
ldd --version

确认 Python 版本、ROCm 设备和 glibc 版本符合要求后，用官方 GPU 安装页给出的 AMD 命令安装（2026-11-04 实测当前页口径：Python 3.12、ROCm 10.0、glibc ≥ 2.35；订单快照口径为 ROCm 7.0——两版并存，以你机器上装的 ROCm 对应 wheel 为准，旧 ROCm 7.2 wheel 仍留档在 https://wheels.vllm.ai/rocm/${VLLM_VERSION}/rocm72）：

uv pip install vllm --extra-index-url https://wheels.vllm.ai/rocm/ --upgrade

官方文档还说明，AMD 的 Docker 发布方式正在从旧的 rocm/vllm-dev 流水线迁移到 vLLM 的 Docker 发布流水线；如果使用镜像，不要继续把旧镜像名称当成唯一安装入口（当前 AMD 镜像为 vllm/vllm-openai-rocm:latest）。

安装后执行：

vllm --help

如果命令存在但启动模型时报错，应先区分“vLLM 包未安装”和“GPU 后端、驱动或模型不匹配”：前者检查 which vllm 与当前 Python 路径，后者检查 rocminfo、驱动版本以及所用命令对应的 AMD 文档版本。不要通过反复卸载重装来掩盖硬件配置问题。

Docker：适合隔离部署和快速验证

Docker 路径的价值是把 Python、依赖和 vLLM 运行时放进同一环境，适合服务器部署、测试镜像以及需要避免污染宿主机的场景。官方仓库明确列出了 docker 目录，官方文档也提供 Using Docker 入口；实际镜像名称和启动参数应从该页面的当前版本复制，不能凭旧教程猜测。

先确认 Docker 和 GPU 容器运行时已经就绪：

docker --version
docker info
nvidia-smi

然后执行官方 deployment/docker 页给出的启动命令（2026-11-04 实测原文结构）：

docker run --runtime nvidia --gpus all 
  -v ~/.cache/huggingface:/root/.cache/huggingface 
  --env "HF_TOKEN=$HF_TOKEN" 
  -p 8000:8000 
  --ipc=host 
  vllm/vllm-openai:latest 
  --model Qwen/Qwen3-0.6B

（AMD 用同页的 vllm/vllm-openai-rocm:latest。）NVIDIA GPU 容器还需要 NVIDIA Container Toolkit；这是让 Docker 容器访问宿主机 GPU 的运行时组件，不是 vLLM 的 Python 依赖。

容器是否成功启动，要通过容器状态和日志判断：

docker ps
docker logs <容器名或容器ID>

<容器名或容器ID> 是模板说明，实际执行时替换为 docker ps 输出的真实值。若容器刚启动就退出，优先查看日志最后几十行；如果日志显示驱动不可见，问题在容器运行时或挂载配置，而不是先修改 vLLM 参数。

常见卡点：先定位层次，再改命令

`uv` 创建的环境没有生效

创建环境后没有执行激活，或激活了另一个 Python。重新执行：

source .venv/bin/activate
which python
which vllm

两个路径应位于同一套环境中。若 which vllm 没有结果，说明命令没有安装到当前虚拟环境，重新执行对应的 uv pip install 命令。

`vllm` 命令找不到

如果之前使用 uv run --with vllm 测试过，之后直接运行 vllm 找不到命令，通常是因为一次性环境已经结束。两种处理方式：继续使用 uv run --with vllm vllm --help，或者在长期环境中执行 uv pip install vllm --torch-backend=auto 后再验证。

GPU 能被系统识别，但 vLLM 无法使用

分别执行 nvidia-smi、rocminfo 和 vllm --help。系统能识别 GPU，只能说明驱动层基本可见；还必须确认当前安装命令选中了正确后端，并且 Python 环境中的 PyTorch 与该后端匹配。NVIDIA 路径使用 --torch-backend=auto 或明确后端；AMD 路径使用官方 AMD 页面当前给出的命令。

镜像启动了但模型加载失败

这通常是模型路径、模型格式、显存或容器参数问题，不是“安装失败”。先用 vllm --help 确认 CLI 正常，再根据官方 Server Arguments 和模型支持文档核对启动参数。对于 Docker，则同时检查容器日志和宿主机驱动，避免只修改模型参数而忽略 GPU 不可见问题。

怎么算安装成功

原生 Python 安装的最低成功标志是：

vllm --help

这条命令能正常返回帮助文本，且 which vllm 指向预期环境。临时环境则应看到：

uv run --with vllm vllm --help

正常显示 CLI 帮助。

Docker 路径的成功标志是 docker ps 中能看到运行中的容器，并且 docker logs 没有显示驱动、镜像或启动参数错误。真正开始部署模型后，还应使用官方文档中的 API Server 入口，通过 OpenAI 兼容接口发送一次请求；此时“能启动服务”和“能返回模型结果”才算两层验证都完成。

参考来源

Installation – vLLM

# AI # 知识

评论区

0 条评论

登录后可评论。