GPU¶

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

vLLM 支持运行 ROCm 6.3 或更高版本的 AMD GPU。目前提供适用于 ROCm 7.0 的预构建 wheel 包。

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

• 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 Data Center GPU，Intel ARC GPU
• OneAPI 要求：oneAPI 2025.1
• Python：3.12

为了实现高性能，vLLM 需要编译许多 CUDA 内核。遗憾的是，这种编译会引入与其他 CUDA 版本和 PyTorch 版本的二进制不兼容性，即使是相同 PyTorch 版本但构建配置不同也会出现此问题。

因此，建议使用全新的环境安装 vLLM。如果您有不同的 CUDA 版本或希望使用现有的 PyTorch 安装，则需要从源代码构建 vLLM。详情请参见下文。

vLLM wheel 包捆绑了 PyTorch 和所有必需的依赖项，您应使用其中包含的 PyTorch 以确保兼容性。由于 vLLM 会编译大量 ROCm 内核以确保经过验证的高性能堆栈，因此生成的二进制文件可能与其他 ROCm 或 PyTorch 构建版本不兼容。 如果您需要不同的 ROCm 版本或希望使用现有的 PyTorch 安装，则需要从源代码构建 vLLM。有关更多详细信息，请参阅下文。

对于此设备，暂无关于创建新 Python 环境的额外信息。

uv pip install vllm --torch-backend=auto

# 使用 CUDA 12.9 安装 vLLM。
pip install vllm --extra-index-url https://download.pytorch.org/whl/cu129

我们推荐使用 uv 通过 --torch-backend=auto（或 UV_TORCH_BACKEND=auto）在运行时自动选择合适的 PyTorch 索引，方法是检查已安装的 CUDA 驱动程序版本。要选择特定的后端（例如 cu128），请设置 --torch-backend=cu128（或 UV_TORCH_BACKEND=cu128）。如果这不起作用，请先尝试运行 uv self update 更新 uv。

截至目前，vLLM 的二进制文件默认使用 CUDA 12.9 和公共 PyTorch 发行版本编译。我们还提供了使用 CUDA 12.8、13.0 和公共 PyTorch 发行版本编译的 vLLM 二进制文件：

# 使用特定 CUDA 版本（例如 13.0）安装 vLLM。
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 # 或其他版本
export CPU_ARCH=$(uname -m) # x86_64 或 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 起为每次提交提供 wheel 文件，地址为 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）也有一个子目录以保持一致性。

要从 nightly 索引安装，请运行：

uv pip install -U vllm \
    --torch-backend=auto \
    --extra-index-url https://wheels.vllm.ai/nightly # 如果需要，在此处添加变体子目录

pip install -U https://wheels.vllm.ai/nightly/vllm-0.11.2.dev399%2Bg3c7461c18-cp38-abi3-manylinux_2_31_x86_64.whl # 当前 nightly 构建（文件名会变化！）
pip install -U https://wheels.vllm.ai/${VLLM_COMMIT}/vllm-0.11.2.dev399%2Bg3c7461c18-cp38-abi3-manylinux_2_31_x86_64.whl # 从特定提交安装

安装特定修订版本¶

如果您想访问以前提交的 wheel 文件（例如，为了二分查找行为变化、性能回归），可以在 URL 中指定提交哈希：

export VLLM_COMMIT=72d9c316d3f6ede485146fe5aabd4e61dbc59069 # 使用 main 分支的完整提交哈希
uv pip install vllm \
    --torch-backend=auto \
    --extra-index-url https://wheels.vllm.ai/${VLLM_COMMIT} # 如果需要，在此处添加变体子目录

要为 Python 3.12、ROCm 7.0 和 glibc >= 2.35 安装最新版本的 vLLM：

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

要安装特定版本和 ROCm 变体的 vLLM wheel 包：

uv pip install vllm --extra-index-url https://wheels.vllm.ai/rocm/0.15.0/rocm700

pip install vllm==0.15.0+rocm700 --extra-index-url https://wheels.vllm.ai/rocm/0.15.0/rocm700

目前，暂无预构建的 XPU 轮子。

使用纯 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 .

此命令将执行以下操作：

1. 查找您的 vLLM 克隆中的当前分支。
2. 确定 main 分支中相应的基础提交。
3. 下载基础提交的预构建 wheel。
4. 在安装中使用其编译库。

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

export VLLM_PRECOMPILED_WHEEL_COMMIT=$(git rev-parse HEAD~1) # 或 main 分支上更早的提交
export VLLM_USE_PRECOMPILED=1
uv pip install --editable .

