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 初步支持在 Intel GPU 平台上进行基本的模型推理和服务。
要求¶
- 操作系统：Linux
- Python: 3.10 -- 3.13
注意
vLLM 不原生支持 Windows。若要在 Windows 上运行 vLLM，可以使用带有兼容 Linux 发行版的 Windows Linux 子系统 (WSL)，或使用社区维护的分支，例如 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 或更高版本
- 支持的硬件：Intel 数据中心 GPU, Intel ARC GPU
- 依赖项：vllm-xpu-kernels：一个在 Intel 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，通过检查已安装的 CUDA 驱动程序版本，使用 --torch-backend=auto（或 UV_TORCH_BACKEND=auto）来在运行时自动选择合适的 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。
提示
您可以通过在 extra-index-url https://wheels.vllm.ai/rocm/ 的索引下查看 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 克隆版本中查找当前分支。
- 识别主分支中对应的基础提交。
- 下载基础提交的预构建安装包。
- 在安装中使用其编译的库。
注意
- 如果您更改了 C++ 或内核代码，则不能使用仅 Python 的构建方式；否则您会看到关于找不到库或未定义符号的导入错误。
- 如果您重新基准化 (rebase) 了开发分支，建议卸载 vllm 并重新运行上述命令，以确保您的库是最新的。
如果您在运行上述命令时看到关于找不到安装包的错误，可能是因为您基于的主分支提交刚刚合并，安装包正在构建中。在这种情况下，您可以等待大约一小时后再试，或者使用 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，以使用主分支上最后已构建的提交。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 二进制文件，构建系统就会自动使用它。在第一次构建之后，后续构建的速度会快得多。
当将 ccache 与 pip install -e . 一起使用时，您应该运行 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，假设您的 gfx 架构是
gfx942。要获取您的 gfx 架构，请运行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-xpupip 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 镜像用作开发基础，可以通过覆盖入口点以交互会话方式启动它。
支持的特性¶
有关特性支持信息，请参阅 Feature x Hardware 兼容性矩阵。
有关特性支持信息，请参阅 Feature x Hardware 兼容性矩阵。
XPU 平台支持张量并行 (tensor parallel) 推理/服务，也支持流水线并行 (pipeline parallel) 作为在线服务的 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 辅助脚本。