跳至内容

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

预构建的wheel包

目前还没有预构建的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++头文件，请尝试卸载并重新安装您的Command Line Tools for 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表示40GiB的KV缓存空间），设置更大的值将允许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层使用预打包(prepack)功能。该参数将传递给ipex.llm.modules.GatedMLPMOE。默认值为1(启用)。在不支持的CPU上，可能需要将此参数设为0(禁用)。
  • VLLM_CPU_SGL_KERNEL (仅限x86架构，实验性功能)：是否对线性层和MoE层使用小批量优化内核，特别适用于在线服务等低延迟需求场景。该内核需要AMX指令集、BFloat16权重类型以及可被32整除的权重形状。默认值为0 (禁用)。

常见问题

应该使用哪种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核心：

Commands 
$ 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等级。因此请注意将单个等级的CPU核心设置在同一个NUMA节点上，以避免跨NUMA节点内存访问。

如何确定 VLLM_CPU_KVCACHE_SPACE 参数？

This value is 4GB by default. Larger space can support more concurrent requests, longer context length. However, users should take care of memory capacity of each NUMA node. The memory usage of each TP rank is the sum of weight shard size and VLLM_CPU_KVCACHE_SPACE, if it exceeds the capacity of a single NUMA node, the TP worker will be killed with exitcode 9 due to out-of-memory.

如何对vLLM CPU进行性能调优？

首先，请确保线程绑定和KV缓存空间已正确设置并生效。您可以通过运行vLLM基准测试并使用htop观察CPU核心使用情况来检查线程绑定。

推理批次大小是影响性能的重要参数。较大的批次通常能提供更高的吞吐量，而较小的批次则能实现更低的延迟。从默认值开始调整最大批次大小，以平衡吞吐量和延迟，是提升vLLM在特定平台上CPU性能的有效方法。vLLM中有两个重要的相关参数：

  • --max-num-batched-tokens, defines the limit of token numbers in a single batch, has more impacts on the first token performance. The default value is set as:
    • 离线推理: 4096 * world_size
    • 在线服务: 2048 * world_size
  • --max-num-seqs, defines the limit of sequence numbers in a single batch, has more impacts on the output token performance.
    • 离线推理: 256 * world_size
    • 在线服务: 128 * world_size

vLLM CPU支持张量并行(TP)和流水线并行(PP)以利用多个CPU插槽和内存节点。有关调整TP和PP的更多详情，请参阅优化与调优。对于vLLM CPU，如果有足够的CPU插槽和内存节点，建议同时使用TP和PP。

vLLM CPU支持哪些量化配置？

  • vLLM CPU supports quantizations:
    • AWQ (仅限x86架构)
    • GPTQ (仅限x86架构)
    • 压缩张量 INT8 W8A8 (x86, s390x)

(仅限x86架构) VLLM_CPU_MOE_PREPACK 和 VLLM_CPU_SGL_KERNEL 的作用是什么？

  • Both of them requires amx CPU flag.
    • VLLM_CPU_MOE_PREPACK 可以为MoE模型提供更好的性能
    • VLLM_CPU_SGL_KERNEL 可以为MoE模型和小批量场景提供更好的性能。
优云智算