还有更多环境变量可用于控制纯 Python 构建的行为：

• VLLM_PRECOMPILED_WHEEL_LOCATION：指定要使用的预编译 wheel 的确切 URL 或本地文件路径。将跳过查找 wheel 的所有其他逻辑。
• VLLM_PRECOMPILED_WHEEL_COMMIT：覆盖要下载预编译 wheel 的提交哈希。可以是 nightly 以使用 main 分支上最后一次已构建的提交。
• VLLM_PRECOMPILED_WHEEL_VARIANT：指定在 nightly 索引上使用的变体子目录，例如 cu129、cu130、cpu。如果未指定，则根据系统的 CUDA 版本（来自 PyTorch 或 nvidia-smi）自动检测变体。您也可以设置 VLLM_MAIN_CUDA_VERSION 来覆盖自动检测。

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

完整构建（带编译）¶

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

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

使用现有的 PyTorch 安装¶

在某些情况下，可能无法通过 uv 轻松安装 PyTorch 依赖项，例如使用非默认 PyTorch 构建（如 nightly 版本或自定义构建）构建 vLLM 时。

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

# 首先安装 PyTorch，可通过 PyPI 或从源代码安装
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 指定为禁用构建隔离的包：

# 首先安装 PyTorch，可通过 PyPI 或从源代码安装
git clone https://github.com/vllm-project/vllm.git
cd vllm
# 直接使用 pip install -e . 不起作用，只有 uv 才能做到这一点
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 限制同时运行的编译任务数量。例如：

export MAX_JOBS=6
uv pip install -e .

这在性能较弱的机器上构建时特别有用。例如，使用 WSL 时默认只分配总内存的 50%，因此使用 export MAX_JOBS=1 可避免同时编译多个文件导致内存耗尽。 副作用是构建过程会慢得多。

此外，如果在构建 vLLM 时遇到问题，建议使用 NVIDIA PyTorch Docker 镜像。

# 使用 `--ipc=host` 确保共享内存足够大。
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 # 验证 nvcc 是否在 PATH 中
${CUDA_HOME}/bin/nvcc --version # 验证 nvcc 是否在 CUDA_HOME 中

不支持的操作系统构建¶

vLLM 只能在 Linux 上完全运行，但出于开发目的，仍可在其他系统（例如 macOS）上构建，从而实现导入和更便捷的开发环境。二进制文件不会被编译，且无法在非 Linux 系统上运行。

只需在安装前禁用 VLLM_TARGET_DEVICE 环境变量：

export VLLM_TARGET_DEVICE=empty
uv pip install -e .

1. 安装先决条件（如果您已经处于安装了以下内容的 environment/docker 中，请跳过此步骤）：

   • ROCm
   • PyTorch

   要安装 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 安装指南。例如：

   # 安装 PyTorch
   pip uninstall torch -y
   pip install --no-cache-dir torch torchvision --index-url https://download.pytorch.org/whl/nightly/rocm7.0
   

2. 安装 适用于 ROCm 的 Triton

   按照 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 ../..
   

   Note

   • 经过验证的 $TRITON_BRANCH 可以在 docker/Dockerfile.rocm_base 中找到。
   • 如果您在构建 triton 期间遇到与下载包相关的 HTTP 问题，请重试，因为 HTTP 错误是间歇性的。

3. 可选地，如果您选择使用 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 ..
   

   Note

   • 经过验证的 $FA_BRANCH 可以在 docker/Dockerfile.rocm_base 中找到。

4. 可选地，如果您选择自行构建 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
   

   Note

   • 您需要根据您的目的配置 $AITER_BRANCH_OR_COMMIT。
   • 经过验证的 $AITER_BRANCH_OR_COMMIT 可以在 docker/Dockerfile.rocm_base 中找到。

5. 可选地，如果您想使用 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
   

   Note

   • 您需要根据您的目的配置 $MORI_BRANCH_OR_COMMIT。
   • 经过验证的 $MORI_BRANCH_OR_COMMIT 可以在 docker/Dockerfile.rocm_base 中找到。

