GPU¶
vLLM 是一个 Python 库，支持以下 GPU 类型。选择您的 GPU 类型以查看特定于供应商的说明
vLLM 包含预编译的 C++ 和 CUDA (12.8) 二进制文件。
vLLM 支持 ROCm 6.3 或更高版本以及 torch 2.8.0 或更高版本的 AMD GPU。
提示
Docker 是在 ROCm 上使用 vLLM 的推荐方式。
vLLM 最初支持在 Intel GPU 平台上进行基本的模型推理和服务。
要求¶
- 操作系统：Linux
- Python: 3.10 -- 3.13
注意
vLLM 不原生支持 Windows。要在 Windows 上运行 vLLM，您可以使用带有兼容 Linux 发行版的 Windows Subsystem for Linux (WSL)，或者使用一些社区维护的 fork，例如 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
- OneAPI 要求：oneAPI 2025.1
- Python：3.12
警告
提供的 IPEX whl 是 Python3.12 特定的，因此此版本是必需的。
使用 Python 进行设置¶
创建新的 Python 环境¶
建议使用 uv，一个非常快速的 Python 环境管理器，来创建和管理 Python 环境。请按照 文档 安装 uv。安装 uv 后，您可以使用以下命令创建新的 Python 环境。
注意
通过 conda 安装的 PyTorch 会静态链接 NCCL 库，这可能导致 vLLM 尝试使用 NCCL 时出现问题。有关更多详细信息，请参阅 https://github.com/vllm-project/vllm/issues/8420。
为了获得高性能，vLLM 需要编译许多 CUDA 核函数。编译过程不幸地引入了与其他 CUDA 版本和 PyTorch 版本之间的二进制不兼容性，即使是相同 PyTorch 版本但具有不同构建配置的情况也是如此。
因此，建议使用**全新**的环境安装 vLLM。如果您有不同的 CUDA 版本或想使用现有的 PyTorch 安装，则需要从源代码构建 vLLM。有关更多详细信息，请参阅下方。
此设备没有关于创建新 Python 环境的额外信息。
此设备没有关于创建新 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 wheel 版本至少为此版本。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
uv pip install https://github.com/vllm-project/vllm/releases/download/v${VLLM_VERSION}/vllm-${VLLM_VERSION}+cu${CUDA_VERSION}-cp38-abi3-manylinux_2_31_x86_64.whl --extra-index-url https://download.pytorch.org/whl/cu${CUDA_VERSION}
安装最新代码¶
LLM 推理是一个快速发展的领域，最新代码可能包含尚未发布的错误修复、性能改进和新功能。为了让用户无需等待下一个版本即可尝试最新代码，vLLM 在 https://wheels.vllm.ai/nightly 上为自 v0.5.3 以来的每个 commit 提供 wheel。可以使用多个索引。
https://wheels.vllm.ai/nightly：默认变体（在VLLM_MAIN_CUDA_VERSION中指定的 CUDA 版本）使用main分支上的最新 commit 构建。当前是 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，则必须指定 wheel 文件的完整 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 中指定提交哈希。
目前，没有预编译的 ROCm wheel。
目前，没有预编译的 XPU wheel。
从源代码构建 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 克隆中的当前分支。
- 识别主分支中相应的基线 commit。
- 下载基线 commit 的预编译 wheel。
- 在安装中使用其编译的库。
注意
- 如果您更改 C++ 或内核代码，则不能使用仅 Python 的构建；否则，您将看到有关“找不到库”或“未定义符号”的导入错误。
- 如果您 rebase 了您的开发分支，建议卸载 vllm 并重新运行上述命令以确保您的库是最新的。
如果您在运行上述命令时看到有关“找不到 wheel”的错误，可能是因为您基于的主分支上的 commit 刚刚合并，并且 wheel 正在构建中。在这种情况下，您可以等待大约一个小时后重试，或者使用 VLLM_PRECOMPILED_WHEEL_LOCATION 环境变量手动在安装中指定前一个 commit。
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：指定要使用的预编译 wheel 的确切 wheel URL 或本地文件路径。将跳过所有其他查找 wheel 的逻辑。VLLM_PRECOMPILED_WHEEL_COMMIT：覆盖用于下载预编译 wheel 的 commit 哈希。它可以是nightly以使用主分支上最后一个**已构建**的 commit。VLLM_PRECOMPILED_WHEEL_VARIANT：指定 nightly 索引上要使用的变体子目录，例如cu129、cpu。如果未指定，将尝试使用VLLM_MAIN_CUDA_VERSION的 CUDA 变体，然后回退到远程索引上的默认变体。
您可以在 安装最新代码 中找到有关 vLLM wheel 的更多信息。
注意
您的源代码可能与最新的 vLLM wheel 具有不同的 commit ID，这可能会导致未知错误。建议将源代码的 commit ID 与您安装的 vLLM wheel 的 commit ID 保持一致。请参阅 安装最新代码 以获取安装指定 wheel 的说明。
完整构建（需要编译）¶
如果您想修改 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 wheel 安装 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 以使用特定的分支或 commit，可以按以下步骤构建 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 中找到。
- 您需要根据您的需求配置
-
构建 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 分钟。目前，
pip install .对于 ROCm 安装无效。提示
- PyTorch 的 ROCm 版本最好与 ROCm 驱动程序版本相匹配。
提示
- 对于 MI300x (gfx942) 用户，为了获得最佳性能，请参阅MI300x 调优指南，了解系统和工作流级别的性能优化和调优技巧。对于 vLLM，请参阅vLLM 性能优化。
- 首先，安装所需的驱动程序和Intel OneAPI 2025.1 或更高版本。
- 其次，安装用于 vLLM XPU 后端构建的 Python 包。
git clone https://github.com/vllm-project/vllm.git
cd vllm
pip install --upgrade pip
pip install -v -r requirements/xpu.txt
- 然后，构建并安装 vLLM XPU 后端。
使用 Docker 进行设置¶
预构建的镜像¶
有关使用官方 Docker 镜像的说明，请参阅 使用 Docker。
访问最新代码的另一种方法是使用 docker 镜像。
export VLLM_COMMIT=33f460b17a54acb3b6cc0b03f4a17876cff5eafd # use full commit hash from the main branch
docker pull public.ecr.aws/q9t5s3a7/vllm-ci-postmerge-repo:${VLLM_COMMIT}
这些 docker 镜像仅用于 CI 和测试，不用于生产环境。它们将在几天后过期。
最新代码可能包含 bug 且可能不稳定。请谨慎使用。
vLLM 的AMD Infinity Hub 提供了一个预构建的、优化的 docker 镜像，用于在 AMD Instinct™ MI300X 加速器上验证推理性能。AMD 还提供来自Docker Hub 的 nightly 预构建 docker 镜像，其中安装了 vLLM 及其所有依赖项。
命令
docker pull rocm/vllm-dev:nightly # to get the latest image
docker run -it --rm \
--network=host \
--group-add=video \
--ipc=host \
--cap-add=SYS_PTRACE \
--security-opt seccomp=unconfined \
--device /dev/kfd \
--device /dev/dri \
-v <path/to/your/models>:/app/models \
-e HF_HOME="/app/models" \
rocm/vllm-dev:nightly
提示
请参阅在 AMD Instinct MI300X 上进行 LLM 推理性能验证，了解如何使用此预构建 docker 镜像的说明。
从源代码构建镜像¶
有关构建 vLLM Docker 镜像的说明，请参阅从源代码构建 vLLM 的 Docker 镜像。
从源代码构建 Docker 镜像是在 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 中进行如下设置并重启守护进程。
要为 MI200 和 MI300 系列在 ROCm 7.0 上构建 vllm，您可以使用默认设置。
构建包含 vLLM 的镜像¶
首先，从 docker/Dockerfile.rocm 构建一个 docker 镜像，并从该镜像启动一个 docker 容器。用户使用 buildkit 启动 docker 构建非常重要。用户可以在调用 docker build 命令时将 DOCKER_BUILDKIT=1 设置为环境变量，或者用户需要在 docker 守护进程配置 /etc/docker/daemon.json 中进行如下设置并重启守护进程。
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，您可以使用默认设置。
要运行上述 docker 镜像 vllm-rocm，请使用以下命令。
命令
其中 <path/to/model> 是模型存储的位置，例如 llama2 或 llama3 模型的权重。
支持的功能¶
有关功能支持信息，请参阅功能 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 实例，将自动启动一个 ray 实例，其 num-gpus 等于 parallel_config.world_size。我们建议在执行前正确启动 ray 集群，请参考examples/online_serving/run_cluster.sh 辅助脚本。