vLLM GPU 安装实战指南：NVIDIA CUDA、AMD ROCm、Intel XPU 与 Apple Silicon 全平台部署详解

本篇指南基于 vLLM 官方安装文档 docs/getting_started/installation/gpu.md，系统讲解在四类 GPU 平台（NVIDIA CUDA、AMD ROCm、Intel XPU、Apple Silicon）上安装与运行 vLLM 的完整流程，覆盖预编译 wheel 安装、源码构建、nightly 版本获取与 Docker 镜像部署。读完本文，你将能够为自己的硬件环境选择正确的安装路径，理解 VLLM_USE_PRECOMPILED、VLLM_TARGET_DEVICE 等关键构建环境变量的作用，并能在构建失败时依据仓库源码定位问题。

平台总览与通用要求

vLLM 是一个 Python 库，针对不同 GPU 生态提供差异化支持。安装文档通过 mkdocs snippets 机制将各平台的说明拆分为独立片段，实际内容分别位于以下四个文件中，本文按此脉络组织：

GPU 平台	说明文件	核心形态
NVIDIA CUDA	gpu.cuda.inc.md	预编译 C++/CUDA 12.9 二进制
AMD ROCm	gpu.rocm.inc.md	ROCm 6.3+ 支持，提供 ROCm 7.0 / 7.2.1 wheel
Intel XPU	gpu.xpu.inc.md	基础推理与服务支持
Apple Silicon	gpu.apple.inc.md	社区维护的 vLLM-Metal 硬件插件（MLX 后端）

通用硬件与系统要求

• 操作系统：Linux
• Python：3.10 – 3.13
• vLLM 不原生支持 Windows。如需在 Windows 上运行，可搭配兼容 Linux 发行版使用 WSL（Windows Subsystem for Linux），或使用社区维护的 fork 项目。

各平台硬件要求

NVIDIA CUDA：GPU 计算能力（compute capability）≥ 7.5，例如 T4、RTX20xx、A100、L4、H100、B200 等。

AMD ROCm：

• 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 XPU：

• 硬件：Intel Data Center GPU、Intel ARC GPU
• 依赖：vllm-xpu-kernels 包（提供 XPU 平台所需的全部自定义 kernel）
• Python：必须 3.12（因为 vllm-xpu-kernels 的 whl 仅面向 Python 3.12 发布）

Apple Silicon：

• macOS Sonoma 或更新版本
• Apple Silicon 硬件，且启用 Metal 支持

创建 Python 环境

官方推荐使用 uv（一个极快的 Python 环境管理器）来创建和管理环境（该片段同时被 CPU/GPU 安装文档复用，见 python_env_setup.inc.md）：

uv venv --python 3.12 --seed --managed-python
source .venv/bin/activate

安装前必须理解两个关键约束，它们决定了为什么官方反复强调“干净环境”：

1. 二进制不兼容性：vLLM 为了性能需要编译大量 CUDA kernel，这些 kernel 编译后与其他 CUDA 版本、PyTorch 版本（甚至同版本 PyTorch 的不同构建配置）都不存在二进制兼容性。因此官方建议在全新环境中安装 vLLM；若你的 CUDA 版本不同、或想复用已有 PyTorch，就需要从源码构建 vLLM。
2. conda 安装的 PyTorch 会静态链接 NCCL 库，可能导致 vLLM 使用 NCCL 时出现问题，这也是推荐使用独立虚拟环境的原因之一。

ROCm 平台的 wheel 自带 PyTorch 及全部依赖，官方明确要求使用 wheel 内附的 PyTorch 以保证兼容性；vLLM 编译了大量 ROCm kernel 以确保经过验证的高性能栈，因此其二进制与其他 ROCm/PyTorch 构建同样不兼容，需要不同版本时须从源码构建。

NVIDIA CUDA：安装预编译 wheel

官方 wheel 以 CUDA 12.9 + 公开 PyTorch 版本编译。安装命令如下：

uv pip install vllm --torch-backend=auto

如果习惯使用 pip（CUDA 12.9）：

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

官方推荐使用 uv 的 --torch-backend=auto（或环境变量 UV_TORCH_BACKEND=auto）在运行时自动探测已安装的 CUDA 驱动版本并选择正确的 PyTorch 索引；若要指定特定后端（如 cu130），则设置 --torch-backend=cu130（或 UV_TORCH_BACKEND=cu130）。若自动选择不生效，可先执行 uv self update 更新 uv。

注意：NVIDIA Blackwell GPU（B200、GB200）最低要求 CUDA 12.8，请确认安装的 PyTorch wheel 版本不低于此。

安装特定 CUDA 版本编译的 wheel

除默认的 CUDA 12.9 外，vLLM 还提供以 CUDA 12.8、13.0 及公开 PyTorch 版本编译的二进制：

