GPU

GPU#

vLLM 是一个 Python 库，支持以下 GPU 变体。选择您的 GPU 类型以查看供应商特定的说明

NVIDIA CUDA

vLLM 包含预编译的 C++ 和 CUDA (12.1) 二进制文件。

AMD ROCm

vLLM 支持使用 ROCm 6.3 的 AMD GPU。

Attention

此设备没有预构建的 wheels，因此您必须使用预构建的 Docker 镜像或从源码构建 vLLM。

Intel XPU

vLLM 最初支持在 Intel GPU 平台上进行基本模型推理和服务。

Attention

此设备没有预构建的 wheels 或镜像，因此您必须从源码构建 vLLM。

要求#

操作系统：Linux
Python: 3.9 – 3.12

NVIDIA CUDA

GPU: 计算能力 7.0 或更高版本（例如，V100、T4、RTX20xx、A100、L4、H100 等）

AMD ROCm

GPU: MI200s (gfx90a), MI300 (gfx942), Radeon RX 7900 系列 (gfx1100)
ROCm 6.3

Intel XPU

支持的硬件：Intel 数据中心 GPU，Intel ARC GPU
OneAPI 要求：oneAPI 2024.2

使用 Python 设置#

创建新的 Python 环境#

您可以使用 conda 创建新的 Python 环境

# (Recommended) Create a new conda environment.
conda create -n vllm python=3.12 -y
conda activate vllm

注意

PyTorch 已经弃用了 conda 发布通道。如果您使用 conda，请仅使用它来创建 Python 环境，而不是安装包。

或者您可以使用 uv 创建新的 Python 环境，这是一个非常快速的 Python 环境管理器。请按照文档安装 uv。安装 uv 后，您可以使用以下命令创建新的 Python 环境

# (Recommended) Create a new uv environment. Use `--seed` to install `pip` and `setuptools` in the environment.
uv venv vllm --python 3.12 --seed
source vllm/bin/activate

NVIDIA CUDA

注意

通过 conda 安装的 PyTorch 将静态链接 NCCL 库，当 vLLM 尝试使用 NCCL 时，可能会导致问题。有关更多详细信息，请参阅 Issue #8420。

为了保证性能，vLLM 必须编译许多 CUDA 内核。不幸的是，即使对于具有不同构建配置的相同 PyTorch 版本，编译也会引入与其他 CUDA 版本和 PyTorch 版本的二进制不兼容性。

因此，建议使用全新的环境安装 vLLM。如果您有不同的 CUDA 版本，或者您想使用现有的 PyTorch 安装，则需要从源码构建 vLLM。有关更多详细信息，请参阅下面的构建源码。

AMD ROCm

没有关于为此设备创建新的 Python 环境的额外信息。

Intel XPU

没有关于为此设备创建新的 Python 环境的额外信息。

预构建 wheels#

NVIDIA CUDA

您可以使用 pip 或 uv pip 安装 vLLM

# Install vLLM with CUDA 12.1.
pip install vllm # If you are using pip.
uv pip install vllm # If you are using uv.

目前，默认情况下，vLLM 的二进制文件是使用 CUDA 12.1 和公共 PyTorch 发布版本编译的。我们还提供使用 CUDA 11.8 和公共 PyTorch 发布版本编译的 vLLM 二进制文件

# Install vLLM with CUDA 11.8.
export VLLM_VERSION=0.6.1.post1
export PYTHON_VERSION=310
pip install https://github.com/vllm-project/vllm/releases/download/v${VLLM_VERSION}/vllm-${VLLM_VERSION}+cu118-cp${PYTHON_VERSION}-cp${PYTHON_VERSION}-manylinux1_x86_64.whl --extra-index-url https://download.pytorch.org/whl/cu118

安装最新代码

LLM 推理是一个快速发展的领域，最新的代码可能包含尚未发布的错误修复、性能改进和新功能。为了让用户在无需等待下一次发布的情况下尝试最新代码，vLLM 为自 v0.5.3 以来的每个提交提供了在运行 Linux 的 x86 平台上使用 CUDA 12 的 wheels。

