GPU¶
vLLM 是一个支持以下 GPU 变体的 Python 库。选择您的 GPU 类型以查看供应商特定说明
vLLM 包含预编译的 C++ 和 CUDA (12.8) 二进制文件。
vLLM 支持搭载 ROCm 6.3 的 AMD GPU。
提示
Docker 是在 ROCm 上使用 vLLM 的推荐方式。
警告
此设备没有预构建的 wheel 包，因此您必须使用预构建的 Docker 镜像或从源代码构建 vLLM。
vLLM 最初支持在 Intel GPU 平台上进行基本的模型推理和提供服务。
警告
此设备没有预构建的 wheel 或镜像，因此您必须从源代码构建 vLLM。
要求¶
- 操作系统：Linux
- Python：3.9 - 3.12
注意
vLLM 不原生支持 Windows。要在 Windows 上运行 vLLM，您可以使用适用于 Linux 的 Windows 子系统 (WSL) 以及兼容的 Linux 发行版，或使用社区维护的一些分支，例如 https://github.com/SystemPanic/vllm-windows。
- 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 数据中心 GPU，Intel ARC GPU
- OneAPI 要求：oneAPI 2025.0
使用 Python 进行设置¶
创建新的 Python 环境¶
建议使用 uv（一个非常快速的 Python 环境管理器）来创建和管理 Python 环境。请按照文档安装 uv。安装 uv 后，您可以使用以下命令创建新的 Python 环境并安装 vLLM：
注意
通过 conda 安装的 PyTorch 会静态链接 NCCL 库，这可能导致 vLLM 尝试使用 NCCL 时出现问题。详见
为了获得高性能，vLLM 必须编译许多 CUDA 内核。不幸的是，编译会导致与其它 CUDA 版本和 PyTorch 版本（即使是相同 PyTorch 版本但构建配置不同）的二进制不兼容性。
因此，建议在 全新 环境中安装 vLLM。如果您有不同的 CUDA 版本或想使用现有的 PyTorch 安装，则需要从源代码构建 vLLM。有关详细信息，请参阅下文。
对于此设备，没有关于创建新 Python 环境的额外信息。
对于此设备，没有关于创建新 Python 环境的额外信息。
预构建的 Wheels¶
您可以使用 pip 或 uv pip 安装 vLLM
# Install vLLM with CUDA 12.8.
# If you are using pip.
pip install vllm --extra-index-url https://download.pytorch.org/whl/cu128
# If you are using uv.
uv pip install vllm --torch-backend=auto
我们建议利用 uv 通过检查已安装的 CUDA 驱动程序版本来自动选择运行时合适的 PyTorch 索引，使用 --torch-backend=auto（或 UV_TORCH_BACKEND=auto）。要选择特定后端（例如 cu126），请设置 --torch-backend=cu126（或 UV_TORCH_BACKEND=cu126）。如果这不起作用，请尝试运行 uv self update 以首先更新 uv。
注意
NVIDIA Blackwell GPU（B200、GB200）最低需要 CUDA 12.8，因此请确保您安装的 PyTorch wheel 版本至少达到该版本。PyTorch 本身提供了专用接口来确定针对给定目标配置运行哪个 pip 命令。
截至目前，vLLM 的二进制文件默认使用 CUDA 12.8 和 PyTorch 公开发布版本进行编译。我们还提供了使用 CUDA 12.6、11.8 和 PyTorch 公开发布版本编译的 vLLM 二进制文件
# Install vLLM with CUDA 11.8.
export VLLM_VERSION=0.6.1.post1
export PYTHON_VERSION=312
uv 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 以来每个提交的 x86 平台 Linux 上的 CUDA 12 提供了 wheel 包。
使用 pip 安装最新代码¶
--pre 对于 pip 考虑预发布版本是必需的。
安装最新代码的另一种方法是使用 uv
使用 pip 安装特定版本¶
如果您想访问先前提交的 wheel 包（例如，为了二分查找行为变化、性能回归），由于 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
请注意，这些 wheel 包是使用 Python 3.8 ABI 构建的（有关 ABI 的更多详细信息，请参阅PEP 425），因此它们与 Python 3.8 及更高版本兼容。wheel 文件名中的版本字符串（1.0.0.dev）只是一个占位符，用于为 wheel 包提供统一的 URL，wheel 包的实际版本包含在 wheel 元数据中（额外索引 URL 中列出的 wheel 包具有正确的版本）。尽管我们不再支持 Python 3.8（因为 PyTorch 2.5 放弃了对 Python 3.8 的支持），但 wheel 包仍然使用 Python 3.8 ABI 构建，以保持与以前相同的 wheel 名称。
使用 uv 安装特定版本¶
如果您想访问先前提交的 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 和默认索引中的软件包结合起来，只选择最新版本，这使得安装早于已发布版本的开发版本变得困难。
目前，没有预构建的 ROCm wheel 包。
目前，没有预构建的 XPU wheel 包。
从源代码构建 Wheel¶
使用纯 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 .
您可以在install-the-latest-code中找到有关 vLLM wheel 的更多信息。
注意
您的源代码可能与最新的 vLLM wheel 包具有不同的提交 ID，这可能导致未知错误。建议源代码使用与您安装的 vLLM wheel 包相同的提交 ID。有关如何安装指定 wheel 包的说明，请参阅install-the-latest-code。
完整构建（带编译）¶
如果您想修改 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 内核更改，在初始 pip install -e . 设置后，考虑使用增量编译工作流，以显著加快仅修改的内核代码的重建速度。
使用现有 PyTorch 安装¶
在某些情况下，PyTorch 依赖项无法通过 pip 轻松安装，例如：
- 使用 PyTorch nightly 或自定义 PyTorch 构建来构建 vLLM。
- 使用 aarch64 和 CUDA (GH200) 构建 vLLM，其中 PyPI 上没有 PyTorch wheel 包。目前，只有 PyTorch nightly 提供适用于带有 CUDA 的 aarch64 的 wheel 包。您可以运行
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 --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 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 中，请跳过）
对于安装 PyTorch，您可以从全新的 docker 镜像开始，例如
rocm/pytorch:rocm6.3_ubuntu24.04_py3.12_pytorch_release_2.4.0,rocm/pytorch-nightly。如果您正在使用 docker 镜像，可以跳到步骤 3。或者，您可以使用 PyTorch wheel 包安装 PyTorch。您可以在 PyTorch 入门指南中查看 PyTorch 安装指南。示例：
-
安装 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 错误是间歇性的。
-
（可选）如果您选择使用 CK flash attention，则可以安装 flash attention for ROCm
按照 ROCm/flash-attention 中的说明安装 ROCm 的 flash attention (v2.7.2)。或者，可以在发布版本中访问适用于 vLLM 的 wheel 包。
例如，对于 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） -
如果您选择自行构建 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。 -
构建 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 naive attention，请使用此标志
export VLLM_USE_TRITON_FLASH_ATTN=0关闭 triton flash attention。 - PyTorch 的 ROCm 版本，理想情况下，应与 ROCm 驱动程序版本匹配。
提示
- 对于 MI300x (gfx942) 用户，为获得最佳性能，请参阅 MI300x 调优指南以获取系统和工作流级别的性能优化和调优技巧。对于 vLLM，请参阅 vLLM 性能优化。
- 首先，安装所需的驱动程序和 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 后端
注意
- FP16 是当前 XPU 后端中的默认数据类型。BF16 数据类型在 Intel 数据中心 GPU 上受支持，但尚未在 Intel Arc GPU 上受支持。
使用 Docker 进行设置¶
预构建的镜像¶
有关使用官方 Docker 镜像的说明，请参阅deployment-docker-pre-built-image。
另一种获取最新代码的方法是使用 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 加速器上的推理性能而设计。
提示
有关如何使用此预构建 docker 镜像的说明，请查看 LLM inference performance validation on AMD Instinct MI300X。
目前，没有预构建的 XPU 镜像。
从源代码构建镜像¶
有关构建 Docker 镜像的说明，请参阅deployment-docker-build-image-from-source。
从源代码构建 Docker 镜像是在 ROCm 上使用 vLLM 的推荐方式。
（可选）构建包含 ROCm 软件栈的镜像¶
从以下位置构建 Docker 镜像rocm/vllm-dev:base 标签下，以加快用户体验。 如果您选择自行构建此 rocm_base 镜像，步骤如下。
重要的是，用户要使用 buildkit 启动 docker build。用户可以在调用 docker build 命令时将 DOCKER_BUILDKIT=1 作为环境变量，或者用户需要在 docker daemon 配置 /etc/docker/daemon.json 中如下设置 buildkit 并重新启动 daemon：
要在 ROCm 6.3 上为 MI200 和 MI300 系列构建 vllm，您可以使用默认的
构建包含 vLLM 的镜像¶
首先，从以下位置构建 Docker 镜像：DOCKER_BUILDKIT=1 作为环境变量，或者用户需要在 docker daemon 配置 /etc/docker/daemon.json 中如下设置 buildkit 并重新启动 daemon：
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，您可以使用默认的
要在 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，请使用以下命令：
命令
其中 <path/to/model> 是模型存储的位置，例如 llama2 或 llama3 模型的权重。
支持的功能¶
有关功能支持信息，请参阅feature-x-hardware兼容性矩阵。
有关功能支持信息，请参阅feature-x-hardware兼容性矩阵。
XPU 平台支持张量并行推理/服务，并支持流水线并行作为在线服务的 Beta 功能。我们要求 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 实例，将自动启动一个 Ray 实例，其中 num-gpus 等于 parallel_config.world_size。我们建议在执行前正确启动 Ray 集群，请参考