CPU

CPU#

vLLM 是一个 Python 库，支持以下 CPU 变体。选择您的 CPU 类型以查看特定于供应商的说明

Intel/AMD x86

vLLM 最初支持在 x86 CPU 平台上进行基本模型推理和服务，数据类型为 FP32、FP16 和 BF16。

注意

此设备没有预构建的 wheels 或镜像，因此您必须从源代码构建 vLLM。

ARM AArch64

vLLM 已被适配为在支持 NEON 的 ARM64 CPU 上工作，利用最初为 x86 平台开发的 CPU 后端。

ARM CPU 后端目前支持 Float32、FP16 和 BFloat16 数据类型。

注意

此设备没有预构建的 wheels 或镜像，因此您必须从源代码构建 vLLM。

Apple silicon

vLLM 对 macOS 和 Apple silicon 具有实验性支持。目前，用户应从源代码构建 vLLM 以在 macOS 上本地运行。

目前，macOS 的 CPU 实现仅支持 FP32 和 FP16 数据类型。

注意

此设备没有预构建的 wheels 或镜像，因此您必须从源代码构建 vLLM。

IBM Z (S390X)

vLLM 对 IBM Z 平台上的 s390x 架构具有实验性支持。目前，用户应从 vLLM 源代码构建以在 IBM Z 平台上本地运行。

目前，s390x 架构的 CPU 实现仅支持 FP32 数据类型。

注意

此设备没有预构建的 wheels 或镜像，因此您必须从源代码构建 vLLM。

要求#

Python: 3.9 – 3.12

Intel/AMD x86

操作系统: Linux
编译器: gcc/g++ >= 12.3.0 (可选，推荐)
指令集架构 (ISA): AVX512 (可选，推荐)

提示

Intel Extension for PyTorch (IPEX) 使用最新的特性优化扩展了 PyTorch，以便在 Intel 硬件上获得额外的性能提升。

ARM AArch64

操作系统: Linux
编译器: gcc/g++ >= 12.3.0 (可选，推荐)
指令集架构 (ISA): 需要 NEON 支持

Apple silicon

操作系统: macOS Sonoma 或更高版本
SDK: XCode 15.4 或更高版本，带命令行工具
编译器: Apple Clang >= 15.0.0

IBM Z (S390X)

操作系统: Linux
SDK: gcc/g++ >= 12.3.0 或更高版本，带命令行工具
指令集架构 (ISA): 需要 VXE 支持。适用于 Z14 及以上版本。
构建安装 python 包: pyarrow, torch 和 torchvision

使用 Python 设置#

创建新的 Python 环境#

您可以使用 conda 创建新的 Python 环境

# (Recommended) Create a new conda environment.
conda create -n vllm python=3.12 -y
conda activate vllm

注意

PyTorch 已弃用 conda 发布通道。如果您使用 conda，请仅使用它来创建 Python 环境，而不是安装包。

或者您可以使用 uv 创建新的 Python 环境，uv 是一个非常快速的 Python 环境管理器。请按照文档安装 uv。安装 uv 后，您可以使用以下命令创建新的 Python 环境

# (Recommended) Create a new uv environment. Use `--seed` to install `pip` and `setuptools` in the environment.
uv venv vllm --python 3.12 --seed
source vllm/bin/activate

预构建 wheels#

目前，没有预构建的 CPU wheels。

从源代码构建 wheel#

Intel/AMD x86

首先，安装推荐的编译器。我们建议使用 gcc/g++ >= 12.3.0 作为默认编译器，以避免潜在的问题。例如，在 Ubuntu 22.4 上，您可以运行

sudo apt-get update  -y
sudo apt-get install -y gcc-12 g++-12 libnuma-dev
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 "cmake>=3.26" wheel packaging ninja "setuptools-scm>=8" numpy
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

注意

AVX512_BF16 是一个扩展 ISA，提供原生的 BF16 数据类型转换和向量积指令，与纯 AVX512 相比，这带来了一些性能提升。CPU 后端构建脚本将检查主机 CPU 标志，以确定是否启用 AVX512_BF16。
如果您想强制启用 AVX512_BF16 以进行交叉编译，请在构建之前设置环境变量 VLLM_CPU_AVX512BF16=1。

ARM AArch64

首先，安装推荐的编译器。我们建议使用 gcc/g++ >= 12.3.0 作为默认编译器，以避免潜在的问题。例如，在 Ubuntu 22.4 上，您可以运行

sudo apt-get update  -y
sudo apt-get install -y gcc-12 g++-12 libnuma-dev
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 "cmake>=3.26" wheel packaging ninja "setuptools-scm>=8" numpy
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

已在 AWS Graviton3 实例上进行了兼容性测试。

Apple silicon

安装 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.

IBM Z (s390x)

在构建 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

从源代码构建镜像#

$ docker build -f docker/Dockerfile.cpu --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

提示

对于 ARM 或 Apple silicon，请使用 docker/Dockerfile.arm

