CPU¶

vLLM 是一個支援以下 CPU 變體的 Python 庫。選擇您的 CPU 型別以檢視特定於供應商的說明

Intel/AMD x86ARM AArch64Apple 晶片IBM Z (S390X)

vLLM 支援在 x86 CPU 平臺上進行基本的模型推理和服務，支援資料型別 FP32、FP16 和 BF16。

vLLM 已適配在支援 NEON 的 ARM64 CPU 上執行，利用了最初為 x86 平臺開發的 CPU 後端。

ARM CPU 後端目前支援 Float32、FP16 和 BFloat16 資料型別。

警告

此裝置沒有預構建的 wheel 或映象，因此您必須從原始碼構建 vLLM。

vLLM 實驗性支援帶 Apple 晶片的 macOS。目前，使用者必須從原始碼構建 vLLM 才能在 macOS 上原生執行。

目前 macOS 的 CPU 實現支援 FP32 和 FP16 資料型別。

警告

此裝置沒有預構建的 wheel 或映象，因此您必須從原始碼構建 vLLM。

vLLM 實驗性支援 IBM Z 平臺上的 s390x 架構。目前，使用者必須從 vLLM 原始碼構建才能在 IBM Z 平臺上原生執行。

目前 s390x 架構的 CPU 實現僅支援 FP32 資料型別。

警告

此裝置沒有預構建的 wheel 或映象，因此您必須從原始碼構建 vLLM。

要求¶

Python：3.9 - 3.12

Intel/AMD x86ARM AArch64Apple 晶片IBM Z (S390X)

作業系統：Linux
CPU 標誌：avx512f, avx512_bf16 (可選), avx512_vnni (可選)

提示

使用 lscpu 檢查 CPU 標誌。

作業系統：Linux
編譯器：gcc/g++ >= 12.3.0 (可選，推薦)
指令集架構 (ISA)：需要支援 NEON

作業系統：macOS Sonoma 或更高版本
SDK：XCode 15.4 或更高版本，帶命令列工具
編譯器：Apple Clang >= 15.0.0

作業系統：Linux
SDK：gcc/g++ >= 12.3.0 或更高版本，帶命令列工具
指令集架構 (ISA)：需要支援 VXE。適用於 Z14 及以上版本。
構建安裝 Python 包：pyarrow, torch 和 torchvision

使用 Python 進行設定¶

建立新的 Python 環境¶

建議使用 uv（一個非常快速的 Python 環境管理器）來建立和管理 Python 環境。請按照文件安裝 uv。安裝 uv 後，您可以使用以下命令建立新的 Python 環境並安裝 vLLM

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

預構建的 Wheels¶

目前，沒有預構建的 CPU wheel。

從原始碼構建 Wheel¶

Intel/AMD x86ARM AArch64Apple 晶片IBM Z (s390x)

首先，安裝推薦的編譯器。我們建議使用 gcc/g++ >= 12.3.0 作為預設編譯器，以避免潛在問題。例如，在 Ubuntu 22.4 上，您可以執行

sudo apt-get update  -y
sudo apt-get install -y --no-install-recommends ccache git curl wget ca-certificates gcc-12 g++-12 libtcmalloc-minimal4 libnuma-dev ffmpeg libsm6 libxext6 libgl1 jq lsof
sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-12 10 --slave /usr/bin/g++ g++ /usr/bin/g++-12

其次，克隆 vLLM 專案

git clone https://github.com/vllm-project/vllm.git vllm_source
cd vllm_source

第三，安裝用於構建 vLLM CPU 後端的 Python 包

pip install --upgrade pip
pip install -v -r requirements/cpu-build.txt --extra-index-url https://download.pytorch.org/whl/cpu
pip install -v -r requirements/cpu.txt --extra-index-url https://download.pytorch.org/whl/cpu

最後，構建並安裝 vLLM CPU 後端

VLLM_TARGET_DEVICE=cpu python setup.py install

如果您想開發 vLLM，請以可編輯模式安裝。

VLLM_TARGET_DEVICE=cpu python setup.py develop

注意

