CPU¶
vLLM 是一个 Python 库，支持以下 CPU 变体。选择您的 CPU 类型以查看特定供应商的说明。
vLLM 在 x86 CPU 平台上支持基本的模型推理和推理服务，支持 FP32、FP16 和 BF16 数据类型。
vLLM 在 Arm CPU 平台上提供基本的模型推理和推理服务，支持 NEON，数据类型为 FP32、FP16 和 BF16。
vLLM 对 Apple Silicon 的 macOS 提供实验性支持。目前，用户必须从源代码构建才能在 macOS 上原生运行。
目前 macOS 的 CPU 实现支持 FP32 和 FP16 数据类型。
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（可选）
提示
使用 lscpu 检查 CPU 标志。
- 操作系统：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 环境。
预构建的 Wheels¶
在指定索引 URL 时，请确保使用 cpu 变体子目录。例如，夜间构建索引是：https://wheels.vllm.ai/nightly/cpu/。
自 0.13.0 版本起，vLLM 提供了 x86 CPU（带 AVX512）的预构建轮子。安装发布轮子
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
在使用通过轮子安装的 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"
安装最新代码
安装从最新主分支构建的轮子
uv pip install vllm --extra-index-url https://wheels.vllm.ai/nightly/cpu --index-strategy first-index --torch-backend cpu
安装特定修订版
如果您想访问之前提交的轮子（例如，为了二分查找行为更改、性能回归），您可以在 URL 中指定提交哈希。
自 0.11.2 版本起，vLLM 提供了 Arm CPU 的预构建轮子。这些轮子包含预编译的 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
在使用通过轮子安装的 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 轮子，位于 https://wheels.vllm.ai/nightly。对于原生 CPU 轮子，应使用此索引。
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，您必须指定轮子文件的完整 URL（链接地址）（可从 https://wheels.vllm.ai/nightly/cpu/vllm 获取）。
安装特定修订版
如果您想访问之前提交的轮子（例如，为了二分查找行为更改、性能回归），您可以在 URL 中指定提交哈希。
目前没有预构建的 Apple silicon CPU 轮子。
目前没有预构建的 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，请改为以可编辑模式安装。
可选地，构建一个便携式轮子，然后可以在其他地方安装。
设置 LD_PRELOAD
在使用通过轮子安装的 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：添加
CMAKE_DISABLE_FIND_PACKAGE_CUDA=ON以在 CPU 构建期间阻止 CUDA 检测，即使 CUDA 已安装。 AMD需要至少第四代处理器（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
在使用通过轮子安装的 vLLM CPU 之前，请确保已安装 TCMalloc 并已添加到 LD_PRELOAD。
安装 XCode 和 Command Line Tools（包含 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++ 头文件等错误而失败，请尝试删除并重新安装您的 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.
如果构建因 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 进行设置¶
预构建的镜像¶
https://gallery.ecr.aws/q9t5s3a7/vllm-cpu-release-repo
警告
如果在没有 avx512f、avx512_bf16 或 avx512_vnni 支持的机器上部署预构建的镜像，可能会引发 Illegal instruction 错误。建议使用适当的构建参数（例如 --build-arg VLLM_CPU_DISABLE_AVX512=true、--build-arg VLLM_CPU_AVX512BF16=false 或 --build-arg VLLM_CPU_AVX512VNNI=false）为这些机器构建镜像，以禁用不支持的功能。请注意，没有 avx512f，将使用 AVX2，并且不推荐使用此版本，因为它只提供基本功能支持。
有关使用官方 Docker 镜像的说明，请参阅 使用 Docker。
自 0.12.0 版本起，vLLM 的稳定 Docker 镜像已为 Arm 预构建。可用的镜像标签在此处：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 和测试使用。它们将在几天后过期。
最新代码可能包含 bug 且可能不稳定。请谨慎使用。
目前没有预构建的 Arm silicon CPU 镜像。
目前没有预构建的 IBM Z CPU 镜像。
从源代码构建镜像¶
docker build -f docker/Dockerfile.cpu \
--build-arg VLLM_CPU_AVX512BF16=false (default)|true \
--build-arg VLLM_CPU_AVX512VNNI=false (default)|true \
--build-arg VLLM_CPU_AMXBF16=false|true (default) \
--build-arg VLLM_CPU_DISABLE_AVX512=false (default)|true \
--tag vllm-cpu-env \
--target vllm-openai .
# Launching OpenAI server
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> \
vllm-cpu-env \
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
提示
--privileged=true 的替代方案是 --cap-add SYS_NICE --security-opt seccomp=unconfined。
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
提示
--privileged=true 的替代方案是 --cap-add SYS_NICE --security-opt seccomp=unconfined。
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 缓存大小（例如，VLLM_CPU_KVCACHE_SPACE=40表示 40 GiB 的 KV 缓存空间），更大的设置将允许 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。但是，由于 PyTorch 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 文件包含基准测试的所有示例命令。
我们建议将张量并行大小配置为匹配您系统上的 NUMA 节点数量。请注意，当前版本不支持张量并行大小=6。要确定可用的 NUMA 节点数量，请使用以下命令。
作为性能参考，用户也可以查阅 vLLM 性能仪表板，该仪表板发布了使用相同基准测试套件生成的默认模型 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 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 的内存使用量是 权重分片大小 和 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，定义单个批次中 token 的数量限制，对第一个 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）
- 压缩张量 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 中添加以下配置来实现与上述相同效果。