# 安装指定 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_28_${CPU_ARCH}.whl --extra-index-url https://download.pytorch.org/whl/cu${CUDA_VERSION}

安装 nightly 最新代码

LLM 推理演进很快，nightly 构建往往包含尚未发布的修复、性能改进与新特性。vLLM 从 v0.5.3 起为每个 main 分支提交都提供 wheel，索引如下：

• https://wheels.vllm.ai/nightly：默认变体（CUDA 版本由 VLLM_MAIN_CUDA_VERSION 指定，当前为 CUDA 12.9），对应 main 分支最后一次提交；
• 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 陷阱：用 pip 从 nightly 索引安装不受支持，因为 pip 会把 --extra-index-url 与默认索引中的包合并、只选最新版本，导致难以安装早于已发布版本的开发版本。而 uv 会赋予额外索引高于默认索引的优先级。如果坚持使用 pip，必须给出 wheel 文件的完整 URL（可从网页获取）：

pip install -U https://wheels.vllm.ai/2f3f441f84bd5b35ec8aa9fcfffb540f107da8a7/vllm-0.23.1rc1.dev901%2Bg2f3f441f8-cp38-abi3-manylinux_2_28_x86_64.whl # 当前 nightly 构建（文件名会变！）
pip install -U https://wheels.vllm.ai/${VLLM_COMMIT}/vllm-0.23.1rc1.dev901%2Bg2f3f441f8-cp38-abi3-manylinux_2_28_x86_64.whl # 指定提交

安装特定提交（如二分定位行为变化、性能回归）：把完整 commit hash 放进 URL：

export VLLM_COMMIT=72d9c316d3f6ede485146fe5aabd4e61dbc59069 # main 分支的完整 commit hash
uv pip install vllm \
    --torch-backend=auto \
    --extra-index-url https://wheels.vllm.ai/${VLLM_COMMIT} # 如需其他变体，在此追加子目录

NVIDIA CUDA：从源码构建 wheel

Python-only 构建（免编译）

如果只改 Python 代码，可以用 VLLM_USE_PRECOMPILED=1 免编译安装，借助 uv pip 的 --editable 机制使改动即时生效：

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

这条命令的内部逻辑是：1）在你克隆的仓库中定位当前分支；2）识别其在 main 分支上对应的 base commit；3）下载该 base commit 的预构建 wheel；4）安装时复用其中的编译产物与 vllm-rs 二进制。

两条注意事项：修改 C++ 或 kernel 代码时不能使用 Python-only 构建，否则会遇到“库未找到/未定义符号”的导入错误；rebase 开发分支后建议先卸载 vllm 再重跑上述命令，确保库与提交匹配。

重建 Rust 前端：vllm-rs 是 vLLM 的 Rust 前端二进制。build_rust.sh 会自动读取 rust-toolchain.toml 中的 toolchain 版本，缺失时自动安装 rustup 与对应工具链，再通过 tools/build_rust.py 完成构建并把产物放入 vllm/vllm-rs：

./build_rust.sh          # release 构建
./build_rust.sh --debug  # 开发期更快的 debug 构建

若报“wheel not found”，通常是你 base 的 main 提交刚合并、预编译 wheel 尚未生成，等约一小时重试，或设置 VLLM_PRECOMPILED_WHEEL_COMMIT=nightly 自动选择 main 上最近一个已构建的提交：

export VLLM_PRECOMPILED_WHEEL_COMMIT=nightly
export VLLM_USE_PRECOMPILED=1
uv pip install --editable .

控制 Python-only 构建行为的环境变量：

环境变量	作用
VLLM_PRECOMPILED_WHEEL_LOCATION	直接指定预编译 wheel 的 URL 或本地路径，跳过所有查找逻辑
VLLM_PRECOMPILED_WHEEL_COMMIT	覆盖用于下载预编译 wheel 的 commit hash；nightly 表示使用 main 上最后一个已构建的提交
VLLM_PRECOMPILED_WHEEL_VARIANT	指定 nightly 索引的变体子目录，如 cu129、cu130、cpu；缺省时根据系统 CUDA 版本（来自 PyTorch 或 nvidia-smi）自动探测，也可用 VLLM_MAIN_CUDA_VERSION 覆盖自动探测

从源码结构看，这些开关最终都汇入构建入口 setup.py：USE_PRECOMPILED_EXTENSIONS = envs.VLLM_USE_PRECOMPILED，且 VLLM_USE_PRECOMPILED 隐含同时启用预编译的 Rust 前端，因此 Python-only 构建能同时跳过 C++/CUDA 编译与 Rust 编译。

建议：源码 commit 与已安装 wheel 的 commit 不一致可能引发未知错误，推荐两者使用相同 commit（参考上文“安装特定提交”）。

