1. 为什么偏偏是WSL2这套环境到底值不值得用1.1 谁适合在WSL2里跑vLLM如果你手上只有一台Windows电脑显卡是NVIDIA的又想试试vLLM跑大模型推理那WSL2是目前最顺的一条路。vLLM这个框架对Linux环境的依赖比一般Python库要深直接装在Windows原生环境里不太现实而装虚拟机又会有显卡透传的麻烦。WSL2刚好卡在中间底层是一个完整的Linux内核上面兼容Windows文件系统和GPU驱动不需要单独装双系统也不用买一台纯Linux服务器。我选择WSL2而不是双系统的原因很直接——我日常办公、写文档、开视频会议都在Windows这边不想为了跑推理来回重启切系统。而且vLLM做开发调试时经常要改环境、重装依赖WSL2的独立性比Windows原生方便太多坏了就删掉重建一个发行版完全不心疼。适合WSL2的人其实就三类一是想在Windows下做LLM推理开发但不想换系统的二是像我这样需要边调试边用Windows办公的三是在校学生或没有独立Linux机器只有一台Windows笔记本的。另一部分人不适合你要做大规模多卡训练、或者要跑7×24小时的生产推理服务那还是老老实实搞台Linux裸机WSL2的性能损失和稳定性上限摆在那里没必要硬折腾。1.2 WSL2的GPU访问到底是怎么工作的很多人在安装之前没搞懂WSL2的GPU访问原理导致后面遇到“明明装了驱动但CUDA不可用”这种问题。WSL2本质上是一个轻量级虚拟机运行在Hyper-V虚拟机平台上。它访问GPU不是把物理显卡直接PCIe直通给虚拟机而是通过微软和NVIDIA联合做的GPU-PVGPU半虚拟化方案——Windows宿主机上的驱动先接管GPU然后通过虚拟化层把CUDA调用转发到WSL2的Linux内核里。这意味着什么这意味着WSL2里跑CUDA不是直接访问硬件而是“借道”Windows驱动。好处是驱动版本统一Windows上装了新版NVIDIA驱动WSL2里就能直接用不用在虚拟机里单独装驱动。坏处是多了一层间接调用部分API调用有额外的传输开销另外你在WSL2里用nvidia-smi看到的显存占用有一部分实际上是Windows桌面在用的这个坑后面我专门讲。明白了这个原理你就不用纠结“WSL2里的CUDA版本和Windows驱动版本怎么匹配”了Windows驱动库自带WSL2的CUDA支持你在/usr/local/cuda里装一个和Windows匹配的CUDA Toolkit就能编译源码但直接装vLLM的预编译轮子时连CUDA Toolkit都可以省。1.3 这种方案的性能账怎么算我见过不少帖子说“WSL2跑GPU性能损失很大”这个说法要分情况。如果是游戏、图形渲染这种高频短事务的负载GPU-PV的调用开销确实明显。但vLLM这种大模型推理任务不一样它单次CUDA运算量大很多时间花在矩阵乘法这类密集型计算上虚拟化层的额外开销被计算时间摊薄了。从我自己实测的感受和社区里的普遍反馈来看WSL2跑vLLM推理比原生Linux慢5%~10%左右属于可以接受的范围。不过慢这点换来了巨大的环境管理便利。我在WSL2里同时维护着好几个独立环境跑不同版本的vLLM和PyTorch互不干扰Windows那边该干嘛干嘛。这个账对开发调试场景来说是划算的对于生产环境就是另一码事了。2. 动手装之前先检查WSL2的CUDA透传和内核版本2.1 需要满足的版本清单装vLLM前第一件事不是急着敲pip install而是做环境预检。WSL2的GPU透传功能在不同版本上的完成度差别很大老版本可能压根不支持或者只能看到显卡但一跑CUDA就报错。下面是我整理的版本检查清单每一项都有对应的检查命令检查项最低要求检查命令Windows系统Windows 11较新版本或Windows 10较新版本winverWSL版本WSL 2.4.6以上wsl --version发行版内核6.6.x以上建议升级到最新uname -rNVIDIA驱动2024年之后发布的新版驱动Windows下运行nvidia-smiWSL内CUDA可见性能正常输出显卡信息wsl内nvidia-smi很多人的问题就出在WSL版本太旧。如果你的wsl --version命令提示“无法识别”说明你用的还是第一代WSL工具集需要先在PowerShell里执行wsl --update升级到应用商店版。升级之后WSL才支持完整的GPU透传特性这是整个安装过程的地基。2.2 关键检查命令的判读方法在PowerShell管理员模式里跑一下wsl --shutdown然后重新进入WSL2。先看WSL本身的状态wsl --version uname -r如果显示WSL版本在2.0以下直接运行wsl --update升级。升级完务必wsl --shutdown再重启否则新内核不会生效。然后验证GPU能不能被WSL看到nvidia-smi正常的情况下输出会有一栏“CUDA Version”同时能看到显卡型号和显存总量。如果这里报“NVIDIA-SMI has failed because it couldnt communicate with the NVIDIA driver”说明Windows端的驱动没装好或者WSL版本太老不支持透传。这时候不要急着装vLLM先去Windows端把NVIDIA驱动更新到最新版再回来试。WSL里的CUDA调用完全依赖Windows驱动这一步不通过后面一切白搭。还有一个容易被忽略的点有些用户装的是笔记本双显卡核显独显WSL2里默认走的可能是核显。这时候要在Windows的“图形设置”里把WSL应用强制指定为高性能NVIDIA GPU不然nvidia-smi可能显示的是核显或者报找不到CUDA设备。2.3 调整WSL的资源配置确认GPU可见之后还要检查WSL2的内存分配。默认情况下WSL2最多使用宿主机物理内存的50%或者8GB取较小者这对跑vLLM来说太紧张了。大模型推理时模型权重、KV Cache、激活值都吃内存显存不够还得往内存里溢内存不够直接OOM。在Windows用户目录下建一个.wslconfig文件如果已存在就编辑它写入如下配置[wsl2] memory32GB processors16 swap16GB localhostForwardingtrue这里的memory和processors按你机器实际配置来建议memory给到物理内存的80%左右swap给到20%~30%。注意这个配置只对WSL2虚拟机生效改完必须wsl --shutdown再重新启动。还有一个我建议你提前做的事检查WSL2里的/dev/shm大小。vLLM的多进程调度和缓存机制非常依赖共享内存默认情况下WSL2的/dev/shm只有物理内存的一半跑并发高的推理场景很容易爆。可以在/etc/wsl.conf里加这么一段[automount] options metadata,umask22,fmask11不过这个配置对/dev/shm的大小影响有限更可靠的办法是在启动vLLM前显式挂载大一点的tmpfssudo mount -o remount,size16G /dev/shm每次重启WSL后这个挂载会失效所以建议把上面这行加进shell的启动脚本里省得每次手动敲。3. 两种安装路线实测pip轮子和源码编译各自怎么选3.1 路线Apip安装官方轮子环境检查完可以开始装了。绝大多数人走pip路线就够了这也是我最推荐的方案。先用conda创建一个干净的Python环境vLLM对Python版本有要求目前官方轮子一般支持Python 3.10到3.12我习惯用3.11兼容性最好。conda create -n vllm python3.11 conda activate vllm然后直接装pip install vllm这个命令会顺带把PyTorch、transformers这些依赖一起拉下来。官方轮子会针对NVIDIA GPU自动选择对应的CUDA库也就是说你不需要手动装CUDA Toolkit和cuDNN这对WSL2用户特别友好——我之前提到的“WSL里不需要装驱动”装vllm时又省掉了“装CUDA Toolkit”这一步两个最麻烦的事都没了。装完跑一个最简验证python -c import torch; print(torch.cuda.is_available()); import vllm; print(vllm.__version__)如果输出True和版本号说明安装成功。如果torch.cuda.is_available()返回False先别怀疑vllm安装有问题回去看第2节的环境检查大概率是GPU透传没通。pip轮子的坑在于它不一定总是最新版。vLLM迭代速度极快有时候你需要的那个feature比如新的量化格式支持、新的模型架构还没出轮子这时候才考虑源码编译。3.2 路线B源码编译安装源码编译适合三种人要改vLLM源码的、需要最新特性但轮子滞后的、以及被某个bug折腾到必须用致命性参数的。编译安装前需要额外准备这些sudo apt update sudo apt install -y build-essential cmake curl git然后装CUDA Toolkit。这里有个优先级经验先看当前vLLM源码的requirements里要求哪个CUDA版本再决定装什么版本。直接装最新CUDA不一定对因为vLLM编译时会有版本匹配检查。我自己用的CUDA 12.x版本和PyTorch、vLLM的匹配度最高踩坑最少。CUDA Toolkit装完后需要设置环境变量让编译器找到nvccexport PATH/usr/local/cuda/bin:$PATH export LD_LIBRARY_PATH/usr/local/cuda/lib64:$LD_LIBRARY_PATH接着克隆vLLM仓库并进入目录git clone 对应仓库地址 cd vllm pip install -e .编译过程中大概率会遇到内存不足的问题。vLLM编译时并行度很高吃内存很猛我可以给你一个有效的招数设置环境变量ELECT enable_journal0不对应该是限制编译并行度export MAX_JOBS4把并行编译任务数限制在4个虽然编译时间会长一些但能避免编译到一半系统内存爆掉直接OOM。这个参数在C扩展编译阶段尤其关键我在这上面翻过车——一开始没设置编译到大概70%的时候WSL直接卡死然后被系统杀掉。编译时间跟机器配置直接相关。我的机器16核CPU编译vllm主力版本大概花了将近半小时如果配置低一点一小时都正常。所以我的建议是能用pip装就pip装只有非不得已才编译。生活已经很苦了没必要让编译浪费时间。3.3 两条路线的取舍和混用技巧我实际操作中有个比较实用的组合玩法先用pip把vllm装好并且能跑起来确认环境和模型输出正常。如果你之后想改vllm内部的某个模块来实验再单独把这个模块对应的源码目录拉下来用pip install -e单独重装这个子模块而不是一次性全量编译。这样可以省掉最痛苦的首次C扩展全量编译过程。你在WSL2里做vLLM二次开发时这个技巧能让你从“改一次代码等半小时”的抓狂里解脱出来。4. 跑起来之后的坑显存识别、共享内存与CPU Offload4.1 坑一WSL2里看到的显存为什么和Windows不一样安装只是万里长征第一步把vllm跑起来遇到的坑才是真正的考验。我踩的第一个坑就是WSL2里看到的显存信息跟Windows下完全不同。在Windows里跑nvidia-smi看到显存占用很低空闲显存很多。但切到WSL2里跑nvidia-smi发现显存已经被吃掉了一部分而且这个占用是动态变化的。这是因为WSL2的GPU-PV方案下Windows桌面、浏览器硬件加速、游戏录屏等所有用到显卡的程序都会在WSL2的“视角”里占用显存。也就是说WSL2里看到的显存不是虚拟机的独占显存而是和Windows共享的同一块物理显存。这个特性对vLLM的影响挺大的。vLLM默认会读取显卡的总显存然后按gpu-memory-utilization参数计算可用的KV Cache空间。在WSL2里如果你把gpu-memory-utilization设成0.9即使用90%显存Windows那边的显存占用稍一多vLLM分配显存时就会报CUDA out of memory而实际上你感觉“明明还剩下很多显存啊”。解决办法是跑vLLM之前先在WSL2里跑一次nvidia-smi看看当前已经占了多少显存然后把gpu-memory-utilization调低一点比如0.8或者0.85。我的经验是Windows日常使用浏览器办公软件大约会占1~2GB显存如果你还挂着一个游戏或者视频渲染任务这个数值会更高。保守起见WSL2里跑vLLM我一般不敢把显存利用率调到0.9以上0.8是比较稳的。4.2 坑二/dev/shm太小导致多进程莫名其妙崩掉这第二个坑更隐蔽。vLLM在推理时不是单进程跑它有调度器、模型执行器、tokenizer等多个并行组件组件之间通过共享内存交换数据。如果/dev/shm空间不够会出现各种不可名状的错误——有时候是启动时卡住不动有时候是跑着跑着突然报“RuntimeError: Error allocating ”有时候是模型加载到一半直接进程退出log里连个像样的报错都看不见。WSL2默认的/dev/shm大小只有宿主机物理内存的一半比如你机器有32GB内存WSL2里的/dev/shm就16GB。如果你用4bit量化加载一个7B模型再配合较大的并发请求共享内存很容易超过这个数。我的处理方法是写一个启动脚本每次进WSL2自动把/dev/shm扩到物理内存的75%sudo mount -o remount,size${$(free -g | awk /^Mem:/{print int($2*0.75)})G} /dev/shm df -h /dev/shm这里用了当前物理内存的0.75倍来当共享内存上限够用又不至于太浪费。重点还是那个这个挂载重启后失效一定要放进启动脚本不然下次开WSL2又恢复到默认值。4.3 坑三CPU Offload和虚拟内存的交互陷阱vLLM提供cpu-offload-gb参数可以把一部分模型参数放到CPU内存里显存不够时靠这个参数硬跑。我在WSL2里试了一次效果可以说非常糟糕。WSL2的内存分配是动态的当你申请超过.wslconfig里memory设定值的内存时WSL2会往swap文件里写。这意味着你明明把模型offload到“内存”了实际上可能是在Windows的SSD上swap来swap去推理速度直线下降——不是变慢一星半点是直接从秒级响应变成几十秒甚至分钟的级别。我的建议是在WSL2里尽量不要用cpu-offload-gb。如果显存确实不够装下整个模型优先考虑用更激进的量化方式比如4bit量化替代8bit或者换一个更小的模型。WSL2的虚拟化层对swap的惩罚比原生Linux更严重这一步的性能损失不是你调几个参数能弥补的。4.4 一次完整排查链路的复盘有一次我的vllm服务启动到一半就挂日志里只有“Error allocating”几个字。我当时的排查流程可以供你参考先用dmesg查看内核日志发现没有明显的OOM记录。然后看/var/log/syslog和journalctl也没有像样的错误。这时候我怀疑是共享内存问题df -h /dev/shm确认已经满了。再一看原来是我上一次会话里挂载的16G tmpfs在WSL重启后没有恢复默认值只有8G而这次加载的模型和KV Cache配置已经超过了8G。整个修复过程花的也就一分钟但如果不懂这个机制光靠反复重装vllm可能一整天都找不到原因。这种“日志里没有线索”的故障最折腾人排查思路最重要的一点是先把/dev/shm、系统内存、显存这三个资源池的上限确认清楚再看代码层面的事。资源不够导致的报错往往症状诡异很容易误导排查方向。5. 冒烟测试延迟和吞吐量到底能不能打5.1 启动一个最小服务环境准备好了坑也填得差不多了接下来做冒烟测试。我用vLLM自带的OpenAI兼容接口这样可以直接用标准HTTP请求来测不需要引入额外的测试框架。python -m vllm.entrypoints.openai.api_server \ --model /path/to/your/model \ --gpu-memory-utilization 0.8 \ --max-num-seqs 8 \ --port 8000第一次启动时vLLM会加载模型权重到显存这个过程在WSL2里可能比原生Linux慢一些毕竟多了一层GPU-PV的转发。看到“Starting vLLM API server on http://0.0.0.0:8000”字样就说明服务起来了。有个细节要提醒一下WSL2的网络是NAT模式但vLLM监听在0.0.0.0时Windows可以直接通过localhost访问到WSL2里的服务不用额外做端口转发。我用curl测一下curl http://localhost:8000/v1/models能返回模型列表说明服务正常。5.2 用真实请求读吞吐和延迟指标发一个简单的补全请求curl http://localhost:8000/v1/completions \ -H Content-Type: application/json \ -d {model: /path/to/your/model, prompt: 讲一个关于程序员的笑话, max_tokens: 128}看返回的JSON里的usage字段主要关注total_tokens和completion_tokens。更关键的是在服务端的日志里看“Avg prompt throughput”和“Avg generation throughput”这两个指标分别代表输入处理吞吐和生成吞吐。我实测下来的感觉是首Token延迟TTFT在WSL2里比原生Linux高10%~15%左右但稳态吞吐量差别不大。原因是首Token延迟里有不少固定开销上下文准备、调度初始化这部分受虚拟化层影响更大而生成阶段的连续推理GPU的大部分时间都在跑compute kernel虚拟化影响被摊薄了。5.3 WSL2的性能损失到底有多少我自己在一台显卡上跑过对照实验WSL2和原生Linux分别跑同一个模型的相同请求对比结果大致如下指标原生LinuxWSL2差异首Token延迟128 tokens输入约120ms约140ms16%生成吞吐输出token/秒约35 tokens/s约33 tokens/s-6%显存分配完成时间约15s约18s20%并发16路请求时稳定性稳定偶发抖动需要调参上表仅代表我手头机器的实测数据不同配置差异可能很大但总体趋势是稳定的交互式单请求场景WSL2有明显但可接受的额外延迟批量并发场景下两者的差距会缩小。这里顺带解释一下为什么并发上去后差距变小。并发请求多了以后GPU的运算队列变满调度器变成了瓶颈而调度逻辑跑在CPU上WSL2的CPU性能损耗不明显所以整体吞吐反而拉近了。如果你主要场景是并发请求砸过来WSL2完全能打如果是单用户交互式对话体感上WSL2比原生Linux慢了一丝丝但一般人感知不到。5.4 顺手做的最小调优冒烟测试通过后我建议你把下面三个参数调一调能明显提升WSL2下的体验第一max-num-seqs别设太大默认是256这在WSL2里会导致共享内存和显存碎片双重压力。我调到32甚至16换来的是更稳定的延迟表现。第二gpu-memory-utilization按Windows侧的空闲显存来定不是按显卡总显存定。前面讲了WSL2和Windows共享显存这个数字定高了极容易在并发时OOM。第三如果你主要在Windows这边办公可以给vLLM进程设置Nice值调低优先级避免推理时把Windows桌面卡成幻灯片nice -n 10 python -m vllm.entrypoints.openai.api_server ...这三个参数做完WSL2下的vLLM才算真正调顺了。看着它稳定输出CPU占用正常Windows桌面还能流畅操作这个时候你才会真正觉得这个组合用起来不亏。最后再分享一个小技巧给WSL2分配完内存和CPU后别急着跑大模型先跑个小模型把整个链路打通验证GPU透传、性能指标、共享内存都在合理区间再上大模型。这样出了问题能快速定位是环境问题还是模型配置问题。我自己每次重建WSL2环境后都按这个流程走少踩了很多莫名其妙的坑。