6. 构建 vLLM。例如，可以使用以下步骤构建 ROCM 7.0 上的 vLLM：

   命令

   pip install --upgrade pip
   
   # 构建并安装 AMD SMI
   pip install /opt/rocm/share/amd_smi
   
   # 安装依赖项
   pip install --upgrade numba \
       scipy \
       huggingface-hub[cli,hf_transfer] \
       setuptools_scm
   pip install -r requirements/rocm.txt
   
   # 要为单一架构（例如 MI300）构建以加快安装速度（推荐）：
   export PYTORCH_ROCM_ARCH="gfx942"
   
   # 要为多个架构 MI210/MI250/MI300 构建 vLLM，请改用此命令
   # export PYTORCH_ROCM_ARCH="gfx90a;gfx942"
   
   python3 setup.py develop
   

   这可能需要 5-10 分钟。目前，从源代码安装 vLLM 时，pip install . 在 ROCm 上不起作用。

   Tip

   • 理想情况下，PyTorch 的 ROCm 版本应与 ROCm 驱动程序版本匹配。

• 首先，安装必需的 驱动程序 和 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 后端：

VLLM_TARGET_DEVICE=xpu python setup.py install

有关使用官方 Docker 镜像的说明，请参阅使用 Docker。

另一种访问最新代码的方法是使用 docker 镜像：

export VLLM_COMMIT=33f460b17a54acb3b6cc0b03f4a17876cff5eafd # 使用主分支的完整提交哈希
docker pull public.ecr.aws/q9t5s3a7/vllm-ci-postmerge-repo:${VLLM_COMMIT}

这些 docker 镜像仅用于 CI 和测试，不适用于生产环境。它们将在几天后过期。

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

使用 vLLM 的官方 Docker 镜像¶

vLLM 提供了一个官方 Docker 镜像用于部署。
该镜像可用于运行兼容 OpenAI 的服务器，并可在 Docker Hub 上以 vllm/vllm-openai-rocm 的形式获取。

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:latest \
    --model Qwen/Qwen3-0.6B

若要将该 Docker 镜像作为开发基础镜像使用，可通过覆盖 entrypoint 以交互模式启动容器。

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" \
    -p 8000:8000 \
    --ipc=host \
    --entrypoint bash \
    vllm/vllm-openai-rocm:latest

使用 AMD 提供的 Docker 镜像¶

AMD Infinity Hub 中的 vLLM 镜像 提供了一个预构建且经过优化的 Docker 镜像，专为在 AMD Instinct™ MI300X 加速器上验证推理性能而设计。
AMD 还提供每日构建的预编译镜像，可在 Docker Hub 上获取，该镜像已安装 vLLM 及其所有依赖项。此镜像的 entrypoint 为 /bin/bash（与 vLLM 官方 Docker 镜像不同）。

docker pull rocm/vllm-dev:nightly # 获取最新镜像
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

目前，我们基于 vLLM 发布版本在 docker hub 上发布预构建的 XPU 镜像。欲了解更多信息，请参考发布 说明。

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

推荐通过源码构建 Docker 镜像的方式在 ROCm 环境下使用 vLLM。

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

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

构建包含 vLLM 的镜像¶

首先，基于 docker/Dockerfile.rocm 构建 Docker 镜像，并从该镜像启动容器。
用户必须使用 buildkit 启动 docker build。可在调用 docker build 命令时设置环境变量 DOCKER_BUILDKIT=1，或在 Docker 守护进程配置文件 /etc/docker/daemon.json 中启用 buildkit 并重启守护进程：

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

docker/Dockerfile.rocm 默认使用 ROCm 7.0，但也支持旧版 vLLM 分支中的 ROCm 5.7、6.0、6.1、6.2、6.3 和 6.4。
该 Dockerfile 提供了以下参数以灵活定制镜像构建：

• BASE_IMAGE：指定运行 docker build 时使用的基镜像。默认值 rocm/vllm-dev:base 是由 AMD 发布和维护的镜像，基于 docker/Dockerfile.rocm_base 构建。
• ARG_PYTORCH_ROCM_ARCH：允许覆盖基镜像中的 gfx 架构值。

这些参数的值可通过 docker build 命令的 --build-arg 选项传入。

若要在 ROCm 7.0 上为 MI200 和 MI300 系列构建 vLLM，可使用默认配置（构建一个以 vllm serve 为 entrypoint 的 Docker 镜像）：

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

运行上述 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 \
--model Qwen/Qwen3-0.6B

其中 <path/to/model> 是模型存储的路径，例如 llama2 或 llama3 模型的权重文件所在位置。

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

请参阅 功能 × 硬件 兼容性矩阵以了解功能支持信息。

XPU 平台支持 tensor parallel 推理/服务，还支持 pipeline parallel 作为在线服务的 beta 功能。对于 pipeline parallel，我们支持在单节点上使用 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 辅助脚本。