vLLM CPU 后端 x86 平台安装指南预编译 Wheel、源码编译与 Docker 部署实践【免费下载链接】vllmA high-throughput and memory-efficient inference and serving engine for LLMs项目地址: https://gitcode.com/GitHub_Trending/vl/vllm导读本指南面向需要在x86 CPUIntel / AMD平台上运行 vLLM 推理与在线服务的开发者完整覆盖四条从简到繁的安装路径直接使用官方预编译 Wheel、从源码自行编译、使用 Docker 预编译镜像、以及为特定目标 CPU 或 AMD Zen 平台自建镜像。读完本文你将掌握如何用uv/pip干净地搭建 CPU 版环境、为什么必须设置LD_PRELOAD指向 Intel OpenMP以及何时需要 TCMalloc、如何拉取与运行vllm-openai-cpu镜像、如何开启并验证 AMD ZenZenDNN/zentorch优化路径以及VLLM_CPU_KVCACHE_SPACE、VLLM_CPU_OMP_THREADS_BIND等关键运行时变量的正确用法。本文主体源自 docs/getting_started/installation/cpu.x86.inc.md 及其宿主文档 docs/getting_started/installation/cpu.md并补充了当前仓库中对应的平台源码与 Docker 构建脚本作为印证。一、x86 CPU 后端能力与前置要求vLLM 支持在 x86 CPU 平台上进行基础的模型推理与在线服务serving支持的推理数据类型为FP32、FP16 与 BF16。这份能力声明同样是后续所有安装方式的前提——无论采用哪种安装路径最终交付的都是同一个面向 CPU 目标的 vLLM 构建产物。安装前请确认满足以下前置条件项目要求操作系统LinuxCPU 指令集标志avx512f推荐avx2仅支持有限功能Python 版本3.10 – 3.13编译器源码构建推荐gcc/g 12.3.0检查 CPU flags 的最直接方式是使用lscpulscpu | grep -E Flags|型号名称 # Flags 一栏中应包含 avx512f 或 avx2需要特别说明仅具备avx2的 CPU 只能获得“受限功能”vLLM 的部分算子实现例如依赖 AVX-512 的 GEMM 调度路径无法启用因此在生产部署中优先选择带avx512f的处理器。此外AMD 平台用户需要注意AMD 处理器至少需要第 4 代Zen 4 / Genoa或更新的架构才支持 AVX-512从而满足 vLLM CPU 运行要求详见后文“疑难排查”一节。本仓库为 CPU 目标提供了多平台支持文档x86 只是其中之一另有 ARM AArch64、Apple silicon、IBM Z s390x可参考 CPU 安装总览 选择对应分支。二、三条安装路径的选择针对 x86 CPU官方提供以下三类主流安装方式你可按场景组合使用安装路径适用场景关键要点预编译 Wheel快速起步、避免编译版本 0.17.0 起提供需设置LD_PRELOAD指向 Intel OpenMP从源码构建二次开发、定制化编译、源码调试需gcc 12.3设置VLLM_TARGET_DEVICEcpuDocker 镜像服务化部署、CI、隔离环境官方镜像vllm/vllm-openai-cpu支持 AMD Zen 目标在开始任一方式之前建议先用uv创建干净的 Python 环境详见第三节。如果你已有现成环境并想先快速验证推理可直接跳到第四节的预编译 Wheel。三、准备 Python 环境推荐 uv官方推荐使用 uv由 Astral 出品的极速 Python 环境/包管理器来创建和管理虚拟环境。创建 CPU 开发环境的标准做法是uv venv --python 3.12 --seed --managed-python source .venv/bin/activate说明--python 3.12CPU 后端与构建链路在 3.10–3.13 上均有验证3.12 为当前默认推荐版本--seed在环境中预置pip与setuptools便于后续回退使用pip安装--managed-python允许 uv 在缺失对应 Python 版本时自动下载托管版本。这套流程来自被 cpu.x86.inc.md 引用的公共片段 python_env_setup.inc.md。此外CPU 安装的 uv/pip 命令普遍带有--torch-backend cpu或--extra-index-url https://download.pytorch.org/whl/cpu作用是让包解析器优先从 PyTorch 官方 CPU index 拉取带cpu后缀的 PyTorch 轮子避免误装 CUDA 版本。四、方式一安装官方预编译 Wheel4.1 Release Wheel稳定版官方为 x86AVX512/AVX2提供预编译 vLLM Wheel自v0.17.0起可用。安装步骤如下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_34_x86_64.whl --torch-backend cpu如果习惯用pip等价命令为pip install https://github.com/vllm-project/vllm/releases/download/v${VLLM_VERSION}/vllm-${VLLM_VERSION}cpu-cp38-abi3-manylinux_2_34_x86_64.whl --extra-index-url https://download.pytorch.org/whl/cpu关于 Wheel 文件名值得解读一下vllm-版本cpu-cp38-abi3-manylinux_2_34_x86_64.whl中cpu标明这是 CPU 构建产物与 CUDA/ROCm 版区分vLLM 构建系统通过VLLM_TARGET_DEVICE决定目标cp38-abi3采用 CPython 的稳定 ABIlimited API即一个 Wheel 可覆盖 Python 3.8 的多个版本因此能服务 3.10–3.13 环境manylinux_2_34_x86_64面向 glibc ≥ 2.34 的 x86_64 Linux 平台。4.2 安装后必须设置LD_PRELOAD⚠️ 通过 Wheel 安装的 vLLM CPU使用前必须确保Intel OpenMP 已被加入LD_PRELOAD# 手动定位 libiomp5.so 路径 sudo find / -iname *libiomp5.so IOMP_PATH... # 注入 LD_PRELOAD export LD_PRELOAD$IOMP_PATH:$LD_PRELOAD原因在于vLLM CPU 推理的核心算子依赖 OpenMP 并行而 vLLM 分发环境中的libiomp5.soIntel OpenMP runtime需要被预加载以保证其线程池与 NUMA/亲和性策略按照 vLLM 预期的方式运行避免运行时符号冲突或线程调度异常。4.3 Nightly 与指定 Commit 的 Wheel安装最新 main 分支构建的轮子适用于抢先体验新功能、跟进 bug 修复uv pip install vllm --extra-index-url https://wheels.vllm.ai/nightly/cpu --index-strategy first-index --torch-backend cpu安装特定 commit 的轮子——当你需要定位行为变更或性能回归如做 bisect时可在 index URL 中直接指定完整的 commit hashexport VLLM_COMMIT730bd35378bf2a5b56b6d3a45be28b3092d26519 # 使用 main 分支的完整 commit hash uv pip install vllm --extra-index-url https://wheels.vllm.ai/${VLLM_COMMIT}/cpu --index-strategy first-index --torch-backend cpu--index-strategy first-index指示 uv 在解析依赖时以第一个命中即用的策略同时查询多个 index配合 CPU 专属 index 能显著减少解析冲突。这类按版本/提交归档 wheel的持续交付机制正是 CPU 用户不必自己编译即可回归测试历史版本的便捷通道。五、方式二从源码构建 x86 CPU 版 vLLM当需要二次开发、定制编译参数或希望使用尚未发布 Wheel 的代码时选择源码构建。5.1 安装推荐的编译器源码构建会编译大量 C/CUDA-free 内核编译器版本直接影响构建成功率。官方建议使用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-12libnuma-dev用于编译 NUMA 相关绑定逻辑update-alternatives则把系统默认gcc/g切换到 12.x。仓库的 CPU Dockerfile docker/Dockerfile.cpu 在 Ubuntu 25.04 基础镜像中进一步用到了 gcc-15同样通过update-alternatives接管默认编译器说明以较新 GCC 为默认编译器是官方一贯做法。5.2 克隆仓库并安装依赖git clone https://github.com/vllm-project/vllm.git vllm_source cd vllm_source先完成第三节的 Python 环境创建然后安装构建期与运行期依赖uv pip install -r requirements/build/cpu.txt --torch-backend cpu --index-strategy unsafe-best-match uv pip install -r requirements/cpu.txt --torch-backend cpu --index-strategy unsafe-best-match使用pip的等价命令为pip install --upgrade pip pip install -v -r requirements/build/cpu.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其中 requirements/cpu.txt 是 CPU 运行期依赖清单含 torch、oneDNN 相关绑定等requirements/build/cpu.txt是编译期依赖清单cmake、ninja 等unsafe-best-match策略允许 uv 跨越 index 边界挑选最优匹配版本。若不需要可移植性而只要本机运行跳过requirements/build/cpu.txt之外的额外编译依赖即可。5.3 构建与安装关键环境变量是VLLM_TARGET_DEVICEcpu——它告诉 vLLM 的构建系统见 setup.py 与 CMake 配置本机没有 GPU需编译 CPU 目标的内核与算子VLLM_TARGET_DEVICEcpu uv pip install . --no-build-isolation开发者模式editable install改动源码即时生效适合调试 vLLM 本体VLLM_TARGET_DEVICEcpu python3 setup.py develop可选地构建一个可分发的可移植 Wheel便于在其它同平台机器安装VLLM_TARGET_DEVICEcpu uv build --wheel --no-build-isolation # 安装产物 uv pip install dist/*.whl使用pip/python -m build的等价流程VLLM_TARGET_DEVICEcpu python -m build --wheel --no-isolation pip install dist/*.whl仓库中 docker/Dockerfile.cpu 的vllm-build阶段正是这一流程的容器化实现设置VLLM_TARGET_DEVICEcpu后执行python3 setup.py bdist_wheel --dist-dirdist --py-limited-apicp38其中--py-limited-apicp38对应上文 Wheel 文件中的cp38-abi3。此外该 Dockerfile 还会在编译前通过 build_rust.sh 先构建 Rust 前端vllm-rs因此从源码构建本仓库最新代码时工具链中还需具备 Rust 环境直接使用官方 release 源即可自动处理。5.4 从源码构建后的LD_PRELOAD要求从源码安装的 vLLM CPU使用前除了 Intel OpenMP 还需要TCMalloc内存分配器两者都要加入LD_PRELOAD# 安装 TCMallocIntel OpenMP 随 vLLM CPU 一并安装 sudo apt-get install -y --no-install-recommends libtcmalloc-minimal4 # 定位动态库路径 sudo find / -iname *libtcmalloc_minimal.so.4 sudo find / -iname *libiomp5.so TC_PATH... IOMP_PATH... # 按顺序注入 export LD_PRELOAD$TC_PATH:$IOMP_PATH:$LD_PRELOAD这与官方 Docker 镜像的做法完全一致docker/Dockerfile.cpu在 x86_64 基础阶段直接写入ENV LD_PRELOAD/usr/lib/x86_64-linux-gnu/libtcmalloc_minimal.so.4:/opt/venv/lib/libiomp5.so。也就是说容器内的运行环境已经替你完成了这一步。5.5 疑难排查Troubleshooting报错/问题解决方案NumPy ≥ 2.0 兼容性报错降级pip install numpy2.0明明有 CUDA 环境CMake 却把 CUDA 捡进 CPU 构建追加CMAKE_DISABLE_FIND_PACKAGE_CUDAON阻止 CUDA 探测AMD CPU 无法运行需至少第 4 代Zen 4/Genoa及以上以支持 AVX-512 才能运行 vLLM CPUCould not find a version that satisfies the requirement torchX.Y.Zcpucpu更新 pyproject.toml 的构建系统依赖帮助 pip 解析 torch 依赖例如[build-system] requires [ cmake3.26.1, ... torchX.Y.Zcpu # ------- 显式加上 cpu 后缀 ]之所以出现cpucpu这类双后缀通常是 pyproject 里torchX.Y.Z与 PyTorch CPU index 提供的X.Y.Zcpu无法精确匹配所致显式声明cpu后 pip/uv 才能命中 CPU 轮子。六、方式三使用 Docker 部署 CPU 版 vLLM6.1 拉取官方预编译镜像从 Docker Hub 拉取最新的 x86_64 CPU 镜像docker pull vllm/vllm-openai-cpu:latest-x86_64拉取指定 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镜像使用示例latest-x86_64标签对应linux/amd64注意与 ARM 的vllm-openai镜像 tag 体系区分docker run \ -v ~/.cache/huggingface:/root/.cache/huggingface \ -p 8000:8000 \ --env HF_TOKENsecret \ vllm/vllm-openai-cpu:latest-x86_64 args...参数含义-v ~/.cache/huggingface:/root/.cache/huggingface挂载 Hugging Face 缓存避免容器内重复下载模型权重-p 8000:8000将容器内 OpenAI 兼容服务端口映射到宿主机--env HF_TOKEN...注入私有模型所需的访问令牌args...追加 vLLM OpenAI server 参数如模型名、--dtype容器默认入口即vllm serve。6.2 从源码构建 Docker 镜像面向目标 CPU 构建默认构建会使用宿主机架构/指令集docker build -f docker/Dockerfile.cpu \ --build-arg VLLM_CPU_X86false (default)|true \ # 用于交叉编译 --tag vllm-cpu-env \ --target vllm-openai .VLLM_CPU_X86true用于在交叉编译场景下显式开启 x86 ISAAVX2/AVX512支持例如在 arm64 构建机上产出 amd64 镜像时使用。仓库里的 docker/Dockerfile.cpu 会校验该参数在linux/arm64下设置VLLM_CPU_X86会直接报错退出防止混用 ISA 标志。该文件还支持PYTHON_VERSION3.10|3.11|3.12|3.13、ENABLE_AMX_FP8等构建参数。AMD Zen 优化镜像仅linux/amd64vllm-openai-zen目标在默认vllm-openai镜像之上通过vllm[zen]extra 额外安装zentorch使运行时自动激活ZenCpuPlatformdocker build -f docker/Dockerfile.cpu \ --tag vllm-cpu-zen-env \ --target vllm-openai-zen .该镜像接受的参数与环境变量与vllm-openai一致见下文 6.3无需额外 flag 即可启用 Zen 优化关于运行时行为与受支持 dtype 的注意事项见 AMD Zen 优化章节。6.3 启动 OpenAI 兼容服务自建镜像启动 CPU 推理服务的标准命令如下docker run --rm \ --security-opt seccompunconfined \ --cap-add SYS_NICE \ --shm-size4g \ -p 8000:8000 \ -e VLLM_CPU_KVCACHE_SPACEKV cache space \ vllm-cpu-env \ meta-llama/Llama-3.2-1B-Instruct \ --dtypebfloat16 \ other vLLM OpenAI server arguments--security-opt seccompunconfined与--cap-add SYS_NICE放开容器对 NUMA 相关系统调用如get_mempolicy、migrate_pages的限制详见下一节--shm-size4g增大/dev/shm满足多进程/多 rank 数据交换需求VLLM_CPU_KVCACHE_SPACE给 CPU 后端分配的 KV cache 空间GiB见运行时环境变量一节--dtypebfloat16CPU 上推荐显式使用 bfloat16原因见 FAQ 部分。6.4 Docker 中 NUMA 系统调用受限的应对部分容器运行时Docker 等默认 seccomp/capabilities 配置会拦截 vLLM 用到的 NUMA 系统调用get_mempolicy、migrate_pages表现为主机日志出现get_mempolicy: Operation not permitted。功能不受影响但 NUMA 内存绑定/迁移优化不会生效性能可能打折扣。官方建议的最小权限放行方案如下docker run ... --cap-add SYS_NICE --security-opt seccompunconfined ... # 1) --cap-add SYS_NICE 用于解决 get_mempolicy 的 EPERM 问题 # 2) --security-opt seccompunconfined 用于放行 migrate_pages供 numa_migrate_pages() 使用 # 若不能接受关闭 seccomp可基于 runtime 默认 seccomp 配置自定义 profile # 将 migrate_pages 加入 SCMP_ACT_ALLOW 列表。--privilegedtrue也能达到目的但权限过大一般不推荐。在 Kubernetes 中可用如下securityContext等价配置securityContext: seccompProfile: type: Unconfined capabilities: add: - SYS_NICE七、AMD Zen 优化AMD Zen Optimizations{#amd-zen-optimizations}在 AMD Zen CPU 上vLLM 会自动选择ZenCpuPlatformCpuPlatform的子类将线性层Linear/GEMM调度到基于zentorch明确注释了这一行为模型加载期vllm/model_executor/layers/utils.py的 dispatch 逻辑会把线性算子路由到zentorch_linear_unary当VLLM_ZENTORCH_WEIGHT_PREPACK1时还会在加载阶段用zentorch_weight_prepack_for_linear预先重排权重。7.1 自动检测规则Detection rulesZenCpuPlatform的启用需要同时满足以下全部条件vLLM 面向 CPU 构建wheel 带cpu或VLLM_TARGET_DEVICEcpu编译/proc/cpuinfo报告AuthenticAMD且包含avx512import zentorch成功。否则 vLLM 回退到默认的CpuPlatformoneDNN / sgl-kernel 路径。这段逻辑与仓库实现完全对应vllm/platforms/init.py 中的_is_amd_zen_cpu()通过读取/proc/cpuinfo检查AuthenticAMD in cpuinfo and avx512 in cpuinfo随后在cpu_platform_plugin()里尝试import zentorch成功则打印AMD Zen CPU detected with zentorch installed, using ZenCpuPlatform.并返回ZenCpuPlatform失败则回退CpuPlatform。也就是说不需要任何额外开关参数装好zentorch即自动生效。7.2 支持的 dtypefloat16在ZenCpuPlatform上不受支持。ZenCpuPlatform.supported_dtypes只对外宣称bfloat16与float32见 vllm/platforms/zen_cpu.py 第 30-32 行。因此以torch_dtypefloat16声明的模型在加载时会被自动降级为bfloat16并打印标准警告Your device cpu doesnt support torch.float16. Falling back to torch.bfloat16 for compatibility.该警告由 vllm/config/model.py 抛出。这解释了为什么官方示例一律建议--dtypebfloat16。7.3 环境变量VLLM_ZENTORCH_WEIGHT_PREPACK默认值为1在模型加载时就急切eagerly把线性层权重预打包成 ZenDNN 的 blocked 布局从而消除每次推理时的布局转换开销设为0关闭该行为内存有限或排查问题时使用。7.4 如何启用 AMD Zen 优化在 AMD Zen 4 / Zen 5 机器上安装带zenextra 的 CPU Wheel即可随发布拉入该版本配套测试过的zentorchexport VLLM_VERSION$(curl -s https://api.github.com/repos/vllm-project/vllm/releases/latest | jq -r .tag_name | sed s/^v//) uv pip install vllm[zen] --extra-index-url https://wheels.vllm.ai/${VLLM_VERSION}/cpu --index-strategy first-index --torch-backend cpu启动服务并确认平台选择日志vllm serve Qwen/Qwen3-0.6B 21 | grep AMD Zen CPU detected with zentorch installed如需查看每个线性层实际绑定到哪个内核可加VLLM_LOGGING_LEVELDEBUG并检索CPU unquantized GEMM dispatch。从源码层面看Zen 快速路径的可选内核包括W4A16 GPTQ 的zentorch_woq_linearvllm/model_executor/kernels/linear/mixed_precision/zentorch.py、W8A8 dynamic 量化的zentorch_dynamic_qlinearvllm/model_executor/kernels/linear/scaled_mm/zentorch.py、以及 MoE 的zentorch_fused_moevllm/model_executor/kernels/linear/zentorch_utils.py——这些实现均以current_platform.is_zen_cpu()作为分派前置条件。八、CPU 运行时环境变量无论走哪条安装路径下面四个环境变量都直接影响 CPU 推理的资源利用率x86 多路服务器场景尤其关键完整清单见 CPU 安装总览 的 Related runtime environment variables 一节VLLM_CPU_KVCACHE_SPACE指定 KV cache 大小GiB。例如VLLM_CPU_KVCACHE_SPACE40表示预留 40 GiB 给 KV cache取值越大可并行处理的请求越多。应依据硬件配置与内存管理模式设定官方 FAQ 指出未显式配置时 CPU 后端默认约为 4GB注意环境变量段标注的默认值0表示“未显式开启”。若某 TP rank 的权重分片大小 KVCACHE_SPACE超过单个 NUMA 节点容量worker 会因 OOM 以exitcode 9被杀死。VLLM_CPU_OMP_THREADS_BIND指定专用于 OpenMP 线程的 CPU 核心。可设为 CPU id 列表、auto默认或nobind不做核心绑定继承用户自定义 OpenMP 变量VLLM_CPU_OMP_THREADS_BIND0-3132 个 OpenMP 线程绑定在 0-31 号核心VLLM_CPU_OMP_THREADS_BIND0-31|32-63两个 tensor-parallel rankrank0 的 32 线程绑 0-31rank1 的 32 线程绑 32-63auto每个 rank 的 OpenMP 线程分别绑定到各自 NUMA 节点的核心nobind线程数由标准OMP_NUM_THREADS决定。VLLM_CPU_NUM_OF_RESERVED_CPU每个 rank 预留不交给 OpenMP的核心数。仅在VLLM_CPU_OMP_THREADS_BINDauto时生效默认None此时world_size 1不预留、world_size 1时每个 rank 预留 1 核。CPU_VISIBLE_MEMORY_NODES限定 CPU worker 可见的 NUMA 内存节点作用类似CUDA_VISIBLE_DEVICES同样仅在auto绑定模式下生效用于掩蔽节点或调整节点绑定顺序。九、启动服务与性能调优 FAQx86 CPU以下经验来自 CPU 安装总览 的 FAQ是 x86 平台落地时的直接参考。9.1 选择什么 dtypeCPU 后端默认跟随模型自身的默认dtype但由于 torch CPU 对 float16 的支持不稳定一旦出现性能或精度问题建议显式指定--dtypebfloat16在 AMD ZenZenCpuPlatform上float16完全不受支持只有bfloat16与float32可用见 7.2。9.2 如何在 CPU 上启动 vLLM 服务在线服务建议预留 1-2 个 CPU 核给 serving 框架避免 CPU 过订阅。例如 32 物理核平台上把 31 号核留给框架、0-30 号核给推理线程export VLLM_CPU_KVCACHE_SPACE40 export VLLM_CPU_OMP_THREADS_BIND0-30 vllm serve facebook/opt-125m --dtypebfloat16或使用默认的 auto 线程绑定并显式预留 1 核export VLLM_CPU_KVCACHE_SPACE40 export VLLM_CPU_NUM_OF_RESERVED_CPU1 vllm serve facebook/opt-125m --dtypebfloat16注意当world_size 1时仍建议手动为 vLLM 前端进程预留 1 个 CPU。9.3 如何选择VLLM_CPU_OMP_THREADS_BIND默认的auto线程绑定适用于大多数场景每个 OpenMP 线程绑定到独立物理核各 rank 线程绑定到同一 NUMA 节点并在world_size 1时为每个 rank 预留 1 核。若遇到性能异常或绑定行为不符合预期可先通过lscpu -e查看逻辑核与物理核的映射关系后手动绑定。在启用超线程的平台上例如 16 逻辑核 / 8 物理核的机器建议只把 OpenMP 线程绑定到同一物理核组0-7 或 8-15的一半逻辑核上$ lscpu -e # CPU 列为逻辑核 IDCORE 列为物理核 ID # 建议绑定逻辑核 0-7 或 8-15 $ export VLLM_CPU_OMP_THREADS_BIND0-7 $ python examples/basic/offline_inference/basic.py在启用 tensor parallel / pipeline parallel 的多路multi-socketNUMA 机器上每个 NUMA 节点会被视为一个 TP/PP rank务必让单个 rank 的核落在同一 NUMA 节点内避免跨节点内存访问。9.4 有哪些性能调优参数线程绑定与 KV cache 空间设置到位后可通过htop观察运行 benchmark 时的核心占用率来确认生效建议--block-size取 32 的倍数默认 128batch 大小是关键参数batch 越大吞吐越高、越小延迟越低。两个核心参数--max-num-batched-tokens单 batch 的 token 数上限主要影响首 tokenTTFT性能。默认 Offline 推理4096 * world_size在线服务2048 * world_size--max-num-seqs单 batch 的序列数上限主要影响输出 token 性能。默认 Offline 推理256 * world_size在线服务128 * world_size。vLLM CPU 支持数据并行DP、张量并行TP与流水线并行PP以利用多路 socket 与多内存节点详见 并行优化文档若 socket/内存节点充足推荐 DP、TP、PP 组合使用。9.5 支持哪些量化方案vLLM CPU 支持以下量化x86 与 s390x 均可用AWQ、GPTQ、compressed-tensor INT8 W8A8W8A8 仅 x86/s390x。在 AMD Zen 平台上W4A16 GPTQ 与 W8A8 还会进一步走 7.4 节所述的 zentorch 加速内核。9.6 支持哪些模型在 CPU 上经过验证支持的模型完整、实时列表见 Supported Models on CPU。官方建议为每个 CPU 支持模型配套的优化运行配置做基准测试见总览文档 FAQ 的 Benchmark Suite 说明并在配置 tensor-parallel-size 时匹配系统 NUMA 节点数可用lscpu | grep NUMA node(s): | awk {print $3}查询注意当前发布不支持tensor-parallel-size6。小结x86 CPU 是 vLLM CPU 后端覆盖最完整、社区最活跃的硬件分支从 v0.17.0 起官方直接提供cp38-abi3预编译 Wheel覆盖 FP32/FP16/BF16 推理与 OpenAI 兼容 serving源码构建仅需确保gcc 12.3与VLLM_TARGET_DEVICEcpuDocker 侧则同时提供vllm-openai-cpu预构建镜像与vllm-openai-zen的 AMD Zen 优化目标。无论选择哪条路径请牢记两件必做事项为运行期配置好LD_PRELOADWheel 需 Intel OpenMP源码构建还需 TCMalloc以及按机器拓扑设置VLLM_CPU_KVCACHE_SPACE与VLLM_CPU_OMP_THREADS_BIND。若你运行在 AMD Zen 4/5 上装上vllm[zen]后即可在启动日志中看到ZenCpuPlatform自动接管线性层分派的提示无需任何手工配置。【免费下载链接】vllmA high-throughput and memory-efficient inference and serving engine for LLMs项目地址: https://gitcode.com/GitHub_Trending/vl/vllm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
vLLM CPU 后端 x86 平台安装指南预编译 Wheel、源码编译与 Docker 部署实践【免费下载链接】vllmA high-throughput and memory-efficient inference and serving engine for LLMs项目地址: https://gitcode.com/GitHub_Trending/vl/vllm导读本指南面向需要在x86 CPUIntel / AMD平台上运行 vLLM 推理与在线服务的开发者完整覆盖四条从简到繁的安装路径直接使用官方预编译 Wheel、从源码自行编译、使用 Docker 预编译镜像、以及为特定目标 CPU 或 AMD Zen 平台自建镜像。读完本文你将掌握如何用uv/pip干净地搭建 CPU 版环境、为什么必须设置LD_PRELOAD指向 Intel OpenMP以及何时需要 TCMalloc、如何拉取与运行vllm-openai-cpu镜像、如何开启并验证 AMD ZenZenDNN/zentorch优化路径以及VLLM_CPU_KVCACHE_SPACE、VLLM_CPU_OMP_THREADS_BIND等关键运行时变量的正确用法。本文主体源自 docs/getting_started/installation/cpu.x86.inc.md 及其宿主文档 docs/getting_started/installation/cpu.md并补充了当前仓库中对应的平台源码与 Docker 构建脚本作为印证。一、x86 CPU 后端能力与前置要求vLLM 支持在 x86 CPU 平台上进行基础的模型推理与在线服务serving支持的推理数据类型为FP32、FP16 与 BF16。这份能力声明同样是后续所有安装方式的前提——无论采用哪种安装路径最终交付的都是同一个面向 CPU 目标的 vLLM 构建产物。安装前请确认满足以下前置条件项目要求操作系统LinuxCPU 指令集标志avx512f推荐avx2仅支持有限功能Python 版本3.10 – 3.13编译器源码构建推荐gcc/g 12.3.0检查 CPU flags 的最直接方式是使用lscpulscpu | grep -E Flags|型号名称 # Flags 一栏中应包含 avx512f 或 avx2需要特别说明仅具备avx2的 CPU 只能获得“受限功能”vLLM 的部分算子实现例如依赖 AVX-512 的 GEMM 调度路径无法启用因此在生产部署中优先选择带avx512f的处理器。此外AMD 平台用户需要注意AMD 处理器至少需要第 4 代Zen 4 / Genoa或更新的架构才支持 AVX-512从而满足 vLLM CPU 运行要求详见后文“疑难排查”一节。本仓库为 CPU 目标提供了多平台支持文档x86 只是其中之一另有 ARM AArch64、Apple silicon、IBM Z s390x可参考 CPU 安装总览 选择对应分支。二、三条安装路径的选择针对 x86 CPU官方提供以下三类主流安装方式你可按场景组合使用安装路径适用场景关键要点预编译 Wheel快速起步、避免编译版本 0.17.0 起提供需设置LD_PRELOAD指向 Intel OpenMP从源码构建二次开发、定制化编译、源码调试需gcc 12.3设置VLLM_TARGET_DEVICEcpuDocker 镜像服务化部署、CI、隔离环境官方镜像vllm/vllm-openai-cpu支持 AMD Zen 目标在开始任一方式之前建议先用uv创建干净的 Python 环境详见第三节。如果你已有现成环境并想先快速验证推理可直接跳到第四节的预编译 Wheel。三、准备 Python 环境推荐 uv官方推荐使用 uv由 Astral 出品的极速 Python 环境/包管理器来创建和管理虚拟环境。创建 CPU 开发环境的标准做法是uv venv --python 3.12 --seed --managed-python source .venv/bin/activate说明--python 3.12CPU 后端与构建链路在 3.10–3.13 上均有验证3.12 为当前默认推荐版本--seed在环境中预置pip与setuptools便于后续回退使用pip安装--managed-python允许 uv 在缺失对应 Python 版本时自动下载托管版本。这套流程来自被 cpu.x86.inc.md 引用的公共片段 python_env_setup.inc.md。此外CPU 安装的 uv/pip 命令普遍带有--torch-backend cpu或--extra-index-url https://download.pytorch.org/whl/cpu作用是让包解析器优先从 PyTorch 官方 CPU index 拉取带cpu后缀的 PyTorch 轮子避免误装 CUDA 版本。四、方式一安装官方预编译 Wheel4.1 Release Wheel稳定版官方为 x86AVX512/AVX2提供预编译 vLLM Wheel自v0.17.0起可用。安装步骤如下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_34_x86_64.whl --torch-backend cpu如果习惯用pip等价命令为pip install https://github.com/vllm-project/vllm/releases/download/v${VLLM_VERSION}/vllm-${VLLM_VERSION}cpu-cp38-abi3-manylinux_2_34_x86_64.whl --extra-index-url https://download.pytorch.org/whl/cpu关于 Wheel 文件名值得解读一下vllm-版本cpu-cp38-abi3-manylinux_2_34_x86_64.whl中cpu标明这是 CPU 构建产物与 CUDA/ROCm 版区分vLLM 构建系统通过VLLM_TARGET_DEVICE决定目标cp38-abi3采用 CPython 的稳定 ABIlimited API即一个 Wheel 可覆盖 Python 3.8 的多个版本因此能服务 3.10–3.13 环境manylinux_2_34_x86_64面向 glibc ≥ 2.34 的 x86_64 Linux 平台。4.2 安装后必须设置LD_PRELOAD⚠️ 通过 Wheel 安装的 vLLM CPU使用前必须确保Intel OpenMP 已被加入LD_PRELOAD# 手动定位 libiomp5.so 路径 sudo find / -iname *libiomp5.so IOMP_PATH... # 注入 LD_PRELOAD export LD_PRELOAD$IOMP_PATH:$LD_PRELOAD原因在于vLLM CPU 推理的核心算子依赖 OpenMP 并行而 vLLM 分发环境中的libiomp5.soIntel OpenMP runtime需要被预加载以保证其线程池与 NUMA/亲和性策略按照 vLLM 预期的方式运行避免运行时符号冲突或线程调度异常。4.3 Nightly 与指定 Commit 的 Wheel安装最新 main 分支构建的轮子适用于抢先体验新功能、跟进 bug 修复uv pip install vllm --extra-index-url https://wheels.vllm.ai/nightly/cpu --index-strategy first-index --torch-backend cpu安装特定 commit 的轮子——当你需要定位行为变更或性能回归如做 bisect时可在 index URL 中直接指定完整的 commit hashexport VLLM_COMMIT730bd35378bf2a5b56b6d3a45be28b3092d26519 # 使用 main 分支的完整 commit hash uv pip install vllm --extra-index-url https://wheels.vllm.ai/${VLLM_COMMIT}/cpu --index-strategy first-index --torch-backend cpu--index-strategy first-index指示 uv 在解析依赖时以第一个命中即用的策略同时查询多个 index配合 CPU 专属 index 能显著减少解析冲突。这类按版本/提交归档 wheel的持续交付机制正是 CPU 用户不必自己编译即可回归测试历史版本的便捷通道。五、方式二从源码构建 x86 CPU 版 vLLM当需要二次开发、定制编译参数或希望使用尚未发布 Wheel 的代码时选择源码构建。5.1 安装推荐的编译器源码构建会编译大量 C/CUDA-free 内核编译器版本直接影响构建成功率。官方建议使用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-12libnuma-dev用于编译 NUMA 相关绑定逻辑update-alternatives则把系统默认gcc/g切换到 12.x。仓库的 CPU Dockerfile docker/Dockerfile.cpu 在 Ubuntu 25.04 基础镜像中进一步用到了 gcc-15同样通过update-alternatives接管默认编译器说明以较新 GCC 为默认编译器是官方一贯做法。5.2 克隆仓库并安装依赖git clone https://github.com/vllm-project/vllm.git vllm_source cd vllm_source先完成第三节的 Python 环境创建然后安装构建期与运行期依赖uv pip install -r requirements/build/cpu.txt --torch-backend cpu --index-strategy unsafe-best-match uv pip install -r requirements/cpu.txt --torch-backend cpu --index-strategy unsafe-best-match使用pip的等价命令为pip install --upgrade pip pip install -v -r requirements/build/cpu.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其中 requirements/cpu.txt 是 CPU 运行期依赖清单含 torch、oneDNN 相关绑定等requirements/build/cpu.txt是编译期依赖清单cmake、ninja 等unsafe-best-match策略允许 uv 跨越 index 边界挑选最优匹配版本。若不需要可移植性而只要本机运行跳过requirements/build/cpu.txt之外的额外编译依赖即可。5.3 构建与安装关键环境变量是VLLM_TARGET_DEVICEcpu——它告诉 vLLM 的构建系统见 setup.py 与 CMake 配置本机没有 GPU需编译 CPU 目标的内核与算子VLLM_TARGET_DEVICEcpu uv pip install . --no-build-isolation开发者模式editable install改动源码即时生效适合调试 vLLM 本体VLLM_TARGET_DEVICEcpu python3 setup.py develop可选地构建一个可分发的可移植 Wheel便于在其它同平台机器安装VLLM_TARGET_DEVICEcpu uv build --wheel --no-build-isolation # 安装产物 uv pip install dist/*.whl使用pip/python -m build的等价流程VLLM_TARGET_DEVICEcpu python -m build --wheel --no-isolation pip install dist/*.whl仓库中 docker/Dockerfile.cpu 的vllm-build阶段正是这一流程的容器化实现设置VLLM_TARGET_DEVICEcpu后执行python3 setup.py bdist_wheel --dist-dirdist --py-limited-apicp38其中--py-limited-apicp38对应上文 Wheel 文件中的cp38-abi3。此外该 Dockerfile 还会在编译前通过 build_rust.sh 先构建 Rust 前端vllm-rs因此从源码构建本仓库最新代码时工具链中还需具备 Rust 环境直接使用官方 release 源即可自动处理。5.4 从源码构建后的LD_PRELOAD要求从源码安装的 vLLM CPU使用前除了 Intel OpenMP 还需要TCMalloc内存分配器两者都要加入LD_PRELOAD# 安装 TCMallocIntel OpenMP 随 vLLM CPU 一并安装 sudo apt-get install -y --no-install-recommends libtcmalloc-minimal4 # 定位动态库路径 sudo find / -iname *libtcmalloc_minimal.so.4 sudo find / -iname *libiomp5.so TC_PATH... IOMP_PATH... # 按顺序注入 export LD_PRELOAD$TC_PATH:$IOMP_PATH:$LD_PRELOAD这与官方 Docker 镜像的做法完全一致docker/Dockerfile.cpu在 x86_64 基础阶段直接写入ENV LD_PRELOAD/usr/lib/x86_64-linux-gnu/libtcmalloc_minimal.so.4:/opt/venv/lib/libiomp5.so。也就是说容器内的运行环境已经替你完成了这一步。5.5 疑难排查Troubleshooting报错/问题解决方案NumPy ≥ 2.0 兼容性报错降级pip install numpy2.0明明有 CUDA 环境CMake 却把 CUDA 捡进 CPU 构建追加CMAKE_DISABLE_FIND_PACKAGE_CUDAON阻止 CUDA 探测AMD CPU 无法运行需至少第 4 代Zen 4/Genoa及以上以支持 AVX-512 才能运行 vLLM CPUCould not find a version that satisfies the requirement torchX.Y.Zcpucpu更新 pyproject.toml 的构建系统依赖帮助 pip 解析 torch 依赖例如[build-system] requires [ cmake3.26.1, ... torchX.Y.Zcpu # ------- 显式加上 cpu 后缀 ]之所以出现cpucpu这类双后缀通常是 pyproject 里torchX.Y.Z与 PyTorch CPU index 提供的X.Y.Zcpu无法精确匹配所致显式声明cpu后 pip/uv 才能命中 CPU 轮子。六、方式三使用 Docker 部署 CPU 版 vLLM6.1 拉取官方预编译镜像从 Docker Hub 拉取最新的 x86_64 CPU 镜像docker pull vllm/vllm-openai-cpu:latest-x86_64拉取指定 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镜像使用示例latest-x86_64标签对应linux/amd64注意与 ARM 的vllm-openai镜像 tag 体系区分docker run \ -v ~/.cache/huggingface:/root/.cache/huggingface \ -p 8000:8000 \ --env HF_TOKENsecret \ vllm/vllm-openai-cpu:latest-x86_64 args...参数含义-v ~/.cache/huggingface:/root/.cache/huggingface挂载 Hugging Face 缓存避免容器内重复下载模型权重-p 8000:8000将容器内 OpenAI 兼容服务端口映射到宿主机--env HF_TOKEN...注入私有模型所需的访问令牌args...追加 vLLM OpenAI server 参数如模型名、--dtype容器默认入口即vllm serve。6.2 从源码构建 Docker 镜像面向目标 CPU 构建默认构建会使用宿主机架构/指令集docker build -f docker/Dockerfile.cpu \ --build-arg VLLM_CPU_X86false (default)|true \ # 用于交叉编译 --tag vllm-cpu-env \ --target vllm-openai .VLLM_CPU_X86true用于在交叉编译场景下显式开启 x86 ISAAVX2/AVX512支持例如在 arm64 构建机上产出 amd64 镜像时使用。仓库里的 docker/Dockerfile.cpu 会校验该参数在linux/arm64下设置VLLM_CPU_X86会直接报错退出防止混用 ISA 标志。该文件还支持PYTHON_VERSION3.10|3.11|3.12|3.13、ENABLE_AMX_FP8等构建参数。AMD Zen 优化镜像仅linux/amd64vllm-openai-zen目标在默认vllm-openai镜像之上通过vllm[zen]extra 额外安装zentorch使运行时自动激活ZenCpuPlatformdocker build -f docker/Dockerfile.cpu \ --tag vllm-cpu-zen-env \ --target vllm-openai-zen .该镜像接受的参数与环境变量与vllm-openai一致见下文 6.3无需额外 flag 即可启用 Zen 优化关于运行时行为与受支持 dtype 的注意事项见 AMD Zen 优化章节。6.3 启动 OpenAI 兼容服务自建镜像启动 CPU 推理服务的标准命令如下docker run --rm \ --security-opt seccompunconfined \ --cap-add SYS_NICE \ --shm-size4g \ -p 8000:8000 \ -e VLLM_CPU_KVCACHE_SPACEKV cache space \ vllm-cpu-env \ meta-llama/Llama-3.2-1B-Instruct \ --dtypebfloat16 \ other vLLM OpenAI server arguments--security-opt seccompunconfined与--cap-add SYS_NICE放开容器对 NUMA 相关系统调用如get_mempolicy、migrate_pages的限制详见下一节--shm-size4g增大/dev/shm满足多进程/多 rank 数据交换需求VLLM_CPU_KVCACHE_SPACE给 CPU 后端分配的 KV cache 空间GiB见运行时环境变量一节--dtypebfloat16CPU 上推荐显式使用 bfloat16原因见 FAQ 部分。6.4 Docker 中 NUMA 系统调用受限的应对部分容器运行时Docker 等默认 seccomp/capabilities 配置会拦截 vLLM 用到的 NUMA 系统调用get_mempolicy、migrate_pages表现为主机日志出现get_mempolicy: Operation not permitted。功能不受影响但 NUMA 内存绑定/迁移优化不会生效性能可能打折扣。官方建议的最小权限放行方案如下docker run ... --cap-add SYS_NICE --security-opt seccompunconfined ... # 1) --cap-add SYS_NICE 用于解决 get_mempolicy 的 EPERM 问题 # 2) --security-opt seccompunconfined 用于放行 migrate_pages供 numa_migrate_pages() 使用 # 若不能接受关闭 seccomp可基于 runtime 默认 seccomp 配置自定义 profile # 将 migrate_pages 加入 SCMP_ACT_ALLOW 列表。--privilegedtrue也能达到目的但权限过大一般不推荐。在 Kubernetes 中可用如下securityContext等价配置securityContext: seccompProfile: type: Unconfined capabilities: add: - SYS_NICE七、AMD Zen 优化AMD Zen Optimizations{#amd-zen-optimizations}在 AMD Zen CPU 上vLLM 会自动选择ZenCpuPlatformCpuPlatform的子类将线性层Linear/GEMM调度到基于zentorch明确注释了这一行为模型加载期vllm/model_executor/layers/utils.py的 dispatch 逻辑会把线性算子路由到zentorch_linear_unary当VLLM_ZENTORCH_WEIGHT_PREPACK1时还会在加载阶段用zentorch_weight_prepack_for_linear预先重排权重。7.1 自动检测规则Detection rulesZenCpuPlatform的启用需要同时满足以下全部条件vLLM 面向 CPU 构建wheel 带cpu或VLLM_TARGET_DEVICEcpu编译/proc/cpuinfo报告AuthenticAMD且包含avx512import zentorch成功。否则 vLLM 回退到默认的CpuPlatformoneDNN / sgl-kernel 路径。这段逻辑与仓库实现完全对应vllm/platforms/init.py 中的_is_amd_zen_cpu()通过读取/proc/cpuinfo检查AuthenticAMD in cpuinfo and avx512 in cpuinfo随后在cpu_platform_plugin()里尝试import zentorch成功则打印AMD Zen CPU detected with zentorch installed, using ZenCpuPlatform.并返回ZenCpuPlatform失败则回退CpuPlatform。也就是说不需要任何额外开关参数装好zentorch即自动生效。7.2 支持的 dtypefloat16在ZenCpuPlatform上不受支持。ZenCpuPlatform.supported_dtypes只对外宣称bfloat16与float32见 vllm/platforms/zen_cpu.py 第 30-32 行。因此以torch_dtypefloat16声明的模型在加载时会被自动降级为bfloat16并打印标准警告Your device cpu doesnt support torch.float16. Falling back to torch.bfloat16 for compatibility.该警告由 vllm/config/model.py 抛出。这解释了为什么官方示例一律建议--dtypebfloat16。7.3 环境变量VLLM_ZENTORCH_WEIGHT_PREPACK默认值为1在模型加载时就急切eagerly把线性层权重预打包成 ZenDNN 的 blocked 布局从而消除每次推理时的布局转换开销设为0关闭该行为内存有限或排查问题时使用。7.4 如何启用 AMD Zen 优化在 AMD Zen 4 / Zen 5 机器上安装带zenextra 的 CPU Wheel即可随发布拉入该版本配套测试过的zentorchexport VLLM_VERSION$(curl -s https://api.github.com/repos/vllm-project/vllm/releases/latest | jq -r .tag_name | sed s/^v//) uv pip install vllm[zen] --extra-index-url https://wheels.vllm.ai/${VLLM_VERSION}/cpu --index-strategy first-index --torch-backend cpu启动服务并确认平台选择日志vllm serve Qwen/Qwen3-0.6B 21 | grep AMD Zen CPU detected with zentorch installed如需查看每个线性层实际绑定到哪个内核可加VLLM_LOGGING_LEVELDEBUG并检索CPU unquantized GEMM dispatch。从源码层面看Zen 快速路径的可选内核包括W4A16 GPTQ 的zentorch_woq_linearvllm/model_executor/kernels/linear/mixed_precision/zentorch.py、W8A8 dynamic 量化的zentorch_dynamic_qlinearvllm/model_executor/kernels/linear/scaled_mm/zentorch.py、以及 MoE 的zentorch_fused_moevllm/model_executor/kernels/linear/zentorch_utils.py——这些实现均以current_platform.is_zen_cpu()作为分派前置条件。八、CPU 运行时环境变量无论走哪条安装路径下面四个环境变量都直接影响 CPU 推理的资源利用率x86 多路服务器场景尤其关键完整清单见 CPU 安装总览 的 Related runtime environment variables 一节VLLM_CPU_KVCACHE_SPACE指定 KV cache 大小GiB。例如VLLM_CPU_KVCACHE_SPACE40表示预留 40 GiB 给 KV cache取值越大可并行处理的请求越多。应依据硬件配置与内存管理模式设定官方 FAQ 指出未显式配置时 CPU 后端默认约为 4GB注意环境变量段标注的默认值0表示“未显式开启”。若某 TP rank 的权重分片大小 KVCACHE_SPACE超过单个 NUMA 节点容量worker 会因 OOM 以exitcode 9被杀死。VLLM_CPU_OMP_THREADS_BIND指定专用于 OpenMP 线程的 CPU 核心。可设为 CPU id 列表、auto默认或nobind不做核心绑定继承用户自定义 OpenMP 变量VLLM_CPU_OMP_THREADS_BIND0-3132 个 OpenMP 线程绑定在 0-31 号核心VLLM_CPU_OMP_THREADS_BIND0-31|32-63两个 tensor-parallel rankrank0 的 32 线程绑 0-31rank1 的 32 线程绑 32-63auto每个 rank 的 OpenMP 线程分别绑定到各自 NUMA 节点的核心nobind线程数由标准OMP_NUM_THREADS决定。VLLM_CPU_NUM_OF_RESERVED_CPU每个 rank 预留不交给 OpenMP的核心数。仅在VLLM_CPU_OMP_THREADS_BINDauto时生效默认None此时world_size 1不预留、world_size 1时每个 rank 预留 1 核。CPU_VISIBLE_MEMORY_NODES限定 CPU worker 可见的 NUMA 内存节点作用类似CUDA_VISIBLE_DEVICES同样仅在auto绑定模式下生效用于掩蔽节点或调整节点绑定顺序。九、启动服务与性能调优 FAQx86 CPU以下经验来自 CPU 安装总览 的 FAQ是 x86 平台落地时的直接参考。9.1 选择什么 dtypeCPU 后端默认跟随模型自身的默认dtype但由于 torch CPU 对 float16 的支持不稳定一旦出现性能或精度问题建议显式指定--dtypebfloat16在 AMD ZenZenCpuPlatform上float16完全不受支持只有bfloat16与float32可用见 7.2。9.2 如何在 CPU 上启动 vLLM 服务在线服务建议预留 1-2 个 CPU 核给 serving 框架避免 CPU 过订阅。例如 32 物理核平台上把 31 号核留给框架、0-30 号核给推理线程export VLLM_CPU_KVCACHE_SPACE40 export VLLM_CPU_OMP_THREADS_BIND0-30 vllm serve facebook/opt-125m --dtypebfloat16或使用默认的 auto 线程绑定并显式预留 1 核export VLLM_CPU_KVCACHE_SPACE40 export VLLM_CPU_NUM_OF_RESERVED_CPU1 vllm serve facebook/opt-125m --dtypebfloat16注意当world_size 1时仍建议手动为 vLLM 前端进程预留 1 个 CPU。9.3 如何选择VLLM_CPU_OMP_THREADS_BIND默认的auto线程绑定适用于大多数场景每个 OpenMP 线程绑定到独立物理核各 rank 线程绑定到同一 NUMA 节点并在world_size 1时为每个 rank 预留 1 核。若遇到性能异常或绑定行为不符合预期可先通过lscpu -e查看逻辑核与物理核的映射关系后手动绑定。在启用超线程的平台上例如 16 逻辑核 / 8 物理核的机器建议只把 OpenMP 线程绑定到同一物理核组0-7 或 8-15的一半逻辑核上$ lscpu -e # CPU 列为逻辑核 IDCORE 列为物理核 ID # 建议绑定逻辑核 0-7 或 8-15 $ export VLLM_CPU_OMP_THREADS_BIND0-7 $ python examples/basic/offline_inference/basic.py在启用 tensor parallel / pipeline parallel 的多路multi-socketNUMA 机器上每个 NUMA 节点会被视为一个 TP/PP rank务必让单个 rank 的核落在同一 NUMA 节点内避免跨节点内存访问。9.4 有哪些性能调优参数线程绑定与 KV cache 空间设置到位后可通过htop观察运行 benchmark 时的核心占用率来确认生效建议--block-size取 32 的倍数默认 128batch 大小是关键参数batch 越大吞吐越高、越小延迟越低。两个核心参数--max-num-batched-tokens单 batch 的 token 数上限主要影响首 tokenTTFT性能。默认 Offline 推理4096 * world_size在线服务2048 * world_size--max-num-seqs单 batch 的序列数上限主要影响输出 token 性能。默认 Offline 推理256 * world_size在线服务128 * world_size。vLLM CPU 支持数据并行DP、张量并行TP与流水线并行PP以利用多路 socket 与多内存节点详见 并行优化文档若 socket/内存节点充足推荐 DP、TP、PP 组合使用。9.5 支持哪些量化方案vLLM CPU 支持以下量化x86 与 s390x 均可用AWQ、GPTQ、compressed-tensor INT8 W8A8W8A8 仅 x86/s390x。在 AMD Zen 平台上W4A16 GPTQ 与 W8A8 还会进一步走 7.4 节所述的 zentorch 加速内核。9.6 支持哪些模型在 CPU 上经过验证支持的模型完整、实时列表见 Supported Models on CPU。官方建议为每个 CPU 支持模型配套的优化运行配置做基准测试见总览文档 FAQ 的 Benchmark Suite 说明并在配置 tensor-parallel-size 时匹配系统 NUMA 节点数可用lscpu | grep NUMA node(s): | awk {print $3}查询注意当前发布不支持tensor-parallel-size6。小结x86 CPU 是 vLLM CPU 后端覆盖最完整、社区最活跃的硬件分支从 v0.17.0 起官方直接提供cp38-abi3预编译 Wheel覆盖 FP32/FP16/BF16 推理与 OpenAI 兼容 serving源码构建仅需确保gcc 12.3与VLLM_TARGET_DEVICEcpuDocker 侧则同时提供vllm-openai-cpu预构建镜像与vllm-openai-zen的 AMD Zen 优化目标。无论选择哪条路径请牢记两件必做事项为运行期配置好LD_PRELOADWheel 需 Intel OpenMP源码构建还需 TCMalloc以及按机器拓扑设置VLLM_CPU_KVCACHE_SPACE与VLLM_CPU_OMP_THREADS_BIND。若你运行在 AMD Zen 4/5 上装上vllm[zen]后即可在启动日志中看到ZenCpuPlatform自动接管线性层分派的提示无需任何手工配置。【免费下载链接】vllmA high-throughput and memory-efficient inference and serving engine for LLMs项目地址: https://gitcode.com/GitHub_Trending/vl/vllm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