完整构建（含编译）

编译器要求：源码构建需要 GCC/G++ ≥ 11.3，PyTorch 的 C++20 头文件与 GCC 10 或 GCC < 11.3 不兼容。Ubuntu 22.04 上可执行：

sudo apt-get install -y gcc-11 g++-11
sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-11 110 \
    --slave /usr/bin/g++ g++ /usr/bin/g++-11

要修改 C++/CUDA 代码，需完整源码构建（耗时数分钟）：

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

CUDA 架构与 PTX 标志：vLLM 按源文件粒度归一化 CUDA 架构以优化构建时间和 wheel 体积。TORCH_CUDA_ARCH_LIST 中的全局 +PTX 请求（如 TORCH_CUDA_ARCH_LIST="8.0+PTX"）在通用扩展目标上会被忽略，vLLM 只为特定内部 kernel 生成 PTX。

编译缓存加速：重复源码构建时强烈建议安装 ccache（conda install ccache 或 apt install ccache）。只要 which ccache 能找到二进制，构建系统会自动启用；首次构建后速度显著提升。若配合 pip install -e . 使用 ccache，应运行 CCACHE_NOHASHDIR="true" pip install --no-build-isolation -e .，因为 pip 每次构建都新建随机目录名，导致 ccache 无法识别重复构建。sccache 类似但支持远端存储缓存，可设置 SCCACHE_BUCKET=vllm-build-sccache SCCACHE_REGION=us-west-2 SCCACHE_S3_NO_CREDENTIALS=1，并建议 SCCACHE_IDLE_TIMEOUT=0。

kernel 高频迭代：频繁改 C++/CUDA kernel 时，首次 uv pip install -e . 之后可参考 增量编译工作流 只重编被修改的 kernel，速度显著更快。

复用已有 PyTorch 安装：当 PyTorch 依赖无法用 uv 直接安装（如 nightly 或自定义构建的 PyTorch）时，仓库提供了 use_existing_torch.py 辅助脚本——它扫描 requirements/**/*.txt、requirements/**/*.in 和 pyproject.toml，把其中所有含 torch 的依赖行剥离（源码中通过 TORCH_LIB_PREFIXES 精确匹配 torch=、torchvision=、torchaudio=、torchcodec= 等前缀），从而让构建使用环境里现成的 PyTorch：

# 先安装 PyTorch（PyPI 或源码）
git clone https://github.com/vllm-project/vllm.git
cd vllm
python use_existing_torch.py
uv pip install -r requirements/build/cuda.txt
uv pip install --no-build-isolation -e .

另一条路径：如果全程用 uv 管理虚拟环境，可利用 uv 针对特定包禁用构建隔离的机制，直接指定 torch 为免隔离包，此时 uv pip install -e . 即可（该能力 pip 不具备）。

使用本地 cutlass 编译：构建默认从 GitHub 拉取 cutlass 源码；如需使用本地 cutlass，设置 VLLM_CUTLASS_SRC_DIR 指向本地目录：

git clone https://github.com/vllm-project/vllm.git
cd vllm
VLLM_CUTLASS_SRC_DIR=/path/to/cutlass uv pip install -e . --torch-backend=auto

构建排错

• 限制并发编译数：通过 MAX_JOBS 环境变量避免压垮机器：

  export MAX_JOBS=6
  uv pip install -e .
  

  WSL 下默认只分配约 50% 内存，可 export MAX_JOBS=1 防止并发编译导致内存耗尽（代价是构建更慢）。

• 构建困难时，推荐直接使用 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，确保 nvcc 在 PATH 中：

  export CUDA_HOME=/usr/local/cuda
  export PATH="${CUDA_HOME}/bin:$PATH"
  
  # 健全性检查
  nvcc --version # 验证 nvcc 在 PATH 中
  ${CUDA_HOME}/bin/nvcc --version # 验证 nvcc 在 CUDA_HOME 中
  

非 Linux 系统构建（开发用途）

vLLM 完整运行仅限 Linux，但出于开发目的可以在其他系统（如 macOS）上构建，使其可 import、便于开发环境搭建——二进制不会被编译，也无法在非 Linux 系统运行。只需安装前将设备置为 empty：

export VLLM_TARGET_DEVICE=empty
uv pip install -e .

从源码结构看，VLLM_TARGET_DEVICE 的自动推断逻辑在 setup.py 中：macOS 上会自动降级为 cpu；Linux 上未显式设置时，则按环境探测依次归为 rocm、xpu、cuda 或 cpu。这一推断结果还会传给 CMake（-DVLLM_TARGET_DEVICE=...），决定 C++/CUDA 扩展的编译目标。

AMD ROCm 安装

预构建 wheel

vLLM 支持 ROCm 6.3+，目前提供 ROCm 7.0 与 7.2.1 的预构建 wheel：

