CPU¶

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

Intel/AMD x86ARM AArch64Apple siliconIBM Z (S390X)

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

警告

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

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

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

警告

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

vLLM 对配备 Apple silicon 的 macOS 提供实验性支持。目前，用户必须从 vLLM 源代码构建才能在 macOS 上原生运行。

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

警告

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

vLLM 对 IBM Z 平台上的 s390x 架构提供实验性支持。目前，用户必须从 vLLM 源代码构建才能在 IBM Z 平台上原生运行。

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

警告

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

要求¶

Python: 3.9 -- 3.12

Intel/AMD x86ARM AArch64Apple siliconIBM Z (S390X)

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

提示

Intel Extension for PyTorch (IPEX) 通过最新的特性优化扩展了 PyTorch，可在 Intel 硬件上提供额外的性能提升。

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

操作系统: macOS Sonoma 或更高版本
SDK: XCode 15.4 或更高版本，包含 Command Line Tools
编译器: Apple Clang >= 15.0.0

操作系统: Linux
SDK: gcc/g++ >= 12.3.0 或更高版本，包含 Command Line Tools
指令集架构 (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

预构建的轮子¶

目前没有预构建的 CPU 轮子。

从源代码构建轮子¶

Intel/AMD x86ARM AArch64Apple siliconIBM Z (s390x)

注意

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

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

安装 XCode 和 Command Line Tools（包括 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 的 Command Line Tools。

[...] 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

从源代码构建镜像¶

$ 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 功能

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

VLLM_CPU_KVCACHE_SPACE: 指定 KV 缓存大小（例如，VLLM_CPU_KVCACHE_SPACE=40 表示 KV 缓存空间为 40 GiB），设置越大，vLLM 可以并行运行更多请求。此参数应根据用户的硬件配置和内存管理模式进行设置。
VLLM_CPU_OMP_THREADS_BIND: 指定分配给 OpenMP 线程的 CPU 核心。例如，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 核心上。
VLLM_CPU_MOE_PREPACK: 是否对 MoE 层使用预打包。这将传递给 ipex.llm.modules.GatedMLPMOE。默认为 1 (True)。在不支持的 CPU 上，您可能需要将其设置为 0 (False)。

性能技巧¶

我们强烈推荐使用 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，并使用 CPU 0-29 用于 OpenMP

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: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 后端，请注意使用 VLLM_CPU_OMP_THREADS_BIND 设置 CPU 核心以避免跨 NUMA 节点的内存访问。

其他注意事项¶

CPU 后端与 GPU 后端显著不同，因为 vLLM 架构最初是为 GPU 使用而优化的。需要进行一系列优化来提升其性能。
将 HTTP 服务组件与推理组件解耦。在 GPU 后端配置中，HTTP 服务和分词任务在 CPU 上运行，而推理在 GPU 上运行，这通常不成问题。然而，在基于 CPU 的设置中，HTTP 服务和分词可能导致显著的上下文切换和降低的缓存效率。因此，强烈建议将这两个组件分开以提高性能。
在启用了 NUMA 的基于 CPU 的设置中，内存访问性能可能很大程度上受到拓扑结构的影响。对于 NUMA 架构，张量并行 (Tensor Parallel) 是提升性能的一个选项。
张量并行 (Tensor Parallel) 支持服务和离线推理。通常，每个 NUMA 节点被视为一个 GPU 卡。下面是为服务启用 Tensor Parallel = 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 rank 的内存使用量是权重分片大小与 VLLM_CPU_KVCACHE_SPACE 的总和，如果超过单个 NUMA 节点的容量，TP 工作进程将因内存不足而被终止。

CPU¶

要求¶

使用 Python 设置¶

创建新的 Python 环境¶

预构建的轮子¶

从源代码构建轮子¶

故障排除¶

使用 Docker 设置¶

预构建镜像¶

从源代码构建镜像¶

支持的功能¶

相关的运行时环境变量¶

性能技巧¶

其他注意事项¶