提到vLLM很多人第一反应是“GPU独占的推理引擎”。说实话我也曾经这么觉得直到有次手里的GPU开发机被同事临时调走手头只剩一台纯CPU的旧服务器而我又必须把vLLM的推理接口跑起来。硬着头皮把CPU版vLLM编译安装完之后我才意识到一个事情纯CPU环境部署vLLM需求比想象中多得多——内网隔离环境、临时开发机、GPU资源不足的团队、甚至只是想低成本验证一下框架能力的人都在等一份能直接复现的编译安装经验。这篇文章把我从零开始编译、安装、运行、调优的完整过程写出来包括为什么选源码编译、每次踩坑的排查链路、以及最终实测的性能数据。如果你手上也只有CPU环境照着走一遍应该能省不少时间。1. 纯CPU环境为什么要用vLLM直接换框架不行吗先说动机。很多人看到“vLLM CPU版本”第一反应是既然没有GPU直接用llama.cpp或者Ollama不就行了为什么还要去编译vLLM这个问题我在做之前也问过自己实际深入之后才发现这两类工具解决的问题其实不太一样。1.1 vLLM在CPU环境下依然保留的三个核心价值llama.cpp这类工具走的是“极轻量、单机优先”路线部署门槛确实低但在服务化能力上差距明显。vLLM即使在纯CPU环境也保留了三个很值钱的东西PagedAttention机制KV Cache按页分配不提前全量占用显存/内存这在大并发场景下能明显提高内存利用率。CPU机器内存虽然比显存大但也没大到可以随便浪费。Continuous Batching动态拼接同批次的请求而不是等某个请求完全结束才开始下一个。这个机制让CPU推理在低并发场景下依然能保持稳定吞吐。OpenAI兼容API直接提供/v1/chat/completions这类接口如果用惯了vLLM的服务化接口迁移成本几乎为零。也就是说如果只是想本地跑一个模型聊聊天llama.cpp确实够用但如果你要做服务化推理、对接已有业务系统、或者未来可能要迁回GPU环境vLLM的接口和调度逻辑会让你省掉很多返工成本。1.2 CPU版本和GPU版本到底差在哪里我一开始以为CPU版就是把GPU代码换个编译器实际看了源码结构之后发现并不是。GPU模式下的算子大量依赖CUDA Kernel编译时会调用flash-attention、cutlass这些库而CPU模式下vLLM会把算子层切换到oneDNN和AVX指令集优化的实现Attention部分也走的是CPU友好的标准算子路径。简单类比GPU版本是给赛车换上赛道专用轮胎CPU版本是给同一台车换上耐磨公路胎。发动机调度引擎还是那台发动机但轮胎的抓地逻辑完全不同了。这也是为什么vLLM CPU版依然能继承PagedAttention和Continuous Batching这些调度层优势——因为这些机制在引擎层不在算子层。搞清楚差异之后我这边的结论是如果你需要vLLM级别的服务化能力又没有GPU那CPU版是值得折腾的如果只是单个模型试玩建议还是直接去用llama.cpp。2. 编译前的硬件和环境准备卡住我很久的几个点编译之前我原本以为最耗时间的是编译本身后来发现真正让人崩溃的是环境不匹配导致的反复报错。这一部分把必须要满足的条件整理出来对照着检查会比报错之后再去Google省时间得多。2.1 硬件上的两道硬门槛第一道门槛是CPU指令集。vLLM CPU版在编译和运行时都会用到比较新的指令集优化尤其依赖AVX2。我一开始在一台比较老的服务器上尝试结果编译完一跑就报“illegal instruction”后来确认是CPU不支持AVX2导致的。这里可以对照一个快速判断方法在Linux下执行lscpu看Flags一栏有没有avx2Windows下可以用CPU-Z之类的工具查看指令集支持情况。没有AVX2的话基本可以放弃官方推荐的vLLM CPU版本转而考虑llama.cpp这种指令集门槛更低的方案。第二道门槛是内存不仅仅看总内存够不够还要看编译过程中的内存尖峰。vLLM编译时会同时启动多个并行编译任务每个编译任务都可能吃掉1-2GB内存。具体对应关系我在后面编译参数部分会详细说这里先给个人建议总内存16GB起步32GB以上舒服编译阶段要留出至少4GB内存给系统本身别全塞满运行大模型时内存占用主要是“模型权重 KV Cache 输入输出缓存”模型多大、KV Cache留多少直接决定你还能不能干别的事。2.2 系统软件版本最容易踩坑的环节这方面的坑主要体现在Ubuntu自带的老版本gcc、cmake、Python跟vLLM的新代码编译不兼容报错信息又长又绕。我实测下来比较稳的组合是软件推荐版本我踩过的版本坑操作系统Ubuntu 22.04 / Debian 12Ubuntu 20.04能跑但glibc较老个别依赖编译会出问题gcc / g12.xgcc 11编译时遇到过模板展开的内部错误gcc 12基本没再报cmake3.18及以上老版本不支持某些新语法会直接报CMake ErrorPython3.10 / 3.113.8太旧3.12有些依赖还没做适配pip22.0太旧的pip不会解析新版依赖的manylinux标签需要注意gcc版本不是越高越好有时候gcc 13反而会引入新的编译告警导致-Werror模式下失败。12.x是我测下来最省心的。2.3 虚拟环境强烈建议这一步不要省编译安装会下载一堆Python依赖有些依赖版本互相有隐性冲突。我一开始图省事直接在系统Python里编装到一半发现系统里另一个服务的依赖被搞坏了。后来老老实实开了虚拟环境之后就再没出现过环境污染的问题。python3 -m venv vllm-cpu-env source vllm-cpu-env/bin/activate pip install --upgrade pip setuptools wheel如果你用的服务器上没有python3-venv先装一下apt-get install -y python3-venv python3-dev3. 编译安装全流程照着我这个顺序来基本不会翻车环境准备好之后就是核心环节了。编译vLLM CPU版有两种常见路径一种是直接用官方发布的预编译wheel包一种是源码编译。我自己对比过后更推荐源码编译理由下面说。3.1 为什么不直接用预编译wheelvLLM官方在PyPI上发布过CPU相关的wheel包安装命令也就一行pip install vllm而已。但实际用过的朋友应该都有体会预编译包对系统版本要求很严比如glibc版本必须高于某个值CPU指令集必须达到某个级别而且不一定覆盖最新特性。源码编译虽然慢但可控性强——你可以针对当前机器的CPU指令集优化也可以修改编译开关还能随时切换分支和版本。反正编译一次之后就会生成出可用的安装包第二次重建也就十几分钟的事。3.2 完整编译命令与耗时参考整体流程分四步拉取源码、创建虚拟环境、设置CPU编译目标变量、进行源码安装。git clone https://github.com/vllm-project/vllm.git cd vllm # 激活虚拟环境使用前面建好的环境 source ~/vllm-cpu-env/bin/activate # 安装Python依赖 pip install --upgrade pip setuptools wheel # 关键指定CPU为编译目标设备 export VLLM_TARGET_DEVICEcpu # 开始源码安装-v 能看到详细日志 pip install -e . -v这一步开始之后就是漫长的等待。我在这台8核16线程、32GB内存的机器上首次编译耗时大约1小时40分钟过程中CPU几乎全部拉满内存峰值接近8GB。如果编译机器核心更多时间会缩短但同时要注意内存会不会爆。编译过程中如果看到大段Building wheel for vllm...、gcc的编译命令以及linking之类的日志都属于正常现象。真正出问题时通常会直接报Error并停止不会一直假死。遇到假死可以先看下CPU和内存占用是不是还在波动如果占用一直不变再考虑中断重来。3.3 MAX_JOBS参数防止编译被内存杀死编译过程中最容易被忽视的一个参数是MAX_JOBS它控制并行编译任务数。不设这个参数时vllm的构建系统会根据CPU核心数自动判断但在内存不够大的机器上容易同时拉起太多编译任务导致内存被打满编译进程直接被杀掉。我当时在一台16核、16GB内存的机器上编译自动并行度太高中段经常看到Killed或者MemoryError。后来查资料才发现可以通过环境变量限制并行数# 编译并行数设为4每任务大约占1-2GB内存 export MAX_JOBS4 pip install -e . -v这个值需要根据内存大小调整经验公式大致是MAX_JOBS≈ 可用内存GB / 2。16GB内存的机器设4到632GB内存的机器设8到12这样既不会跑太慢也不会被内存杀死。3.4 编译完怎么验证是否真的装好编译安装完成后别急着直接启动服务先跑一下验证命令确认基础环境没问题# 查看版本能正常输出版本号说明主包装好了 vllm --version # 在Python里再验证一次import确认没有缺库 python -c import vllm; print(vllm.__version__)如果vllm --version能找到命令但import vllm报错通常是虚拟环境和系统PATH没对好检查一下是不是激活了正确的虚拟环境。如果import vllm时报缺少libGL.so.1这类动态库错误装一下系统依赖就行apt-get install -y libgl1 libglib2.0-04. 首次运行、性能测试与调参编译装好只是第一步真正能不能用还得看跑起来的效果。我第一次在纯CPU上跑Qwen2.5-7B时性能确实跟GPU没法比但也没有想象中那么不堪关键是要把几个环境变量调对。4.1 启动一个CPU推理服务装好之后启动服务本身很简单vLLM走的是OpenAI兼容接口一行命令就可以拉起一个服务# 设置CPU推理相关的环境变量 export VLLM_CPU_KVCACHE_SPACE8 export OMP_NUM_THREADS16 # 启动服务 vllm serve Qwen/Qwen2.5-7B-Instruct \ --host 0.0.0.0 \ --port 8000 \ --max-model-len 8192这里有两个细节要注意。第一VLLM_CPU_KVCACHE_SPACE是KV Cache空间占用量单位是GB。设得太小长上下文场景下KV Cache不够用会频繁触发重新计算设得太大又会挤压模型权重和其他进程的内存空间。我一般是按“总内存减模型权重占用再减4GB”来估算。第二OMP_NUM_THREADS控制OpenMP并行线程数。很多CPU机器的核心数很多但不意味着线程数设得越高越好。线程数超过内存带宽瓶颈之后速度不仅不涨反而会因为线程切换开销导致下降。这个值建议用实际压测去试不要直接拉满。启动完成后可以快速测一下服务是否正常curl http://127.0.0.1:8000/v1/chat/completions \ -H Content-Type: application/json \ -d { model: Qwen/Qwen2.5-7B-Instruct, messages: [{role: user, content: 你好介绍一下你自己}], max_tokens: 200 }能正常返回内容说明服务通了接下来才是调优时间。4.2 三个关键调优变量直接影响吞吐和延迟除了上面提到的VLLM_CPU_KVCACHE_SPACE和OMP_NUM_THREADS还有一个比较隐蔽但影响巨大的参数是VLLM_CPU_OMP_THREADS_BIND。这个参数控制线程是否绑定到物理核。默认情况下操作系统调度器会把线程来回迁移对GPU推理影响不大但对CPU推理来说线程迁移会导致缓存命中率下降性能损失可能达到20%左右。在Linux下可以这样设置export VLLM_CPU_OMP_THREADS_BIND1设置之后线程会固定绑定在物理核上缓存局部性提升速度会更稳定。不过这个参数在多NUMA节点的服务器上要小心如果不了解当前机器的NUMA拓扑绑定反而可能导致跨节点内存访问变慢。先用lscpu | grep NUMA看一眼再决定要不要开。三个参数的作用范围整理如下环境变量作用调整逻辑VLLM_CPU_KVCACHE_SPACEKV Cache空间GB小则上下文受限大则挤占内存OMP_NUM_THREADSOpenMP并行线程数过高会因内存带宽饱和而变慢VLLM_CPU_OMP_THREADS_BIND线程绑定物理核提升缓存命中率但需考虑NUMA拓扑4.3 实测性能什么样的速度算“能用”我在一台双路Intel Xeon32物理核/64线程、64GB内存的服务器上跑了Qwen2.5-7B没有量化、上下文8192实测数据如下场景生成速度首token延迟单并发短问题生成6-9 token/s1-3秒4并发中等上下文整体吞吐约15-20 token/s2-5秒8并发长上下文单请求速度下降明显5-10秒6 token/s这个数字跟GPU动辄几百token/s确实没法比但对于企业内部工具、知识库问答这类非实时场景这个速度是可以接受的。如果追求更好的CPU推理性能可以尝试用量化后的GGUF格式配合其他推理框架但那就离开了vLLM的范畴vLLM CPU版本的主要价值还是在于服务化能力和接口一致性。从实际调参经验来看单请求场景下OMP_NUM_THREADS设为物理核数的一半左右往往是最平衡的并发上来了则可以逐步提高线程数但注意观察内存带宽是否成为瓶颈。多试几组用/v1/chat/completions接口做压测比看任何理论值都靠谱。5. 编译和运行过程中我踩过的坑及完整排查思路这一部分是我最想写给后来者的。vLLM CPU版编译安装的报错一旦出现本身的信息量往往不够网上现成的答案又很少排查起来非常费时间。把几个高频坑的排查链路展开写出来希望帮你绕开几个我最开始踩疼过的位置。5.1 编译中段被杀掉先查内存而不是报错日志现象很典型编译进行到一半终端突然打印Killed或者日志里出现MemoryError然后整个pip install进程退出。很多人第一反应是去搜代码错误日志但这个问题根因往往是系统OOM Killer把编译进程杀掉了。排查链路一般是这样的# 第一步确认是否真的是OOM dmesg | grep -i killed process | tail -20 # 第二步查看可用内存和交换分区 free -h swapon --show如果dmesg里有明显的内存写入记录那就说明是硬件资源问题不是代码问题。解决方案就是限制并行编译任务数也就是前面提到的MAX_JOBS参数。我在这台16GB的机器上把MAX_JOBS从8降到4之后编译就稳定下来了。5.2 装完一跑就报GLIBCXX not found问题在环境不一致编译安装结束后启动服务时如果在日志里看到这类报错ImportError: /usr/lib/x86_64-linux-gnu/libstdc.so.6: version GLIBCXX_3.4.29 not found这说明编译环境和运行环境的C标准库版本不一致。最常见的情况是编译时用的是系统默认的gcc和libstdc但Python环境或某些依赖库在运行时加载的是旧的libstdc。我的处理方法是先看当前系统支持什么版本strings /usr/lib/x86_64-linux-gnu/libstdc.so.6 | grep GLIBCXX如果确认版本不足要么升级系统libstdc要么换一个更新版本的系统。事实上这一步在准备阶段就该做好——确保gcc 12对应的libstdc已装好。5.3 模型加载很慢首token迟迟不出现这个不是报错但比报错更容易让人怀疑人生。在纯CPU环境跑7B模型时加载权重就需要一两分钟而很多人第一次跑看浏览器一直没返回以为服务挂了直接CtrlC杀掉重来。我建议的做法是启动模型时加--max-model-len限制最大上下文长度可以显著减少内存分配数量间接加快启动。另外启动完成之后先用一个非常短的请求“热”一下模型让Prefill相关的缓存路径先跑一遍之后的请求会顺畅很多。5.4 vLLM版本和Python依赖之间的隐性冲突还有一个比较隐蔽的问题vLLM新版本对某些依赖如torch、transformers、tokenizers有精确的版本约束如果之前装了别的版本pip可能不会主动帮你降级导致运行时出现奇怪的报错。这个问题的排查思路是看pip依赖树pip check pip list | grep -E torch|transformers|tokenizers如果发现版本不对最简单的做法是删掉虚拟环境重建让pip按requirements重新解析一套完整兼容的版本。手动改版本依赖往往是按下葫芦浮起瓢不推荐。5.5 多实例部署时CPU资源互相抢占最后提醒一下如果你在一台机器上想同时起多个vLLM实例一定要手动分配每个实例的OMP_NUM_THREADS总量别让两个实例都默认“用满全核”。我曾经同时起了两个实例后台日志看起来都正常但两个服务的响应速度都掉了一大截。检查之后发现两个进程各自把64个线程全占了操作系统在拼命切换线程缓存全部失效。启动前用taskset给每个实例绑定不同的CPU核心集合再配合合理的OMP_NUM_THREADS会比单纯依赖操作系统调度要稳定得多。这也是纯CPU环境多实例部署最容易被忽略的一点。6. 最后一点实操建议如果你想在纯CPU环境部署vLLM我的个人建议是第一次编译前把环境检查清单过一遍指令集、内存、gcc版本、虚拟环境每项都确认没问题再开始编译中遇到报错不要急着改代码先看资源和版本问题跑起来之后花一点时间做线程数和KV Cache空间的组合压测这步对最终性能的影响比你想的大得多。我第一次以为随便调调就行结果同一台机器上调参前后的吞吐差了一倍不止这笔时间花得值。