如果您從原始碼構建 vLLM 且不使用預構建映象，請記住在 x86 機器上執行 vLLM 之前設定 LD_PRELOAD="/usr/lib/x86_64-linux-gnu/libtcmalloc_minimal.so.4:$LD_PRELOAD"。

首先，安裝推薦的編譯器。我們建議使用 gcc/g++ >= 12.3.0 作為預設編譯器，以避免潛在問題。例如，在 Ubuntu 22.4 上，您可以執行

sudo apt-get update  -y
sudo apt-get install -y --no-install-recommends ccache git curl wget ca-certificates gcc-12 g++-12 libtcmalloc-minimal4 libnuma-dev ffmpeg libsm6 libxext6 libgl1 jq lsof
sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-12 10 --slave /usr/bin/g++ g++ /usr/bin/g++-12

其次，克隆 vLLM 專案

git clone https://github.com/vllm-project/vllm.git vllm_source
cd vllm_source

第三，安裝用於構建 vLLM CPU 後端的 Python 包

pip install --upgrade pip
pip install -v -r requirements/cpu-build.txt --extra-index-url https://download.pytorch.org/whl/cpu
pip install -v -r requirements/cpu.txt --extra-index-url https://download.pytorch.org/whl/cpu

最後，構建並安裝 vLLM CPU 後端

VLLM_TARGET_DEVICE=cpu python setup.py install

如果您想開發 vLLM，請以可編輯模式安裝。

VLLM_TARGET_DEVICE=cpu python setup.py develop

注意

如果您從原始碼構建 vLLM 且不使用預構建映象，請記住在 x86 機器上執行 vLLM 之前設定 LD_PRELOAD="/usr/lib/x86_64-linux-gnu/libtcmalloc_minimal.so.4:$LD_PRELOAD"。

已在 AWS Graviton3 例項上進行相容性測試。

安裝 XCode 和包含 Apple Clang 的命令列工具後，執行以下命令從原始碼構建並安裝 vLLM。

git clone https://github.com/vllm-project/vllm.git
cd vllm
pip install -r requirements/cpu.txt
pip install -e .

注意

在 macOS 上，VLLM_TARGET_DEVICE 會自動設定為 cpu，這是目前唯一支援的裝置。

故障排除

如果構建出現類似以下片段的錯誤，即找不到標準 C++ 標頭檔案，請嘗試刪除並重新安裝您的 Xcode 命令列工具。

[...] fatal error: 'map' file not found
        1 | #include <map>
            |          ^~~~~
    1 error generated.
    [2/8] Building CXX object CMakeFiles/_C.dir/csrc/cpu/pos_encoding.cpp.o

[...] fatal error: 'cstddef' file not found
        10 | #include <cstddef>
            |          ^~~~~~~~~
    1 error generated.

在構建 vLLM 之前，從包管理器安裝以下包。例如在 RHEL 9.4 上

dnf install -y \
    which procps findutils tar vim git gcc g++ make patch make cython zlib-devel \
    libjpeg-turbo-devel libtiff-devel libpng-devel libwebp-devel freetype-devel harfbuzz-devel \
    openssl-devel openblas openblas-devel wget autoconf automake libtool cmake numactl-devel

安裝 rust>=1.80，這是安裝 outlines-core 和 uvloop Python 包所需的。

curl https://sh.rustup.rs -sSf | sh -s -- -y && \
    . "$HOME/.cargo/env"

執行以下命令從原始碼構建並安裝 vLLM。

提示