使用 `pip` 安装最新代码

pip install vllm --pre --extra-index-url https://wheels.vllm.ai/nightly

--pre 是 pip 考虑预发布版本所必需的。

如果您想访问以前提交的 wheels（例如，为了剖析行为更改、性能回归），由于 pip 的限制，您必须通过在 URL 中嵌入提交哈希来指定 wheel 文件的完整 URL

export VLLM_COMMIT=33f460b17a54acb3b6cc0b03f4a17876cff5eafd # use full commit hash from the main branch
pip install https://wheels.vllm.ai/${VLLM_COMMIT}/vllm-1.0.0.dev-cp38-abi3-manylinux1_x86_64.whl

请注意，wheels 是使用 Python 3.8 ABI 构建的（有关 ABI 的更多详细信息，请参阅 PEP 425），因此它们与 Python 3.8 及更高版本兼容。wheel 文件名中的版本字符串 (1.0.0.dev) 只是一个占位符，用于为 wheels 提供统一的 URL，wheels 的实际版本包含在 wheel 元数据中（额外索引 URL 中列出的 wheels 具有正确的版本）。尽管我们不再支持 Python 3.8（因为 PyTorch 2.5 放弃了对 Python 3.8 的支持），但 wheels 仍然使用 Python 3.8 ABI 构建，以保持与以前相同的 wheel 名称。

使用 `uv` 安装最新代码

安装最新代码的另一种方法是使用 uv

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

如果您想访问以前提交的 wheels（例如，为了剖析行为更改、性能回归），您可以在 URL 中指定提交哈希

export VLLM_COMMIT=72d9c316d3f6ede485146fe5aabd4e61dbc59069 # use full commit hash from the main branch
uv pip install vllm --extra-index-url https://wheels.vllm.ai/${VLLM_COMMIT}

uv 方法适用于 vLLM v0.6.6 及更高版本，并提供易于记忆的命令。uv 的一个独特功能是 --extra-index-url 中的包具有比默认索引更高的优先级。如果最新的公共版本是 v0.6.6.post1，uv 的行为允许通过指定 --extra-index-url 来安装 v0.6.6.post1 之前的提交。相比之下，pip 组合来自 --extra-index-url 和默认索引的包，仅选择最新版本，这使得安装早于发布版本的开发版本变得困难。

AMD ROCm

目前，没有预构建的 ROCm wheels。

Intel XPU

目前，没有预构建的 XPU wheels。

从源码构建 wheel#

NVIDIA CUDA

使用仅 Python 构建（不编译）进行设置

如果您只需要更改 Python 代码，则可以构建并安装 vLLM 而无需编译。使用 pip 的 --editable 标志，您对代码所做的更改将在您运行 vLLM 时反映出来

git clone https://github.com/vllm-project/vllm.git
cd vllm
VLLM_USE_PRECOMPILED=1 pip install --editable .

此命令将执行以下操作

在您的 vLLM 克隆中查找当前分支。
识别主分支中对应的基本提交。
下载基本提交的预构建 wheel。
在安装中使用其编译的库。

注意

如果您更改 C++ 或内核代码，则不能使用仅 Python 构建；否则，您将看到关于找不到库或未定义符号的导入错误。
如果您变基了您的开发分支，建议卸载 vllm 并重新运行上述命令，以确保您的库是最新的。

如果您在运行上述命令时看到关于找不到 wheel 的错误，则可能是因为您在主分支中基于的提交刚刚合并，并且 wheel 正在构建中。在这种情况下，您可以等待大约一个小时再试一次，或者使用 VLLM_PRECOMPILED_WHEEL_LOCATION 环境变量手动分配安装中的先前提交。

export VLLM_COMMIT=72d9c316d3f6ede485146fe5aabd4e61dbc59069 # use full commit hash from the main branch
export VLLM_PRECOMPILED_WHEEL_LOCATION=https://wheels.vllm.ai/${VLLM_COMMIT}/vllm-1.0.0.dev-cp38-abi3-manylinux1_x86_64.whl
pip install --editable .