ROCm 变体	Python 版本	ROCm 版本	glibc 要求	支持版本
rocm700	3.12	7.0	≥ 2.35	0.14.0 – 0.18.0
rocm721	3.12	7.2.1	≥ 2.35	commit 171775f306a333a9cf105bfd533bf3e113d401d9 之后的 nightly

警告：ROCm wheel 仅支持 Python 3.12。使用其他版本（如 3.11 或 3.13）时，安装器会静默回退到 PyPI 的 CUDA wheel，进而在 AMD GPU 上报 libcudart.so: cannot open shared object file 一类错误。用 python3 --version 检查版本；需要 3.12 时可用 uv 建隔离环境：

uv venv --python 3.12 --seed --managed-python
source .venv/bin/activate

安装最新 ROCm 7.0 版本（要求 Python 3.12、ROCm 7.0、glibc ≥ 2.35）：

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

可以自动探测 wheel 变体与版本号：

# 自动提取可用的 rocm 变体
export VLLM_ROCM_VARIANT=$(curl -s https://wheels.vllm.ai/rocm/vllm | grep -oP 'rocm\d+' | head -1)
# 自动提取 vLLM 版本
export VLLM_VERSION=$(curl -s https://wheels.vllm.ai/rocm/vllm | grep -oP 'vllm-\K[0-9.]+' | head -1)
echo $VLLM_ROCM_VARIANT
echo $VLLM_VERSION

安装特定版本与变体：

# 版本号不带 `v`
uv pip install vllm==${VLLM_VERSION} --extra-index-url https://wheels.vllm.ai/rocm/${VLLM_VERSION}/${VLLM_ROCM_VARIANT}

# 示例
uv pip install vllm==0.18.0 --extra-index-url https://wheels.vllm.ai/rocm/0.18.0/rocm700

与 CUDA 平台相同，pip 从自定义索引安装存在“只选最新版本”的问题，坚持用 pip 时须指定精确版本号并给出完整 --extra-index-url：

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

ROCm nightly 与特定提交

nightly wheel 自 commit 171775f306a333a9cf105bfd533bf3e113d401d9 起提供，首个支持 nightly 的变体是 ROCm 7.2.1。索引为 https://wheels.vllm.ai/rocm/nightly/${VLLM_ROCM_VARIANT}：

# 自动提取可用的 rocm 变体
export VLLM_ROCM_VARIANT=$(curl -s https://wheels.vllm.ai/rocm/nightly | \
    grep -oP 'rocm\d+' | head -1  | sed 's/%2B/+/g')
echo $VLLM_ROCM_VARIANT

uv pip install --pre vllm \
    --extra-index-url https://wheels.vllm.ai/rocm/nightly/${VLLM_ROCM_VARIANT} \
    --index-strategy unsafe-best-match

安装特定提交（用于行为二分/回归定位）：

export VLLM_COMMIT=5b8c30d62b754b575e043ce2fc0dcbf8a64f6306

export VLLM_ROCM_VARIANT=$(curl -s https://wheels.vllm.ai/rocm/${VLLM_COMMIT} | \
    grep -oP 'rocm\d+' | head -1  | sed 's/%2B/+/g')

# 从 wheel URL 提取版本号
export VLLM_VERSION=$(curl -s https://wheels.vllm.ai/rocm/${VLLM_COMMIT}/${VLLM_ROCM_VARIANT}/vllm/ | \
    grep -oP 'vllm-\K[^-]+' | head -1  | sed 's/%2B/+/g')

echo $VLLM_ROCM_VARIANT
echo $VLLM_VERSION

uv pip install vllm==${VLLM_VERSION} \
  --extra-index-url https://wheels.vllm.ai/rocm/${VLLM_COMMIT}/${VLLM_ROCM_VARIANT} \
  --index-strategy unsafe-best-match

ROCm Python-only 构建

git clone https://github.com/vllm-project/vllm.git
cd vllm
VLLM_USE_PRECOMPILED=1 python3 setup.py develop

其流程比 CUDA 多一步“检测环境中的 ROCm 版本并选择匹配的 wheel 变体”：定位当前分支 → 找 main 上的 base commit → 探测 ROCm 版本 → 下载 base commit 的预构建 wheel → 复用其编译库与 vllm-rs 二进制。若报 wheel 缺失，检查 https://wheels.vllm.ai/rocm/<commit>/ 下可用变体（例如 ROCm 7.2.1 对应 rocm721）。控制环境变量与 CUDA 平台一致：VLLM_PRECOMPILED_WHEEL_LOCATION、VLLM_PRECOMPILED_WHEEL_COMMIT、VLLM_PRECOMPILED_WHEEL_VARIANT（指定时其值必须与探测到的 ROCm 环境匹配）。Rust 前端重建同样使用 ./build_rust.sh / ./build_rust.sh --debug。

ROCm 完整源码构建

完整步骤（ROCm 7.0 为例）：

1. 安装前置依赖：ROCm 与 PyTorch（可跳过如果已在容器环境中）。PyTorch 可从干净 docker 镜像起步（如 rocm/pytorch:rocm7.0_ubuntu22.04_py3.10_pytorch_release_2.8.0），或用 wheel 安装：

   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 的指引，验证过的分支见 docker/Dockerfile.rocm_base）：

   python3 -m pip install ninja cmake wheel pybind11
   pip uninstall -y triton
   git clone https://github.com/ROCm/triton.git
   cd triton
   git checkout f9e5bf54
   if [ ! -f setup.py ]; then cd python; fi
   python3 setup.py install
   cd ../..
   

3. （可选）CK flash attention：安装 ROCm 版 flash-attention（v2.8.0）。例如 ROCm 7.0 下、gfx942 架构（rocminfo |grep gfx 查看）：

   git clone https://github.com/Dao-AILab/flash-attention.git
   cd flash-attention
   git checkout 0e60e394
   git submodule update --init
   GPU_ARCHS="gfx942" python3 setup.py install
   cd ..
   

4. （可选）自建 AITER（使用特定分支/commit 时）：

   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
   

5. （可选）安装 MORI（用于 EP 或 PD 分离场景）：

   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
   

6. 构建 vLLM（耗时 5–10 分钟；注意 ROCm 从源码安装当前 pip install . 不可用，需走 setup.py develop）：

   pip install --upgrade pip
   
   # 构建并安装 AMD SMI
   pip install /opt/rocm/share/amd_smi
   
   # 安装依赖
   pip install --upgrade numba \
       scipy \
       huggingface-hub[cli] \
       setuptools_scm
   pip install -r requirements/rocm.txt
   
   # 为单一架构（如 MI300）构建以加速安装（推荐）：
   export PYTORCH_ROCM_ARCH="gfx942"
   
   # 为 MI210/MI250/MI300 多架构构建则使用：
   # export PYTORCH_ROCM_ARCH="gfx90a;gfx942"
   
   python3 setup.py develop
   

   其中依赖清单即仓库中的 requirements/rocm.txt。PyTorch 的 ROCm 版本最好与 ROCm 驱动版本一致。MI300x（gfx942）用户还可通过 AMD 官方的 MI300x tuning 指南做系统与流程层调优。

Intel XPU 安装

预构建 wheel

XPU wheel 发布在 wheels.vllm.ai，每个 XPU wheel 索引同时包含下文所述的 triton==3.7.2+xpu shim；PyTorch XPU 包来自 PyTorch XPU 索引，因此两个索引都要提供。

安装最新 main 构建：

uv pip install vllm --extra-index-url https://wheels.vllm.ai/nightly/xpu --extra-index-url https://download.pytorch.org/whl/xpu --index-strategy unsafe-best-match

安装特定提交：

export VLLM_COMMIT=730bd35378bf2a5b56b6d3a45be28b3092d26519 # main 分支完整 commit hash
uv pip install vllm --extra-index-url https://wheels.vllm.ai/${VLLM_COMMIT}/xpu --extra-index-url https://download.pytorch.org/whl/xpu --index-strategy unsafe-best-match

从源码构建

1. 先安装 Intel GPU 驱动；

2. 安装 XPU 后端构建依赖（Intel OneAPI 依赖随 torch-xpu 自动安装），依赖清单为 requirements/xpu.txt；自 vllm-xpu-kernels v0.1.10 起建议升级驱动到 compute runtime 26.18 以避免兼容性问题：

   git clone https://github.com/vllm-project/vllm.git
   cd vllm
   pip install --upgrade pip
   pip install -v -r requirements/xpu.txt
   

3. 安装 vLLM XPU 后端：

   VLLM_TARGET_DEVICE=xpu pip install --no-build-isolation -e . -v
   

triton shim 说明：requirements/xpu.txt 锁定了 triton==3.7.2+xpu——一个托管在 https://wheels.vllm.ai/xpu 上的兼容 shim，透明解析到真正的 Intel XPU 实现（triton-xpu）。其存在原因是部分传递依赖（如 xgrammar）无条件要求字面名为 triton 的发行版，否则在 XPU 上会错误解析到仅面向 NVIDIA 的 PyPI triton，引发正确性或运行期问题。无需手动卸载/重装，pip install 与 uv pip install --index-strategy unsafe-best-match 都会自动解析到正确包。

分布式后端：XPU 平台在 torch < 2.8 时使用 torch-ccl，torch ≥ 2.8 时使用 xccl（torch 2.8 起内置 xccl 作为 XPU 后端）。

支持特性：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 实例，会自动启动一个，num-gpus 等于 parallel_config.world_size；建议预先启动 ray 集群，可参考辅助脚本 examples/ray_serving/run_cluster.sh。

Apple Silicon 安装（vLLM-Metal）

Apple Silicon 上使用社区维护的硬件插件 vLLM-Metal：它以 MLX 为计算后端，通过 Apple Metal 框架提供原生 GPU 加速，并配合 Hugging Face mlx-community 组织的 MLX 优化模型（含量化版本）。

要求：macOS Sonoma+、Apple Silicon 硬件、启用 Metal 支持。安装即完成三件事：建立合适的 Python 环境、安装 MLX 及依赖、安装 vLLM-Metal 包。

安装后即可使用其内置 CLI 启动 OpenAI 兼容服务：

# 激活 vLLM-Metal 环境
source ~/.venv-vllm-metal/bin/activate

# 启动 API 服务（指定 mlx-community 模型，或使用默认模型）
vllm serve

服务运行后，交互方式有三：

方式 1：交互式聊天

source ~/.venv-vllm-metal/bin/activate
vllm chat

方式 2：curl 请求 API

curl http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{"role": "user", "content": "Hello!"}],
    "max_tokens": 50
  }'

