GPU¶
vLLM 是一个支持以下 GPU 变体的 Python 库。请选择您的 GPU 类型以查看特定供应商的说明。
vLLM 包含预编译的 C++ 和 CUDA (12.8) 二进制文件。
vLLM 支持使用 ROCm 6.3 或更高版本的 AMD GPU。目前提供适用于 ROCm 7.0 和 ROCm 7.2.1 的预构建安装包。
预构建安装包¶
| ROCm 变体 | Python 版本 | ROCm 版本 | glibc 要求 | 支持的版本 |
|---|---|---|---|---|
rocm700 | 3.12 | 7.0 | >= 2.35 | 0.14.0 到 0.18.0 |
rocm721 | 3.12 | 7.2.1 | >= 2.35 | 提交记录 171775f306a333a9cf105bfd533bf3e113d401d9 之后的每日构建版 (Nightly releases) |
vLLM 最初支持在英特尔 GPU 平台上进行基础模型推理和服务。
要求¶
- 操作系统：Linux
- Python: 3.10 -- 3.13
注意
vLLM 不原生支持 Windows。要在 Windows 上运行 vLLM，您可以使用适用于 Linux 的 Windows 子系统 (WSL) 并搭配兼容的 Linux 发行版，或者使用一些社区维护的分支版本，例如 https://github.com/SystemPanic/vllm-windows。
- GPU：计算能力 7.0 或更高（例如，V100、T4、RTX20xx、A100、L4、H100 等）
- GPU: MI200s (gfx90a), MI300 (gfx942), MI350 (gfx950), Radeon RX 7900 系列 (gfx1100/1101), Radeon RX 9000 系列 (gfx1200/1201), Ryzen AI MAX / AI 300 系列 (gfx1151/1150)
- ROCm 6.3 或更高版本
- MI350 需要 ROCm 7.0 或更高版本
- Ryzen AI MAX / AI 300 系列需要 ROCm 7.0.2 或更高版本
- 支持的硬件: 英特尔数据中心 GPU, 英特尔 ARC GPU
- 依赖项: vllm-xpu-kernels: 该软件包提供了在英特尔 GPU 平台上运行 vLLM 时所有必要的 vLLM 自定义内核。
- Python：3.12
警告
提供的 vllm-xpu-kernels whl 文件是专门针对 Python 3.12 的，因此该版本是必需的。
使用 Python 进行设置¶
创建新的 Python 环境¶
建议使用 uv，一个非常快速的 Python 环境管理器，来创建和管理 Python 环境。请按照 文档 安装 uv。安装 uv 后，您可以使用以下命令创建新的 Python 环境。
注意
通过 conda 安装的 PyTorch 会静态链接 NCCL 库，当 vLLM 尝试使用 NCCL 时，这可能会导致问题。详细信息请参阅 Issue #8420。
为了获得高性能，vLLM 必须编译许多 CUDA 内核。遗憾的是，这种编译引入了与其它 CUDA 版本和 PyTorch 版本（即使是构建配置不同的同一 PyTorch 版本）的二进制不兼容性。
因此，建议在全新的环境中安装 vLLM。如果您拥有不同的 CUDA 版本，或者想要使用现有的 PyTorch 安装，则需要从源码构建 vLLM。详细信息请参阅下文。
vLLM 安装包中捆绑了 PyTorch 和所有必需的依赖项，您应该使用其中包含的 PyTorch 以保证兼容性。由于 vLLM 编译了许多 ROCm 内核以确保验证过的高性能堆栈，生成的二进制文件可能与其它 ROCm 或 PyTorch 构建版本不兼容。如果您需要不同的 ROCm 版本或想要使用现有的 PyTorch 安装，则需要从源码构建 vLLM。详细信息请参阅下文。
对于此设备，没有创建新 Python 环境的额外说明。
预构建的 Wheels¶
pip
我们建议利用 uv，通过 --torch-backend=auto（或 UV_TORCH_BACKEND=auto）检查已安装的 CUDA 驱动版本，从而在运行时自动选择合适的 PyTorch 索引。要选择特定的后端（例如 cu128），请设置 --torch-backend=cu128（或 UV_TORCH_BACKEND=cu128）。如果这不起作用，请先尝试运行 uv self update 更新 uv。
注意
NVIDIA Blackwell GPU (B200, GB200) 至少需要 CUDA 12.8，因此请确保您安装的 PyTorch 安装包至少是该版本。PyTorch 本身提供了一个专用界面，用于确定针对特定目标配置应运行的 pip 命令。
目前，vLLM 的二进制文件默认使用 CUDA 12.9 和公共 PyTorch 发布版本编译。我们也提供使用 CUDA 12.8、13.0 和公共 PyTorch 发布版本编译的 vLLM 二进制文件。
# Install vLLM with a specific CUDA version (e.g., 13.0).
export VLLM_VERSION=$(curl -s https://api.github.com/repos/vllm-project/vllm/releases/latest | jq -r .tag_name | sed 's/^v//')
export CUDA_VERSION=130 # or other
export CPU_ARCH=$(uname -m) # x86_64 or aarch64
uv pip install https://github.com/vllm-project/vllm/releases/download/v${VLLM_VERSION}/vllm-${VLLM_VERSION}+cu${CUDA_VERSION}-cp38-abi3-manylinux_2_35_${CPU_ARCH}.whl --extra-index-url https://download.pytorch.org/whl/cu${CUDA_VERSION}
安装最新代码¶
LLM 推理是一个快速发展的领域，最新的代码可能包含尚未发布的错误修复、性能改进和新功能。为了让用户在无需等待下一次发布的情况下试用最新代码，vLLM 为自 v0.5.3 以来的每次提交在 https://wheels.vllm.ai/nightly 上提供了安装包。可以使用多个索引：
https://wheels.vllm.ai/nightly：默认变体（CUDA 版本由VLLM_MAIN_CUDA_VERSION指定），基于main分支的最后一次提交构建。目前为 CUDA 12.9。https://wheels.vllm.ai/nightly/<variant>：所有其它变体。现在包含cu130和cpu。默认变体 (cu129) 也有一个子目录以保持一致性。
要从夜间索引安装，请运行
uv pip install -U vllm \
--torch-backend=auto \
--extra-index-url https://wheels.vllm.ai/nightly # add variant subdirectory here if needed
pip 注意事项
使用 pip 从夜间索引安装是不受支持的，因为 pip 会合并来自 --extra-index-url 和默认索引的包，仅选择最新版本，这使得安装发布版本之前的开发版本变得困难。相比之下，uv 使额外的索引比默认索引具有 更高的优先级。
如果您坚持使用 pip，则必须指定安装包文件的完整 URL（可从网页获取）。
pip install -U https://wheels.vllm.ai/nightly/vllm-0.11.2.dev399%2Bg3c7461c18-cp38-abi3-manylinux_2_31_x86_64.whl # current nightly build (the filename will change!)
pip install -U https://wheels.vllm.ai/${VLLM_COMMIT}/vllm-0.11.2.dev399%2Bg3c7461c18-cp38-abi3-manylinux_2_31_x86_64.whl # from specific commit
安装特定版本¶
如果您想访问之前提交的轮子（例如，为了二分查找行为更改、性能回归），您可以在 URL 中指定提交哈希。
安装适用于 Python 3.12、ROCm 7.0 和 glibc >= 2.35 的最新版 vLLM。
提示
您可以通过查看 https://wheels.vllm.ai/rocm/ 中 extra-index-url 下的 vllm 软件包（地址：https://wheels.vllm.ai/rocm/vllm）来了解最新版 vLLM 支持哪个 ROCm 版本。
另一种方法是使用以下命令自动提取安装包变体：
# automatically extract the available rocm variant
export VLLM_ROCM_VARIANT=$(curl -s https://wheels.vllm.ai/rocm/vllm | grep -oP 'rocm\d+' | head -1)
# automatically extract the vLLM version
export VLLM_VERSION=$(curl -s https://wheels.vllm.ai/rocm/vllm | grep -oP 'vllm-\K[0-9.]+' | head -1)
# inspect if the ROCm version is compatible with your environment
echo $VLLM_ROCM_VARIANT
echo $VLLM_VERSION
安装特定版本和 ROCm 变体的 vLLM 安装包。
# version without the `v`
uv pip install vllm==${VLLM_VERSION} --extra-index-url https://wheels.vllm.ai/rocm/${VLLM_VERSION}/${VLLM_ROCM_VARIANT}
# Example
uv pip install vllm==0.18.0 --extra-index-url https://wheels.vllm.ai/rocm/0.18.0/rocm700
使用 pip 的注意事项
我们建议利用 uv 来安装 vLLM。使用 pip 从自定义索引安装非常繁琐，因为 pip 会合并 --extra-index-url 和默认索引中的软件包，并仅选择最新版本。这使得在不指定所有软件包确切版本的情况下，很难从自定义索引安装安装包。相比之下，uv 会赋予额外索引比默认索引更高的优先级。
如果您坚持使用 pip，则需要在软件包名称中指定确切的 vLLM 版本，并通过 --extra-index-url 提供自定义索引 URL：https://wheels.vllm.ai/rocm/${VLLM_VERSION}/${VLLM_ROCM_VARIANT}。
安装最新代码¶
LLM 推理是一个快速发展的领域，最新的代码可能包含尚未发布的错误修复、性能改进和新功能。为了让用户在无需等待下一次发布的情况下试用最新代码，vLLM 为自提交 171775f306a333a9cf105bfd533bf3e113d401d9 以来的每次提交在 https://wheels.vllm.ai/rocm/nightly/ 上提供了安装包。要使用的自定义索引为 https://wheels.vllm.ai/rocm/nightly/${VLLM_ROCM_VARIANT}。
注意： 第一个支持每日构建安装包的 ROCm 变体是 ROCm 7.2.1。
要从最新的每日构建索引安装，请运行：
# automatically extract the available rocm variant
export VLLM_ROCM_VARIANT=$(curl -s https://wheels.vllm.ai/rocm/nightly | \
grep -oP 'rocm\d+' | head -1 | sed 's/%2B/+/g')
# inspect if the ROCm version is compatible with your environment
echo $VLLM_ROCM_VARIANT
uv pip install --pre vllm \
--extra-index-url https://wheels.vllm.ai/rocm/nightly/${VLLM_ROCM_VARIANT} \
--index-strategy unsafe-best-match
安装特定版本¶
如果您想访问之前提交的安装包（例如为了二分排查行为变化或性能回归），可以在 URL 中指定提交哈希，例如：
export VLLM_COMMIT=5b8c30d62b754b575e043ce2fc0dcbf8a64f6306
export VLLM_ROCM_VARIANT=$(curl -s https://wheels.vllm.ai/rocm/${VLLM_COMMIT} | \
grep -oP 'rocm\d+' | head -1 | sed 's/%2B/+/g')
# Extract the version from the wheel URL
export VLLM_VERSION=$(curl -s https://wheels.vllm.ai/rocm/${VLLM_COMMIT}/${VLLM_ROCM_VARIANT}/vllm/ | \
grep -oP 'vllm-\K[^-]+' | head -1 | sed 's/%2B/+/g')
# inspect the version if it is compatible with the ROCm version of your environment
echo $VLLM_ROCM_VARIANT
echo $VLLM_VERSION
uv pip install vllm==${VLLM_VERSION} \
--extra-index-url https://wheels.vllm.ai/rocm/${VLLM_COMMIT}/${VLLM_ROCM_VARIANT} \
--index-strategy unsafe-best-match
pip 注意事项
使用 pip 从夜间索引安装是不受支持的，因为 pip 会合并来自 --extra-index-url 和默认索引的包，仅选择最新版本，这使得安装发布版本之前的开发版本变得困难。相比之下，uv 使额外的索引比默认索引具有 更高的优先级。
如果您坚持使用 pip，则需要在软件包名称中指定确切的 vLLM 版本，并提供自定义索引 URL（可从网页获取）。
export VLLM_COMMIT=5b8c30d62b754b575e043ce2fc0dcbf8a64f6306
export VLLM_ROCM_VARIANT=$(curl -s https://wheels.vllm.ai/rocm/${VLLM_COMMIT} | \
grep -oP 'rocm\d+' | head -1 | sed 's/%2B/+/g')
# Extract the version from the wheel URL
export VLLM_VERSION=$(curl -s https://wheels.vllm.ai/rocm/${VLLM_COMMIT}/${VLLM_ROCM_VARIANT}/vllm/ | \
grep -oP 'vllm-\K[^-]+' | head -1 | sed 's/%2B/+/g')
# inspect the version if it is compatible with the ROCm version of your environment
echo $VLLM_ROCM_VARIANT
echo $VLLM_VERSION
pip install vllm==${VLLM_VERSION} \
--extra-index-url https://wheels.vllm.ai/rocm/${VLLM_COMMIT}/${VLLM_ROCM_VARIANT}
目前没有预构建的 XPU 安装包。
从源代码构建 Wheel¶
通过纯 Python 构建（无需编译）进行设置¶
如果您只需要修改 Python 代码，则可以在不进行编译的情况下构建并安装 vLLM。使用 uv pip 的 --editable 标志，您对代码所做的更改在运行 vLLM 时就会生效。
git clone https://github.com/vllm-project/vllm.git
cd vllm
VLLM_USE_PRECOMPILED=1 uv pip install --editable .
此命令将执行以下操作：
- 在您的 vLLM 克隆版本中查找当前分支。
- 识别 main 分支中对应的基础提交。
- 下载基础提交的预构建安装包。
- 在安装中使用其编译好的库。
注意
- 如果您更改了 C++ 或内核代码，则不能使用仅 Python 的构建方式；否则您会看到关于找不到库或未定义符号的导入错误。
- 如果您重新基准化 (rebase) 了开发分支，建议卸载 vllm 并重新运行上述命令，以确保您的库是最新的。
如果您在运行上述命令时看到关于未找到安装包的错误，可能是因为您所基于的 main 分支提交刚被合并，安装包正在构建中。在这种情况下，您可以等待大约一小时后再试，或者使用 VLLM_PRECOMPILED_WHEEL_LOCATION 环境变量在安装中手动指定之前的提交。
export VLLM_PRECOMPILED_WHEEL_COMMIT=$(git rev-parse HEAD~1) # or earlier commit on main
export VLLM_USE_PRECOMPILED=1
uv pip install --editable .
还有更多环境变量可用于控制仅 Python 构建的行为：
VLLM_PRECOMPILED_WHEEL_LOCATION：指定要使用的预编译安装包的确切 URL 或本地文件路径。所有其它查找安装包的逻辑都将被跳过。VLLM_PRECOMPILED_WHEEL_COMMIT：覆盖要下载的预编译安装包的提交哈希。可以设置为nightly以使用 main 分支上最后一次已构建的提交。VLLM_PRECOMPILED_WHEEL_VARIANT：指定要在每日构建索引上使用的变体子目录，例如cu129,cu130,cpu。如果未指定，将根据系统 CUDA 版本（从 PyTorch 或 nvidia-smi 获取）自动检测变体。您还可以设置VLLM_MAIN_CUDA_VERSION来覆盖自动检测。
您可以在“安装最新代码”中找到有关 vLLM 安装包的更多信息。
注意
您的源代码可能与最新的 vLLM 安装包具有不同的提交 ID，这可能会导致未知错误。建议源代码使用与已安装 vLLM 安装包相同的提交 ID。有关如何安装指定安装包的说明，请参阅“安装最新代码”。
完整构建（需要编译）¶
如果您想修改 C++ 或 CUDA 代码，则需要从源码构建 vLLM。这可能需要几分钟时间。
提示
从源码构建需要大量编译。如果您反复进行源码构建，缓存编译结果会更高效。
例如，您可以使用 conda install ccache 或 apt install ccache 安装 ccache。只要 which ccache 命令能找到 ccache 二进制文件，构建系统就会自动使用它。首次构建后，后续构建速度会快得多。
在使用 pip install -e . 时配合 ccache，您应该运行 CCACHE_NOHASHDIR="true" pip install --no-build-isolation -e .。这是因为 pip 会为每次构建创建一个名称随机的新文件夹，从而阻止 ccache 识别出正在构建的是相同文件。
sccache 的工作方式与 ccache 类似，但具有在远程存储环境中利用缓存的功能。可以设置以下环境变量来配置 vLLM sccache 远程存储：SCCACHE_BUCKET=vllm-build-sccache SCCACHE_REGION=us-west-2 SCCACHE_S3_NO_CREDENTIALS=1。我们还建议设置 SCCACHE_IDLE_TIMEOUT=0。
更快的内核开发
对于频繁的 C++/CUDA 内核更改，在初始的 uv pip install -e . 设置完成后，可以考虑使用 增量编译工作流，以便显著加快仅修改后的内核代码的重建速度。
使用现有的 PyTorch 安装¶
在某些情况下，PyTorch 依赖项无法通过 uv 轻松安装，例如在使用非默认 PyTorch 构建版本（如 nightly 或自定义构建版本）构建 vLLM 时。
使用现有的 PyTorch 安装构建 vLLM：
# install PyTorch first, either from PyPI or from source
git clone https://github.com/vllm-project/vllm.git
cd vllm
python use_existing_torch.py
uv pip install -r requirements/build.txt
uv pip install --no-build-isolation -e .
或者：如果您仅使用 uv 创建和管理虚拟环境，它有一种独特的机制可以针对特定软件包禁用构建隔离。vLLM 可以利用此机制指定 torch 为需要禁用构建隔离的软件包。
# install PyTorch first, either from PyPI or from source
git clone https://github.com/vllm-project/vllm.git
cd vllm
# pip install -e . does not work directly, only uv can do this
uv pip install -e .
使用本地 cutlass 进行编译¶
目前，在开始构建过程之前，vLLM 会从 GitHub 获取 cutlass 代码。但是，在某些情况下您可能希望使用本地版本的 cutlass。要实现这一点，您可以设置环境变量 VLLM_CUTLASS_SRC_DIR 指向您的本地 cutlass 目录。
git clone https://github.com/vllm-project/vllm.git
cd vllm
VLLM_CUTLASS_SRC_DIR=/path/to/cutlass uv pip install -e .
故障排除¶
为避免系统负载过重，您可以通过环境变量 MAX_JOBS 限制同时运行的编译任务数量。例如：
这在性能较弱的机器上构建时特别有用。例如，当您使用 WSL 时，它默认仅分配总内存的 50%，因此使用 export MAX_JOBS=1 可以避免同时编译多个文件导致内存耗尽。副作用是构建过程会慢得多。
此外，如果您在构建 vLLM 时遇到问题，我们建议使用 NVIDIA PyTorch Docker 镜像。
# Use `--ipc=host` to make sure the shared memory is large enough.
docker run \
--gpus all \
-it \
--rm \
--ipc=host nvcr.io/nvidia/pytorch:23.10-py3
如果您不想使用 docker，建议完整安装 CUDA Toolkit。您可以从官网下载并安装。安装完成后，将环境变量 CUDA_HOME 设置为 CUDA Toolkit 的安装路径，并确保 nvcc 编译器在您的 PATH 中，例如：
以下是验证 CUDA Toolkit 是否已正确安装的健全性检查：
nvcc --version # verify that nvcc is in your PATH
${CUDA_HOME}/bin/nvcc --version # verify that nvcc is in your CUDA_HOME
不支持的操作系统构建¶
vLLM 仅能在 Linux 上完整运行，但出于开发目的，您仍然可以在其它系统（例如 macOS）上进行构建，从而实现导入并获得更方便的开发环境。二进制文件将不会被编译，也无法在非 Linux 系统上工作。
在安装前禁用 VLLM_TARGET_DEVICE 环境变量即可。
提示
- 如果您发现以下安装步骤对您无效，请参阅 docker/Dockerfile.rocm_base。Dockerfile 记录了安装步骤。
-
安装先决条件（如果您已经在安装了以下组件的环境/docker 中，请跳过）
对于 PyTorch 安装，您可以从全新的 docker 镜像开始，例如
rocm/pytorch:rocm7.0_ubuntu22.04_py3.10_pytorch_release_2.8.0或rocm/pytorch-nightly。如果您使用的是 docker 镜像，可以直接跳到第 3 步。或者，您可以使用 PyTorch 安装包安装 PyTorch。您可以查看 PyTorch 入门指南中的 PyTorch 安装说明。例如：
-
按照 ROCm/triton 中的说明安装 ROCm 版 Triton。
python3 -m pip install ninja cmake wheel pybind11 pip uninstall -y triton git clone https://github.com/ROCm/triton.git cd triton # git checkout $TRITON_BRANCH git checkout f9e5bf54 if [ ! -f setup.py ]; then cd python; fi python3 setup.py install cd ../..注意
- 经验证的
$TRITON_BRANCH可在 docker/Dockerfile.rocm_base 中找到。 - 如果您在构建 triton 过程中遇到与下载软件包相关的 HTTP 问题，请重试，因为 HTTP 错误通常是间歇性的。
- 经验证的
-
（可选）如果您选择使用 CK flash attention，可以安装 ROCm 版 flash attention。
按照 ROCm/flash-attention 中的说明安装 ROCm 版 flash attention (v2.8.0)。
例如，对于 ROCm 7.0，假设您的显卡架构是
gfx942。要获取显卡架构，请运行rocminfo |grep gfx。git clone https://github.com/Dao-AILab/flash-attention.git cd flash-attention # git checkout $FA_BRANCH git checkout 0e60e394 git submodule update --init GPU_ARCHS="gfx942" python3 setup.py install cd ..注意
- 经验证的
$FA_BRANCH可在 docker/Dockerfile.rocm_base 中找到。
- 经验证的
-
（可选）如果您选择自行构建 AITER 以使用特定的分支或提交，可以使用以下步骤构建 AITER：
python3 -m pip uninstall -y aiter git clone --recursive https://github.com/ROCm/aiter.git cd aiter git checkout $AITER_BRANCH_OR_COMMIT git submodule sync; git submodule update --init --recursive python3 setup.py develop注意
- 您需要根据您的目的配置
$AITER_BRANCH_OR_COMMIT。 - 经验证的
$AITER_BRANCH_OR_COMMIT可在 docker/Dockerfile.rocm_base 中找到。
- 您需要根据您的目的配置
-
（可选）如果您想将 MORI 用于 EP 或 PD 解耦，可以使用以下步骤安装 MORI：
git clone https://github.com/ROCm/mori.git cd mori git checkout $MORI_BRANCH_OR_COMMIT git submodule sync; git submodule update --init --recursive MORI_GPU_ARCHS="gfx942;gfx950" python3 setup.py install注意
- 您需要根据您的目的配置
$MORI_BRANCH_OR_COMMIT。 - 经验证的
$MORI_BRANCH_OR_COMMIT可在 docker/Dockerfile.rocm_base 中找到。
- 您需要根据您的目的配置
-
构建 vLLM。例如，ROCM 7.0 上的 vLLM 可以通过以下步骤构建：
命令
pip install --upgrade pip # Build & install AMD SMI pip install /opt/rocm/share/amd_smi # Install dependencies pip install --upgrade numba \ scipy \ huggingface-hub[cli,hf_transfer] \ setuptools_scm pip install -r requirements/rocm.txt # To build for a single architecture (e.g., MI300) for faster installation (recommended): export PYTORCH_ROCM_ARCH="gfx942" # To build vLLM for multiple arch MI210/MI250/MI300, use this instead # export PYTORCH_ROCM_ARCH="gfx90a;gfx942" python3 setup.py develop这可能需要 5-10 分钟。目前，当从源码安装 vLLM 时，
pip install .对 ROCm 不起作用。提示
- ROCm 版 PyTorch 最好应与 ROCm 驱动版本相匹配。
提示
- 对于 MI300x (gfx942) 用户，为了获得最佳性能，请参阅 MI300x 调优指南，了解系统和工作流层面的性能优化及调优技巧。对于 vLLM，请参阅 vLLM 性能优化。
- 首先，安装所需的 驱动程序。
- 其次，为 vLLM XPU 后端构建安装 Python 软件包（Intel OneAPI 依赖项会作为
torch-xpu的一部分自动安装，请参阅 PyTorch XPU 入门）。
git clone https://github.com/vllm-project/vllm.git
cd vllm
pip install --upgrade pip
pip install -v -r requirements/xpu.txt
-
然后，安装适用于 Intel XPU 的正确 Triton 软件包。
默认的
triton软件包（用于 NVIDIA GPU）可能作为传递依赖项安装（例如通过xgrammar）。对于 Intel XPU，您必须将其替换为triton-xpu。pip uninstall -y triton triton-xpu pip install triton-xpu==3.6.0 --extra-index-url https://download.pytorch.org/whl/xpu注意
triton（无后缀）仅适用于 NVIDIA GPU。在 XPU 上，使用它代替triton-xpu可能会导致正确性或运行时问题。- 对于 torch 2.10（
requirements/xpu.txt中使用的版本），匹配的软件包是triton-xpu==3.6.0。如果您使用不同版本的 torch，请在 docker/Dockerfile.xpu 中检查相应的triton-xpu版本。
-
最后，构建并安装 vLLM XPU 后端：
使用 Docker 进行设置¶
预构建的镜像¶
vLLM 提供了一个用于部署的官方 Docker 镜像。该镜像可用于运行 OpenAI 兼容服务器，可在 Docker Hub 上找到，地址为 vllm/vllm-openai。
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
此镜像也可用于其他容器引擎，例如 Podman。
podman run --device nvidia.com/gpu=all \
-v ~/.cache/huggingface:/root/.cache/huggingface \
--env "HF_TOKEN=$HF_TOKEN" \
-p 8000:8000 \
--ipc=host \
docker.io/vllm/vllm-openai:latest \
--model Qwen/Qwen3-0.6B
您可以在镜像标签（vllm/vllm-openai:latest）后添加任何其他 engine-args。
注意
您可以使用 ipc=host 标志或 --shm-size 标志允许容器访问主机的共享内存。vLLM 使用 PyTorch，它在底层使用共享内存来在进程之间共享数据，特别是对于张量并行推理。
注意
可选依赖项未包含在内，以避免许可问题（例如 Issue #8030）。
如果您需要使用这些依赖项（已接受许可条款），请在基础镜像之上创建一个自定义 Dockerfile，其中包含一个安装它们的额外层
提示
一些新模型可能仅在 HF Transformers 的 main 分支上可用。
要使用开发版本的 transformers，请在基础镜像之上创建一个自定义 Dockerfile，其中包含一个额外层，用于从源代码安装其代码
在具有较旧 CUDA 驱动的系统上运行¶
vLLM 的 Docker 镜像预装了 CUDA 兼容性库。这允许您在 NVIDIA 驱动版本低于镜像中所用 CUDA Toolkit 版本的系统上运行 vLLM，但仅支持选定的专业和数据中心 NVIDIA GPU。
要启用此功能，请在运行容器时将 VLLM_ENABLE_CUDA_COMPATIBILITY 环境变量设置为 1 或 true。
docker run --runtime nvidia --gpus all \
-v ~/.cache/huggingface:/root/.cache/huggingface \
-p 8000:8000 \
--env "HF_TOKEN=<secret>" \
--env "VLLM_ENABLE_CUDA_COMPATIBILITY=1" \
vllm/vllm-openai <args...>
这将自动配置 LD_LIBRARY_PATH，以便在加载 PyTorch 和其它依赖项之前指向兼容性库。
vLLM 提供官方 Docker 镜像用于部署。这些镜像可用于运行 OpenAI 兼容服务器，并在 Docker Hub 上提供，地址为 vllm/vllm-openai-rocm。
vllm/vllm-openai-rocm:latest— 稳定发布版vllm/vllm-openai-rocm:nightly— 来自最新开发分支的预览版，如果您想要最新的功能和修复，请使用此版本。
docker run --rm \
--group-add=video \
--cap-add=SYS_PTRACE \
--security-opt seccomp=unconfined \
--device /dev/kfd \
--device /dev/dri \
-v ~/.cache/huggingface:/root/.cache/huggingface \
--env "HF_TOKEN=$HF_TOKEN" \
-p 8000:8000 \
--ipc=host \
vllm/vllm-openai-rocm:<tag> \
--model Qwen/Qwen3-0.6B
要将 docker 镜像用作开发基础，可以通过覆盖入口点以交互会话方式启动它。
命令
docker run --rm -it \
--group-add=video \
--cap-add=SYS_PTRACE \
--security-opt seccomp=unconfined \
--device /dev/kfd \
--device /dev/dri \
-v ~/.cache/huggingface:/root/.cache/huggingface \
--env "HF_TOKEN=$HF_TOKEN" \
--network=host \
--ipc=host \
--entrypoint /bin/bash \
vllm/vllm-openai-rocm:<tag>
使用 AMD 的 Docker 镜像 (已弃用)¶
已弃用
AMD 的 Docker 镜像 (rocm/vllm 和 rocm/vllm-dev) 已被弃用，转而使用上述官方 vLLM Docker 镜像 (vllm/vllm-openai-rocm)。请迁移到官方镜像。
在 2026 年 1 月 20 日官方 docker 镜像在 上游 vLLM docker hub 可用之前，vLLM AMD Infinity Hub 提供了一个预构建、经过优化的 docker 镜像，旨在验证 AMD Instinct MI300X™ 加速器上的推理性能。AMD 还从 Docker Hub 提供每日构建的预安装 docker 镜像，其中安装了 vLLM 及其所有依赖项。该 docker 镜像的入口点是 /bin/bash（与 vLLM 官方 Docker 镜像不同）。
提示
请查看 AMD Instinct MI300X 上的 LLM 推理性能验证以获取如何使用此预构建 docker 镜像的说明。
从源代码构建镜像¶
您可以通过提供的 docker/Dockerfile 从源代码构建和运行 vLLM。要构建 vLLM
# optionally specifies: --build-arg max_jobs=8 --build-arg nvcc_threads=2
DOCKER_BUILDKIT=1 docker build . \
--target vllm-openai \
--tag vllm/vllm-openai \
--file docker/Dockerfile
注意
默认情况下，vLLM 将为所有 GPU 类型构建，以实现最广泛的分发。如果您只为机器当前运行的 GPU 类型构建，可以添加参数 --build-arg torch_cuda_arch_list=""，以便 vLLM 找到当前的 GPU 类型并为此构建。
如果您使用的是 Podman 而不是 Docker，则在运行 podman build 命令时可能需要禁用 SELinux 标签，方法是添加 --security-opt label=disable，以避免某些现有问题。
注意
如果您没有更改任何 C++ 或 CUDA 内核代码，可以使用预编译的 wheel 显着减少 Docker 构建时间。
- **启用功能**，添加构建参数：
--build-arg VLLM_USE_PRECOMPILED="1"。 - **工作原理**：默认情况下，vLLM 通过使用与上游
main分支的合并基础提交，自动从我们的Nightly Builds中查找正确的 wheel。 - **覆盖提交**：要使用来自特定提交的 wheel，请提供
--build-arg VLLM_PRECOMPILED_WHEEL_COMMIT=<commit_hash>参数。
有关详细解释，请参阅从源代码构建 wheel中关于“使用仅 Python 构建（无需编译）进行设置”部分的文档，这些参数是相似的。
为 Arm64/aarch64 从源代码构建 vLLM 的 Docker 镜像¶
可以为 aarch64 系统（如 Nvidia Grace-Hopper 和 Grace-Blackwell）构建一个 docker 容器。使用标志 --platform "linux/arm64" 将为 arm64 构建。
注意
必须编译多个模块，因此此过程可能需要一段时间。建议使用 --build-arg max_jobs= & --build-arg nvcc_threads= 标志来加速构建过程。但是，请确保您的 max_jobs 大于 nvcc_threads 以获得最大的好处。请留意并行作业的内存使用情况，因为它可能很大（参见下面的示例）。
命令
# Example of building on Nvidia GH200 server. (Memory usage: ~15GB, Build time: ~1475s / ~25 min, Image size: 6.93GB)
DOCKER_BUILDKIT=1 docker build . \
--file docker/Dockerfile \
--target vllm-openai \
--platform "linux/arm64" \
-t vllm/vllm-gh200-openai:latest \
--build-arg max_jobs=66 \
--build-arg nvcc_threads=2 \
--build-arg torch_cuda_arch_list="9.0 10.0+PTX" \
--build-arg RUN_WHEEL_CHECK=false
对于 (G)B300，我们建议使用 CUDA 13，如下命令所示。
命令
DOCKER_BUILDKIT=1 docker build \
--build-arg CUDA_VERSION=13.0.1 \
--build-arg BUILD_BASE_IMAGE=nvidia/cuda:13.0.1-devel-ubuntu22.04 \
--build-arg max_jobs=256 \
--build-arg nvcc_threads=2 \
--build-arg RUN_WHEEL_CHECK=false \
--build-arg torch_cuda_arch_list='9.0 10.0+PTX' \
--platform "linux/arm64" \
--tag vllm/vllm-gb300-openai:latest \
--target vllm-openai \
-f docker/Dockerfile \
.
注意
如果您在非 ARM 主机（例如 x86_64 机器）上构建 linux/arm64 镜像，则需要确保您的系统已使用 QEMU 设置为交叉编译。这允许您的主机模拟 ARM64 执行。
在您的主机上运行以下命令以注册 QEMU 用户静态处理程序
设置完 QEMU 后，您可以在 docker build 命令中使用 --platform "linux/arm64" 标志。
使用自定义构建的 vLLM Docker 镜像**¶
要使用自定义构建的 Docker 镜像运行 vLLM
docker run --runtime nvidia --gpus all \
-v ~/.cache/huggingface:/root/.cache/huggingface \
-p 8000:8000 \
--env "HF_TOKEN=<secret>" \
vllm/vllm-openai <args...>
参数 vllm/vllm-openai 指定要运行的镜像，应替换为自定义构建的镜像名称（构建命令中的 -t 标签）。
注意
仅适用于 0.4.1 和 0.4.2 版本 - 这些版本的 vLLM docker 镜像应在 root 用户下运行，因为需要在运行时加载位于 root 用户主目录下的库，即 /root/.config/vllm/nccl/cu12/libnccl.so.2.18.1。如果您在不同的用户下运行容器，您可能需要先更改该库（以及所有父目录）的权限以允许用户访问它，然后使用环境变量 VLLM_NCCL_SO_PATH=/root/.config/vllm/nccl/cu12/libnccl.so.2.18.1 运行 vLLM。
您可以通过提供的 docker/Dockerfile.rocm 从源代码构建和运行 vLLM。
(可选) 构建一个带有 ROCm 软件栈的镜像
从 docker/Dockerfile.rocm_base 构建一个 docker 镜像，该镜像设置了 vLLM 所需的 ROCm 软件栈。**此步骤是可选的，因为此 rocm_base 镜像通常是预构建的并存储在 Docker Hub 上，标签为 rocm/vllm-dev:base，以加快用户体验。**如果您选择自己构建此 rocm_base 镜像，步骤如下。
用户使用 buildkit 启动 docker 构建非常重要。用户要么在调用 docker build 命令时将 DOCKER_BUILDKIT=1 作为环境变量，要么需要在 docker 守护进程配置 /etc/docker/daemon.json 中按如下方式设置 buildkit 并重新启动守护进程
要在 MI200 和 MI300 系列上使用 ROCm 7.0 构建 vllm，您可以使用默认设置
首先，从 docker/Dockerfile.rocm 构建一个 docker 镜像并从该镜像启动一个 docker 容器。用户使用 buildkit 启动 docker 构建非常重要。用户要么在调用 docker build 命令时将 DOCKER_BUILDKIT=1 作为环境变量，要么需要在 docker 守护进程配置 /etc/docker/daemon.json 中按如下方式设置 buildkit 并重新启动守护进程
docker/Dockerfile.rocm 默认使用 ROCm 7.0，但也支持旧版 vLLM 分支中的 ROCm 5.7、6.0、6.1、6.2、6.3 和 6.4。它提供了使用以下参数自定义构建 docker 镜像的灵活性
BASE_IMAGE：指定运行docker build时使用的基础镜像。默认值rocm/vllm-dev:base是 AMD 发布和维护的镜像。它使用 docker/Dockerfile.rocm_base 构建ARG_PYTORCH_ROCM_ARCH：允许覆盖基础 docker 镜像中的 gfx 架构值
在运行 docker build 时，可以通过 --build-arg 选项传递它们的值。
要在 MI200 和 MI300 系列上使用 ROCm 7.0 构建 vllm，您可以使用默认设置（该设置构建一个以 vllm serve 为入口点的 docker 镜像）
要使用自定义构建的 Docker 镜像运行 vLLM
docker run --rm \
--group-add=video \
--cap-add=SYS_PTRACE \
--security-opt seccomp=unconfined \
--device /dev/kfd \
--device /dev/dri \
-v ~/.cache/huggingface:/root/.cache/huggingface \
--env "HF_TOKEN=$HF_TOKEN" \
-p 8000:8000 \
--ipc=host \
vllm/vllm-openai-rocm <args...>
参数 vllm/vllm-openai-rocm 指定要运行的镜像，应替换为自定义构建的镜像名称（构建命令中的 -t 标签）。
要将 docker 镜像用作开发基础，可以通过覆盖入口点以交互会话方式启动它。
支持的特性¶
请参阅 特性 x 硬件兼容性矩阵以获取特性支持信息。
请参阅 特性 x 硬件兼容性矩阵以获取特性支持信息。
XPU 平台支持张量并行推理/服务，并作为在线服务的 Beta 功能支持流水线并行。对于流水线并行，我们支持在以 mp 为后端的单节点上运行。例如，如下参考执行所示：
vllm serve facebook/opt-13b \
--dtype=bfloat16 \
--max_model_len=1024 \
--distributed-executor-backend=mp \
--pipeline-parallel-size=2 \
-tp=8
默认情况下，如果系统中未检测到现有的 ray 实例，则会自动启动一个，其 num-gpus 等于 parallel_config.world_size。我们建议在执行前正确启动 ray 集群，请参考 examples/online_serving/run_cluster.sh 辅助脚本。