您可以在安装最新代码中找到有关 vLLM 的 wheels 的更多信息。

注意

您的源代码可能具有与最新的 vLLM wheel 不同的提交 ID，这可能会导致未知的错误。建议为源代码使用与您已安装的 vLLM wheel 相同的提交 ID。请参阅安装最新代码，了解如何安装指定的 wheel 的说明。

完整构建（带编译）

如果您想修改 C++ 或 CUDA 代码，您需要从源码构建 vLLM。这可能需要几分钟

git clone https://github.com/vllm-project/vllm.git
cd vllm
pip install -e .

提示

从源码构建需要大量编译。如果您要重复从源码构建，则缓存编译结果会更有效。

例如，您可以使用 conda install ccache 或 apt install ccache 安装 ccache 。只要 which ccache 命令可以找到 ccache 二进制文件，它就会被构建系统自动使用。首次构建后，后续构建将快得多。

sccache 的工作方式与 ccache 类似，但具有在远程存储环境中利用缓存的功能。可以设置以下环境变量来配置 vLLM sccache 远程：SCCACHE_BUCKET=vllm-build-sccache SCCACHE_REGION=us-west-2 SCCACHE_S3_NO_CREDENTIALS=1。我们还建议设置 SCCACHE_IDLE_TIMEOUT=0。

使用现有的 PyTorch 安装

在某些情况下，PyTorch 依赖项无法通过 pip 轻松安装，例如

使用 PyTorch nightly 或自定义 PyTorch 构建构建 vLLM。
使用 aarch64 和 CUDA (GH200) 构建 vLLM，其中 PyTorch wheels 在 PyPI 上不可用。目前，只有 PyTorch nightly 具有用于 aarch64 和 CUDA 的 wheels。您可以运行 pip3 install --pre torch torchvision torchaudio --index-url https://download.pytorch.org/whl/nightly/cu124 来安装 PyTorch nightly，然后在它之上构建 vLLM。

要使用现有的 PyTorch 安装构建 vLLM

git clone https://github.com/vllm-project/vllm.git
cd vllm
python use_existing_torch.py
pip install -r requirements-build.txt
pip install -e . --no-build-isolation

使用本地 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 pip install -e .

故障排除

为了避免您的系统过载，您可以通过环境变量 MAX_JOBS 限制同时运行的编译作业数。例如

export MAX_JOBS=6
pip install -e .

当您在功能较弱的机器上构建时，这尤其有用。例如，当您使用 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 中，例如

export CUDA_HOME=/usr/local/cuda
export PATH="${CUDA_HOME}/bin:$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 环境变量

export VLLM_TARGET_DEVICE=empty
pip install -e .

AMD ROCm

安装先决条件（如果您已在安装了以下内容的环境/docker 中，请跳过）

ROCm
PyTorch

对于安装 PyTorch，您可以从全新的 docker 镜像开始，例如 rocm/pytorch:rocm6.3_ubuntu24.04_py3.12_pytorch_release_2.4.0, rocm/pytorch-nightly。如果您正在使用 docker 镜像，您可以跳到步骤 3。

或者，您可以使用 PyTorch wheels 安装 PyTorch。您可以在 PyTorch 入门中查看 PyTorch 安装指南。示例
```
# Install PyTorch
$ pip uninstall torch -y
$ pip install --no-cache-dir --pre torch --index-url https://download.pytorch.org/whl/rocm6.3
```

安装 ROCm 的 Triton flash attention

按照 ROCm/triton 中的说明安装 ROCm 的 Triton flash attention（默认 triton-mlir 分支）
```
python3 -m pip install ninja cmake wheel pybind11
pip uninstall -y triton
git clone https://github.com/OpenAI/triton.git
cd triton
git checkout e5be006
cd python
pip3 install .
cd ../..
```
注意

如果您在构建 triton 期间看到与下载软件包相关的 HTTP 问题，请重试，因为 HTTP 错误是间歇性的。
或者，如果您选择使用 CK flash attention，您可以安装 ROCm 的 flash attention