方式 3：Python + OpenAI SDK

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8000/v1",
    api_key="dummy"  # 本地服务无需鉴权
)

response = client.chat.completions.create(
    model="mlx-community/Qwen2.5-0.5B-Instruct-4bit",
    messages=[{"role": "user", "content": "Hello!"}]
)

print(response.choices[0].message.content)

vllm CLI 的更多命令细节见 OpenAI 兼容服务器文档。vLLM-Metal 提供的能力包括：Metal 原生 GPU 加速、面向 Apple Silicon 优化的 MLX 计算后端、OpenAI 兼容 API 服务器，以及对流行模型架构的支持；具体特性边界以其项目文档为准。

Docker 部署：官方镜像与源码构建

NVIDIA：官方预构建镜像

官方镜像 vllm/vllm-openai 提供 OpenAI 兼容服务：

docker run --runtime nvidia --gpus all \
    -v ~/.cache/huggingface:/root/.cache/huggingface \
    --env "HF_TOKEN=$HF_TOKEN" \
    -p 8000:8000 \
    --ipc=host \
    vllm/vllm-openai:latest \
    --model Qwen/Qwen3-0.6B

Podman 等价写法：

podman run --device nvidia.com/gpu=all \
-v ~/.cache/huggingface:/root/.cache/huggingface \
--env "HF_TOKEN=$HF_TOKEN" \
-p 8000:8000 \
--ipc=host \
docker.io/vllm/vllm-openai:latest \
--model Qwen/Qwen3-0.6B

