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 (WSL) 和兼容的 Linux 发行版，或者使用一些社区维护的 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 通过检查已安装的 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 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 为 v0.5.3 以来的每个提交提供了 wheel 包，位于 https://wheels.vllm.ai/nightly。可以使用多个索引。
https://wheels.vllm.ai/nightly：默认变体（在VLLM_MAIN_CUDA_VERSION中指定的 CUDA 版本）使用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，则必须指定 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 克隆中的当前分支。
- 识别主分支中对应的基线提交。
- 下载基线提交的预构建 wheel。
- 在安装中使用其编译的库。
注意
- 如果您更改 C++ 或内核代码，则不能使用纯 Python 构建；否则，您将看到关于库未找到或符号未定义的导入错误。
- 如果您 rebase 了您的开发分支，建议卸载 vllm 并重新运行上述命令以确保您的库是最新的。
如果您在运行上述命令时遇到 wheel 未找到的错误，可能是因为您基于的主分支上的提交刚刚合并，并且 wheel 正在构建中。在这种情况下，您可以等待大约一个小时再试，或者使用 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：指定要使用的预编译 wheel 的确切 wheel URL 或本地文件路径。所有其他查找 wheel 的逻辑将被跳过。VLLM_PRECOMPILED_WHEEL_COMMIT：覆盖要下载预编译 wheel 的提交哈希。它可以是nightly以使用主分支上最后一个 **已构建** 的提交。VLLM_PRECOMPILED_WHEEL_VARIANT：指定 nightly 索引上要使用的变体子目录，例如cu129、cpu。如果未指定，将尝试使用VLLM_MAIN_CUDA_VERSION的 CUDA 变体，然后回退到远程索引上的默认变体。
您可以在 安装最新代码 中找到有关 vLLM wheel 的更多信息。
注意
您的源代码可能与最新的 vLLM wheel 具有不同的提交 ID，这可能会导致未知错误。建议使用与您安装的 vLLM wheel 相同的提交 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 wheels 安装 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 中找到。
- 您需要根据您的需求配置
-
构建 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 安装。提示
- ROCm 版的 PyTorch 理想情况下应与 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 且可能不稳定。请谨慎使用。
AMD Infinity hub for vLLM 提供了一个预构建的、优化的 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 镜像的说明。
从源代码构建镜像¶
有关从源代码构建 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 设置为环境变量，或者用户需要将 buildkit 配置在 docker 守护进程的 /etc/docker/daemon.json 中，如下所示，然后重新启动守护进程。
要为 MI200 和 MI300 系列在 ROCm 7.0 上构建 vllm，您可以使用默认设置。
构建带 vLLM 的镜像¶
首先，从 docker/Dockerfile.rocm 构建一个 docker 镜像并从该镜像启动一个 docker 容器。用户使用 buildkit 启动 docker 构建非常重要。用户可以在调用 docker build 命令时将 DOCKER_BUILDKIT=1 设置为环境变量，或者用户需要将 buildkit 配置在 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 辅助脚本。