先给结论想在 Windows 上把 vLLM 跑起来别折腾原生编译了直接用 WSL 2。vLLM 是目前大模型推理落地用得最多的高性能引擎但它从设计上就是面向 Linux 的直接塞进 Windows 会撞上一堆编译依赖和动态库问题。WSL 2Windows Subsystem for Linux相当于在 Windows 里开了一个轻量级 Linux 虚拟机既能跑原生 Linux 二进制又能通过 NVIDIA GPU 直通调用显卡这正好是 vLLM 需要的工作环境。这篇文章会从 WSL 2 安装、CUDA 配置到 vLLM 启动服务一步步带着你走一遍。我会把自己踩过的坑和验证过可行的方法都写清楚适合两类人看一类是手头只有 Windows 机器、想在本地开发环境跑大模型推理的开发者另一类是想在公司 Windows 办公机上快速搭一个 vLLM 测试服务的运维或算法同学。1. 为什么是 WSL 2vLLM 的 Linux 依赖与 Windows 的现实1.1 vLLM 是什么为什么需要它vLLM 是一个专门为大型语言模型LLM设计的高性能推理引擎核心卖点是高吞吐和显存高效。它最有名的技术是 PagedAttention简单说就是把显存里的 KV Cache 像操作系统管理内存一样分页管理避免碎片化大幅提升了显存利用率。再加上连续批处理机制在并发请求很多的时候它的吞吐量可以比传统方案高出不少。这些特性对部署大模型服务很关键。你可以在 vLLM 上部署开源模型比如 Qwen、LLaMA、DeepSeek 系列然后通过它提供的 OpenAI 风格接口给上层应用调用。如果你只是想在本地体验一下大模型Ollama 上手更快但如果你要做服务化部署、高并发推理、精细控制显存和批处理参数vLLM 是更主流的选择。同类的引擎还有 SGLang也很优秀但 vLLM 的生态最成熟模型兼容性最好社区资料也最多遇到问题基本都能搜到答案。1.2 WSL 2、Docker、双系统、原生 Windows 到底选哪个不少人在 Windows 上跑 vLLM 时会在几种方案之间纠结我把对比说清楚。原生 Windows 跑 vLLM 是最不建议的路。vLLM 官方没有提供 Windows 原生支持虽然有爱好者通过修改源码在 Windows 上做过实验性编译但会遇到大量的问题比如 flash-attention 编译不过、CUDA 工具链不兼容、模型并发控制异常等。除非你想研究编译原理否则别浪费这个时间。双系统Dual Boot性能最好因为显卡完全由 Linux 系统直管。但它的缺点是开发体验割裂跑模型要重启切系统切回 Windows 处理日常事务又要重启来回太折腾。如果你有长期跑大量训练或大模型服务的需求双系统可以但如果只是日常开发和测试灵活度不够。Docker Desktop with WSL 2 backend 也是一种选择而且 vLLM 官方就发布 Docker 镜像一条docker run --gpus all vllm/vllm-openai:latest就能跑起来。适合已经习惯容器化部署、不想污染本地环境的场景。但它的缺点是内部结构不够透明如果想让 vLLM 开发调试顺手一些还是原生安装更直观。WSL 2 是大部分人的最优解。它本质上是运行在 Hyper-V 轻量虚拟机里的完整 Linux 内核可以装 Ubuntu、跑 Docker、编译原生 Linux 软件同时通过 GPU 直通技术调用 Windows 侧的 NVIDIA 显卡。也就是说你可以在 Windows 桌面上一边开浏览器刷网页一边在 WSL 2 里跑 vLLM 服务中间不止没有双系统的割裂感还能用 VS Code 的 WSL 插件直接开发调试体验很接近原生 Linux。1.3 WSL 2 是怎么把显卡“借”给 Linux 的这里值得多说一句原理因为很多人装完环境后会在驱动和 CUDA 的对应关系上犯迷糊。WSL 2 通过 NVIDIA 的 GPU-PVGPU Partitioning Virtualization技术实现 GPU 透传简单理解就是Windows 宿主机上的 NVIDIA 驱动负责管理物理显卡WSL 2 里的 CUDA 程序通过一条特殊的通信路径调用这块显卡相当于“借”了宿主机的驱动能力。所以关键点就出来了NVIDIA 驱动只需要在 Windows 侧安装WSL 2 内不需要也不应该再装一遍驱动。WSL 2 里需要装的是 CUDA Toolkit也就是用户态的 CUDA 库和工具链比如 nvcc 编译器。很多人以为在 WSL 里跑nvidia-smi显示出来就行其实这只能证明显卡被透传成功了真正让 vLLM 用上 CUDA 计算还需要配套的用户态库。2. WSL 2 环境准备从零开始装一个可用的 Linux 子系统2.1 安装前先检查系统版本和虚拟化在动手之前先确认你的电脑满足基本条件。WSL 2 要求 Windows 10 版本 2004 及以上或者 Windows 11。我这边的测试环境是 Windows 11 23H2问题不大。如果你的系统比较老建议先升级系统再继续。Windows 10 1903 到 1909 可以通过手动启用功能组件支持 WSL 2但后续维护体验不太好不推荐。其次虚拟化功能必须在 BIOS 里开启。大多数近几年的电脑默认开启但有些品牌机或老主板需要进 BIOS 手动打开。你可以打开任务管理器切到“性能”标签页下面有个“虚拟化已启用”的字段确认它显示的是“已启用”。如果显示“已禁用”需要重启进 BIOS找到 Intel Virtualization TechnologyVT-x或者 AMD SVM 这类选项打开。最后建议用管理员身份打开 PowerShell 或 Windows Terminal。下面所有 wsl 开头的命令都需要管理员权限不然会提示权限不足。2.2 一行命令装好 WSL 2安装 WSL 2 最爽的一点是现在基本一条命令就搞定。在管理员 PowerShell 里执行wsl --install这条命令会做三件事启用 Windows 的 WSL 和虚拟机平台组件、下载并安装 WSL 2 内核、默认安装 Ubuntu 发行版。执行完成后通常需要重启电脑重启后会自动弹出 Ubuntu 窗口让你设置 Linux 用户名和密码。如果你的系统是旧版本或者wsl --install执行时报错可以手动启用组件dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart然后重启电脑再执行wsl --set-default-version 2 wsl --update安装完成后用wsl -l -v查看当前的发行版和版本号。输出的 VERSION 列必须是 2如果显示 1说明当前发行版用的还是旧版 WSL 1需要手动转换wsl --set-version Ubuntu 2转换可能需要一两分钟耐心等它跑完。还有一个容易被忽略的点装完之后 WSL 2 的内核版本可以通过在 WSL 终端里运行uname -r来确认正常会看到类似-microsoft-standard-WSL2的后缀。如果内核版本太老可以用wsl --update强制更新。2.3 发行版选择与基本配置wsl --install默认装的是 Ubuntu 最新 LTS 版本。如果你在安装时想指定发行版可以用wsl -l -o查看可用的发行版列表然后执行wsl --install -d Ubuntu-22.04Ubuntu 22.04 自带 Python 3.10Ubuntu 24.04 自带 Python 3.12对 vLLM 来说都是兼容的。我的建议是直接用 Ubuntu 22.04因为很多编译工具链和依赖库在 22.04 上验证得比较充分。进入 WSL 后建议先做两件事。第一更新软件源sudo apt update sudo apt upgrade -y第二配置 WSL 2 的资源限制。默认情况下 WSL 2 可能占用所有物理内存也可能只分配很少内存这取决于你的 Windows 版本和配置。为了跑模型稳定推荐在 Windows 用户目录下创建.wslconfig文件路径是C:\Users\你的用户名\.wslconfig然后写入[wsl2] memory16GB processors8 swap8GB localhostForwardingtrue这里的memory表示 WSL 2 最大可用内存建议至少给到 12GB-16GBswap是虚拟内存跑大模型时 KV Cache 容易顶满显存但 CPU 内存溢出也会导致进程崩溃留一个 swap 能救急。配置完要重启 WSL 才生效在 PowerShell 里执行wsl --shutdown然后再重新进入 WSL。这一步很多人会忘记导致改了.wslconfig却不生效白白折腾半天。3. GPU 与 CUDA让 WSL 2 真正用上 NVIDIA 显卡3.1 WSL 2 的 CUDA 架构驱动在 WindowsToolkit 在 Linux前面提过 WSL 2 的驱动是宿主机 Windows 负责的所以安装 GPU 支持链条分成两步Windows 侧装 NVIDIA 驱动WSL 2 里装 CUDA Toolkit。这个结构让很多人不适应觉得怎么 WSL 里nvidia-smi能识别显卡但编译 vLLM 时却报找不到 CUDA原因就是两边职责不同。还要补充一个实操心得vLLM 通过 pip 安装时会带上 PyTorch而 PyTorch 的 GPU 版本自带 CUDA runtime所以如果你只是跑预编译的 vLLM理论上不单独装系统级 CUDA Toolkit 也能运行。那为什么还要装因为后续你很可能需要编译自定义算子、调试底层 CUDA 代码或者在安装某些要求 nvcc 的依赖库时用到它。我建议先按下面的流程把 CUDA Toolkit 装上一步到位省得后面补。3.2 更新 Windows 侧 NVIDIA 驱动这一步不要跳过WSL 2 的 GPU 透传依赖较新的 NVIDIA 驱动。如果你的驱动是很早之前装的可能只支持到 CUDA 11.x而新版本 vLLM 默认需要 CUDA 12.1 以上驱动版本太低会直接导致运行时报出各种 CUDA 错误。打开 NVIDIA 官方网站下载对应显卡型号的最新驱动。推荐选择 Game Ready 或 Studio 驱动两者都可以对 CUDA 开发来说没有本质区别。装完后在 Windows 的 CMD 里执行nvidia-smi确认输出的右上角 CUDA Version 是 12.x。这里显示的“CUDA Version”其实是驱动支持的最高 CUDA 版本而不是你已经安装了 CUDA。只要它大于等于 12.1WSL 2 就能满足 vLLM 的基本要求。装完驱动后务必重启一次 Windows再进入 WSL 2。3.3 在 WSL 2 里安装 CUDA Toolkit进入 WSL 2 的终端先执行nvidia-smi确认能看到显卡信息。如果输出command not found大概率是 WSL 内核或驱动没有正确联动先回到 3.2 检查。能看到显卡之后安装 CUDA Toolkit。NVIDIA 官方提供了面向 WSL 的 Ubuntu 源安装命令如下wget https://developer.download.nvidia.com/compute/cuda/repos/wsl-ubuntu/x86_64/cuda-keyring_1.1-1_all.deb sudo dpkg -i cuda-keyring_1.1-1_all.deb sudo apt-get update然后安装指定版本的 CUDA Toolkit。以 12.6 为例sudo apt-get -y install cuda-toolkit-12-6安装过程比较长包很大好几个 GB建议提前确认磁盘空间。装完后配置环境变量编辑~/.bashrcexport PATH/usr/local/cuda-12.6/bin:$PATH export LD_LIBRARY_PATH/usr/local/cuda-12.6/lib64:$LD_LIBRARY_PATH export CUDA_HOME/usr/local/cuda-12.6然后执行source ~/.bashrc再用nvcc --version验证是否生效。这里有个细节安装完 CUDA Toolkit 后WSL 里的nvidia-smi还是能看到显卡但显示的是 Windows 驱动版本对应的 CUDA 版本。这个没关系不用纠结版本号是否和 Toolkit 完全一致。只要nvcc --version的版本满足 vLLM 要求即可。4. Python 环境与 vLLM 的安装4.1 Python 版本选择和虚拟环境vLLM 对 Python 版本有明确要求不同版本支持范围略有差异。按我目前实测的经验Python 3.10 到 3.12 都是稳妥的选择。Ubuntu 22.04 自带的 Python 3.10 可以直接用Ubuntu 24.04 自带的 Python 3.12 也完全没问题。我不建议在系统 Python 里直接装 vLLM因为 vLLM 的依赖树很重容易和系统的其他 Python 包发生冲突。创建虚拟环境是最省心的方式python3 -m venv ~/vllm_env source ~/vllm_env/bin/activate激活后shell 提示符前面会多出(vllm_env)字样。这里需要特别提醒一个坑WSL 2 的文件系统和 Windows 文件系统是跨系统访问如果虚拟环境建在/mnt/c/这类 Windows 挂载路径下IO 性能和文件锁机制都会出现问题很容易出现安装中途卡死、文件莫名锁定的情况。所以虚拟环境一定要放在 Linux 文件系统里比如~/vllm_env。4.2 安装 vLLM两种方式主流方式是直接用 pip 安装预编译 wheelpip install --upgrade pip pip install vllm它会自动拉取 PyTorch、Transformers、tokenizers 等一堆依赖。如果你处于国内网络环境PyPI 主板源速度可能不理想可以临时换国内镜像加速比如清华源pip install vllm -i https://pypi.tuna.tsinghua.edu.cn/simple如果默认依赖解析出来的 PyTorch 版本和你想要的不一致也可以先手动安装指定 CUDA 版本的 PyTorch再装 vLLMpip install torch --index-url https://download.pytorch.org/whl/cu124 pip install vllm这种顺序的好处是 PyTorch 的 CUDA 版本由你指定避免 vLLM 默认依赖的 PyTorch 与本地环境不匹配。第二种方式是从源码安装适合需要修改 vLLM 内部实现或者调试底层算子的开发者。源码安装对编译环境要求很高需要 GCC、CMake、CUDA Toolkit 等工具链齐全而且编译时间很长新手不建议一上来就尝试。另外如果你只需要 OpenAPI 服务端的核心功能不需要额外的多模态或量化依赖pip install vllm就够了。需要量化模型支持的话可以根据官方文档按需加装对应的扩展依赖。4.3 验证安装import vllm 与 torch.cuda装完后不要急着起服务先在命令行里做两个验证。第一个确认 vLLM 能正常导入并打印版本号python -c import vllm; print(vllm.__version__)如果这一步报错先看是缺什么库最常见的是 numpy 版本冲突或者显卡驱动相关库缺失。按报错信息处理即可。第二个确认 PyTorch 能识别到 GPUpython -c import torch; print(torch.cuda.is_available()); print(torch.cuda.get_device_name(0))如果输出True和你的显卡型号说明 CUDA 环境完全正常。如果输出False常见原因有三个一是 PyTorch 装成了 CPU 版本需要用 4.2 里的方式重装 GPU 版本二是 WSL 2 里的 GPU 透传没有正确工作三是驱动版本太低。按照这个顺序排查基本能解决。这里有一个很多人容易踩的坑在 WSL 2 里执行python有时会命中 Windows 侧的 Python而不是 WSL 里的 Python。建议在虚拟环境激活后用which python确认路径在/home/xxx/vllm_env/bin/python。如果发现不对说明 WSL 的 PATH 里被 Windows 的 Python 干扰了需要在~/.bashrc里调整 PATH 顺序或者用绝对路径调用虚拟环境里的 Python。5. 实操用 vLLM 启动一个 OpenAI 兼容的推理服务5.1 准备模型文件vLLM 支持直接从 Hugging Face 或 ModelScope 下载模型。如果你网络环境访问海外站点比较慢或者不稳定从 ModelScope 下载会更顺畅。推荐先用一个小模型把流程跑通验证环境没问题之后再去部署更大的模型。比如可以先拿 Qwen2.5-7B-Instruct 试它的效果和生态都很好对显存的要求也不算极端。用 huggingface-cli 下载pip install huggingface-hub huggingface-cli download Qwen/Qwen2.5-7B-Instruct --local-dir ./models/Qwen2.5-7B-Instruct用 ModelScope 下载pip install modelscope modelscope download --model Qwen/Qwen2.5-7B-Instruct --local_dir ./models/Qwen2.5-7B-Instruct下载完成后模型就保存在本地目录。这里有一个实际经验模型的缓存目录默认在~/.cache/huggingface如果你直接用模型名启动 vLLM它会自动去这个目录找。手动下载到自定义目录的话后续启动命令要填绝对路径或相对路径。还要注意大模型的权重文件动辄十几个 GB建议下载前用df -h看一下磁盘空间别下到一半磁盘满。5.2 启动 vLLM 服务在虚拟环境激活的状态下执行vllm serve ./models/Qwen2.5-7B-Instruct --gpu-memory-utilization 0.9 --max-model-len 8192 --host 0.0.0.0 --port 8000拆开解释几个关键参数。--gpu-memory-utilization表示 vLLM 最多可以占用多少比例的显存默认是 0.9。如果显存偏小可以降到 0.7 避免进程崩溃。--max-model-len是模型支持的最大上下文长度Qwen2.5-7B-Instruct 原生支持 32K 上下文但显存不够时强行开长上下文会导致 OOM可以先从 8192 开始。--host 0.0.0.0让服务监听所有网络接口这样 Windows 侧和其他局域网机器都能访问--port 8000是服务端口。启动成功后日志会显示模型加载时间、GPU 显存使用情况最后输出类似Uvicorn running on http://0.0.0.0:8000的信息。如果启动时显存不够会看到 OutOfMemory 相关的报错。这时候有两个调整方向把--max-model-len改小比如改为 4096或者降低--gpu-memory-utilization。要是改完还不行就要考虑量化模型。vLLM 支持 AWQ、GPTQ 等量化格式同样一个 7B 模型FP16 权重约 14GB量化成 INT4 大概只要 4GB 多显存占用差距非常大。启动服务时还有一个参数我建议记住--tensor-parallel-size。如果你的电脑有多块 NVIDIA 显卡可以设置--tensor-parallel-size 2让模型切分到两张卡上并行推理。在 WSL 2 里如果宿主机的多卡被正确透传这个参数是可以直接生效的。5.3 从 Windows 侧调用服务vLLM 启动后默认提供 OpenAI 兼容接口根路径是/v1。WSL 2 默认开启了 localhost 转发所以 Windows 浏览器里直接访问http://localhost:8000/v1/models就能看到已部署的模型列表。用 curl 查看模型列表curl http://localhost:8000/v1/models发起一个对话补全请求curl http://localhost:8000/v1/chat/completions \ -H Content-Type: application/json \ -d { model: Qwen/Qwen2.5-7B-Instruct, messages: [{role: user, content: 用一句话解释什么是Kubernetes}], max_tokens: 128 }注意model字段要填模型名vLLM 默认使用你传入的路径作为模型名如果你是用./models/Qwen2.5-7B-Instruct启动的这个字段也要填./models/Qwen2.5-7B-Instruct。如果不想让客户端写这么别扭的路径启动时加一个参数--served-model-name qwen7b这样请求里的model填qwen7b就行。如果局域网里的另一台电脑想访问你 WSL 2 里的服务先确认 Windows 防火墙放行了 8000 端口的入站请求再通过 Windows 主机的局域网 IP 访问。这里有个小坑WSL 2 的网络地址和宿主机不完全一致不同版本的 WSL 网络行为也有差别。同一台 Windows 电脑上通过 localhost 访问没问题但跨机器访问时建议优先访问 Windows 的局域网 IP而不是 WSL 的 IP。另外如果你的电脑没有 NVIDIA 显卡或者显卡太老不支持 CUDA 12vLLM 新版本也提供纯 CPU 模式启动命令加--device cpu就可以。但只能说能跑速度完全没法跟 GPU 比小模型做功能验证可以真上生产别用 CPU。6. 常见问题与排查实录6.1 高频问题速查表这一节把我在实际安装和使用过程中遇到的高频问题整理成表格方便你直接对号入座。现象可能原因解决方法wsl --install提示无法找到命令系统版本过低或 WSL 组件未启用手动启用两个 Windows 功能并重启再执行wsl --updateWSL 2 里执行nvidia-smi提示 command not foundWindows 驱动未正确安装或版本过旧在 Windows 侧安装最新 NVIDIA 驱动重启后重试torch.cuda.is_available()返回 FalsePyTorch 是 CPU 版本或驱动不支持 CUDA 12重装 GPU 版 PyTorch确认驱动 CUDA 版本 ≥ 12.1启动 vLLM 报CUDA error: no kernel image is availableGPU 算力和当前 CUDA 版本不匹配升级驱动选择与 GPU 算力匹配的 CUDA 版本启动时报显存不足 OOM模型过大或上下文过长降低--max-model-len调低--gpu-memory-utilization或者换量化模型pip install vllm 找不到匹配版本Python 版本过旧或过新换成 Python 3.10-3.12再执行安装vLLM 启动极慢模型文件在 Windows 文件系统挂载路径下把模型和代码复制到 Linux 文件系统比如~/models/局域网其他机器访问不到服务Windows 防火墙拦截或访问了错误的 IP放行 8000 端口优先通过 Windows 主机局域网 IP 访问WSL 2 磁盘占用越来越大vhdx 虚拟磁盘文件只增不减wsl --shutdown后用 diskpart 压缩 vhdx6.2 三个让我记忆深刻的坑第一个坑是跨文件系统导致的模型加载慢。有一次我把模型下载到 Windows 的 D 盘然后在 WSL 2 里通过/mnt/d/models/...路径启动 vLLM。结果模型加载花了快 20 分钟启动后推理延迟也比正常情况高很多。后来把模型复制到 WSL 2 的~/models/目录加载时间直接降到两三分钟。WSL 2 访问 Windows 挂载盘是通过跨系统网络转换实现的大文件 IO 开销非常大凡是跟模型、数据集、Python 虚拟环境相关的文件都要放到 Linux 文件系统里。第二个坑是虚拟环境和系统 Python 混淆。第一次装完 vLLM 后我直接执行vllm serve报模块找不到折腾了半天才发现是系统 PATH 优先匹配了 Windows 侧的 Python 环境。后来在 WSL 的~/.bashrc里确保 Linux 的 bin 目录排在 PATH 前面问题才解决。建议每次进入虚拟环境后先用which python确认当前解释器路径这个习惯能帮你省很多排查时间。第三个坑是.wslconfig没生效。一开始我在 Windows 用户目录下建了.wslconfig但是当时 WSL 正在运行改完没有执行wsl --shutdown导致内存配置一直没生效跑大模型时经常把 Windows 卡死。这之后我养成了一个习惯任何 WSL 配置改动第一步永远是wsl --shutdown等几秒再重启 WSL。最后再分享一个小技巧。vLLM 的日志输出默认只有 INFO 级别如果你启动服务时遇到诡异问题加上环境变量VLLM_LOGGING_LEVELDEBUG再跑一次日志会详细很多。我在排查模型加载失败和显存分配问题时这一招经常能直接定位到具体原因。Windows 上跑 vLLM 这条路只要你把 WSL 2 和 CUDA 这套底层环境理顺了后续升级 vLLM 版本、换模型、上多卡都会顺畅很多。