在镜像 tag 后可追加任意 engine-args。三点重要说明：

• 共享内存：--ipc=host 或 --shm-size 二选一。vLLM 基于 PyTorch，其跨进程数据共享（尤其张量并行推理）依赖共享内存；

• 可选依赖不包含在镜像中（避免许可问题）。需要时基于基础镜像加一层安装，且版本必须与基础镜像匹配：

  FROM vllm/vllm-openai:v0.11.0
  
  # 例如安装 audio 可选依赖
  RUN uv pip install --system vllm[audio]==0.11.0
  

• 使用 transformers 开发版（某些新模型只在 transformers main 分支可用）：

  FROM vllm/vllm-openai:latest
  
  RUN uv pip install --system git+https://github.com/huggingface/transformers.git
  

旧 CUDA 驱动系统：启用 CUDA 兼容库

vLLM 的 Docker 镜像预装了 CUDA 兼容性（compatibility）库，可在宿主驱动旧于镜像 CUDA Toolkit 版本时运行 vLLM，但仅支持部分专业/数据中心 GPU。CUDA 13 镜像在正常运行时要求宿主内核 ≥ Linux 4.15（CUDA 13 需要 R580+ 驱动）；兼容模式支持 R535 与 R570 宿主驱动，其中 R535 将最低内核降至 Linux 3.10，R570 仍要求 Linux 4.15。开启方式：

docker run --runtime nvidia --gpus all \
    -v ~/.cache/huggingface:/root/.cache/huggingface \
    -p 8000:8000 \
    --env "HF_TOKEN=<secret>" \
    --env "VLLM_ENABLE_CUDA_COMPATIBILITY=1" \
    vllm/vllm-openai <args...>

该环境变量会自动在加载 PyTorch 及依赖前把 LD_LIBRARY_PATH 指向兼容性库。

从源码构建 NVIDIA 镜像

使用仓库提供的 docker/Dockerfile：

