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（推荐）、avx512_bf16（可选）、avx512_vnni（可选）
Tip
使用 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/。
自 v0.13.0 版本起，vLLM 提供了支持 AVX512 的 x86 预构建 wheel 包。要安装发布版本的 wheel 包，请执行：
export VLLM_VERSION=$(curl -s https://api.github.com/repos/vllm-project/vllm/releases/latest | jq -r .tag_name | sed 's/^v//')
# 使用 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 环境变量中：
安装最新代码
要安装基于最新 main 分支构建的 wheel 包：
uv pip install vllm --extra-index-url https://wheels.vllm.ai/nightly/cpu --index-strategy first-index --torch-backend cpu
安装特定版本
如果您需要访问之前提交的 wheel 包（例如为了二分查找行为变更或性能退化问题），可以在 URL 中指定提交哈希值：
自 0.11.2 版本起，vLLM 提供适用于 Arm 的预编译 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 来安装 v0.6.6.post1 之前的某个提交版本。相比之下，pip 会合并来自 --extra-index-url 和默认索引的包，并只选择最新版本，这使得安装发布版本之前的开发版本变得困难。
安装最新代码
LLM 推理是一个快速发展的领域，最新代码可能包含尚未发布的错误修复、性能改进和新功能。为了让用户无需等待下一次发布即可试用最新代码，vLLM 为自 v0.11.2 以来的每一次提交提供了可用的预编译 Arm CPU wheel 包，可在 https://wheels.vllm.ai/nightly 获取。
对于原生 CPU wheel 包，应使用以下索引：
https://wheels.vllm.ai/nightly/cpu/vllm
要从 nightly 索引安装，请运行：
uv pip install vllm --extra-index-url https://wheels.vllm.ai/nightly/cpu --index-strategy first-index
pip（有一个注意事项）
不支持使用 pip 从 nightly 索引安装，因为 pip 会合并来自 --extra-index-url 和默认索引的包，并只选择最新版本，这使得安装发布版本之前的开发版本变得困难。相比之下，uv 给予额外索引比默认索引更高的优先级。
如果您坚持使用 pip，则必须指定 wheel 文件的完整 URL（链接地址）（可从 https://wheels.vllm.ai/nightly/cpu/vllm 获取）。
安装特定版本
如果您想获取之前提交的 wheel 包（例如，用于二分查找行为变更、性能回归），可以在 URL 中指定提交哈希：
目前暂无适用于 Apple Silicon CPU 的预构建 wheel 文件。
目前没有预构建的 IBM Z CPU 轮子文件。
从源码构建 wheel¶
使用纯 Python 构建（无编译）¶
请参考 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.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
推荐使用 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 环境变量中：
故障排除
- NumPy ≥2.0 错误：使用
pip install "numpy<2.0"降级。 - CMake 检测到 CUDA：添加
CMAKE_DISABLE_FIND_PACKAGE_CUDA=ON以防止在 CPU 构建过程中检测到 CUDA（即使已安装 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.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 项目：
第三，安装所需的依赖项：
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 .
Tip
--index-strategy unsafe-best-match 标志用于跨多个包索引解析依赖关系（PyTorch CPU 索引和 PyPI）。缺少此标志时，您可能会遇到 typing-extensions 版本冲突问题。
此处的“unsafe”指的是包解析策略，而非安全性。默认情况下，uv 只搜索找到包的第一个索引，以防止依赖混淆攻击。此标志允许 uv 搜索所有配置的索引以找到最佳兼容版本。由于 PyTorch 和 PyPI 都是受信任的包源，使用此策略在 vLLM 安装中是安全且合适的。
Note
在 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
安装 outlines-core 和 uvloop Python 包所需的 rust>=1.80：
执行以下命令从源码构建并安装 vLLM。
Tip
请在构建 vLLM 之前先从源码构建以下依赖项：torchvision、pyarrow。
sed -i '/^torch/d' requirements/build.txt # 从 requirements/build.txt 中移除 torch，因为我们使用夜间构建
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 # 从 requirements/build.txt 中移除 torch，因为我们使用夜间构建
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
Warning
如果在没有 avx512f、avx512_bf16 或 avx512_vnni 支持的机器上部署预构建镜像，可能会引发 非法指令 错误。请参阅下面的“从源码构建镜像”部分，了解如何根据目标 CPU 能力设置构建参数。
有关使用官方 Docker 镜像的说明，请参阅使用 Docker。
从 0.12.0 版本开始，vLLM 为 Arm 预构建稳定的 Docker 镜像。可用的镜像标签请参见：https://gallery.ecr.aws/q9t5s3a7/vllm-arm64-cpu-release-repo。
export VLLM_VERSION=$(curl -s https://api.github.com/repos/vllm-project/vllm/releases/latest | jq -r .tag_name | sed 's/^v//')
docker pull public.ecr.aws/q9t5s3a7/vllm-arm64-cpu-release-repo:v${VLLM_VERSION}
您也可以使用 Docker 镜像获取最新代码。这些镜像不适用于生产环境，仅用于 CI 和测试。它们将在几天后过期。最新代码可能包含错误，可能不够稳定。请谨慎使用。
目前暂无适用于 Arm Silicon CPU 的预构建镜像。
目前没有预构建的 IBM Z CPU 镜像。
从源码构建镜像¶
为目标 CPU 构建¶
docker build -f docker/Dockerfile.cpu \
--build-arg VLLM_CPU_DISABLE_AVX512=<false (默认)|true> \
--build-arg VLLM_CPU_AVX2=<false (默认)|true> \
--build-arg VLLM_CPU_AVX512=<false (默认)|true> \
--build-arg VLLM_CPU_AVX512BF16=<false (默认)|true> \
--build-arg VLLM_CPU_AVX512VNNI=<false (默认)|true> \
--build-arg VLLM_CPU_AMXBF16=<false|true (默认)> \
--tag vllm-cpu-env \
--target vllm-openai .
默认自动检测
默认情况下，CPU 指令集（AVX512、AVX2 等）会根据构建系统的 CPU 标志自动检测。构建参数如 VLLM_CPU_AVX2、VLLM_CPU_AVX512、VLLM_CPU_AVX512BF16、VLLM_CPU_AVX512VNNI 和 VLLM_CPU_AMXBF16 用于交叉编译：
VLLM_CPU_{ISA}=true- 强制启用该指令集（无论构建系统能力如何，均使用 ISA 构建）VLLM_CPU_{ISA}=false- 依赖自动检测（默认）
示例¶
自动检测构建（默认）
为 AVX512 交叉编译
docker build -f docker/Dockerfile.cpu \
--build-arg VLLM_CPU_AVX512=true \
--build-arg VLLM_CPU_AVX512BF16=true \
--build-arg VLLM_CPU_AVX512VNNI=true \
--tag vllm-cpu-avx512 \
--target vllm-openai .
为 AVX2 交叉编译
docker build -f docker/Dockerfile.cpu \
--build-arg VLLM_CPU_AVX2=true \
--tag vllm-cpu-avx2 \
--target vllm-openai .
启动 OpenAI 服务器¶
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
Tip
--privileged=true 的替代方案是 --cap-add SYS_NICE --security-opt seccomp=unconfined。
docker build -f docker/Dockerfile.s390x \
--tag vllm-cpu-env .
# 启动 OpenAI 服务器
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
Tip
--privileged true 的替代方案是 --cap-add SYS_NICE --security-opt seccomp=unconfined。
相关运行时环境变量¶
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（默认）或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 CPU 核心上，rank1 的 OpenMP 线程绑定在 32-63 CPU 核心上。设置为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: 为 vLLM CPU 工作者指定可见的 NUMA 内存节点，类似于CUDA_VISIBLE_DEVICES。当 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 测试用例中提供，定义在 cpu test cases 关于如何确定这些优化配置的详细信息，请参见： performance-benchmark-details。 要使用这些优化设置对支持的模型进行基准测试，请按照 手动运行 vLLM 基准套件 中的步骤操作，并在 CPU 环境中运行基准套件。
以下是使用优化配置对所有 CPU 支持的模型进行基准测试的示例命令。
基准测试结果将保存在 ./benchmark/results/ 目录中。 在该目录中，生成的 .commands 文件包含基准测试的所有示例命令。
我们建议将 tensor-parallel-size 配置为与系统上的 NUMA 节点数量相匹配。请注意，当前版本不支持 tensor-parallel-size=6。 要确定可用的 NUMA 节点数量，请使用以下命令：
作为性能参考，用户还可以查阅 vLLM Performance Dashboard ，该仪表板发布使用相同基准测试套件生成的默认模型 CPU 结果。
如何决定 VLLM_CPU_OMP_THREADS_BIND？¶
-
对于大多数情况，推荐使用默认的
auto线程绑定。理想情况下，每个 OpenMP 线程将分别绑定到专用的物理核心，每个 rank 的线程将分别绑定到相同的 NUMA 节点，并且当world_size > 1时将为其他 vLLM 组件保留 1 个 CPU 每 rank。如果您有任何性能问题或意外的绑定行为，请尝试按以下方式绑定线程。 -
在启用超线程的平台上，具有 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 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/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 核心使用情况来检查线程绑定。
使用 32 的倍数作为 --block-size，默认为 128。
推理批处理大小是性能的重要参数。较大的批处理通常提供更高的吞吐量，较小的批处理提供更低的延迟。从默认值开始调整最大批处理大小以平衡吞吐量和延迟，是在特定平台上提高 vLLM CPU 性能的有效方法。vLLM 中有两个重要的相关参数：
--max-num-batched-tokens，定义单个批次中令牌数量的限制，对第一个令牌性能影响更大。默认值设置为：- 离线推理：
4096 * world_size - 在线服务：
2048 * world_size
- 离线推理：
--max-num-seqs，定义单个批次中序列数量的限制，对输出令牌性能影响更大。- 离线推理：
256 * world_size - 在线服务：
128 * world_size
- 离线推理：
vLLM CPU 支持数据并行 (DP)、张量并行 (TP) 和流水线并行 (PP) 以利用多个 CPU 插槽和内存节点。有关调优 DP、TP 和 PP 的更多详细信息，请参阅 Optimization and Tuning。对于 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/功能设置中被阻止/拒绝。这可能导致类似 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.docker.com/engine/security/seccomp/
或者，使用 --privileged=true 运行也可以，但权限更广泛，通常不推荐。
在 K8S 中，可以在工作负载 yaml 中添加以下配置以实现与上述相同的效果：