跳到内容

CPU

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

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
  • 操作系统：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

首先，安装推荐的编译器。我们建议使用 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 进行设置

预构建的镜像

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

警告

如果将预构建镜像部署在仅包含 avx512f 的机器上，可能会出现 Illegal instruction 错误。建议使用 --build-arg VLLM_CPU_AVX512BF16=false 和 --build-arg VLLM_CPU_AVX512VNNI=false 为这些机器构建镜像。

从源代码构建镜像

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 模型和小批量场景提供更好的性能。