# 可选：--build-arg max_jobs=8 --build-arg nvcc_threads=2
DOCKER_BUILDKIT=1 docker build . \
    --target vllm-openai \
    --tag vllm/vllm-openai \
    --file docker/Dockerfile

要点：

• 默认会为所有 GPU 类型构建以获得最广分发；只构建当前 GPU 架构时可加 --build-arg torch_cuda_arch_list="" 把架构选择委托给 PyTorch（需要构建时 GPU 对容器可见，标准 BuildKit 构建不暴露 GPU，PyTorch 会回退到常见架构列表）；
• Podman 构建可能需 --security-opt label=disable 关闭 SELinux 标签以避免已知问题；
• 未改 C++/CUDA 代码时可用预编译 wheel 大幅缩短 Docker 构建时间：加 --build-arg VLLM_USE_PRECOMPILED="1" 启用；默认按与上游 main 的 merge-base commit 自动从 nightly 索引定位 wheel；--build-arg VLLM_PRECOMPILED_WHEEL_COMMIT=<commit_hash> 可指定特定 commit。

Arm64/aarch64（Grace-Hopper / Grace-Blackwell）：加 --platform "linux/arm64"。多个模块需编译，耗时较长；建议用 --build-arg max_jobs= 与 --build-arg nvcc_threads= 提速，但 max_jobs 应显著大于 nvcc_threads，并留意并行编译的内存占用。GH200 上的示例（内存占用约 15GB，构建约 25 分钟，镜像约 6.93GB）：

DOCKER_BUILDKIT=1 docker build . \
--file docker/Dockerfile \
--target vllm-openai \
--platform "linux/arm64" \
-t vllm/vllm-gh200-openai:latest \
--build-arg max_jobs=66 \
--build-arg nvcc_threads=2 \
--build-arg BUILD_BASE_IMAGE=pytorch/manylinuxaarch64-builder:cuda13.0-78e737ad29420ffc4800e677c51e2a852caf8359 \
--build-arg torch_cuda_arch_list="9.0 10.0+PTX"

(G)B300 推荐 CUDA 13：

DOCKER_BUILDKIT=1 docker build \
--build-arg CUDA_VERSION=13.0.2 \
--build-arg BUILD_BASE_IMAGE=pytorch/manylinuxaarch64-builder:cuda13.0-78e737ad29420ffc4800e677c51e2a852caf8359 \
--build-arg max_jobs=256 \
--build-arg nvcc_threads=2 \
--build-arg torch_cuda_arch_list='9.0 10.0+PTX' \
--platform "linux/arm64" \
--tag vllm/vllm-gb300-openai:latest \
--target vllm-openai \
-f docker/Dockerfile \
.

在 x86_64 主机上交叉构建 linux/arm64 镜像时，需要先用 QEMU 注册用户态静态处理器：

docker run --rm --privileged multiarch/qemu-user-static --reset -p yes

之后即可使用 --platform "linux/arm64"。文档同时提供了面向 NVIDIA Rubin 架构的 Preview 构建路径（INSTALL_RUBIN_PRERELEASE=true，需要 NVIDIA 内部 CUDA 13.4/13.5 开发镜像与预发布包），仅限有 NVIDIA 内部权限的用户，此处不再展开。

自定义镜像运行方式与官方镜像相同，把 vllm/vllm-openai 替换为构建时 -t 指定的 tag 即可。

AMD ROCm：官方镜像与源码构建

官方镜像 vllm/vllm-openai-rocm：

• vllm/vllm-openai-rocm:latest — 稳定发布
• vllm/vllm-openai-rocm:nightly — 最新开发分支预览构建

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

开发场景下可通过 --entrypoint /bin/bash 覆盖入口点进入交互 shell（再加 --network=host）。

已弃用：AMD 的 rocm/vllm 与 rocm/vllm-dev 镜像已被上述官方镜像取代，2026-01-20 起官方镜像在上游 Docker Hub 可用，请迁移。

源码构建分两层。可选的 docker/Dockerfile.rocm_base 搭建 ROCm 软件栈（通常已有预构建基础镜像可复用）：

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

然后构建 docker/Dockerfile.rocm（默认 ROCm 7.0，entrypoint 为 vllm serve）。构建必须启用 buildkit（环境变量 DOCKER_BUILDKIT=1 或在 /etc/docker/daemon.json 中开启 "features": {"buildkit": true} 并重启 daemon）：

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

可用构建参数：BASE_IMAGE（基础镜像，默认 AMD 维护的 rocm/vllm-dev:base）、ARG_PYTORCH_ROCM_ARCH（覆盖基础镜像的 gfx 架构值）。运行自定义镜像的命令与官方镜像一致（见上文，注意 --group-add=video、--cap-add=SYS_PTRACE、--device /dev/kfd、--device /dev/dri 等 ROCm 必需的容器参数）。