提示

对于 IBM Z (s390x)，请使用 docker/Dockerfile.s390x，并在 docker run 中使用标志 --dtype float

支持的特性#

vLLM CPU 后端支持以下 vLLM 特性

张量并行
模型量化 (INT8 W8A8, AWQ, GPTQ)
分块预填充
前缀缓存
FP8-E5M2 KV 缓存

性能技巧#

我们强烈建议使用 TCMalloc 以获得高性能内存分配和更好的缓存局部性。例如，在 Ubuntu 22.4 上，您可以运行

sudo apt-get install libtcmalloc-minimal4 # install TCMalloc library
find / -name *libtcmalloc* # find the dynamic link library path
export LD_PRELOAD=/usr/lib/x86_64-linux-gnu/libtcmalloc_minimal.so.4:$LD_PRELOAD # prepend the library to LD_PRELOAD
python examples/offline_inference/basic/basic.py # run vLLM

当使用在线服务时，建议为服务框架保留 1-2 个 CPU 核心，以避免 CPU 过度订阅。例如，在具有 32 个物理 CPU 核心的平台上，为框架保留 CPU 30 和 31，并为 OpenMP 使用 CPU 0-29。

export VLLM_CPU_KVCACHE_SPACE=40
export VLLM_CPU_OMP_THREADS_BIND=0-29
vllm serve facebook/opt-125m

如果在具有超线程的机器上使用 vLLM CPU 后端，建议使用 VLLM_CPU_OMP_THREADS_BIND 在每个物理 CPU 核心上仅绑定一个 OpenMP 线程。在具有超线程的平台上，具有 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          yes 2401.0000 800.0000  800.000
  0      0    1 1:1:1:0          yes 2401.0000 800.0000  800.000
  0      0    2 2:2:2:0          yes 2401.0000 800.0000  800.000
  0      0    3 3:3:3:0          yes 2401.0000 800.0000  800.000
  0      0    4 4:4:4:0          yes 2401.0000 800.0000  800.000
  0      0    5 5:5:5:0          yes 2401.0000 800.0000  800.000
  0      0    6 6:6:6:0          yes 2401.0000 800.0000  800.000
  0      0    7 7:7:7:0          yes 2401.0000 800.0000  800.000
  0      0    0 0:0:0:0          yes 2401.0000 800.0000  800.000
  0      0    1 1:1:1:0          yes 2401.0000 800.0000  800.000
 0      0    2 2:2:2:0          yes 2401.0000 800.0000  800.000
 0      0    3 3:3:3:0          yes 2401.0000 800.0000  800.000
 0      0    4 4:4:4:0          yes 2401.0000 800.0000  800.000
 0      0    5 5:5:5:0          yes 2401.0000 800.0000  800.000
 0      0    6 6:6:6:0          yes 2401.0000 800.0000  800.000
 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 后端，请注意使用 VLLM_CPU_OMP_THREADS_BIND 设置 CPU 核心，以避免跨 NUMA 节点内存访问。

其他注意事项#

CPU 后端与 GPU 后端显着不同，因为 vLLM 架构最初是为 GPU 使用而优化的。需要进行许多优化以增强其性能。
将 HTTP 服务组件与推理组件分离。在 GPU 后端配置中，HTTP 服务和分词任务在 CPU 上运行，而推理在 GPU 上运行，这通常不会造成问题。但是，在基于 CPU 的设置中，HTTP 服务和分词可能会导致显著的上下文切换和降低的缓存效率。因此，强烈建议隔离这两个组件以提高性能。
在启用 NUMA 的基于 CPU 的设置中，内存访问性能可能很大程度上受到拓扑结构的影响。对于 NUMA 架构，张量并行是获得更好性能的一种选择。
- 张量并行支持服务和离线推理。通常，每个 NUMA 节点被视为一个 GPU 卡。以下是启用张量并行 = 2 以进行服务的示例脚本。
```
VLLM_CPU_KVCACHE_SPACE=40 VLLM_CPU_OMP_THREADS_BIND="0-31|32-63" vllm serve meta-llama/Llama-2-7b-chat-hf -tp=2 --distributed-executor-backend mp
```
- 对于 VLLM_CPU_OMP_THREADS_BIND 中的每个线程 ID 列表，用户应保证列表中的线程属于同一个 NUMA 节点。
- 同时，用户还应注意每个 NUMA 节点的内存容量。每个 TP 秩的内存使用量是权重分片大小和 VLLM_CPU_KVCACHE_SPACE 的总和，如果超过单个 NUMA 节点的容量，TP 工作进程将因内存不足而被终止。

CPU

目录

CPU#

要求#

使用 Python 设置#

创建新的 Python 环境#

预构建 wheels#

从源代码构建 wheel#

问题排查

使用 Docker 设置#

预构建镜像#

从源代码构建镜像#

支持的特性#

相关的运行时环境变量#

性能技巧#

其他注意事项#