GPU¶

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

vLLM支持配备ROCm 6.3的AMD GPU。

vLLM 最初支持在英特尔 GPU 平台上的基础模型推理和服务。

• GPU: 计算能力7.0或更高(例如V100、T4、RTX20xx、A100、L4、H100等)

• GPU: MI200s (gfx90a)、MI300 (gfx942)、Radeon RX 7900系列(gfx1100/1101)、Radeon RX 9000系列(gfx1200/1201)
• ROCm 6.3

• 支持的硬件：Intel Data Center GPU、Intel ARC GPU
• OneAPI 要求：oneAPI 2025.0

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

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

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

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

uv pip install vllm --torch-backend=auto

# Install vLLM with CUDA 12.8.
pip install vllm --extra-index-url https://download.pytorch.org/whl/cu128

我们建议利用uv工具，通过--torch-backend=auto（或UV_TORCH_BACKEND=auto）参数在运行时自动选择合适的PyTorch索引，该功能会检测已安装的CUDA驱动版本。如需指定特定后端（例如cu126），可设置--torch-backend=cu126（或UV_TORCH_BACKEND=cu126）。若此方法无效，请尝试先运行uv self update更新uv工具。

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

# Install vLLM with a specific CUDA version (e.g., 11.8 or 12.6).
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=118 # or 126
uv pip install https://github.com/vllm-project/vllm/releases/download/v${VLLM_VERSION}/vllm-${VLLM_VERSION}+cu${CUDA_VERSION}-cp38-abi3-manylinux1_x86_64.whl --extra-index-url https://download.pytorch.org/whl/cu${CUDA_VERSION}

安装最新代码¶

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

uv pip install -U vllm \
    --torch-backend=auto \
    --extra-index-url https://wheels.vllm.ai/nightly

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

安装特定版本¶

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

export VLLM_COMMIT=72d9c316d3f6ede485146fe5aabd4e61dbc59069 # use full commit hash from the main branch
uv pip install vllm \
    --torch-backend=auto \
    --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和默认索引的包，只选择最新版本，这使得在发布版本之前安装开发版本变得困难。

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

目前还没有预构建的ROCm轮包。

目前还没有预构建的XPU轮包。

仅使用纯Python构建（无需编译）¶

如果只需修改Python代码，您可以在不编译的情况下构建并安装vLLM。使用uv pip的--editable flag，您对代码所做的更改将在运行vLLM时生效：

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

该命令将执行以下操作：

1. 在你的vLLM克隆仓库中查找当前分支。
2. 在主分支中识别对应的基础提交。
3. 下载基础提交的预构建wheel包。
4. 在安装中使用其编译的库。

如果在运行上述命令时看到关于找不到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
uv pip install --editable .

你可以在install-the-latest-code中找到更多关于vLLM wheels的信息。

完整构建（包含编译）¶

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

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

使用现有的PyTorch安装¶

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

• 使用PyTorch nightly版本或自定义PyTorch构建来构建vLLM。
• 在aarch64架构和CUDA（GH200）环境下构建vLLM时，PyPI上未提供对应的PyTorch预编译包。目前只有PyTorch nightly版本提供支持aarch64架构的CUDA预编译包。您可以运行uv pip install --index-url https://download.pytorch.org/whl/nightly/cu128 torch torchvision torchaudio来安装PyTorch nightly版本，然后在此基础上构建vLLM。

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

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 .

使用本地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镜像。

# 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
uv pip install -e .

1. 安装必备组件（如果已处于包含以下组件的环境/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入门指南中的安装说明。例如：

   # Install PyTorch
   pip uninstall torch -y
   pip install --no-cache-dir --pre torch --index-url https://download.pytorch.org/whl/nightly/rocm6.3
   

2. 安装 Triton flash attention for ROCm

   按照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错误是间歇性的。

3. 可选地，如果您选择使用CK闪存注意力机制，可以安装适用于ROCm的flash attention

   按照ROCm/flash-attention的说明安装ROCm的闪存注意力(v2.7.2)。或者，可以在发布版本下获取专为vLLM设计的预编译包。

   例如，对于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)

4. 如果您选择自行构建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参数。

5. 构建vLLM。例如，在ROCM 6.3上可以通过以下步骤构建vLLM：

   Commands

   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驱动程序版本相匹配。

• 首先，安装所需的驱动和Intel OneAPI 2025.0或更高版本。
• 其次，安装用于构建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

查看deployment-docker-pre-built-image获取使用官方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 Infinity hub for vLLM 提供了一个预构建且经过优化的docker镜像，专为在AMD Instinct™ MI300X加速器上验证推理性能而设计。

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

查看deployment-docker-build-image-from-source获取构建Docker镜像的说明。

从源代码构建Docker镜像是推荐的使用vLLM搭配ROCm的方式。

(可选) 使用ROCm软件栈构建镜像¶

从构建一个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 docker/Dockerfile.rocm_base \
    -t rocm/vllm-dev:base .

使用vLLM构建镜像¶

首先，从构建一个Docker镜像，并从该镜像启动一个Docker容器。关键点在于用户需要使用BuildKit来执行Docker构建。用户可以在调用docker build命令时设置环境变量DOCKER_BUILDKIT=1，或者按照以下方式在Docker守护进程配置文件/etc/docker/daemon.json中配置BuildKit并重启守护进程：

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

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

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

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

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

DOCKER_BUILDKIT=1 docker build -f docker/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 docker/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

其中 是模型存储的位置，例如 llama2 或 llama3 模型的权重文件路径。

查看feature-x-hardware兼容性矩阵获取功能支持信息。

查看feature-x-hardware兼容性矩阵获取功能支持信息。

XPU平台支持张量并行推理/服务，并作为测试版功能支持流水线并行在线服务。我们要求使用Ray作为分布式运行时后端。例如，参考以下执行方式：

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

默认情况下，如果系统中未检测到现有的ray实例，将自动启动一个实例，其中num-gpus等于parallel_config.world_size。我们建议在执行前正确启动ray集群，可参考辅助脚本。