CPU¶
vLLM 是一个支持以下 CPU 变体的 Python 库。请选择您的 CPU 类型以查看特定于供应商的说明：
vLLM 支持在 x86 CPU 平台上进行基本的模型推理和服务，支持的数据类型包括 FP32、FP16 和 BF16。
vLLM 在 Arm CPU 平台上提供基本的模型推理和服务，支持 NEON 以及 FP32、FP16 和 BF16 数据类型。
vLLM 对 Apple Silicon (macOS) 提供实验性支持。目前，用户必须从源码编译才能在 macOS 上原生运行。
目前，macOS 的 CPU 实现支持 FP32 和 FP16 数据类型。
使用 vLLM-Metal 进行 GPU 加速推理
如需在 Apple Silicon 上使用 Metal 进行 GPU 加速推理，请查看 vLLM-Metal，这是一个由社区维护的硬件插件，使用 MLX 作为计算后端。
vLLM 对 IBM Z 平台上的 s390x 架构提供实验性支持。目前，用户必须从源码编译才能在 IBM Z 平台上原生运行。
目前，s390x 架构的 CPU 实现仅支持 FP32 数据类型。
技术讨论¶
主要讨论在 vLLM Slack 的 #sig-cpu 频道中进行。
当提交关于 CPU 后端的 Github issue 时，请在标题中添加 [CPU Backend]，以便将其标记为 cpu，从而获得更多关注。
要求¶
- Python: 3.10 -- 3.13
- 操作系统：Linux
- CPU 标志：
avx512f（推荐），avx2（功能受限）
提示
使用 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 环境。
预构建的 Wheels¶
指定索引 URL 时，请确保使用 cpu 变体子目录。例如，每日构建版的索引为：https://wheels.vllm.ai/nightly/cpu/。
自 0.17.0 版本起，提供适用于 x86（含 AVX512/AVX2）的预构建 vLLM wheel。安装发布版 wheel：
export VLLM_VERSION=$(curl -s https://api.github.com/repos/vllm-project/vllm/releases/latest | jq -r .tag_name | sed 's/^v//')
# use uv
uv pip install https://github.com/vllm-project/vllm/releases/download/v${VLLM_VERSION}/vllm-${VLLM_VERSION}+cpu-cp38-abi3-manylinux_2_35_x86_64.whl --torch-backend cpu
pip
设置 LD_PRELOAD
在使用通过 wheel 安装的 vLLM CPU 之前，请确保已安装 TCMalloc 和 Intel OpenMP，并将其添加到 LD_PRELOAD
# install TCMalloc, Intel OpenMP is installed with vLLM CPU
sudo apt-get install -y --no-install-recommends libtcmalloc-minimal4
# manually find the path
sudo find / -iname *libtcmalloc_minimal.so.4
sudo find / -iname *libiomp5.so
TC_PATH=...
IOMP_PATH=...
# add them to LD_PRELOAD
export LD_PRELOAD="$TC_PATH:$IOMP_PATH:$LD_PRELOAD"
安装最新代码¶
安装从 main 分支最新构建的 wheel：
uv pip install vllm --extra-index-url https://wheels.vllm.ai/nightly/cpu --index-strategy first-index --torch-backend cpu
安装特定版本¶
如果您想访问之前提交的轮子（例如，为了二分查找行为更改、性能回归），您可以在 URL 中指定提交哈希。
自 0.11.2 版本起，提供适用于 Arm 的预构建 vLLM wheel。这些 wheel 包含预编译的 C++ 二进制文件。
export VLLM_VERSION=$(curl -s https://api.github.com/repos/vllm-project/vllm/releases/latest | jq -r .tag_name | sed 's/^v//')
uv pip install https://github.com/vllm-project/vllm/releases/download/v${VLLM_VERSION}/vllm-${VLLM_VERSION}+cpu-cp38-abi3-manylinux_2_35_aarch64.whl
pip
设置 LD_PRELOAD
在使用通过 wheel 安装的 vLLM CPU 之前，请确保已安装 TCMalloc，并将其添加到 LD_PRELOAD
uv 方法适用于 vLLM v0.6.6 及更高版本。uv 的一个独特功能是 --extra-index-url 中的包具有 比默认索引更高的优先级。如果最新的公开版本是 v0.6.6.post1，uv 允许通过指定 --extra-index-url 来安装早于该版本的 commit。相比之下，pip 会合并来自 --extra-index-url 和默认索引的包，且仅选择最新版本，这使得安装早于已发布版本的开发版本变得困难。
安装最新代码¶
LLM 推理是一个快速发展的领域，最新代码可能包含尚未发布的错误修复、性能改进和新特性。为了让用户无需等待下一次发布即可尝试最新代码，vLLM 为 v0.11.2 以来的每个 commit 提供了可用的预构建 Arm CPU wheel，地址为 https://wheels.vllm.ai/nightly。对于原生 CPU wheel，应使用以下索引：
https://wheels.vllm.ai/nightly/cpu/vllm
要从夜间索引安装，请运行
uv pip install vllm --extra-index-url https://wheels.vllm.ai/nightly/cpu --index-strategy first-index
pip（有一个注意事项）
使用 pip 从夜间索引安装是不受支持的，因为 pip 会合并来自 --extra-index-url 和默认索引的包，仅选择最新版本，这使得安装发布版本之前的开发版本变得困难。相比之下，uv 使额外的索引比默认索引具有 更高的优先级。
如果您坚持使用 pip，则必须指定 wheel 文件的完整 URL（链接地址，可从 https://wheels.vllm.ai/nightly/cpu/vllm 获取）。
安装特定版本¶
如果您想访问之前提交的轮子（例如，为了二分查找行为更改、性能回归），您可以在 URL 中指定提交哈希。
目前，没有预构建的 Apple Silicon CPU wheel。
目前，没有预构建的 IBM Z CPU wheel。
从源代码构建 Wheel¶
通过纯 Python 构建（无需编译）进行设置¶
此方法需要针对您平台的预构建 wheel。
请参考 GPU 上仅 Python 构建的说明，并将构建命令替换为：
VLLM_USE_PRECOMPILED=1 VLLM_PRECOMPILED_WHEEL_VARIANT=cpu VLLM_TARGET_DEVICE=cpu uv pip install --editable .
完整构建（需要编译）¶
安装推荐的编译器。我们建议使用 gcc/g++ >= 12.3.0 作为默认编译器以避免潜在问题。例如，在 Ubuntu 22.04 上，您可以运行：
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
建议使用 uv，一个非常快速的 Python 环境管理器，来创建和管理 Python 环境。请按照 文档 安装 uv。安装 uv 后，您可以使用以下命令创建新的 Python 环境。
克隆 vLLM 项目
安装所需的依赖项
uv pip install -r requirements/cpu-build.txt --torch-backend cpu
uv pip install -r requirements/cpu.txt --torch-backend cpu
pip
构建并安装 vLLM
如果您想开发 vLLM，请以可编辑模式安装。
（可选）构建一个可移植的 wheel，以便在其他地方安装
设置 LD_PRELOAD
在使用通过 wheel 安装的 vLLM CPU 之前，请确保已安装 TCMalloc 和 Intel OpenMP，并将其添加到 LD_PRELOAD
# install TCMalloc, Intel OpenMP is installed with vLLM CPU
sudo apt-get install -y --no-install-recommends libtcmalloc-minimal4
# manually find the path
sudo find / -iname *libtcmalloc_minimal.so.4
sudo find / -iname *libiomp5.so
TC_PATH=...
IOMP_PATH=...
# add them to LD_PRELOAD
export LD_PRELOAD="$TC_PATH:$IOMP_PATH:$LD_PRELOAD"
故障排除
- NumPy ≥2.0 错误：使用
pip install "numpy<2.0"降级。 - CMake 选择了 CUDA：即使安装了 CUDA，也请添加
CMAKE_DISABLE_FIND_PACKAGE_CUDA=ON以在 CPU 构建期间阻止 CUDA 检测。 AMD需要至少第 4 代处理器（Zen 4/Genoa）或更高版本才能支持 AVX512 从而在 CPU 上运行 vLLM。- 如果您收到类似
Could not find a version that satisfies the requirement torch==X.Y.Z+cpu+cpu的错误，请考虑更新 pyproject.toml 以帮助 pip 解析依赖项。
首先，安装推荐的编译器。我们建议使用 gcc/g++ >= 12.3.0 作为默认编译器。例如，在 Ubuntu 22.04 上，您可以运行：
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 项目
第三，安装所需的依赖项
uv pip install -r requirements/cpu-build.txt --torch-backend cpu
uv pip install -r requirements/cpu.txt --torch-backend cpu
pip
最后，构建并安装 vLLM
如果您想开发 vLLM，请以可编辑模式安装。
已在 AWS Graviton3 实例上进行了兼容性测试。
设置 LD_PRELOAD
在使用通过 wheel 安装的 vLLM CPU 之前，请确保已安装 TCMalloc，并将其添加到 LD_PRELOAD
安装 XCode 和包含 Apple Clang 的命令行工具后，执行以下命令从源码构建并安装 vLLM。
git clone https://github.com/vllm-project/vllm.git
cd vllm
uv pip install -r requirements/cpu.txt --index-strategy unsafe-best-match
uv pip install -e .
提示
需要使用 --index-strategy unsafe-best-match 标志来跨多个包索引（PyTorch CPU 索引和 PyPI）解析依赖项。如果不使用此标志，可能会遇到 typing-extensions 版本冲突。
术语“unsafe”指的是包解析策略，而非安全性。默认情况下，uv 仅搜索找到包的第一个索引以防止依赖混淆攻击。此标志允许 uv 搜索所有配置的索引以找到最佳兼容版本。由于 PyTorch 和 PyPI 都是受信任的包来源，因此此策略对于 vLLM 安装是安全且合适的。
注意
在 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.
如果构建失败并出现类似以下的 C++11/C++17 兼容性错误，问题在于构建系统默认使用了较旧的 C++ 标准：
[...] error: 'constexpr' is not a type
[...] error: expected ';' before 'constexpr'
[...] error: 'constexpr' does not name a type
解决方案：您的编译器可能正在使用较旧的 C++ 标准。编辑 cmake/cpu_extension.cmake，并在 set(CMAKE_CXX_STANDARD_REQUIRED ON) 之前添加 set(CMAKE_CXX_STANDARD 17)。
检查编译器的 C++ 标准支持情况：
在 Apple Clang 16 上，您应该看到：#define __cplusplus 201703L 在构建 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 包所必需的。
执行以下命令从源码构建并安装 vLLM。
提示
请在构建 vLLM 之前从源码构建以下依赖项：torchvision, pyarrow。
sed -i '/^torch/d' requirements/build.txt # remove torch from requirements/build.txt since we use nightly builds
uv pip install -v \
--torch-backend auto \
-r requirements/build.txt \
-r requirements/cpu.txt \
VLLM_TARGET_DEVICE=cpu python setup.py bdist_wheel && \
uv pip install dist/*.whl
pip
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 进行设置¶
预构建的镜像¶
您可以从 Docker Hub 拉取最新的可用 CPU 镜像：
拉取特定 vLLM 版本的镜像：
export VLLM_VERSION=$(curl -s https://api.github.com/repos/vllm-project/vllm/releases/latest | jq -r .tag_name | sed 's/^v//')
docker pull vllm/vllm-openai-cpu:v${VLLM_VERSION}-x86_64
所有可用的镜像标签请见：https://hub.docker.com/r/vllm/vllm-openai-cpu/tags
您可以通过以下方式运行这些镜像：
从 Docker Hub 拉取最新镜像：
拉取特定 vLLM 版本的镜像：
export VLLM_VERSION=$(curl -s https://api.github.com/repos/vllm-project/vllm/releases/latest | jq -r .tag_name | sed 's/^v//')
docker pull vllm/vllm-openai-cpu:v${VLLM_VERSION}-arm64
所有可用的镜像标签请见：https://hub.docker.com/r/vllm/vllm-openai-cpu/tags。
您可以通过以下方式运行这些镜像：
docker run \
-v ~/.cache/huggingface:/root/.cache/huggingface \
-p 8000:8000 \
--env "HF_TOKEN=<secret>" \
vllm/vllm-openai-cpu:latest-arm64 <args...>
您也可以使用 Docker 镜像访问最新代码。这些镜像不适用于生产环境，仅供 CI 和测试使用。它们将在几天后过期。
最新代码可能包含 bug 且可能不稳定。请谨慎使用。
目前没有预构建的 Arm CPU 镜像。
目前没有预构建的 IBM Z CPU 镜像。
从源代码构建镜像¶
为目标 CPU 构建¶
docker build -f docker/Dockerfile.cpu \
--build-arg VLLM_CPU_X86=<false (default)|true> \ # For cross-compilation
--tag vllm-cpu-env \
--target vllm-openai .
启动 OpenAI 服务器¶
为目标 ARM CPU 构建¶
docker build -f docker/Dockerfile.cpu \
--platform=linux/arm64 \
--build-arg VLLM_CPU_ARM_BF16=<false (default)|true> \
--tag vllm-cpu-env \
--target vllm-openai .
默认自动检测
默认情况下，ARM CPU 指令集（BF16、NEON 等）会从构建系统的 CPU 标志中自动检测。VLLM_CPU_ARM_BF16 构建参数用于交叉编译：
VLLM_CPU_ARM_BF16=true- 强制启用 ARM BF16 支持（无论构建系统能力如何，均使用 BF16 构建）VLLM_CPU_ARM_BF16=false- 依赖自动检测（默认）
示例¶
自动检测构建（原生 ARM）¶
# Building on ARM64 system - platform auto-detected
docker build -f docker/Dockerfile.cpu \
--tag vllm-cpu-arm64 \
--target vllm-openai .
支持 BF16 的 ARM 交叉编译¶
# Building on ARM64 for newer ARM CPUs with BF16
docker build -f docker/Dockerfile.cpu \
--build-arg VLLM_CPU_ARM_BF16=true \
--tag vllm-cpu-arm64-bf16 \
--target vllm-openai .
从 x86_64 交叉编译到 ARM64（含 BF16）¶
# Requires Docker buildx with ARM emulation (QEMU)
docker buildx build -f docker/Dockerfile.cpu \
--platform=linux/arm64 \
--build-arg VLLM_CPU_ARM_BF16=true \
--build-arg max_jobs=4 \
--tag vllm-cpu-arm64-bf16 \
--target vllm-openai \
--load .
ARM BF16 要求
ARM BF16 支持需要 ARMv8.6-A 或更高版本 (FEAT_BF16)。受 AWS Graviton3/4、AmpereOne 及其他近期 ARM 处理器的支持。
启动 OpenAI 服务器¶
docker run --rm \
--security-opt seccomp=unconfined \
--cap-add SYS_NICE \
--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-arm64 \
meta-llama/Llama-3.2-1B-Instruct \
--dtype=bfloat16 \
other vLLM OpenAI server arguments
--privileged 的替代方案
为了更好的安全性，请使用 --cap-add SYS_NICE --security-opt seccomp=unconfined 代替 --privileged=true。
docker build -f docker/Dockerfile.s390x \
--tag vllm-cpu-env .
# Launch 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
提示
--privileged true 的替代方案是 --cap-add SYS_NICE --security-opt seccomp=unconfined。
相关运行时环境变量¶
VLLM_CPU_KVCACHE_SPACE：指定 KV Cache 大小（例如，VLLM_CPU_KVCACHE_SPACE=40表示为 KV Cache 分配 40 GiB 空间），更大的设置允许 vLLM 并行运行更多请求。此参数应根据用户的硬件配置和内存管理模式进行设置。默认值为0。VLLM_CPU_OMP_THREADS_BIND：指定专用于 OpenMP 线程的 CPU 核心。可以设置为 CPU ID 列表、auto（默认）或nobind（禁用绑定到单个 CPU 核心，继承用户定义的 OpenMP 变量）。例如，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 核心，rank1 的 OpenMP 线程绑定到 32-63 核心。设置为auto时，每个 rank 的 OpenMP 线程将分别绑定到各 NUMA 节点内的 CPU 核心。若设为nobind，OpenMP 线程数由标准OMP_NUM_THREADS环境变量确定。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。CPU_VISIBLE_MEMORY_NODES：类似于CUDA_VISIBLE_DEVICES，指定 vLLM CPU worker 可见的 NUMA 内存节点。仅当 VLLM_CPU_OMP_THREADS_BIND 设置为auto时生效。该变量为自动线程绑定功能提供了更多控制权，例如屏蔽节点或更改节点绑定顺序。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。
CPU 支持哪些模型？¶
有关在 CPU 平台上验证过的完整且最新的模型列表，请参阅官方文档：CPU 支持的模型
如何找到受支持 CPU 模型的基准测试配置示例？¶
对于 CPU 支持的模型 下列出的任何模型，vLLM 基准套件的 CPU 测试用例中提供了优化的运行时配置（定义在 serving-tests-cpu.json 中）。纯文本模型、多模态模型和嵌入模型的完整测试用例分别位于 serving-tests-cpu-text.json、serving-tests-cpu-multimodal.json 和 serving-tests-cpu-embed.json 中。
有关如何确定这些优化配置的详细信息，请参阅：性能基准测试详情。要使用这些优化设置对受支持的模型进行基准测试，请遵循手动运行 vLLM 基准套件中的步骤，并在 CPU 环境中运行该套件。
以下是使用优化配置对所有 CPU 支持的模型进行基准测试的示例命令。
基准测试结果将保存在 ./benchmark/results/ 中。在该目录下，生成的 .commands 文件包含了基准测试的所有示例命令。
我们建议将 tensor-parallel-size 配置为与您系统上的 NUMA 节点数量相匹配。注意，当前版本不支持 tensor-parallel-size=6。要确定可用的 NUMA 节点数量，请使用以下命令：
有关性能参考，用户还可以查阅 vLLM 性能仪表板，该仪表板发布了使用相同基准套件生成的默认模型 CPU 结果。
预演模式 (Dry-Run)¶
对于仅需获取优化运行时配置而无需运行基准测试的用户，提供了预演模式。通过传递环境变量 DRY_RUN=1 给 run-performance-benchmarks.sh，所有命令将在 ./benchmark/results/ 下生成。
通过提供不同的 JSON 文件，用户可以获取不同模型（如嵌入模型）的运行时配置。
ON_CPU=1 SERVING_JSON=serving-tests-cpu-embed.json DRY_RUN=1 bash .buildkite/performance-benchmarks/scripts/run-performance-benchmarks.sh
通过提供 MODEL_FILTER 和 DTYPE_FILTER，将仅生成相关模型 ID 和数据类型的命令。
ON_CPU=1 SERVING_JSON=serving-tests-cpu-text.json DRY_RUN=1 MODEL_FILTER=meta-llama/Llama-3.1-8B-Instruct DTYPE_FILTER=bfloat16 bash .buildkite/performance-benchmarks/scripts/run-performance-benchmarks.sh
如何确定 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 recommended to only bind openMP threads on logical CPU cores 0-7 or 8-15
$ export VLLM_CPU_OMP_THREADS_BIND=0-7
$ python examples/basic/offline_inference/basic.py
- 在具有 NUMA 的多插槽机器上部署 vLLM CPU 后端并启用张量并行或流水线并行时，每个 NUMA 节点被视为一个 TP/PP rank。因此，请确保将同一 rank 的 CPU 核心设置在同一个 NUMA 节点上，以避免跨 NUMA 节点的内存访问。
如何确定 VLLM_CPU_KVCACHE_SPACE？¶
此值默认为 4GB。更大的空间可以支持更多的并发请求和更长的上下文长度。但是，用户应注意每个 NUMA 节点的内存容量。每个 TP rank 的内存使用量是 权重分片大小 与 VLLM_CPU_KVCACHE_SPACE 之和；如果超过单个 NUMA 节点的容量，TP worker 将因内存不足 (OOM) 而被杀掉，退出代码为 9。
如何对 vLLM CPU 进行性能调优？¶
首先，请确保已正确设置并生效了线程绑定和 KV cache 空间。您可以通过运行 vLLM 基准测试并使用 htop 观察 CPU 核心使用情况来检查线程绑定。
使用 32 的倍数作为 --block-size（默认值为 128）。
推理批次大小是影响性能的关键参数。较大的批次通常提供更高的吞吐量，而较小的批次则提供更低的延迟。从默认值开始调整最大批次大小，以平衡吞吐量和延迟，是提高 vLLM CPU 性能的有效途径。vLLM 中有两个重要的相关参数：
--max-num-batched-tokens：定义单批次中 token 数量的限制，对首字性能影响较大。默认值设置为：- 离线推理：
4096 * world_size - 在线服务：
2048 * world_size
- 离线推理：
--max-num-seqs：定义单批次中序列数量的限制，对输出 token 性能影响较大。- 离线推理：
256 * world_size - 在线服务：
128 * world_size
- 离线推理：
vLLM CPU 支持数据并行 (DP)、张量并行 (TP) 和流水线并行 (PP)，以利用多个 CPU 插槽和内存节点。有关调优 DP、TP 和 PP 的更多详细信息，请参考优化与调优。对于 vLLM CPU，如果拥有足够的 CPU 插槽和内存节点，建议结合使用 DP、TP 和 PP。
vLLM CPU 支持哪些量化配置？¶
- vLLM CPU 支持以下量化：
- AWQ（仅 x86）
- GPTQ（仅 x86）
- compressed-tensor INT8 W8A8（x86, s390x）
为什么在 Docker 中运行时会看到 get_mempolicy: Operation not permitted？¶
在某些容器环境（如 Docker）中，vLLM 使用的 NUMA 相关系统调用（如 get_mempolicy, migrate_pages）在运行时的默认 seccomp/capabilities 设置中被阻止或拒绝。这可能导致类似 get_mempolicy: Operation not permitted 的警告。这不会影响功能，但 NUMA 内存绑定/迁移优化可能无法生效，导致性能不佳。
要在 Docker 中以最小权限启用这些优化，您可以参考以下建议：
docker run ... --cap-add SYS_NICE --security-opt seccomp=unconfined ...
# 1) `--cap-add SYS_NICE` is to address `get_mempolicy` EPERM issue.
# 2) `--security-opt seccomp=unconfined` is to enable `migrate_pages` for `numa_migrate_pages()`.
# Actually, `seccomp=unconfined` bypasses the seccomp for container,
# if it's unacceptable, you can customize your own seccomp profile,
# based on docker/runtime default.json and add `migrate_pages` to `SCMP_ACT_ALLOW` list.
# reference : https://docs.container.net.cn/engine/security/seccomp/
或者，使用 --privileged=true 运行也可以，但该方式权限过大，通常不推荐。
在 K8S 中，可以将以下配置添加到工作负载 yaml 中以达到同样的效果：