按照 ROCm/flash-attention 中的说明安装 ROCm 的 flash attention (v2.7.2)。或者，用于 vLLM 的 wheels 可以在版本下访问。

例如，对于 ROCm 6.3，假设您的 gfx 架构是 gfx90a。要获取您的 gfx 架构，请运行 rocminfo |grep gfx。
```
git clone https://github.com/ROCm/flash-attention.git
cd flash-attention
git checkout b7d29fb
git submodule update --init
GPU_ARCHS="gfx90a" python3 setup.py install
cd ..
```
注意

您可能需要将 “ninja” 版本降级到 1.10，它在编译 flash-attention-2 时不使用（例如 pip install ninja==1.10.2.4）
构建 vLLM。例如，ROCm 6.3 上的 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 "numpy<2"
$ pip install -r requirements-rocm.txt

# Build vLLM for MI210/MI250/MI300.
$ export PYTORCH_ROCM_ARCH="gfx90a;gfx942"
$ python3 setup.py develop
```
这可能需要 5-10 分钟。目前，pip install . 不适用于 ROCm 安装。
提示
- 默认情况下使用 Triton flash attention。为了进行基准测试，建议在收集性能数据之前运行预热步骤。
- Triton flash attention 目前不支持滑动窗口注意力。如果使用半精度，请使用 CK flash-attention 来获得滑动窗口支持。
- 要使用 CK flash-attention 或 PyTorch 原生注意力，请使用此标志 export VLLM_USE_TRITON_FLASH_ATTN=0 关闭 triton flash attention。
- 理想情况下，PyTorch 的 ROCm 版本应与 ROCm 驱动程序版本匹配。

提示

对于 MI300x (gfx942) 用户，为了获得最佳性能，请参阅 MI300x 调优指南，了解系统和工作流程级别的性能优化和调优技巧。对于 vLLM，请参阅 vLLM 性能优化。

Intel XPU

首先，安装所需的驱动程序和 intel OneAPI 2024.2 或更高版本。
其次，安装用于 vLLM XPU 后端构建的 Python 包

source /opt/intel/oneapi/setvars.sh
pip install --upgrade pip
pip install -v -r requirements-xpu.txt

最后，构建并安装 vLLM XPU 后端

VLLM_TARGET_DEVICE=xpu python setup.py install

注意

FP16 是当前 XPU 后端中的默认数据类型。BF16 数据类型在 Intel 数据中心 GPU 上受支持，但在 Intel Arc GPU 上尚不受支持。

使用 Docker 设置#

预构建镜像#

NVIDIA CUDA

有关使用官方 Docker 镜像的说明，请参阅使用 vLLM 的官方 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 和测试，不适用于生产用途。它们将在几天后过期。

最新代码可能包含错误，并且可能不稳定。请谨慎使用。

AMD ROCm

vLLM 的 AMD Infinity hub 提供了一个预构建的、优化的 docker 镜像，旨在验证 AMD Instinct™ MI300X 加速器上的推理性能。

提示

有关如何使用此预构建 docker 镜像的说明，请查看 AMD Instinct MI300X 上的 LLM 推理性能验证。

Intel XPU

目前，没有预构建的 XPU 镜像。

从源码构建镜像#

NVIDIA CUDA

有关构建 Docker 镜像的说明，请参阅从源码构建 vLLM 的 Docker 镜像。

AMD ROCm

从源码构建 Docker 镜像是在 ROCm 上使用 vLLM 的推荐方法。

（可选）构建带有 ROCm 软件栈的镜像

从 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，如下所示并重启守护程序

{
    "features": {
        "buildkit": true
    }
}

要在 ROCm 6.3 上为 MI200 和 MI300 系列构建 vllm，您可以使用默认设置

DOCKER_BUILDKIT=1 docker build -f Dockerfile.rocm_base -t rocm/vllm-dev:base .

构建带有 vLLM 的镜像

首先，从 Dockerfile.rocm 构建 docker 镜像，并从该镜像启动 docker 容器。重要的是，用户使用 buildkit 启动 docker 构建。用户可以在调用 docker build 命令时将 DOCKER_BUILDKIT=1 作为环境变量，或者用户需要在 docker 守护程序配置文件 /etc/docker/daemon.json 中设置 buildkit，如下所示并重启守护程序

{
    "features": {
        "buildkit": true
    }
}

Dockerfile.rocm 默认使用 ROCm 6.3，但也支持 ROCm 5.7、6.0、6.1 和 6.2（在较旧的 vLLM 分支中）。它提供了灵活性，可以使用以下参数自定义 docker 镜像的构建

BASE_IMAGE: 指定运行 docker build 时使用的基础镜像。默认值 rocm/vllm-dev:base 是 AMD 发布和维护的镜像。它是使用 Dockerfile.rocm_base 构建的
USE_CYTHON: 在 docker 构建时在 Python 文件子集上运行 cython 编译的选项
BUILD_RPD: 在镜像中包含 RocmProfileData 性能分析工具
ARG_PYTORCH_ROCM_ARCH: 允许覆盖来自基础 docker 镜像的 gfx 架构值

它们的值可以在运行 docker build 时使用 --build-arg 选项传入。

要在 ROCm 6.3 上为 MI200 和 MI300 系列构建 vllm，您可以使用默认设置

DOCKER_BUILDKIT=1 docker build -f Dockerfile.rocm -t vllm-rocm .

要在 ROCm 6.3 上为 Radeon RX7900 系列 (gfx1100) 构建 vllm，您应该选择替代的基础镜像

DOCKER_BUILDKIT=1 docker build --build-arg BASE_IMAGE="rocm/vllm-dev:navi_base" -f Dockerfile.rocm -t vllm-rocm .

要运行上述 docker 镜像 vllm-rocm，请使用以下命令

docker run -it \
   --network=host \
   --group-add=video \
   --ipc=host \
   --cap-add=SYS_PTRACE \
   --security-opt seccomp=unconfined \
   --device /dev/kfd \
   --device /dev/dri \
   -v <path/to/model>:/app/model \
   vllm-rocm \
   bash

其中 <model_path> 是模型存储的位置，例如 llama2 或 llama3 模型的权重。

Intel XPU

$ docker build -f Dockerfile.xpu -t vllm-xpu-env --shm-size=4g .
$ docker run -it \
             --rm \
             --network=host \
             --device /dev/dri \
             -v /dev/dri/by-path:/dev/dri/by-path \
             vllm-xpu-env

支持的功能#

NVIDIA CUDA

有关功能支持信息，请参阅功能 x 硬件兼容性矩阵。

AMD ROCm

有关功能支持信息，请参阅功能 x 硬件兼容性矩阵。

Intel XPU

XPU 平台支持张量并行推理/服务，并且还支持流水线并行作为在线服务的 Beta 功能。我们要求 Ray 作为分布式运行时后端。例如，参考执行如下

python -m vllm.entrypoints.openai.api_server \
     --model=facebook/opt-13b \
     --dtype=bfloat16 \
     --device=xpu \
     --max_model_len=1024 \
     --distributed-executor-backend=ray \
     --pipeline-parallel-size=2 \
     -tp=8

默认情况下，如果在系统中未检测到现有 ray 实例，则会自动启动一个 ray 实例，其中 num-gpus 等于 parallel_config.world_size。我们建议在执行之前正确启动 ray 集群，请参阅 examples/online_serving/run_cluster.sh 辅助脚本。

GPU

目录

GPU#

要求#

使用 Python 设置#

创建新的 Python 环境#

预构建 wheels#

安装最新代码

使用 pip 安装最新代码

使用 uv 安装最新代码

从源码构建 wheel#

使用仅 Python 构建（不编译）进行设置

完整构建（带编译）

使用现有的 PyTorch 安装

使用本地 cutlass 进行编译

故障排除

不支持的操作系统构建

使用 Docker 设置#

预构建镜像#

从源码构建镜像#

（可选）构建带有 ROCm 软件栈的镜像

构建带有 vLLM 的镜像

支持的功能#

使用 `pip` 安装最新代码

使用 `uv` 安装最新代码