請在構建 vLLM 之前，從原始碼構建以下依賴項：torchvision、pyarrow。

    sed -i '/^torch/d' requirements-build.txt    # remove torch from requirements-build.txt since we use nightly builds
    pip install -v \
        --extra-index-url https://download.pytorch.org/whl/nightly/cpu \
        -r requirements-build.txt \
        -r requirements-cpu.txt \
    VLLM_TARGET_DEVICE=cpu python setup.py bdist_wheel && \
    pip install dist/*.whl

使用 Docker 進行設定¶

預構建的映象¶

Intel/AMD x86

https://gallery.ecr.aws/q9t5s3a7/vllm-cpu-release-repo

警告

如果將預構建映象部署在僅包含 avx512f 的機器上，可能會出現 Illegal instruction 錯誤。建議使用 --build-arg VLLM_CPU_AVX512BF16=false 和 --build-arg VLLM_CPU_AVX512VNNI=false 為這些機器構建映象。

從原始碼構建映象¶

Intel/AMD x86ARM AArch64Apple 晶片IBM Z (S390X)

docker build -f docker/Dockerfile.cpu \
        --build-arg VLLM_CPU_AVX512BF16=false (default)|true \
        --build-arg VLLM_CPU_AVX512VNNI=false (default)|true \
        --tag vllm-cpu-env \
        --target vllm-openai .

# Launching OpenAI server
docker run --rm \
            --privileged=true \
            --shm-size=4g \
            -p 8000:8000 \
            -e VLLM_CPU_KVCACHE_SPACE=<KV cache space> \
            -e VLLM_CPU_OMP_THREADS_BIND=<CPU cores for inference> \
            vllm-cpu-env \
            --model=meta-llama/Llama-3.2-1B-Instruct \
            --dtype=bfloat16 \
            other vLLM OpenAI server arguments

docker build -f docker/Dockerfile.cpu \
        --tag vllm-cpu-env .

# Launching OpenAI server
docker run --rm \
            --privileged=true \
            --shm-size=4g \
            -p 8000:8000 \
            -e VLLM_CPU_KVCACHE_SPACE=<KV cache space> \
            -e VLLM_CPU_OMP_THREADS_BIND=<CPU cores for inference> \
            vllm-cpu-env \
            --model=meta-llama/Llama-3.2-1B-Instruct \
            --dtype=bfloat16 \
            other vLLM OpenAI server arguments

docker build -f docker/Dockerfile.cpu \
        --tag vllm-cpu-env .

# Launching OpenAI server
docker run --rm \
            --privileged=true \
            --shm-size=4g \
            -p 8000:8000 \
            -e VLLM_CPU_KVCACHE_SPACE=<KV cache space> \
            -e VLLM_CPU_OMP_THREADS_BIND=<CPU cores for inference> \
            vllm-cpu-env \
            --model=meta-llama/Llama-3.2-1B-Instruct \
            --dtype=bfloat16 \
            other vLLM OpenAI server arguments

docker build -f docker/Dockerfile.s390x \
        --tag vllm-cpu-env .

# Launching OpenAI server
docker run --rm \
            --privileged=true \
            --shm-size=4g \
            -p 8000:8000 \
            -e VLLM_CPU_KVCACHE_SPACE=<KV cache space> \
            -e VLLM_CPU_OMP_THREADS_BIND=<CPU cores for inference> \
            vllm-cpu-env \
            --model=meta-llama/Llama-3.2-1B-Instruct \
            --dtype=float \
            other vLLM OpenAI server arguments

VLLM_CPU_KVCACHE_SPACE：指定 KV 快取大小（例如，VLLM_CPU_KVCACHE_SPACE=40 表示 KV 快取空間為 40 GiB），更大的設定將允許 vLLM 並行執行更多請求。此引數應根據硬體配置和使用者記憶體管理模式進行設定。預設值為 0。
VLLM_CPU_OMP_THREADS_BIND：指定用於 OpenMP 執行緒的 CPU 核心，可以設定為 CPU ID 列表或 auto（預設）。例如，VLLM_CPU_OMP_THREADS_BIND=0-31 表示將有 32 個 OpenMP 執行緒繫結到 0-31 CPU 核心。VLLM_CPU_OMP_THREADS_BIND=0-31|32-63 表示將有 2 個張量並行程序，rank0 的 32 個 OpenMP 執行緒繫結到 0-31 CPU 核心，rank1 的 OpenMP 執行緒繫結到 32-63 CPU 核心。透過設定為 auto，每個 rank 的 OpenMP 執行緒將分別繫結到各自 NUMA 節點中的 CPU 核心。
VLLM_CPU_NUM_OF_RESERVED_CPU：指定每個 rank 不用於 OpenMP 執行緒的 CPU 核心數量。此變數僅當 VLLM_CPU_OMP_THREADS_BIND 設定為 auto 時生效。預設值為 None。如果未設定此值且使用 auto 執行緒繫結，則當 world_size == 1 時不保留 CPU，當 world_size > 1 時每個 rank 保留 1 個 CPU。
VLLM_CPU_MOE_PREPACK（僅限 x86）：是否對 MoE 層使用預打包。這將傳遞給 ipex.llm.modules.GatedMLPMOE。預設值為 1 (True)。在不支援的 CPU 上，您可能需要將其設定為 0 (False)。
VLLM_CPU_SGL_KERNEL（僅限 x86，實驗性）：是否對線性層和 MoE 層使用小批次最佳化的核心，特別是對於線上服務等低延遲要求。這些核心需要 AMX 指令集、BFloat16 權重型別和可被 32 整除的權重形狀。預設值為 0 (False)。

常見問題¶

應使用哪種 `dtype`？¶

目前 vLLM CPU 使用模型預設設定作為 dtype。然而，由於 torch CPU 中 float16 支援不穩定，如果存在任何效能或精度問題，建議明確設定 dtype=bfloat16。

如何在 CPU 上啟動 vLLM 服務？¶

在使用線上服務時，建議為服務框架保留 1-2 個 CPU 核心，以避免 CPU 過載。例如，在具有 32 個物理 CPU 核心的平臺上，為框架保留 CPU 31，並使用 CPU 0-30 進行推理執行緒

export VLLM_CPU_KVCACHE_SPACE=40
export VLLM_CPU_OMP_THREADS_BIND=0-30
vllm serve facebook/opt-125m --dtype=bfloat16

或使用預設的自動執行緒繫結

export VLLM_CPU_KVCACHE_SPACE=40
export VLLM_CPU_NUM_OF_RESERVED_CPU=1
vllm serve facebook/opt-125m --dtype=bfloat16

注意，當 world_size == 1 時，建議手動為 vLLM 前端程序保留 1 個 CPU。

如何決定 `VLLM_CPU_OMP_THREADS_BIND`？¶

對於大多數情況，推薦使用預設的 auto 執行緒繫結。理想情況下，每個 OpenMP 執行緒將分別繫結到專用物理核心，每個 rank 的執行緒將分別繫結到同一個 NUMA 節點，並且當 world_size > 1 時，每個 rank 將保留 1 個 CPU 用於其他 vLLM 元件。如果遇到任何效能問題或意外的繫結行為，請嘗試按以下方式繫結執行緒。
在啟用超執行緒的平臺（16 個邏輯 CPU 核心 / 8 個物理 CPU 核心）上

命令

$ lscpu -e # check the mapping between logical CPU cores and physical CPU cores

# The "CPU" column means the logical CPU core IDs, and the "CORE" column means the physical core IDs. On this platform, two logical cores are sharing one physical core.
CPU NODE SOCKET CORE L1d:L1i:L2:L3 ONLINE    MAXMHZ   MINMHZ      MHZ
0    0      0    0 0:0:0:0          yes 2401.0000 800.0000  800.000
1    0      0    1 1:1:1:0          yes 2401.0000 800.0000  800.000
2    0      0    2 2:2:2:0          yes 2401.0000 800.0000  800.000
3    0      0    3 3:3:3:0          yes 2401.0000 800.0000  800.000
4    0      0    4 4:4:4:0          yes 2401.0000 800.0000  800.000
5    0      0    5 5:5:5:0          yes 2401.0000 800.0000  800.000
6    0      0    6 6:6:6:0          yes 2401.0000 800.0000  800.000
7    0      0    7 7:7:7:0          yes 2401.0000 800.0000  800.000
8    0      0    0 0:0:0:0          yes 2401.0000 800.0000  800.000
9    0      0    1 1:1:1:0          yes 2401.0000 800.0000  800.000
10   0      0    2 2:2:2:0          yes 2401.0000 800.0000  800.000
11   0      0    3 3:3:3:0          yes 2401.0000 800.0000  800.000
12   0      0    4 4:4:4:0          yes 2401.0000 800.0000  800.000
13   0      0    5 5:5:5:0          yes 2401.0000 800.0000  800.000
14   0      0    6 6:6:6:0          yes 2401.0000 800.0000  800.000
15   0      0    7 7:7:7:0          yes 2401.0000 800.0000  800.000

# On this platform, it is recommend to only bind openMP threads on logical CPU cores 0-7 or 8-15
$ export VLLM_CPU_OMP_THREADS_BIND=0-7
$ python examples/offline_inference/basic/basic.py

當在具有 NUMA 的多插槽機器上部署 vLLM CPU 後端並啟用張量並行或流水線並行時，每個 NUMA 節點都被視為一個 TP/PP rank。因此請注意將單個 rank 的 CPU 核心設定在同一個 NUMA 節點上，以避免跨 NUMA 節點的記憶體訪問。

如何決定 `VLLM_CPU_KVCACHE_SPACE`？¶

此值預設為 4GB。更大的空間可以支援更多的併發請求，更長的上下文長度。然而，使用者應注意每個 NUMA 節點的記憶體容量。每個 TP rank 的記憶體使用量是 weight shard size 和 VLLM_CPU_KVCACHE_SPACE 的總和，如果超過單個 NUMA 節點的容量，TP 工作程序將因記憶體不足而以 exitcode 9 終止。

如何為 vLLM CPU 進行效能調優？¶

首先，請確保執行緒繫結和 KV 快取空間設定正確並生效。您可以透過執行 vLLM 基準測試並透過 htop 觀察 CPU 核心使用情況來檢查執行緒繫結。

推理批次大小是影響效能的重要引數。更大的批次通常提供更高的吞吐量，更小的批次提供更低的延遲。從預設值開始調整最大批次大小以平衡吞吐量和延遲是提高特定平臺上 vLLM CPU 效能的有效方法。vLLM 中有兩個重要的相關引數

--max-num-batched-tokens，定義單個批次中令牌數量的限制，對第一個令牌的效能影響更大。預設值設定為
- 離線推理：4096 * world_size
- 線上服務：2048 * world_size
--max-num-seqs，定義單個批次中序列數量的限制，對輸出令牌的效能影響更大。
- 離線推理：256 * world_size
- 線上服務：128 * world_size

vLLM CPU 支援張量並行（TP）和流水線並行（PP）以利用多個 CPU 插槽和記憶體節點。有關 TP 和 PP 調優的更多細節，請參閱最佳化和調優。對於 vLLM CPU，如果 CPU 插槽和記憶體節點足夠，建議同時使用 TP 和 PP。

vLLM CPU 支援哪些量化配置？¶

vLLM CPU 支援以下量化
- AWQ (僅限 x86)
- GPTQ (僅限 x86)
- 壓縮張量 INT8 W8A8 (x86, s390x)

（僅限 x86）`VLLM_CPU_MOE_PREPACK` 和 `VLLM_CPU_SGL_KERNEL` 的用途是什麼？¶

兩者都需要 amx CPU 標誌。
- VLLM_CPU_MOE_PREPACK 可以為 MoE 模型提供更好的效能
- VLLM_CPU_SGL_KERNEL 可以為 MoE 模型和小批次場景提供更好的效能。

CPU¶

要求¶

使用 Python 進行設定¶

建立新的 Python 環境¶

預構建的 Wheels¶

從原始碼構建 Wheel¶

使用 Docker 進行設定¶

預構建的映象¶

從原始碼構建映象¶

相關執行時環境變數¶

常見問題¶

應使用哪種 dtype？¶

如何在 CPU 上啟動 vLLM 服務？¶

如何決定 VLLM_CPU_OMP_THREADS_BIND？¶

如何決定 VLLM_CPU_KVCACHE_SPACE？¶

如何為 vLLM CPU 進行效能調優？¶

vLLM CPU 支援哪些量化配置？¶

（僅限 x86）VLLM_CPU_MOE_PREPACK 和 VLLM_CPU_SGL_KERNEL 的用途是什麼？¶

應使用哪種 `dtype`？¶

如何決定 `VLLM_CPU_OMP_THREADS_BIND`？¶

如何決定 `VLLM_CPU_KVCACHE_SPACE`？¶

（僅限 x86）`VLLM_CPU_MOE_PREPACK` 和 `VLLM_CPU_SGL_KERNEL` 的用途是什麼？¶