GPU¶
vLLM 是一個 Python 庫，支援以下 GPU 型號。選擇您的 GPU 型別以檢視特定於供應商的說明
vLLM 包含預編譯的 C++ 和 CUDA (12.8) 二進位制檔案。
vLLM 支援 ROCm 6.3 或更高版本以及 torch 2.8.0 或更高版本的 AMD GPU。
提示
Docker 是在 ROCm 上使用 vLLM 的推薦方式。
vLLM 最初支援 Intel GPU 平臺上的基本模型推理和服務。
要求¶
- 作業系統：Linux
- Python: 3.10 -- 3.13
注意
vLLM 不支援 Windows 原生。要在 Windows 上執行 vLLM，您可以使用支援 Linux 子系統的 Windows (WSL) 和相容的 Linux 發行版，或者使用一些社群維護的 fork，例如 https://github.com/SystemPanic/vllm-windows。
- 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 資料中心 GPU，Intel ARC GPU
- OneAPI 要求：oneAPI 2025.1
- Python：3.12
警告
提供的 IPEX whl 特定於 Python3.12，因此必須使用此版本。
使用 Python 進行設定¶
建立新的 Python 環境¶
建議使用 uv，一個非常快速的 Python 環境管理器，來建立和管理 Python 環境。請按照 文件 安裝 uv。安裝 uv 後，您可以使用以下命令建立新的 Python 環境。
注意
透過 conda 安裝的 PyTorch 會靜態連結 NCCL 庫，這可能導致 vLLM 嘗試使用 NCCL 時出現問題。有關更多詳細資訊，請參閱 https://github.com/vllm-project/vllm/issues/8420。
為了獲得高效能，vLLM 必須編譯許多 cuda 核心。不幸的是，編譯會導致與其他 CUDA 版本和 PyTorch 版本之間的二進位制不相容，即使是相同的 PyTorch 版本，如果構建配置不同，也會出現不相容。
因此，建議在 **全新** 環境中安裝 vLLM。如果您有不同的 CUDA 版本或想使用現有的 PyTorch 安裝，則需要從原始碼構建 vLLM。有關更多詳細資訊，請參閱 下方。
此裝置沒有關於建立新 Python 環境的額外資訊。
此裝置沒有關於建立新 Python 環境的額外資訊。
預構建的 Wheels¶
pip
我們建議利用 uv 透過檢查已安裝的 CUDA 驅動程式版本（使用 --torch-backend=auto 或 UV_TORCH_BACKEND=auto）來在執行時自動選擇合適的 PyTorch 索引。要選擇特定的後端（例如 cu128），請設定 --torch-backend=cu128（或 UV_TORCH_BACKEND=cu128）。如果這不起作用，請嘗試執行 uv self update 來首先更新 uv。
注意
NVIDIA Blackwell GPU（B200、GB200）需要最低 CUDA 12.8，因此請確保您安裝的 PyTorch wheel 版本至少為此版本。PyTorch 本身提供了一個專用介面，用於確定針對給定目標配置執行的合適 pip 命令。
目前，vLLM 的二進位制檔案預設使用 CUDA 12.9 和公共 PyTorch 發行版編譯。我們還提供使用 CUDA 12.8、13.0 和公共 PyTorch 發行版編譯的 vLLM 二進位制檔案。
# Install vLLM with a specific CUDA version (e.g., 13.0).
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 # or other
uv pip install https://github.com/vllm-project/vllm/releases/download/v${VLLM_VERSION}/vllm-${VLLM_VERSION}+cu${CUDA_VERSION}-cp38-abi3-manylinux_2_31_x86_64.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：預設變體（在VLLM_MAIN_CUDA_VERSION中指定的 CUDA 版本）使用main分支的最新提交構建。目前是 CUDA 12.9。https://wheels.vllm.ai/nightly/<variant>：所有其他變體。現在包括cu130和cpu。預設變體（cu129）也有一個子目錄以保持一致性。
要從夜間索引安裝，請執行
uv pip install -U vllm \
--torch-backend=auto \
--extra-index-url https://wheels.vllm.ai/nightly # add variant subdirectory here if needed
pip 注意事項
使用 pip 從夜間索引安裝是不受支援的，因為 pip 會合並來自 --extra-index-url 和預設索引的包，僅選擇最新版本，這使得安裝釋出版本之前的開發版本變得困難。相比之下，uv 使額外的索引比預設索引具有 更高的優先順序。
如果您堅持使用 pip，則必須指定 wheel 檔案的完整 URL（可以從網頁上獲取）。
pip install -U https://wheels.vllm.ai/nightly/vllm-0.11.2.dev399%2Bg3c7461c18-cp38-abi3-manylinux_2_31_x86_64.whl # current nightly build (the filename will change!)
pip install -U https://wheels.vllm.ai/${VLLM_COMMIT}/vllm-0.11.2.dev399%2Bg3c7461c18-cp38-abi3-manylinux_2_31_x86_64.whl # from specific commit
安裝特定版本¶
如果您想訪問之前提交的輪子（例如，為了二分查詢行為更改、效能迴歸），您可以在 URL 中指定提交雜湊。
目前沒有預構建的 ROCm wheel。
目前沒有預構建的 XPU wheel。
從原始碼構建 Wheel¶
透過純 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 .
此命令將執行以下操作：
- 查詢您 vLLM 克隆中的當前分支。
- 識別主分支中對應的基線提交。
- 下載基線提交的預構建 wheel。
- 在安裝中使用其編譯的庫。
注意
- 如果您更改 C++ 或核心程式碼，則不能使用純 Python 構建；否則，您將看到關於庫未找到或符號未定義的匯入錯誤。
- 如果您 rebase 了您的開發分支，建議解除安裝 vllm 並重新執行上述命令以確保您的庫是最新的。
如果您在執行上述命令時遇到 wheel 未找到的錯誤，可能是因為您基於的主分支上的提交剛剛合併，並且 wheel 正在構建中。在這種情況下，您可以等待大約一個小時再試，或者使用 VLLM_PRECOMPILED_WHEEL_LOCATION 環境變數在安裝中手動指定前一個提交。
export VLLM_PRECOMPILED_WHEEL_COMMIT=$(git rev-parse HEAD~1) # or earlier commit on main
export VLLM_USE_PRECOMPILED=1
uv pip install --editable .
有更多環境變數可以控制純 Python 構建的行為
VLLM_PRECOMPILED_WHEEL_LOCATION：指定要使用的預編譯 wheel 的確切 wheel URL 或本地檔案路徑。所有其他查詢 wheel 的邏輯將被跳過。VLLM_PRECOMPILED_WHEEL_COMMIT：覆蓋要下載預編譯 wheel 的提交雜湊。它可以是nightly以使用主分支上最後一個 **已構建** 的提交。VLLM_PRECOMPILED_WHEEL_VARIANT：指定 nightly 索引上要使用的變體子目錄，例如cu129、cpu。如果未指定，將嘗試使用VLLM_MAIN_CUDA_VERSION的 CUDA 變體，然後回退到遠端索引上的預設變體。
您可以在 安裝最新程式碼 中找到有關 vLLM wheel 的更多資訊。
注意
您的原始碼可能與最新的 vLLM wheel 具有不同的提交 ID，這可能會導致未知錯誤。建議使用與您安裝的 vLLM wheel 相同的提交 ID 的原始碼。請參閱 安裝最新程式碼 以獲取安裝指定 wheel 的說明。
完整構建（需要編譯）¶
如果您想修改 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 核心更改，在完成初始 uv pip install -e . 設定後，請考慮使用 增量編譯工作流 以顯著加快僅對修改過的核心程式碼的重新構建。
使用現有的 PyTorch 安裝¶
在某些情況下，PyTorch 依賴項無法使用 uv 輕鬆安裝，例如，當使用非預設 PyTorch 構建（如 nightly 或自定義構建）編譯 vLLM 時。
使用現有的 PyTorch 安裝構建 vLLM
# install PyTorch first, either from PyPI or from source
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 作為停用構建隔離的包。
# install PyTorch first, either from PyPI or from source
git clone https://github.com/vllm-project/vllm.git
cd vllm
# pip install -e . does not work directly, only uv can do this
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 來限制同時執行的編譯作業數量。例如：
這在您在功能較弱的機器上構建時尤其有用。例如，當您使用 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/Dockerfile.rocm_base。Dockerfile 是一種安裝步驟的形式。
-
安裝先決條件（如果您已處於包含以下內容的已安裝環境/docker 中，則跳過此步驟）
要安裝 PyTorch，您可以從一個全新的 docker 映象開始，例如
rocm/pytorch:rocm7.0_ubuntu22.04_py3.10_pytorch_release_2.8.0、rocm/pytorch-nightly。如果您使用的是 docker 映象，則可以跳到步驟 3。或者，您可以使用 PyTorch wheels 安裝 PyTorch。您可以在 PyTorch 入門中檢視 PyTorch 安裝指南。示例：
-
按照 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 ../..注意
- 已驗證的
$TRITON_BRANCH可以在 docker/Dockerfile.rocm_base 中找到。 - 如果在構建 triton 時看到與下載包相關的 HTTP 問題，請重試，因為 HTTP 錯誤是間歇性的。
- 已驗證的
-
可選地，如果您選擇使用 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 ..注意
- 已驗證的
$FA_BRANCH可以在 docker/Dockerfile.rocm_base 中找到。
- 已驗證的
-
如果您選擇自行構建 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。 - 已驗證的
$AITER_BRANCH_OR_COMMIT可以在 docker/Dockerfile.rocm_base 中找到。
- 您需要根據您的需求配置
-
構建 vLLM。例如，可以使用以下步驟構建 ROCM 7.0 上的 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 -r requirements/rocm.txt # To build for a single architecture (e.g., MI300) for faster installation (recommended): export PYTORCH_ROCM_ARCH="gfx942" # To build vLLM for multiple arch MI210/MI250/MI300, use this instead # export PYTORCH_ROCM_ARCH="gfx90a;gfx942" python3 setup.py develop這可能需要 5-10 分鐘。目前，
pip install .不適用於 ROCm 安裝。提示
- ROCm 版的 PyTorch 理想情況下應與 ROCm 驅動程式版本匹配。
提示
- 對於 MI300x (gfx942) 使用者，為了獲得最佳效能，請參考MI300x 調優指南，瞭解系統和工作流程級別的效能最佳化和調優技巧。對於 vLLM，請參閱vLLM 效能最佳化。
- 首先，安裝必需的驅動程式和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 後端。
使用 Docker 進行設定¶
預構建的映象¶
有關使用官方 Docker 映象的說明，請參閱 使用 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 和測試，不適用於生產環境。它們將在幾天後過期。
最新程式碼可能包含 bug 且可能不穩定。請謹慎使用。
AMD Infinity hub for vLLM 提供了一個預構建的、最佳化的 docker 映象，用於在 AMD Instinct™ MI300X 加速器上驗證推理效能。AMD 還提供來自Docker Hub 的 nightly 預構建 docker 映象，其中安裝了 vLLM 及其所有依賴項。
命令
docker pull rocm/vllm-dev:nightly # to get the latest image
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
提示
請參閱AMD Instinct MI300X 上的 LLM 推理效能驗證，瞭解如何使用此預構建 docker 映象的說明。
從原始碼構建映象¶
有關從原始碼構建 Docker 映象的說明，請參閱 從原始碼構建 vLLM 的 Docker 映象。
從原始碼構建 Docker 映象是在 ROCm 上使用 vLLM 的推薦方式。
(可選) 構建帶 ROCm 軟體棧的映象
從 docker/Dockerfile.rocm_base 構建一個 docker 映象，該映象設定了 vLLM 所需的 ROCm 軟體棧。**此步驟是可選的，因為此 rocm_base 映象通常預先構建並存儲在 Docker Hub 的 rocm/vllm-dev:base 標籤下，以加快使用者體驗。** 如果您選擇自行構建此 rocm_base 映象，步驟如下：
使用者使用 buildkit 啟動 docker 構建非常重要。使用者可以在呼叫 docker build 命令時將 DOCKER_BUILDKIT=1 設定為環境變數，或者使用者需要將 buildkit 配置在 docker 守護程序的 /etc/docker/daemon.json 中，如下所示，然後重新啟動守護程序。
要為 MI200 和 MI300 系列在 ROCm 7.0 上構建 vllm，您可以使用預設設定。
構建帶 vLLM 的映象¶
首先，從 docker/Dockerfile.rocm 構建一個 docker 映象並從該映象啟動一個 docker 容器。使用者使用 buildkit 啟動 docker 構建非常重要。使用者可以在呼叫 docker build 命令時將 DOCKER_BUILDKIT=1 設定為環境變數，或者使用者需要將 buildkit 配置在 docker 守護程序的 /etc/docker/daemon.json 中，如下所示，然後重新啟動守護程序。
docker/Dockerfile.rocm 預設使用 ROCm 7.0，但在舊版 vLLM 中也支援 ROCm 5.7、6.0、6.1、6.2、6.3 和 6.4。它提供了使用以下引數自定義 docker 映象構建的靈活性：
BASE_IMAGE：指定執行docker build時使用的基礎映象。預設值rocm/vllm-dev:base是 AMD 釋出和維護的映象。它使用 docker/Dockerfile.rocm_base 構建。ARG_PYTORCH_ROCM_ARCH：允許覆蓋基礎 docker 映象中的 gfx 架構值。
在執行 docker build 時，可以使用 --build-arg 選項傳遞它們的值。
要為 MI200 和 MI300 系列在 ROCm 7.0 上構建 vllm，您可以使用預設設定。
要執行上述 docker 映象 vllm-rocm，請使用以下命令：
命令
其中 <path/to/model> 是模型儲存的位置，例如 llama2 或 llama3 模型的權重。
支援的功能¶
有關功能支援資訊，請參閱 功能 x 硬體 相容性矩陣。
有關功能支援資訊，請參閱 功能 x 硬體 相容性矩陣。
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 例項，將自動啟動一個 ray 例項，其 num-gpus 等於 parallel_config.world_size。我們建議在執行前正確啟動一個 ray 叢集，請參考 examples/online_serving/run_cluster.sh 輔助指令碼。