干过这行的都知道vLLM 这东西官方文档默认只讲 LinuxWindows 上想跑起来第一反应基本是“别想了”。但实际项目里有时候你手上就一台 Windows 工作站显卡是 RTX 4090临时要起个 OpenAI 兼容的服务来测 Qwen3-8B-FP8总不能为这个专门装个 Linux 双系统吧。我折腾过几次之后总结出一套还比较顺的流程不用 Docker Desktop不碰原生 Windows Python直接通过 WSL2 来跑 vLLM从零到把 Qwen3-8B-FP8 的接口调通整个链路是完整且可复现的。这篇文章就把这套流程掰开揉碎讲清楚包括每一步背后的原因、容易踩的坑、以及我实际跑模型时遇到的各种怪异问题。适合手里有 N 卡、想在 Windows 下快速验证模型效果的人也适合刚接触 vLLM 想少走弯路的同学。1. 为什么 Windows 跑 vLLM 要先绕道 WSL21.1 vLLM 的底层依赖决定了它不适合直接在 Windows 上跑先从根源说。vLLM 不是一个普通的 Python 库它为了提高推理吞吐做了很多底层优化比如 PagedAttention 管理 KV Cache、连续批处理、以及多卡场景下的 NCCL 通信。这些能力大量依赖 Linux 内核的特性比如大页内存、设备文件映射、CUDA 驱动的用户态接口、NCCL 的 socket 和 shared memory 机制。Windows 虽然也能跑 CUDA 程序但在这些细颗粒度的系统接口上和 Linux 内核不是一回事。vLLM 官方在 Windows 上既没有提供正式的 wheel 包也没有保证可用的运行时强行在 Windows 的 Python 环境里pip install vllm经常会在编译或者运行时挂掉尤其是那些依赖 NCCL 的环节。打个比方vLLM 就像一台为 Linux 精心调校过的跑车Windows 是条水泥路不是说完全不能开但轮子、悬挂、变速箱全都是按赛道设计的硬上容易爆缸。所以想省心就要先给它铺一条 Linux 兼容层也就是 WSL2。1.2 三条可行路径对比原生、Docker、WSL2我试过三种方式先说结论日常调试最推荐 WSL2没有之一。方案优点缺点适合场景原生 Windows 安装 vLLM操作直观不用装子系统依赖 Python、CUDA 环境容易冲突vLLM 官方不提供 Windows 支持编译过程非常痛苦不推荐Docker DesktopWindows 容器隔离干净能复用现有镜像团队协作方便与 WSL2 相比多了一层虚拟化磁盘占用大GPU 直通需要额外配置文件挂载路径容易混乱已有 Docker 基础设施、需要统一部署环境WSL2 Ubuntu轻量启动快与 Windows 共享 GPU 驱动vLLM 兼容性好首次安装有几步配置网络是 NAT 模式少数端口需要手动处理本地开发、推理测试、脚本调试我最常用另外Docker Desktop 在 Windows 上本身也有 WSL2 后端等于套了两层性能上会有额外开销。而直接使用 WSL2相当于在 Windows 里跑了一个精简的 Linux 虚拟机vLLM 的 CUDA 调用能直接穿透到宿主的显卡驱动上损耗很小。1.3 为什么推荐 WSL2 而不是 VM 虚拟机如果你用过 VirtualBox 或 VMware 装 Ubuntu 跑 GPU 任务会发现一个痛点显卡直通要么需要额外配置要么性能损失明显。WSL2 用的是 Windows 自己这套 Hyper-V 虚拟化底层对 GPU 的支持经过了专门优化NVIDIA 驱动在 Windows 里装好后WSL2 内部直接就能用nvidia-smi不需要再装一遍 Linux 驱动。这一点是省时省力的关键。而且 WSL2 不只解决了 GPU 的问题文件系统集成也很自然。你可以在 Windows 的D:\models目录下放模型文件然后在 WSL2 里通过/mnt/d/models直接访问虽然跨文件系统读写性能一般但模型权重这种只读文件完全能接受。比开机切系统或者来回拷贝方便太多。这也是我最终选择 WSL2 的原因。2. 基础环境准备Windows WSL2 显卡驱动2.1 Windows 侧开启 WSL 功能开始之前先确认 Windows 版本。最好用 Windows 10 21H2 以上或者 Windows 11老版本虽然也能装但坑更多。打开 PowerShell管理员权限执行wsl --install这个命令会安装 WSL2 所需的全部组件然后重启一次系统。如果你之前已经装过旧版 WSL建议先升级到最新版本wsl --update重启之后在 PowerShell 里查看版本wsl --status wsl --list --verbose正常情况下会显示默认版本是 2。如果还是 1手动改成 2wsl --set-default-version 2这一步很关键因为 vLLM 对 WSL1 的兼容性极差很多 Linux 系统调用在 WSL1 上是模拟出来的跑起来容易出莫名其妙的问题。2.2 安装 Ubuntu 发行版继续在 PowerShell 里执行wsl --install -d Ubuntu-22.04装完会自动弹出 Ubuntu 窗口第一次启动会让你设置用户名和密码。这个密码不需要和 Windows 登录密码一致记好就行。装完以后后续用 Windows Terminal 进入非常方便。我习惯用 Ubuntu 22.04原因是它的 glibc 和系统库版本比较新兼容 vLLM 预编译 wheel 的要求。Ubuntu 20.04 也见过能跑的但遇到编译安装时容易因为 GCC 版本过老而失败没必要给自己添堵。进入 Ubuntu 以后先做基础更新sudo apt update sudo apt upgrade -y2.3 显卡驱动和 WSL2 的 GPU 透传这一步很多人会卡住其实比你想象的简单。WSL2 不需要在 Linux 内部安装 NVIDIA 驱动只需要确保 Windows 侧已经装好了 NVIDIA 显卡驱动而且版本不能太老。在 Ubuntu 终端里直接执行nvidia-smi如果能看到显卡信息说明 GPU 透传正常。如果提示找不到命令先检查 Windows 下nvidia-smi是否正常再确认 WSL 已经更新到最新版。NVIDIA 官方驱动安装包一般自带 WSL 支持我遇到的一次问题是驱动版本太旧升级到最新驱动后就解决了。验证 CUDA 版本时要注意这里的 CUDA 版本显示的是驱动支持的版本不一定要和你后面安装的 PyTorch 完全一致。vLLM 的预编译 wheel 通常自带 CUDA runtime所以不需要在 WSL 里再装一套完整 CUDA Toolkit。这个知识点很多人搞混以为必须先装 CUDA其实没必要。2.4 安装 Miniconda 并创建干净环境为了不污染系统 Python建议用 Miniconda 管理环境。在 Ubuntu 终端里执行wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh bash Miniconda3-latest-Linux-x86_64.sh安装过程一路默认最后记得勾选初始化 conda。如果当时忘了安装完执行source ~/.bashrc然后创建独立的 Python 环境conda create -n vllm python3.10 -y conda activate vllmPython 版本建议 3.10 或 3.11。vLLM 对 3.12 的支持这几年已经跟上来了但 3.10 是最稳的选择尤其是跑 Qwen3 这种模型时很少因为 Python 版本踩坑。如果你想让 WSL2 分到更多内存可以在 Windows 用户目录下创建一个.wslconfig文件内容类似[wsl2] memory32GB processors16 swap8GB改完执行wsl --shutdown再重新进入否则不会生效。这个文件对资源管理非常有用特别是你要同时开 Windows 侧的浏览器、编辑器再跑一个大模型推理不限制内存的话 WSL2 可能把整个电脑吃满。3. 安装 vLLM 的版本选择和依赖关系3.1 vLLM 安装前必须理解的两件事第一vLLM 的安装包是依赖 PyTorch 的而且它要求 PyTorch 的 CUDA 版本要匹配。不过现在 pip 安装vllm的时候会自动拉取合适的 PyTorch一般不需要手动装。如果你之前手动装过 CPU 版本的 PyTorch一定要先卸掉不然 vLLM 会在运行时直接报 CUDA error。第二vLLM 的预编译 wheel 包只支持特定架构和特定 CUDA 版本。WSL2 的环境是 x86_64 Linux市面上主流的 vLLM 版本都能找到匹配的 wheel不需要从源码编译。网上有些教程让你先克隆仓库再构建那是开发环境的玩法正常使用pip install就够了构建一次能吃掉你两三个小时。3.2 执行安装并验证在 conda 环境激活后pip install vllm如果你希望指定 CUDA 版本或者想要最新的 nightly 版本可以查一下官方索引。一般情况下直接装最新稳定版就好Qwen3-8B-FP8 这种比较新的模型需要相对较新的 vLLM 版本才能正确识别 FP8 量化。我装的时候 vLLM 已经发布到 0.6.x 之后了很顺利。安装完成后先跑一个最低限度的验证python -c import vllm; print(vllm.__version__)再跑一行检查 GPU 是否被 vLLM 正确识别python -c from vllm.utils import get_device; print(get_device())不过最直接的验证还是启动一个小模型试跑。下面会讲 Qwen3-8B-FP8 的完整部署你可以直接用它当“试金石”。3.3 关于 FP8 模型和显卡架构的兼容问题Qwen3-8B-FP8 是 8B 参数的 FP8 量化版本权重文件大小比 BF16 版本小很多推理时显存占用也更低。但有一个容易忽视的点FP8 计算需要显卡支持相应的指令集目前消费级显卡里比较合适的是 Ada Lovelace 架构RTX 40 系列以及更新的 Blackwell 架构RTX 50 系列。如果你是 RTX 30 系列虽然显存可能够但 FP8 的核心算子不一定能用硬件加速vLLM 可能会报不支持或者性能很差。我实际测试时用了 RTX 409024GB 显存跑 Qwen3-8B-FP8 非常舒服。如果你的卡是 RTX 3080 或者更低建议不要硬上这个模型版本直接换 Qwen3-8B 的 BF16 版本或者降低并发和上下文长度再试试。4. 下载 Qwen3-8B-FP8 并启动 vLLM 服务4.1 下载模型文件Qwen3-8B-FP8 的模型文件我直接用 ModelScope 下载。原因很简单不用额外配置就能拉下来断点续传也比较稳。先安装相关依赖pip install modelscope然后在 Python 里执行from modelscope import snapshot_download model_dir snapshot_download(Qwen/Qwen3-8B-FP8, local_dir/data/models/Qwen3-8B-FP8) print(model_dir)如果你希望放在 Windows 盘上共享可以指定 local_dir 为/mnt/d/models/Qwen3-8B-FP8。不过我不建议这么做因为跨文件系统读文件速度会有损失最好还是放在 WSL2 自己的文件系统里例如~/models/Qwen3-8B-FP8。下载完成后检查一下目录内容里面应该包含config.json、多个*.safetensors文件、tokenizer.json等。注意看权重文件的后缀FP8 版本一般是*fp8*.safetensors或者统一在model.safetensors.index.json里记录分片。如果你更喜欢用 Hugging Face 的仓库也可以直接pip install huggingface_hub huggingface-cli download Qwen/Qwen3-8B-FP8 --local-dir ~/models/Qwen3-8B-FP8只要能稳定下载渠道无所谓的。4.2 vLLM 启动推理服务模型放在~/models/Qwen3-8B-FP8之后启动命令非常简单vllm serve ~/models/Qwen3-8B-FP8 \ --served-model-name qwen3-8b \ --gpu-memory-utilization 0.85 \ --max-model-len 32768 \ --port 8000解释一下这几个参数--served-model-name对外暴露的模型名称这个名称要和后续调用接口时填的model字段一致。我这里写的是qwen3-8b你也可以改成Qwen3-8B-FP8。--gpu-memory-utilization允许 vLLM 使用的 GPU 显存比例。0.85 表示最多用 85%剩下 15% 留给显卡驱动和其他应用避免显存爆掉。如果你只有 16GB 显存可以试着改成 0.75。--max-model-len最大上下文长度。我设为 32768也就是 32K tokens。Qwen3 本身支持更长的上下文但越长占用的 KV Cache 显存越多。如果你的显存不够要先把这里调低。--port服务端口。默认是 8000也可以改成其他端口。启动后日志里会显示模型加载进度、显存占用等信息。重点关注下面几行INFO: Shard 0: gpu_memory_usage 18.2 GiB INFO: Graph capturing finished in 3 sec. INFO: Maximum concurrency for 32768 tokens per request: 8看到Graph capturing finished意味着模型已经编译好计算图服务准备就绪。随后日志尾端会出现类似这样的信息Uvicorn running on http://0.0.0.0:8000这就说明服务已经起来了。4.3 为什么启动时没有强制指定量化参数很多第一次玩 FP8 模型的人会问启动时要不要加--quantization fp8。大多数情况下不需要vLLM 会从模型的config.json里自动读取量化配置。如果你强制指定反而可能因为版本兼容问题报错。只有一种情况需要显式加参数你下载的模型没有标准的quantization_config字段或者 vLLM 版本较旧识别不了此时再手动加vllm serve ~/models/Qwen3-8B-FP8 --quantization fp8如果这样还报错先升级 vLLM别浪费时间排查。5. 调用 OpenAI 兼容接口5.1 用 curl 快速验证vLLM 启动后默认提供 OpenAI 风格的/v1/chat/completions接口。在 WSL2 里可以直接用 curl 测试curl http://localhost:8000/v1/chat/completions \ -H Content-Type: application/json \ -d { model: qwen3-8b, messages: [ {role: user, content: 你好请用一句话介绍你自己} ], max_tokens: 512 }如果一切正常返回的 JSON 里会包含choices数组里面有模型生成的文本。注意这里的model字段必须和启动时的--served-model-name保持一致否则会报model not found。5.2 用 Python 封装调用实际项目中不会用 curl而是通过 requests 或 OpenAI SDK 来调用。看一个最小示例import requests url http://localhost:8000/v1/chat/completions payload { model: qwen3-8b, messages: [ {role: system, content: 你是一个有用的助手。}, {role: user, content: 解释一下什么是 KV Cache} ], temperature: 0.7, max_tokens: 1024 } resp requests.post(url, jsonpayload) data resp.json() print(data[choices][0][message][content])如果使用 OpenAI SDK只需要设置base_url指向 vLLM 服务from openai import OpenAI client OpenAI( api_keyEMPTY, base_urlhttp://localhost:8000/v1 ) resp client.chat.completions.create( modelqwen3-8b, messages[{role: user, content: 你好}], max_tokens512 ) print(resp.choices[0].message.content)5.3 Windows 侧访问 WSL2 里的服务比较舒服的一点是WSL2 里的服务默认通过localhost就能在 Windows 侧访问。也就是说你可以在 Windows 浏览器里直接打开http://localhost:8000/docs查看接口文档或者在 Python 脚本里直接调用不需要额外端口转发。不过偶尔会出现localhost不通的情况尤其在 WSL 版本较老或者配置被改动过的时候。排查方法很简单在 WSL2 里执行ip addr找到 eth0 的 IPv4 地址然后在 Windows 浏览器里访问http://WSL_IP:8000。如果这样才能访问说明 localhost 转发没有自动生效可能需要重启 WSL 或重置端口转发规则。6. 常见问题与性能调优实录6.1 WSL2 内存不足导致 OOM这是所有 vLLM 跑大模型最容易遇到的问题。WSL2 默认内存占用上限通常是物理内存的 50% 或者 8GB而 Qwen3-8B-FP8 加载后光权重就要 9GB 左右再加上 KV Cache 和计算图整体内存很容易超过 16GB。如果服务启动后立刻被 kill或者日志里出现Killed字样十有八九是 OOM。解决办法是前面提到的.wslconfig文件把 memory 调到你模型实际需要的数值。我一般设成 32GB这样 WSL2 里有足够的页缓存给模型权重和 CUDA context 使用。6.2 GPU 显存不足或 KV Cache 分配失败显存不足的表现有两种一种是启动时报 OutOfMemory另一种是启动成功但一旦请求变长就崩溃。先说第一种启动时分配 GPU 显存失败主要原因是--gpu-memory-utilization设置得太高或者同时有其他程序占用了显存。你可以在 Windows 的任务管理器里看 GPU 显存占用也可以在 WSL2 里执行nvidia-smi查看。把参数从 0.9 降到 0.8一般就好了。第二种情况请求变长后崩溃多半是--max-model-len设得太高导致 KV Cache 预分配不够。解决办法是降低--max-model-len。比如从 32768 降到 16384再配合--gpu-memory-utilization 0.85基本能缓解。KV Cache 本质上是用显存换并发上下文越长同一个批次能处理的请求越少。6.3 模型下载慢或中断如果你发现 ModelScope 下载速度很慢或者下载到一半断了先检查磁盘空间。Qwen3-8B-FP8 的权重文件加起来接近 10GBWSL2 默认磁盘大小会随使用自动增长但如果宿主 C 盘空间不够下载会失败。建议用snapshot_download的local_dir参数指定放在空间足够的分区。另外 ModelScope 是支持断点续传的重新执行一遍下载命令它会自动检查已下载的文件。不要因为失败就删掉重来先去目标目录看看有些文件已经完整落盘了。6.4 启动时出现 NCCL 相关报错vLLM 在 WSL2 里单卡运行一般不会触发复杂的 NCCL 问题。但如果看到类似[1/0] NCCL error: unhandled system error大概率是 WSL2 的共享内存或网络配置出了问题。一个有效的处理方式是检查本机是否同时运行了 Docker Desktop两个虚拟化组件抢占资源时NCCL 的初始化容易失败。先退出 Docker Desktop重启 WSLwsl --shutdown再重新进入启动 vLLM。6.5 我实测下来的性能数据最后分享一个参考数据。我在 RTX 4090、24GB 显存、AMD Ryzen 9 5900X、WSL2 环境下用默认参数启动 Qwen3-8B-FP8单请求输出 2000 tokens 时吞吐大约在每秒 120-150 tokens 左右。并发 8 个请求时整体吞吐能到 500 tokens/s 以上但单请求延迟会上升。如果你用的是 16GB 显存的卡建议把--max-model-len限制在 16384 以内否则长文本生成时很容易顶到显存上限。对于只是做接口测试或原型验证这个性能已经非常够用了。真正上生产、追求高并发吞吐的话还是建议放到 Linux 服务器上配置多卡并行和持续批处理优化那样 vLLM 的潜力能发挥得更完整。回到最开始的问题Windows 上跑 vLLM 真的可行吗我用 WSL2 跑了非常多轮之后可以负责任地说完全可行。刚开始遇到的那些乱七八糟的坑基本上都是环境没理顺或者显存分配策略不合适。把 WSL2 的基础配置、驱动版本、显存参数这三件事处理好Qwen3-8B-FP8 从零到跑通一个下午的时间足够了。
Windows下用WSL2跑vLLM：从零部署Qwen3-8B-FP8
干过这行的都知道vLLM 这东西官方文档默认只讲 LinuxWindows 上想跑起来第一反应基本是“别想了”。但实际项目里有时候你手上就一台 Windows 工作站显卡是 RTX 4090临时要起个 OpenAI 兼容的服务来测 Qwen3-8B-FP8总不能为这个专门装个 Linux 双系统吧。我折腾过几次之后总结出一套还比较顺的流程不用 Docker Desktop不碰原生 Windows Python直接通过 WSL2 来跑 vLLM从零到把 Qwen3-8B-FP8 的接口调通整个链路是完整且可复现的。这篇文章就把这套流程掰开揉碎讲清楚包括每一步背后的原因、容易踩的坑、以及我实际跑模型时遇到的各种怪异问题。适合手里有 N 卡、想在 Windows 下快速验证模型效果的人也适合刚接触 vLLM 想少走弯路的同学。1. 为什么 Windows 跑 vLLM 要先绕道 WSL21.1 vLLM 的底层依赖决定了它不适合直接在 Windows 上跑先从根源说。vLLM 不是一个普通的 Python 库它为了提高推理吞吐做了很多底层优化比如 PagedAttention 管理 KV Cache、连续批处理、以及多卡场景下的 NCCL 通信。这些能力大量依赖 Linux 内核的特性比如大页内存、设备文件映射、CUDA 驱动的用户态接口、NCCL 的 socket 和 shared memory 机制。Windows 虽然也能跑 CUDA 程序但在这些细颗粒度的系统接口上和 Linux 内核不是一回事。vLLM 官方在 Windows 上既没有提供正式的 wheel 包也没有保证可用的运行时强行在 Windows 的 Python 环境里pip install vllm经常会在编译或者运行时挂掉尤其是那些依赖 NCCL 的环节。打个比方vLLM 就像一台为 Linux 精心调校过的跑车Windows 是条水泥路不是说完全不能开但轮子、悬挂、变速箱全都是按赛道设计的硬上容易爆缸。所以想省心就要先给它铺一条 Linux 兼容层也就是 WSL2。1.2 三条可行路径对比原生、Docker、WSL2我试过三种方式先说结论日常调试最推荐 WSL2没有之一。方案优点缺点适合场景原生 Windows 安装 vLLM操作直观不用装子系统依赖 Python、CUDA 环境容易冲突vLLM 官方不提供 Windows 支持编译过程非常痛苦不推荐Docker DesktopWindows 容器隔离干净能复用现有镜像团队协作方便与 WSL2 相比多了一层虚拟化磁盘占用大GPU 直通需要额外配置文件挂载路径容易混乱已有 Docker 基础设施、需要统一部署环境WSL2 Ubuntu轻量启动快与 Windows 共享 GPU 驱动vLLM 兼容性好首次安装有几步配置网络是 NAT 模式少数端口需要手动处理本地开发、推理测试、脚本调试我最常用另外Docker Desktop 在 Windows 上本身也有 WSL2 后端等于套了两层性能上会有额外开销。而直接使用 WSL2相当于在 Windows 里跑了一个精简的 Linux 虚拟机vLLM 的 CUDA 调用能直接穿透到宿主的显卡驱动上损耗很小。1.3 为什么推荐 WSL2 而不是 VM 虚拟机如果你用过 VirtualBox 或 VMware 装 Ubuntu 跑 GPU 任务会发现一个痛点显卡直通要么需要额外配置要么性能损失明显。WSL2 用的是 Windows 自己这套 Hyper-V 虚拟化底层对 GPU 的支持经过了专门优化NVIDIA 驱动在 Windows 里装好后WSL2 内部直接就能用nvidia-smi不需要再装一遍 Linux 驱动。这一点是省时省力的关键。而且 WSL2 不只解决了 GPU 的问题文件系统集成也很自然。你可以在 Windows 的D:\models目录下放模型文件然后在 WSL2 里通过/mnt/d/models直接访问虽然跨文件系统读写性能一般但模型权重这种只读文件完全能接受。比开机切系统或者来回拷贝方便太多。这也是我最终选择 WSL2 的原因。2. 基础环境准备Windows WSL2 显卡驱动2.1 Windows 侧开启 WSL 功能开始之前先确认 Windows 版本。最好用 Windows 10 21H2 以上或者 Windows 11老版本虽然也能装但坑更多。打开 PowerShell管理员权限执行wsl --install这个命令会安装 WSL2 所需的全部组件然后重启一次系统。如果你之前已经装过旧版 WSL建议先升级到最新版本wsl --update重启之后在 PowerShell 里查看版本wsl --status wsl --list --verbose正常情况下会显示默认版本是 2。如果还是 1手动改成 2wsl --set-default-version 2这一步很关键因为 vLLM 对 WSL1 的兼容性极差很多 Linux 系统调用在 WSL1 上是模拟出来的跑起来容易出莫名其妙的问题。2.2 安装 Ubuntu 发行版继续在 PowerShell 里执行wsl --install -d Ubuntu-22.04装完会自动弹出 Ubuntu 窗口第一次启动会让你设置用户名和密码。这个密码不需要和 Windows 登录密码一致记好就行。装完以后后续用 Windows Terminal 进入非常方便。我习惯用 Ubuntu 22.04原因是它的 glibc 和系统库版本比较新兼容 vLLM 预编译 wheel 的要求。Ubuntu 20.04 也见过能跑的但遇到编译安装时容易因为 GCC 版本过老而失败没必要给自己添堵。进入 Ubuntu 以后先做基础更新sudo apt update sudo apt upgrade -y2.3 显卡驱动和 WSL2 的 GPU 透传这一步很多人会卡住其实比你想象的简单。WSL2 不需要在 Linux 内部安装 NVIDIA 驱动只需要确保 Windows 侧已经装好了 NVIDIA 显卡驱动而且版本不能太老。在 Ubuntu 终端里直接执行nvidia-smi如果能看到显卡信息说明 GPU 透传正常。如果提示找不到命令先检查 Windows 下nvidia-smi是否正常再确认 WSL 已经更新到最新版。NVIDIA 官方驱动安装包一般自带 WSL 支持我遇到的一次问题是驱动版本太旧升级到最新驱动后就解决了。验证 CUDA 版本时要注意这里的 CUDA 版本显示的是驱动支持的版本不一定要和你后面安装的 PyTorch 完全一致。vLLM 的预编译 wheel 通常自带 CUDA runtime所以不需要在 WSL 里再装一套完整 CUDA Toolkit。这个知识点很多人搞混以为必须先装 CUDA其实没必要。2.4 安装 Miniconda 并创建干净环境为了不污染系统 Python建议用 Miniconda 管理环境。在 Ubuntu 终端里执行wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh bash Miniconda3-latest-Linux-x86_64.sh安装过程一路默认最后记得勾选初始化 conda。如果当时忘了安装完执行source ~/.bashrc然后创建独立的 Python 环境conda create -n vllm python3.10 -y conda activate vllmPython 版本建议 3.10 或 3.11。vLLM 对 3.12 的支持这几年已经跟上来了但 3.10 是最稳的选择尤其是跑 Qwen3 这种模型时很少因为 Python 版本踩坑。如果你想让 WSL2 分到更多内存可以在 Windows 用户目录下创建一个.wslconfig文件内容类似[wsl2] memory32GB processors16 swap8GB改完执行wsl --shutdown再重新进入否则不会生效。这个文件对资源管理非常有用特别是你要同时开 Windows 侧的浏览器、编辑器再跑一个大模型推理不限制内存的话 WSL2 可能把整个电脑吃满。3. 安装 vLLM 的版本选择和依赖关系3.1 vLLM 安装前必须理解的两件事第一vLLM 的安装包是依赖 PyTorch 的而且它要求 PyTorch 的 CUDA 版本要匹配。不过现在 pip 安装vllm的时候会自动拉取合适的 PyTorch一般不需要手动装。如果你之前手动装过 CPU 版本的 PyTorch一定要先卸掉不然 vLLM 会在运行时直接报 CUDA error。第二vLLM 的预编译 wheel 包只支持特定架构和特定 CUDA 版本。WSL2 的环境是 x86_64 Linux市面上主流的 vLLM 版本都能找到匹配的 wheel不需要从源码编译。网上有些教程让你先克隆仓库再构建那是开发环境的玩法正常使用pip install就够了构建一次能吃掉你两三个小时。3.2 执行安装并验证在 conda 环境激活后pip install vllm如果你希望指定 CUDA 版本或者想要最新的 nightly 版本可以查一下官方索引。一般情况下直接装最新稳定版就好Qwen3-8B-FP8 这种比较新的模型需要相对较新的 vLLM 版本才能正确识别 FP8 量化。我装的时候 vLLM 已经发布到 0.6.x 之后了很顺利。安装完成后先跑一个最低限度的验证python -c import vllm; print(vllm.__version__)再跑一行检查 GPU 是否被 vLLM 正确识别python -c from vllm.utils import get_device; print(get_device())不过最直接的验证还是启动一个小模型试跑。下面会讲 Qwen3-8B-FP8 的完整部署你可以直接用它当“试金石”。3.3 关于 FP8 模型和显卡架构的兼容问题Qwen3-8B-FP8 是 8B 参数的 FP8 量化版本权重文件大小比 BF16 版本小很多推理时显存占用也更低。但有一个容易忽视的点FP8 计算需要显卡支持相应的指令集目前消费级显卡里比较合适的是 Ada Lovelace 架构RTX 40 系列以及更新的 Blackwell 架构RTX 50 系列。如果你是 RTX 30 系列虽然显存可能够但 FP8 的核心算子不一定能用硬件加速vLLM 可能会报不支持或者性能很差。我实际测试时用了 RTX 409024GB 显存跑 Qwen3-8B-FP8 非常舒服。如果你的卡是 RTX 3080 或者更低建议不要硬上这个模型版本直接换 Qwen3-8B 的 BF16 版本或者降低并发和上下文长度再试试。4. 下载 Qwen3-8B-FP8 并启动 vLLM 服务4.1 下载模型文件Qwen3-8B-FP8 的模型文件我直接用 ModelScope 下载。原因很简单不用额外配置就能拉下来断点续传也比较稳。先安装相关依赖pip install modelscope然后在 Python 里执行from modelscope import snapshot_download model_dir snapshot_download(Qwen/Qwen3-8B-FP8, local_dir/data/models/Qwen3-8B-FP8) print(model_dir)如果你希望放在 Windows 盘上共享可以指定 local_dir 为/mnt/d/models/Qwen3-8B-FP8。不过我不建议这么做因为跨文件系统读文件速度会有损失最好还是放在 WSL2 自己的文件系统里例如~/models/Qwen3-8B-FP8。下载完成后检查一下目录内容里面应该包含config.json、多个*.safetensors文件、tokenizer.json等。注意看权重文件的后缀FP8 版本一般是*fp8*.safetensors或者统一在model.safetensors.index.json里记录分片。如果你更喜欢用 Hugging Face 的仓库也可以直接pip install huggingface_hub huggingface-cli download Qwen/Qwen3-8B-FP8 --local-dir ~/models/Qwen3-8B-FP8只要能稳定下载渠道无所谓的。4.2 vLLM 启动推理服务模型放在~/models/Qwen3-8B-FP8之后启动命令非常简单vllm serve ~/models/Qwen3-8B-FP8 \ --served-model-name qwen3-8b \ --gpu-memory-utilization 0.85 \ --max-model-len 32768 \ --port 8000解释一下这几个参数--served-model-name对外暴露的模型名称这个名称要和后续调用接口时填的model字段一致。我这里写的是qwen3-8b你也可以改成Qwen3-8B-FP8。--gpu-memory-utilization允许 vLLM 使用的 GPU 显存比例。0.85 表示最多用 85%剩下 15% 留给显卡驱动和其他应用避免显存爆掉。如果你只有 16GB 显存可以试着改成 0.75。--max-model-len最大上下文长度。我设为 32768也就是 32K tokens。Qwen3 本身支持更长的上下文但越长占用的 KV Cache 显存越多。如果你的显存不够要先把这里调低。--port服务端口。默认是 8000也可以改成其他端口。启动后日志里会显示模型加载进度、显存占用等信息。重点关注下面几行INFO: Shard 0: gpu_memory_usage 18.2 GiB INFO: Graph capturing finished in 3 sec. INFO: Maximum concurrency for 32768 tokens per request: 8看到Graph capturing finished意味着模型已经编译好计算图服务准备就绪。随后日志尾端会出现类似这样的信息Uvicorn running on http://0.0.0.0:8000这就说明服务已经起来了。4.3 为什么启动时没有强制指定量化参数很多第一次玩 FP8 模型的人会问启动时要不要加--quantization fp8。大多数情况下不需要vLLM 会从模型的config.json里自动读取量化配置。如果你强制指定反而可能因为版本兼容问题报错。只有一种情况需要显式加参数你下载的模型没有标准的quantization_config字段或者 vLLM 版本较旧识别不了此时再手动加vllm serve ~/models/Qwen3-8B-FP8 --quantization fp8如果这样还报错先升级 vLLM别浪费时间排查。5. 调用 OpenAI 兼容接口5.1 用 curl 快速验证vLLM 启动后默认提供 OpenAI 风格的/v1/chat/completions接口。在 WSL2 里可以直接用 curl 测试curl http://localhost:8000/v1/chat/completions \ -H Content-Type: application/json \ -d { model: qwen3-8b, messages: [ {role: user, content: 你好请用一句话介绍你自己} ], max_tokens: 512 }如果一切正常返回的 JSON 里会包含choices数组里面有模型生成的文本。注意这里的model字段必须和启动时的--served-model-name保持一致否则会报model not found。5.2 用 Python 封装调用实际项目中不会用 curl而是通过 requests 或 OpenAI SDK 来调用。看一个最小示例import requests url http://localhost:8000/v1/chat/completions payload { model: qwen3-8b, messages: [ {role: system, content: 你是一个有用的助手。}, {role: user, content: 解释一下什么是 KV Cache} ], temperature: 0.7, max_tokens: 1024 } resp requests.post(url, jsonpayload) data resp.json() print(data[choices][0][message][content])如果使用 OpenAI SDK只需要设置base_url指向 vLLM 服务from openai import OpenAI client OpenAI( api_keyEMPTY, base_urlhttp://localhost:8000/v1 ) resp client.chat.completions.create( modelqwen3-8b, messages[{role: user, content: 你好}], max_tokens512 ) print(resp.choices[0].message.content)5.3 Windows 侧访问 WSL2 里的服务比较舒服的一点是WSL2 里的服务默认通过localhost就能在 Windows 侧访问。也就是说你可以在 Windows 浏览器里直接打开http://localhost:8000/docs查看接口文档或者在 Python 脚本里直接调用不需要额外端口转发。不过偶尔会出现localhost不通的情况尤其在 WSL 版本较老或者配置被改动过的时候。排查方法很简单在 WSL2 里执行ip addr找到 eth0 的 IPv4 地址然后在 Windows 浏览器里访问http://WSL_IP:8000。如果这样才能访问说明 localhost 转发没有自动生效可能需要重启 WSL 或重置端口转发规则。6. 常见问题与性能调优实录6.1 WSL2 内存不足导致 OOM这是所有 vLLM 跑大模型最容易遇到的问题。WSL2 默认内存占用上限通常是物理内存的 50% 或者 8GB而 Qwen3-8B-FP8 加载后光权重就要 9GB 左右再加上 KV Cache 和计算图整体内存很容易超过 16GB。如果服务启动后立刻被 kill或者日志里出现Killed字样十有八九是 OOM。解决办法是前面提到的.wslconfig文件把 memory 调到你模型实际需要的数值。我一般设成 32GB这样 WSL2 里有足够的页缓存给模型权重和 CUDA context 使用。6.2 GPU 显存不足或 KV Cache 分配失败显存不足的表现有两种一种是启动时报 OutOfMemory另一种是启动成功但一旦请求变长就崩溃。先说第一种启动时分配 GPU 显存失败主要原因是--gpu-memory-utilization设置得太高或者同时有其他程序占用了显存。你可以在 Windows 的任务管理器里看 GPU 显存占用也可以在 WSL2 里执行nvidia-smi查看。把参数从 0.9 降到 0.8一般就好了。第二种情况请求变长后崩溃多半是--max-model-len设得太高导致 KV Cache 预分配不够。解决办法是降低--max-model-len。比如从 32768 降到 16384再配合--gpu-memory-utilization 0.85基本能缓解。KV Cache 本质上是用显存换并发上下文越长同一个批次能处理的请求越少。6.3 模型下载慢或中断如果你发现 ModelScope 下载速度很慢或者下载到一半断了先检查磁盘空间。Qwen3-8B-FP8 的权重文件加起来接近 10GBWSL2 默认磁盘大小会随使用自动增长但如果宿主 C 盘空间不够下载会失败。建议用snapshot_download的local_dir参数指定放在空间足够的分区。另外 ModelScope 是支持断点续传的重新执行一遍下载命令它会自动检查已下载的文件。不要因为失败就删掉重来先去目标目录看看有些文件已经完整落盘了。6.4 启动时出现 NCCL 相关报错vLLM 在 WSL2 里单卡运行一般不会触发复杂的 NCCL 问题。但如果看到类似[1/0] NCCL error: unhandled system error大概率是 WSL2 的共享内存或网络配置出了问题。一个有效的处理方式是检查本机是否同时运行了 Docker Desktop两个虚拟化组件抢占资源时NCCL 的初始化容易失败。先退出 Docker Desktop重启 WSLwsl --shutdown再重新进入启动 vLLM。6.5 我实测下来的性能数据最后分享一个参考数据。我在 RTX 4090、24GB 显存、AMD Ryzen 9 5900X、WSL2 环境下用默认参数启动 Qwen3-8B-FP8单请求输出 2000 tokens 时吞吐大约在每秒 120-150 tokens 左右。并发 8 个请求时整体吞吐能到 500 tokens/s 以上但单请求延迟会上升。如果你用的是 16GB 显存的卡建议把--max-model-len限制在 16384 以内否则长文本生成时很容易顶到显存上限。对于只是做接口测试或原型验证这个性能已经非常够用了。真正上生产、追求高并发吞吐的话还是建议放到 Linux 服务器上配置多卡并行和持续批处理优化那样 vLLM 的潜力能发挥得更完整。回到最开始的问题Windows 上跑 vLLM 真的可行吗我用 WSL2 跑了非常多轮之后可以负责任地说完全可行。刚开始遇到的那些乱七八糟的坑基本上都是环境没理顺或者显存分配策略不合适。把 WSL2 的基础配置、驱动版本、显存参数这三件事处理好Qwen3-8B-FP8 从零到跑通一个下午的时间足够了。