Intel XPU：官方镜像与源码构建

官方镜像 vllm/vllm-openai-xpu：latest（自 v0.26.0 起提供）、nightly。

docker run --rm \
    --network=host \
    --device /dev/dri:/dev/dri \
    -v /dev/dri/by-path:/dev/dri/by-path \
    -v ~/.cache/huggingface:/root/.cache/huggingface \
    --env "HF_TOKEN=$HF_TOKEN" \
    --ipc=host \
    --privileged \
    vllm/vllm-openai-xpu:<tag> \
    --model Qwen/Qwen3-0.6B

开发时同样可用 --entrypoint /bin/bash 进入交互 shell。源码构建基于 docker/Dockerfile.xpu：

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

平台检测机制：安装结果如何在运行期生效

从源码结构看，安装时选择的设备形态最终由两套机制衔接：

1. 构建期：setup.py 读取 envs.VLLM_TARGET_DEVICE（未设置时按操作系统与探测结果自动推断为 rocm/xpu/cuda/cpu，macOS 强制 cpu），并通过 CMake 参数 -DVLLM_TARGET_DEVICE 传递给 C++/CUDA 扩展编译；envs.VLLM_USE_PRECOMPILED 则控制是否跳过编译、直接复用预编译产物。
2. 运行期：平台插件体系位于 vllm/platforms/__init__.py，通过 PLATFORM_PLUGINS_GROUP 插件组加载，内置实现包括 vllm/platforms/cuda.py、vllm/platforms/rocm.py、vllm/platforms/xpu.py 以及 CPU/TPU/zen 平台。这也解释了为什么 wheel 的“平台专属性”如此之强——CUDA wheel 里编译的就是 CUDA 平台的 kernel，装到 AMD 机器上自然找不到 libcudart.so。

版本信息方面，vllm/version.py 从 _version 模块读取版本号，读取失败时回退为 dev——所以排查问题时先确认 vllm --version 是否输出了真实版本，有助于区分“官方发布 wheel”与“源码安装”的差异。

各平台的功能支持矩阵（特性 × 硬件兼容性）见 Feature x Hardware 文档。

关键环境变量速查

环境变量	适用场景	作用
VLLM_USE_PRECOMPILED	Python-only 构建 / Docker 构建	复用预编译 C++/CUDA 产物与 vllm-rs，跳过编译
VLLM_PRECOMPILED_WHEEL_LOCATION	Python-only 构建	直接指定 wheel URL/本地路径，跳过查找逻辑
VLLM_PRECOMPILED_WHEEL_COMMIT	Python-only 构建	覆盖下载的预编译 wheel commit；nightly = main 上最近已构建提交
VLLM_PRECOMPILED_WHEEL_VARIANT	Python-only 构建	指定变体子目录（cu129/cu130/cpu/rocm700/rocm721）
VLLM_MAIN_CUDA_VERSION	Python-only 构建	覆盖 CUDA 变体的自动探测
VLLM_TARGET_DEVICE	源码构建	指定构建目标设备；empty 用于非 Linux 开发环境
MAX_JOBS	源码构建	限制并发编译任务数，防止内存/负载过载
CUDA_HOME	CUDA 源码构建	指向 CUDA Toolkit 安装路径，需保证 nvcc 可执行
VLLM_CUTLASS_SRC_DIR	CUDA 源码构建	指向本地 cutlass 源码目录
PYTORCH_ROCM_ARCH	ROCm 源码构建	指定 gfx 架构，如 gfx942
VLLM_ENABLE_CUDA_COMPATIBILITY	Docker 运行	启用 CUDA 兼容库，支持旧宿主驱动
UV_TORCH_BACKEND	uv 安装	等价于 --torch-backend，如 auto、cu130

小结

vLLM 的 GPU 安装路径可以归纳为三条主线：能装预编译 wheel 就绝不源码构建（CUDA 用 uv pip install vllm --torch-backend=auto，ROCm 认准 Python 3.12 + wheels.vllm.ai/rocm 索引，XPU 必须 Python 3.12 并双索引）；只改 Python 就用 VLLM_USE_PRECOMPILED=1 免编译开发（配合 build_rust.sh 单独重建 Rust 前端）；部署优先官方 Docker 镜像（vllm/vllm-openai、vllm/vllm-openai-rocm、vllm/vllm-openai-xpu），并牢记 --ipc=host 共享内存参数。当需要定位回归或尝鲜 nightly 时，利用 wheels.vllm.ai 的按 commit 索引安装是官方推荐的二分手段。理解 setup.py 中的设备推断与 vllm/platforms/ 插件体系，能帮助你把安装报错（如 libcudart.so 缺失、架构不匹配）快速归因到“装错了平台的 wheel”或“驱动/工具链版本不达标”这两类根因。