vLLM 在 IBM Zs390x平台上的 CPU 从源码构建与容器部署指南【免费下载链接】vllmA high-throughput and memory-efficient inference and serving engine for LLMs项目地址: https://gitcode.com/GitHub_Trending/vl/vllm导读本文面向需要在 IBM Z / LinuxONE 主机的 s390x CPU 架构上运行 vLLM 的开发者与运维工程师完整讲解当前仓库中 s390x CPU 后端从源码编译、本地 wheel 安装、Docker 镜像构建到 OpenAI 兼容服务启动的全流程。读完本文你将掌握s390x 平台当前的能力边界与硬件/工具链前提、逐个从源码构建torchvision/llvmlite/numba/opencv-python-headless/hf-xet等无预编译 wheel 依赖的关键细节、绕过 LLVM 版本与 Protobuf C 扩展等典型坑位的方法以及如何利用仓库中的 VXE 向量化注意力内核在 Z15 及以上机器上获得原生推理性能。一、s390x 支持概览能力边界与当前状态vLLM 对 IBM Z 平台s390x 架构的支持目前仍处于experimental实验性阶段。核心限制是必须从源码构建才能在 IBM Z 上原生运行——当前官方既没有预构建的 IBM Z CPU wheel也没有预构建的镜像这一点在 docs/getting_started/installation/cpu.s390x.inc.md 及 docker/Dockerfile.s390x 中均可得到印证。从该文档可以确认s390x CPU 实现当前支持的数据精度与量化方案为浮点精度FP32、BF16、FP16量化AWQ与GPTQ的 4-bit 量化以及compressed-tensors的INT8 W8A8量化从仓库源码结构看这一支持并非简单的能跑通而是有专门针对 s390x 的底层实现vLLM 的 CPU 注意力后端为 IBM Z 提供了独立的向量化实现路径详见下文第五节源码佐证。因此使用方需要明确这是针对特定硬件体系做的原生适配而不是靠模拟或通用回退路径。二、硬性前提条件Requirements在动手构建之前请先核对目标环境是否满足以下全部条件任何一项缺失都会导致构建失败或运行期崩溃条件要求说明操作系统Linux文档示例基于 RHEL 9.6UBI 9.6编译器gcc/g 14.0.0需配套 Command Line Tools即完整的开发工具链RHEL 上对应gcc-toolset-14指令集VXE 支持为必需仅适用于Z15 及以上的 IBM Z 主机VXE 即 Vector Extension Facility上游 Python 包需从源码自行构建torchvision、llvmlite、numba、opencv-python-headless、hf-xet均没有 s390x 的预编译 wheel上述第 4 点是构建链路中最耗时的部分因为torchvision、llvmlite、numba、opencv都不是小项目。文档给出的建议做法是参照仓库内的多阶段构建脚本 docker/Dockerfile.s390x 中各阶段使用的精确版本与编译命令逐一构建——也就是说Dockerfile 本身就是一份可追溯的构建配方。为什么这几个包必须从源码构建从 requirements/cpu.txt 可以看出仓库侧的印证torchvision; platform_machine ! s390x ...—— 官方依赖中直接排除了 s390x 的 torchvisionnumba 0.65.0; platform_machine ! s390x—— numba 同样在 s390x 上不可通过 pip 直接安装同理torchaudio、torchcodec也均以平台标记排除了 s390x。而 requirements/build/cpu.txt 则明确torch2.13.0cpu需要覆盖x86_64/s390x/aarch64说明 PyTorch CPU 版本身对 s390x 是有关键支持的。三、在 IBM Z 上从源码构建 vLLM本节完全对应原文档build-wheel-from-source章节的命令流程建议按顺序逐段执行。3.1 安装系统级构建依赖以 RHEL 9.6 为例先用包管理器安装 vLLM 构建所需的基础工具链dnf install -y \ which procps findutils tar vim git patch xz ninja-build \ gcc-toolset-14 gcc-toolset-14-binutils gcc-toolset-14-libatomic-devel zlib-devel \ libjpeg-turbo-devel libtiff-devel libpng-devel libwebp-devel freetype-devel harfbuzz-devel \ openssl-devel openblas openblas-devel autoconf automake libtool cmake numpy libsndfile \ clang llvm-devel llvm-static clang-devel要点说明gcc-toolset-14系列包是为了满足 gcc/g ≥ 14 的前提注意使用前需 source 对应环境Dockerfile 中通过显式设置PATH/LD_LIBRARY_PATH指向/opt/rh/gcc-toolset-14/root完成激活参见 docker/Dockerfile.s390xopenblas/libsndfile等是 PyTorch CPU 推理与音频解码链路常用依赖llvm-devel、clang等与后面 llvmlite/numba 的源码构建相关但需注意版本坑见 3.4 节。3.2 从源码构建并安装 numactlvLLM 的 CPU 后端依赖numactl做 NUMA 感知的核绑定与内存分配而发行版仓库中的版本可能过旧因此文档要求从源码安装 v2.0.19curl -LO https://github.com/numactl/numactl/archive/refs/tags/v2.0.19.tar.gz tar -xvzf v2.0.19.tar.gz cd numactl-2.0.19 ./autogen.sh ./configure make make install cd ..注在 docker/Dockerfile.s390x 的numa-build阶段中numactl 同样以 v2.0.19 源码构建并通过C_INCLUDE_PATH/usr/local/include让后续的 vLLM 编译能找到头文件。3.3 安装 Rust≥ 1.80outlines-core、uvloop、hf-xet这三个 Python 包在 s390x 上需要 Rust 工具链参与构建官方要求 Rust ≥ 1.80curl https://sh.rustup.rs -sSf | sh -s -- -y \ . $HOME/.cargo/env3.4 从源码构建 5 个无预编译 wheel 的上游包这一步是整个流程中最容易出现连环坑的部分官方明确提示Pre-built wheels are not available for s390x for the following packages. Build them from source before building vLLM:torchvision,llvmlite,numba,opencv-python-headless,hf-xet. 精确版本与构建命令可参考 docker/Dockerfile.s390x 中各 multi-stage 构建阶段。其中值得单独展开的是llvmlite 与 LLVM 20 的版本冲突LLVM 20 必须从源码构建llvmlite 的硬性要求llvmlite v0.47要求 LLVM 20但 UBI 9.6 / RHEL 9.6 仓库默认提供的是LLVM 21二者不兼容。因此必须先从源码构建 LLVM 20只需 SystemZ 目标后端即可可大幅缩短编译时间curl -LO https://github.com/llvm/llvm-project/releases/download/llvmorg-20.1.8/llvm-project-20.1.8.src.tar.xz tar -xf llvm-project-20.1.8.src.tar.xz cmake -G Ninja -S llvm-project-20.1.8.src/llvm -B llvm-build \ -DCMAKE_BUILD_TYPERelease \ -DCMAKE_INSTALL_PREFIX/opt/llvm20 \ -DLLVM_TARGETS_TO_BUILDSystemZ \ -DLLVM_ENABLE_RTTION \ -DLLVM_BUILD_TOOLSOFF \ -DLLVM_BUILD_UTILSON \ -DLLVM_BUILD_EXAMPLESOFF \ -DLLVM_BUILD_TESTSOFF \ -DLLVM_INCLUDE_TESTSOFF \ -DLLVM_INCLUDE_EXAMPLESOFF \ -DLLVM_INCLUDE_BENCHMARKSOFF ninja -C llvm-build install关键参数解读-DLLVM_TARGETS_TO_BUILDSystemZ只编译 IBM Z 后端这是大幅节省构建时间与磁盘的关键-DLLVM_ENABLE_RTTIONllvmlite 运行时依赖 RTTI必须开启关闭 Tools/Tests/Examples/Benchmarks 各开关均为最小化构建安装前缀/opt/llvm20需与下一步保持一致。随后基于这份自建 LLVM 20 构建 llvmliteCMAKE_PREFIX_PATH/opt/llvm20 LLVM_CONFIG/opt/llvm20/bin/llvm-config \ python setup.py bdist_wheel对照 docker/Dockerfile.s390x 的llvm20-build与numba-builder阶段可知llvmlite 版本固定为v0.47.0numba 固定为0.65.0且构建 numba 时还额外对numba/_dispatcher.cpp打了一个补丁在pycore_atomic.h之前插入dynamic_annotations.h头文件这是仓库为 s390x 验证过的修正自行构建时可参照。至于torchvision对应v0.28.0、opencv-python-headless对应 opencv-python 分支90、hf-xet基于 Rust 的maturin build --release的构建方式官方并未在文档正文逐一展开而是统一指向 Dockerfile 中的torch-vision、opencv-builder、hf-xet-builder阶段——那是经过仓库验证的标准答案强烈建议直接照抄其中的命令与版本号。3.5 安装 vLLM 依赖并构建 wheel完成上述 5 个 wheel 后即可安装 vLLM 的 CPU 构建依赖并产出最终 wheel。官方首选uvuv pip install -v \ /path/to/torchvision.whl \ /path/to/llvmlite.whl \ /path/to/numba.whl \ /path/to/opencv_python_headless.whl \ /path/to/hf_xet.whl \ -r requirements/build/cpu.txt \ -r requirements/cpu.txt \ --torch-backend cpu \ --index-strategy unsafe-best-match \ VLLM_TARGET_DEVICEcpu VLLM_CPU_MOE_PREPACK0 python setup.py bdist_wheel \ uv pip install dist/*.whl如果使用传统pip可切换到如下等价命令需额外指定 PyTorch CPU 索引pip install -v \ --extra-index-url https://download.pytorch.org/whl/cpu \ /path/to/torchvision.whl \ /path/to/llvmlite.whl \ /path/to/numba.whl \ /path/to/opencv_python_headless.whl \ /path/to/hf_xet.whl \ -r requirements/build/cpu.txt \ -r requirements/cpu.txt \ VLLM_TARGET_DEVICEcpu VLLM_CPU_MOE_PREPACK0 python setup.py bdist_wheel \ pip install dist/*.whl两个关键构建期环境变量的作用VLLM_TARGET_DEVICEcpu显式声明目标是 CPU 设备控制 setup.py 中平台判定仓库中可见其对s390x与aarch64/x86_64的显式处理以及 C 扩展的编译开关VLLM_CPU_MOE_PREPACK0关闭 MoE 权重的预打包prepack优化路径。从 csrc/cpu/dnnl_kernels.cpp 等源码中可以看到部分 CPU 内核针对__powerpc64__/__s390x__有不同的编译路径这里通过环境变量保持保守行为避免在 s390x 上引入未经验证的打包布局。3.6 推荐设置 LD_PRELOAD 加载 TCMalloc为了获得最佳内存分配性能官方警告必须构建并预加载 TCMallocgperftools# 从源码构建并安装 TCMalloc curl -LO https://github.com/gperftools/gperftools/releases/download/gperftools-2.16/gperftools-2.16.tar.gz tar -xzf gperftools-2.16.tar.gz cd gperftools-2.16 ./configure --enable-minimal make -j$(nproc) sudo make install sudo ldconfig cd .. # 加入 LD_PRELOAD export LD_PRELOAD/usr/local/lib/libtcmalloc_minimal.so.4:$LD_PRELOAD说明CPU 推理场景下大量 KV Cache 与激活值的分配/释放对内存分配器极其敏感TCMalloc 能显著改善碎片化。如果走 Docker 路线则无需手动处理——官方镜像 docker/Dockerfile.s390x 的gperftools-build阶段已构建 gperftools 2.16 并通过ENV LD_PRELOAD/usr/local/lib/libtcmalloc_minimal.so.4自动注入。3.7 绕开 Protobuf C 扩展崩溃s390x 特有这是 IBM Z 上运行 vLLM 时必须处理的另一个坑s390x 上 Protobuf 的 C 扩展会崩溃。安装完成后需强制使用纯 Python 实现并删除 C 扩展export PROTOCOL_BUFFERS_PYTHON_IMPLEMENTATIONpython # 移除在 s390x 上会崩溃的 C protobuf 扩展 SITE_PKGS$(python -c import site; print(site.getsitepackages()[0])) rm -rf $SITE_PKGS/google/_upb/*.so \ $SITE_PKGS/google/protobuf/pyext/*.so 2/dev/null || truerm -rf的路径做了精细限定仅删除_upb与pyext下的.so并加了2/dev/null || true容错可安全执行。同样地Dockerfile 的最终阶段也执行了等价清理见 docker/Dockerfile.s390x 中rm -rf /opt/vllm/.../google/_upb/*.so ...并在环境变量中预设了PROTOCOL_BUFFERS_PYTHON_IMPLEMENTATIONpython。四、Docker 镜像构建与容器化部署官方为 s390x 提供了专用镜像构建配方 docker/Dockerfile.s390x。该 Dockerfile 是一个高度工程化的多阶段构建基础镜像为registry.access.redhat.com/ubi9/ubi-minimal:9.6RHEL UBI 9.6整体流水线包含python-install阶段安装 Python 3.12 并创建/opt/vllmvenv装入uvrust阶段安装 Rustup 稳定版工具链numa-build阶段构建 numactl 2.0.19gperftools-build阶段构建 TCMalloc 2.16torch-vision阶段在安装torch2.13.0cpu后从源码构建 torchvisionv0.28.0hf-xet-builder阶段用 Rust maturin构建hf_xetllvm20-build阶段从源码构建 LLVM 20.1.8仅 SystemZ 目标numba-builder阶段构建 llvmlite v0.47.0 与 numba 0.65.0含_dispatcher.cpp补丁opencv-builder阶段从源码构建opencv-python分支 90headless 模式vllm-cpu最终阶段通过 BuildKit--mounttypebind将上述各阶段产物以只读方式挂入统一安装依赖后执行VLLM_TARGET_DEVICEcpu VLLM_CPU_MOE_PREPACK0 python setup.py bdist_wheel最后以vllm serve作为默认入口。整个多阶段设计把大量无关但必需的源码编译与最终的 vLLM 编译彻底隔离任意中间包的重编都不会污染最终层缓存这也是阅读该 Dockerfile 时值得借鉴的工程实践。4.1 构建镜像docker build -f docker/Dockerfile.s390x \ --tag vllm-cpu-env .4.2 启动 OpenAI 兼容服务# 启动 OpenAI server docker run --rm \ --security-opt seccompunconfined \ --cap-add SYS_NICE \ --shm-size 4g \ -p 8000:8000 \ -e VLLM_CPU_KVCACHE_SPACEKV cache space \ -e VLLM_CPU_OMP_THREADS_BINDCPU cores for inference \ vllm-cpu-env \ --model meta-llama/Llama-3.2-1B-Instruct \ --dtype bfloat16 \ other vLLM OpenAI server arguments各参数含义--security-opt seccompunconfined与--cap-add SYS_NICECPU 推理线程的调度与亲和性设置需要放宽容器默认的 seccomp 与权限限制官方 tip 提到也可以用--privilegedtrue达到同样效果但该方式权限面过宽不推荐在生产使用--shm-size 4g为进程间共享内存预留足够空间数据并行与 NCCL 等分布式初始化依赖/dev/shmVLLM_CPU_KVCACHE_SPACE指定分配给 KV Cache 的显存等价空间大小是 CPU 推理吞吐的关键调优项例如8表示 8GBVLLM_CPU_OMP_THREADS_BIND指定用于推理的 CPU 核列表/亲和策略例如0-31vLLM 的 CPU 后端会基于 OpenMP 线程做物理核绑定容器镜像入口已固定为vllm serve因此docker run末尾直接追加模型名、--dtype等 serve 参数即可。需要注意示例中默认拉起的是带 Chat 模板与 OpenAI 协议兼容的 serve 模式KV cache space、CPU cores for inference两处需按实际机型核数与内存替换。五、源码级佐证s390x 并非能跑而是有原生内核为了让你对experimental的含金量有准确预期这里补充几处仓库中可验证的 s390x 专属实现均为本文主题直接相关的核心证据非泛泛介绍1. 独立的 VXE 注意力内核。csrc/cpu/cpu_attn_vxe.hpp 是专门面向 IBM Z 的注意力实现文件内含gemm_micro_s390x_Mx8_Ku4、gemm_macro_s390x_Mx8_Ku4、TileGemmS390X模板类以及AttentionImplISA::VXE, ...特化文件头部注明 s390x Vector 16 bytes (128 bits)即基于 128 位 VXE 向量寄存器实现分块 GEMM 与 attention 迭代。CPU 注意力调度的 ISA 枚举也包含VXE见 csrc/cpu/cpu_attn_impl.hpp运行期 ISA 判定会回退到 VXE见 csrc/cpu/cpu_attn.cpp 中的ISA::VXE分支。这正是需要 VXE、仅支持 Z15 及以上这条硬性要求的内核级原因。2. 大端序与 FP16 的定制处理。csrc/cpu/cpu_types_vxe.hpp 中有两条关键注释s390x 的 FP16 通过自定义的位操作转换实现PyTorch 本身缺少原生 s390x FP16 支持且由于 s390x 是大端架构BF16 需要以特定字节序排列才能得到正确结果。这解释了为什么 FP16/BF16 在文档中被单独列出为支持但不平凡的能力。3. 快速指数函数的 VXE 指令路径。csrc/cpu/cpu_arch_macros.h 在__s390x__分支中通过DEFINE_FAST_EXP宏把 softmax 所需的exp委托给cpu_types_vxe.hpp中基于 VXE intrinsics 实现的 5 项 minimax 多项式近似——这是注意力 softmax 在 s390x 上保持性能的关键底层支撑。4. FP8 KV Cache 在 s390x 上为占位路径。同文件 csrc/cpu/cpu_types_vxe.hpp 注释指出 FP8 相关代码在 s390x 上是 dead codeFP8 KV Cache 仅面向 x86这从内核层面印证了文档中量化支持清单为何只列出 AWQ/GPTQ 4-bit 与 compressed-tensors INT8 W8A8而不包含 FP8 KV Cache。5. CPU 指令分发的体系结构适配。构建期脚本 csrc/cpu/generate_cpu_attn_dispatch.py 会为 s390x 生成[VXE, VEC, VEC16]的指令候选序列说明注意力调度在 s390x 上按 VXE 优先、通用向量次之的顺序做编译期/运行期派发。六、总结与常见问题提醒在 IBM Zs390x上落地 vLLM 的关键结论可浓缩为以下几条定位是实验性原生支持无任何预构建 wheel 或镜像必须从源码构建docker/Dockerfile.s390x 是最可信的构建配方参照物硬件门槛清晰必须是 Z15 及以上VXE 必需工具链需 gcc/g ≥ 14五个上游包必须自建torchvision、llvmlite、numba、opencv-python-headless、hf-xet其中 llvmlite 又强制要求先自建 LLVM 20仓库发行版默认 LLVM 21 不可用两个运行期必做动作通过LD_PRELOAD注入 TCMalloc 提升内存分配性能设置PROTOCOL_BUFFERS_PYTHON_IMPLEMENTATIONpython并删除 Protobuf C 扩展以避免崩溃能力范围支持 FP32/BF16/FP16 精度AWQ、GPTQ 4-bit 与 compressed-tensors INT8 W8A8 量化底层由 VXE 向量化注意力内核提供原生性能路径。按上述流程完成构建后即可通过vllm serve或容器入口在 IBM Z 主机上以 OpenAI 兼容协议对外提供 LLM 推理服务并继续沿用 vLLM 标准的 CPU 部署调优手段VLLM_CPU_KVCACHE_SPACE、VLLM_CPU_OMP_THREADS_BIND等进行性能调优。【免费下载链接】vllmA high-throughput and memory-efficient inference and serving engine for LLMs项目地址: https://gitcode.com/GitHub_Trending/vl/vllm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考