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 叢集，請參考