说句实在话vLLM 这东西放到 Linux 上是真省心装好驱动和 Python 环境pip install vllm就能把模型服务跑起来但如果你手里只有一台 Windows 机器情况就开始变得有意思了。我在 Windows 上跑通 Qwen3-8B-FP8 之前翻了不少资料也踩了不少坑——vLLM 官方对 Windows 的支持长期停留在“实验性”阶段很多教程看了开头就不想继续。这篇文章是我完整的实操记录从一台 Windows 11 机器开始通过 WSL2 部署 vLLM把 Qwen3-8B-FP8 这个 FP8 量化模型拉起来暴露成 OpenAI 兼容的 HTTP API然后用 curl、Python requests 和 OpenAI SDK 三种方式完成调用。整个过程对显存和系统要求说得比较清楚适合手里有 16GB 及以上显存、又暂时不想换 Linux 环境的读者。1. 为什么要在Windows上折腾vLLM想清楚再动手1.1 vLLM是什么为什么它这么挑环境vLLM 是目前大模型推理服务里使用率非常高的一个开源框架核心卖点是 PagedAttention 和 Continuous Batching。PagedAttention 这个机制你可以理解成“给显存做虚拟内存”把 KV Cache 切成小块按需分配解决了长上下文推理时显存碎片化的问题Continuous Batching 则是把多个请求动态拼成一个 batch 去推理而不是等前一个请求完全结束才接下一个。这两点叠加起来让 vLLM 在并发场景下的吞吐量比朴素的推理脚本高出很多。但 vLLM 从诞生起就把 Linux 当成“默认生存环境”因为它的高性能路径依赖 Linux 下成熟的 CUDA 生态比如 FlashAttention、NCCL、各种自定义算子。Windows 上不是不能跑只是很多算子需要单独编译碰上 FlashAttention 这类对编译器版本敏感的库一个坑接一个坑。社区从某个版本开始提供了 Windows 下的实验性支持但性能没法和 Linux 比综合体验也不稳定所以我的建议非常直接生产环境用 LinuxWindows 上想快速体验就用 WSL2。WSL2 本质上就是 Windows 内置的轻量虚拟机里面跑的是真正的 Linux 内核。对显卡用户来说NVIDIA 驱动在 Windows 和 WSL2 之间是共享的WSL2 里可以直接拿到 GPU 的 CUDA 能力性能损耗很小。所以我选择了 WSL2 路线而不是折腾原生 Windows 版 vLLM也不是再套一层 Docker。1.2 Windows上跑vLLM的三条路线对比这里我把常见的几条路线拉出来对比一下方便你根据自己情况选。路线优点缺点适合场景WSL2 原生安装 vLLM性能接近 Linux配置简单社区资料最多需要先了解 WSL2虚拟磁盘占空间个人开发、跑实验、学习部署Docker Desktop vLLM 镜像环境隔离最干净团队复制方便多一层虚拟化磁盘占用更大已有 Docker 习惯或要做交付Windows 原生安装 vLLM不用虚拟化路径最直接官方支持实验性算子编译容易出问题只跑极小模型或者想尝鲜我个人推荐 WSL2。理由不复杂性能上它最接近原生 Linux而且 vLLM 官方文档里的常见问题、GitHub issue 基本都是围绕 Linux 环境你在 WSL2 里遇到问题照着 Linux 的解决方案改一改就能用。Docker 路线虽然隔离性好但 GPU 透传、镜像版本、磁盘空间这些变量叠加起来排查起来更费劲不适合新手起步。1.3 Qwen3-8B-FP8为什么选这个模型当案例Qwen3-8B 是通义千问第三代的 8B 参数模型指令跟随和代码能力都很能打8B 这个规模意味着它对单卡用户非常友好。FP8 是它的量化版本权重用 8 位浮点数E4M3存储相比 BF16 版本的 8B 模型权重文件直接减半显存占用明显下降推理时内存带宽压力也更小而质量损失在大部分场景下很难感知到。这套组合对 Windows vLLM 实战来说特别合适模型权重合计约 8GB 左右FP8 加载后显存占用更小16GB 显存能跑得比较宽松24GB 显存可以留出大量空间给 KV Cache 做长上下文。相比那些动辄需要多卡部署的大模型Qwen3-8B-FP8 在成本和效果之间平衡得很好作为第一个跑通的模型不会让你在硬件上就被劝退。2. 环境准备WSL2、驱动、Python环境一次配好2.1 开启WSL2并安装Ubuntu发行版在开始之前确认你的 Windows 版本。Windows 10 2004 及以上、Windows 11 都能直接用官方命令装 WSL2如果你的系统比较老建议先手动开启“适用于 Linux 的 Windows 子系统”和“虚拟机平台”这两个 Windows 功能再安装 WSL2 内核更新包。我个人最常用的方式是管理员身份打开 PowerShell执行wsl --install -d Ubuntu-22.04如果之前没有安装过 WSL这个命令会自动启用相关 Windows 功能、安装 WSL2 内核并下载 Ubuntu 发行版。整个过程可能需要重启一次。重启后第一次进入 Ubuntu 会让你设置用户名和密码这个用户默认有 sudo 权限后续大部分操作都要在这个 Linux 环境里完成。装完以后例行检查wsl -l -v输出结果里应该看到 Ubuntu 的 VERSION 列是 2。如果显示的版本是 1需要用下面命令把默认版本切到 2wsl --set-default-version 2这里有个很容易忽略的细节WSL2 和 WSL1 对 GPU 的支持完全不同只有 WSL2 才有真正的 GPU 透传能力切到 2 这一步别跳过。2.2 检查显卡驱动与CUDA环境WSL2 里不需要单独安装 NVIDIA 的 Linux 驱动这是一个让很多人意外的点。你只需要在 Windows 侧装好 NVIDIA 官方驱动WSL2 里的 nvidia-smi 会自动对应到同一个驱动层。装完驱动后进入 Ubuntu 终端执行nvidia-smi能看到显卡型号和驱动版本就说明 GPU 透传没问题。我踩过的一个坑是驱动太老vLLM 加载时直接报 CUDA 版本不兼容后来把驱动升级到最新版才消停。建议你在动手前就把驱动更新到 550 或更高版本省得后面排查。vLLM 的 pip 安装包已经自带了 CUDA runtime 相关的库所以你在 WSL2 里不需要手动安装完整的 CUDA Toolkit只要显卡驱动新到能支撑当前 CUDA 版本就行。这一点和原生 Linux 部署略有区别很多人在这里白白浪费了大量时间去装 CUDA其实装完 vLLM 之后CUDA 相关的东西基本都被 pip 依赖自动带上了。2.3 Python环境准备用uv管理依赖更省心WSL2 里通常自带 Python 3.10 或 3.12但直接拿系统 Python 装 vLLM 容易出现依赖冲突。我的习惯是先装 uv它是目前处理 Python 依赖速度最快、也最省心的工具之一。在 Ubuntu 的终端里执行curl -LsSf https://astral.sh/uv/install.sh | sh安装好后创建一个虚拟环境并激活uv venv .venv source .venv/bin/activate后续所有 pip 安装都走uv pip install不仅快还能避免很多 Python 包版本打架的问题。如果你更习惯 conda也不是不行但我实测下来 uv 在 WSL2 里体感更轻、装大包时不容易超时。2.4 显存、磁盘和基础资源检查开始部署之前建议先确认三件事显存、磁盘空间、内存。nvidia-smi看显存Qwen3-8B-FP8 权重约 8GB启动时 vLLM 还会根据你的设置划走一部分显存做 KV Cache所以 16GB 显存是起步线24GB 会比较舒服。磁盘方面模型仓库加运行日志至少预留 20GB而且强烈建议放在 WSL2 内部的 Linux 文件系统里不要放在/mnt/c这种 Windows 挂载盘上跨文件系统读写会让模型加载速度肉眼可见地变慢。内存建议至少有 16GB因为模型加载过程中需要先读入内存再拷贝到显存内存太小会出现看着像卡死、实际上在疯狂换页的表现。3. 安装vLLM与下载Qwen3-8B-FP8模型3.1 安装vLLM一行命令背后的版本选择在刚才创建并激活的虚拟环境里安装 vLLMuv pip install vllm默认会安装当前最新稳定版我写这篇实操时是 0.9.x。如果你希望更稳妥可以指定一个已知大版本号uv pip install vllm0.9,0.10官方 PyPI 上的 vLLM wheel 体积不小安装耗时较长。国内网络环境下如果下载慢或者超时可以临时切换到清华 PyPI 镜像uv pip install vllm -i https://pypi.tuna.tsinghua.edu.cn/simple装完以后验证版本python -c import vllm; print(vllm.__version__)能正常输出版本号说明 vLLM 主体安装成功。这里有一个非常关键的细节vLLM 和 PyTorch 的版本绑定关系比较强你不需要也不应该手动指定 torch 版本直接装 vllm 会让 pip 自动解析出配套的 torch。手动乱装 torch 很容易把环境搞崩回头排查依赖冲突才是最耗时间的。3.2 下载Qwen3-8B-FP8模型两条国内可用的路径模型推荐直接下载到 WSL2 内部路径用类似~/models/Qwen3-8B-FP8这种目录。第一条路径是使用 Hugging Face 的国内镜像站点 hf-mirror。通过环境变量把下载源指到镜像export HF_ENDPOINThttps://hf-mirror.com huggingface-cli download Qwen/Qwen3-8B-FP8 --local-dir ~/models/Qwen3-8B-FP8如果你没装 huggingface_hub先执行uv pip install huggingface_hub。第二条路径是 ModelScope。Qwen 系列在 ModelScope 上有官方仓库下载速度在国内相当乐观pip install modelscope modelscope download --model Qwen/Qwen3-8B-FP8 --local_dir ~/models/Qwen3-8B-FP8两条路我都实测过ModelScope 对国内网络更友好Hugging Face 镜像胜在模型目录结构和 vLLM 生态天然一致。下载完成后确认目录里至少有 config.json、tokenizer.json 和若干个 .safetensors 权重文件缺文件的话后续加载一定会报错。3.3 模型文件完整性与路径规划模型下载好以后我建议把路径固定在一个地方避免每次启动都找半天。比如统一放到~/models/下那么 vLLM 启动时直接用--model ~/models/Qwen3-8B-FP8指定本地路径即可不用每次写完整的 HF 仓库名。另外一个容易被忽略的点是vLLM 加载本地模型目录时会自动读取目录里的 config.json里面已经包含了 FP8 量化的配置信息。也就是说正常情况下你不需要手动指定--quantization fp8vLLM 会自己识别。这点和加载某些第三方量化模型时需要手动传参的体验不太一样对新手更友好。4. vLLM服务启动实战参数逐项拆解4.1 最小化启动命令先跑通再说在 WSL2 终端里确保虚拟环境已激活然后执行vllm serve ~/models/Qwen3-8B-FP8 \ --host 0.0.0.0 \ --port 8000如果一切正常你会看到 vLLM 先加载模型权重再初始化推理引擎最后输出类似下面的日志INFO: Started server process [12345] INFO: Application startup complete. INFO: Uvicorn running on http://0.0.0.0:8000看到Application startup complete就说明服务已经起来了。用浏览器打开http://localhost:8000再访问/health或/healthz路径通常能返回健康检查状态。不过“先跑通”的命令只是最小集实际使用中很少这样裸跑。你大概率会遇到显存不够用、上下文长度不合适、端口被占用等问题。下面我把关键参数逐个拆开讲你不需要全记住先按自己的硬件情况挑几个改动跑通一次后再回头细看就好。4.2 关键启动参数说明每个参数为什么值得调参数作用我的建议--model指定模型路径或 HF 仓库名本地路径更稳定建议用绝对路径--host/--port服务监听地址和端口默认 0.0.0.0:8000注意端口冲突--max-model-len模型最大上下文长度显存紧张时设 8192 或 16384 立省显存--gpu-memory-utilization允许 vLLM 占用显存的比例默认 0.9单卡共享机器可以降到 0.6-0.7--tensor-parallel-size使用几张卡做张量并行单卡千万别设大于 1多卡也要谨慎--quantization强制指定量化方式本模型可省异常时显式用fp8--served-model-name对外暴露的模型名称方便对接已有客户端配置--trust-remote-code允许加载仓库里的自定义代码部分模型需要Qwen 一般不需要--api-key为 API 增加访问密钥暴露公网时强烈建议开启之所以把--max-model-len单独拎出来说是因为这个参数对显存影响巨大。Qwen3-8B 原生支持 32K 上下文但如果你只是做日常问答、代码生成大部分请求的上下文也就是几千 token。把--max-model-len从 32768 降到 8192KV Cache 占用直接少一大截在 16GB 显存上体感非常明显。4.3 FP8量化在vLLM里的处理细节Qwen3-8B-FP8 的 config.json 里自带quantization_configvLLM 加载时会自动识别。如果你在日志中看到模型被当作 BF16 加载说明量化信息没被正确解析这时候可以显式指定vllm serve ~/models/Qwen3-8B-FP8 \ --quantization fp8 \ --kv-cache-dtype fp8_e4m3--kv-cache-dtype fp8_e4m3的作用是把 KV Cache 也切成 FP8 存储进一步压显存。这个选项在 Ada Lovelace 及以上架构的显卡上支持比较好如果你的显卡是 RTX 30 系建议先不开启实测一部分场景会有兼容性问题。另外注意FP8 权重在推理时会反量化回更高精度做计算所以它不会像整型量化那样明显牺牲模型质量这也是 FP8 这两年被大规模采用的原因之一。在 vLLM 里使用 FP8 模型你不需要改动任何业务代码API 层面和普通模型完全一致。4.4 启动日志怎么看快速判断服务健康状态刚开始跑的时候日志非常长很多人一刷屏就慌了。其实不需要逐行读重点盯这几类信息显存分配情况日志里会显示类似GPU memory usage: xxx或Number of GPU blocks如果这里的数字很小说明可用 KV Cache 空间不足并发能力会受限模型加载完成提示出现Load avg weights took ...表示权重加载完成这里时间太久的话要怀疑是不是模型放到了/mnt/c下Starting vLLM server at ...和Application startup complete这两行是服务可用的信号。如果启动过程中卡在某一步不动大概率就是网络问题还在下载或者显存不足。前者检查模型路径是否指向本地目录后者看 nvidia-smi 确认显存没被其他进程占满。4.5 让服务在后台运行nohup和tmuxWSL2 终端一旦关闭前台运行的 vLLM 服务也会跟着退出。为了避免反复重启我习惯用 nohup 把服务放到后台并把日志写进文件nohup vllm serve ~/models/Qwen3-8B-FP8 \ --host 0.0.0.0 \ --port 8000 \ --max-model-len 8192 \ vllm.log 21 要查日志就看tail -f vllm.log想杀掉服务就pkill -f vllm serve。这个操作方式在 Windows Terminal 里配合 WSL2 使用很顺手不需要额外装工具。5. 调用推理接口OpenAI兼容API从curl到SDK5.1 用curl快速验证30秒确认服务正常vLLM 启动后暴露的是 OpenAI 兼容 API所以最简单的验证方式就是 curl。打开一个新的终端Windows PowerShell 也可以因为 localhost 是通的curl http://localhost:8000/v1/chat/completions \ -H Content-Type: application/json \ -d { model: Qwen3-8B-FP8, messages: [ {role: user, content: 用一句话解释什么是PagedAttention} ], max_tokens: 128, temperature: 0.7 }返回 JSON 里会出现choices[0].message.content字段里面就是模型生成的回答。这一步能通说明整个服务链路已经问题不大了。如果你启动时指定了--served-model-name这里model字段要用你指定的名字。5.2 用Python requests调用不依赖额外库很多人写 demo 不想引入 OpenAI SDK那就直接用 requestsimport requests url http://localhost:8000/v1/chat/completions payload { model: Qwen3-8B-FP8, messages: [ {role: user, content: 写一段Python代码实现快速排序} ], max_tokens: 512, temperature: 0.3 } response requests.post(url, jsonpayload) data response.json() print(data[choices][0][message][content])注意返回结构里content是最终拼接好的完整回答。requests 的json参数会自动设置 Content-Type不用手动加 header这一点比 curl 命令省事。5.3 用OpenAI SDK调用复用现有代码如果你的项目本来就用了 OpenAI 的 Python SDK只需要改一下 base_urlfrom openai import OpenAI client OpenAI( api_keyEMPTY, base_urlhttp://localhost:8000/v1 ) completion client.chat.completions.create( modelQwen3-8B-FP8, messages[ {role: system, content: 你是一个乐于助人的助手。}, {role: user, content: 介绍一下Qwen3主力模型的特点} ] ) print(completion.choices[0].message.content)api_key 填一个占位字符串就行因为 vLLM 默认不校验密钥。如果你启动时设置了--api-key记得把这里换成真实密钥。这套写法最大的价值在于以后你想换成其他 OpenAI 兼容服务比如别的推理框架或云厂商接口代码几乎不用动。5.4 流式输出实战类ChatGPT打字机效果非流式接口要等模型完整生成完才返回长响应时会明显感受到延迟。流式输出可以让 token 一个接一个蹦出来体感和 ChatGPT 网页版接近。用 OpenAI SDK 的话只需加一个streamTruefrom openai import OpenAI client OpenAI( api_keyEMPTY, base_urlhttp://localhost:8000/v1 ) stream client.chat.completions.create( modelQwen3-8B-FP8, messages[ {role: user, content: 写一段500字左右的产品介绍} ], streamTrue ) for chunk in stream: delta chunk.choices[0].delta.content if delta: print(delta, end, flushTrue)底层原理是 SSEServer-Sent EventsvLLM 会把每个生成的 token 通过 HTTP 长连接实时推给客户端。对 Web 前端来说解析 SSE 流把内容渲染到页面就可以了。流式响应对长文本生成体验改善非常明显建议对接业务时优先考虑。6. 性能调优与Windows/WSL2踩坑实录6.1 性能和显存之间的取舍三个关键参数先说明一个原则vLLM 的性能不是某个参数单独决定的而是“显存预算、批次大小、上下文长度”三者之间权衡的结果。我建议按顺序调这三个参数--gpu-memory-utilization决定 vLLM 能占用多少显存。留太少KV Cache 不够并发能力上不去留太多会和桌面环境抢显存导致其他应用崩溃。我一般设 0.85。--max-model-len直接决定单请求最长上下文。不需要超长上下文时调低它给 KV Cache 腾空间效果立竿见影。--max-num-seqs控制一次推理 batch 里最多有多少个请求。默认值通常会比较保守显存宽裕时可以适度调高吞吐量随之上升。下面这组是我在 24GB 显存显卡上实测比较舒服的配置vllm serve ~/models/Qwen3-8B-FP8 \ --host 0.0.0.0 \ --port 8000 \ --max-model-len 16384 \ --gpu-memory-utilization 0.9 \ --max-num-seqs 64 \ --enable-prefix-caching--enable-prefix-caching开启后重复的 prompt 前缀比如系统提示词、固定模板会被缓存多轮对话场景下能省不少计算量。这个参数没有副作用建议常开。6.2 常见问题排查表遇到报错先看这张表现象可能原因解决办法启动报 CUDA out of memory显存不足或max-model-len太大调低--max-model-len降--gpu-memory-utilization关掉其他吃显存的应用加载模型时提示找不到量化配置模型目录不完整或 config.json 读取失败检查目录文件完整性或显式加--quantization fp8服务起来了但 curl 不返回端口被占用或请求地址错误换端口确认model字段与实际--served-model-name一致WSL2 内能访问但 Windows 浏览器打不开老版本 WSL2 网络模式不同新版本一般自动转发不行就用netsh interface portproxy做端口转发启动特别慢日志卡在读模型模型放在/mnt/c跨盘读取把模型挪到 WSL2 内部目录重新下载或复制多卡设置--tensor-parallel-size 2报 NCCL 错误WSL2 下多卡通信支持不稳定单卡先别开多卡或考虑 Docker Linux 环境Python 依赖冲突、torch 版本不对手动装了 torch重开虚拟环境直接uv pip install vllm让 pip 自动解析依赖6.3 WSL2里跑vLLM特有的三个坑第一个坑是显存不释放。Windows 桌面端一旦有进程加载了 CUDA 上下文即使程序退出了显存也可能被系统占用一段时间。vLLM 启动前先打开任务管理器看一眼如果显存被某个残留进程占着用wsl --shutdown重启一下 WSL2 实例状态会干净很多。第二个坑是/mnt/c文件系统性能很慢。Windows 的 NTFS 挂载到 WSL2 里走的是 9P 协议IO 性能远不如 WSL2 原生的 ext4。模型下载到 Linux 文件系统里看起来只是换个目录的事实际体验差异巨大模型放对了地方加载时间能差出一倍。所以我的习惯是模型一定放~/models绝不放/mnt/c/Users/xxx/...。第三个坑是 WSL2 的 IP 和端口转发问题。新版本 WSL2 默认使用镜像网络模式mirrored networkingWindows 侧直接访问 localhost 就能通。如果你遇到 Windows 侧始终访问不了 WSL2 里的服务可以先在 WSL2 里执行ip addr show eth0拿到 WSL2 的 IP再从 Windows 访问这个 IP 加端口实在不行再上端口转发。6.4 一个简单压测看看Qwen3-8B-FP8能跑多快配置好以后我想大家都会好奇模型到底跑多快。这里分享一组我自己的实测数据仅供参考硬件与配置场景实测结果RTX 4090 24GBmax-model-len16384单请求流式生成500 token 输出约 80-110 tokens/s同一配置并发 16 个请求批量推理整体吞吐总吞吐可以到 800 tokens/s2048 token prompt 预填充prefill 阶段约 4000-6000 tokens/s数据会随着输入长度、并发数、驱动版本有波动但趋势很明确单请求的速度取决于内存带宽并发时 Continuous Batching 能把吞吐量拉得很高。这也是 vLLM 在生产环境里真正的价值所在——它不是把单次生成做多快而是让 GPU 在大量请求面前不被浪费。如果你也想验证自己的环境可以用 Python 并发发十几个请求对比一下整体耗时就能直观感受到“批量处理”和“逐个排队”的巨大差异。这个测试不要在生产服务器上做本地开发机完全没问题。写到这里我发现自己每次在 Windows 上折腾这类工具最后都会得出同一个结论Windows 从来不是不能做只是很多坑需要人到场踩一遍才知道怎么绕。按我这套流程走下来你应该能在半小时到一小时左右跑通 Qwen3-8B-FP8然后再按自己的硬件条件微调那三个性能参数把它变成一台真正能用的本地模型服务。如果你在启动过程中遇到上面表格里没写到的报错建议优先把完整日志发到 vLLM 的 GitHub issue 里搜一搜很多问题都有现成的讨论和结论。最后再分享一个小技巧把启动命令和常用参数写成一个 shell 脚本放进 WSL2 的~/.local/bin里下次启动模型服务只需要一行命令不用再翻历史记录找参数了。 Windows上跑通vLLM部署Qwen3-8B-FP8的完整实操指南
说句实在话vLLM 这东西放到 Linux 上是真省心装好驱动和 Python 环境pip install vllm就能把模型服务跑起来但如果你手里只有一台 Windows 机器情况就开始变得有意思了。我在 Windows 上跑通 Qwen3-8B-FP8 之前翻了不少资料也踩了不少坑——vLLM 官方对 Windows 的支持长期停留在“实验性”阶段很多教程看了开头就不想继续。这篇文章是我完整的实操记录从一台 Windows 11 机器开始通过 WSL2 部署 vLLM把 Qwen3-8B-FP8 这个 FP8 量化模型拉起来暴露成 OpenAI 兼容的 HTTP API然后用 curl、Python requests 和 OpenAI SDK 三种方式完成调用。整个过程对显存和系统要求说得比较清楚适合手里有 16GB 及以上显存、又暂时不想换 Linux 环境的读者。1. 为什么要在Windows上折腾vLLM想清楚再动手1.1 vLLM是什么为什么它这么挑环境vLLM 是目前大模型推理服务里使用率非常高的一个开源框架核心卖点是 PagedAttention 和 Continuous Batching。PagedAttention 这个机制你可以理解成“给显存做虚拟内存”把 KV Cache 切成小块按需分配解决了长上下文推理时显存碎片化的问题Continuous Batching 则是把多个请求动态拼成一个 batch 去推理而不是等前一个请求完全结束才接下一个。这两点叠加起来让 vLLM 在并发场景下的吞吐量比朴素的推理脚本高出很多。但 vLLM 从诞生起就把 Linux 当成“默认生存环境”因为它的高性能路径依赖 Linux 下成熟的 CUDA 生态比如 FlashAttention、NCCL、各种自定义算子。Windows 上不是不能跑只是很多算子需要单独编译碰上 FlashAttention 这类对编译器版本敏感的库一个坑接一个坑。社区从某个版本开始提供了 Windows 下的实验性支持但性能没法和 Linux 比综合体验也不稳定所以我的建议非常直接生产环境用 LinuxWindows 上想快速体验就用 WSL2。WSL2 本质上就是 Windows 内置的轻量虚拟机里面跑的是真正的 Linux 内核。对显卡用户来说NVIDIA 驱动在 Windows 和 WSL2 之间是共享的WSL2 里可以直接拿到 GPU 的 CUDA 能力性能损耗很小。所以我选择了 WSL2 路线而不是折腾原生 Windows 版 vLLM也不是再套一层 Docker。1.2 Windows上跑vLLM的三条路线对比这里我把常见的几条路线拉出来对比一下方便你根据自己情况选。路线优点缺点适合场景WSL2 原生安装 vLLM性能接近 Linux配置简单社区资料最多需要先了解 WSL2虚拟磁盘占空间个人开发、跑实验、学习部署Docker Desktop vLLM 镜像环境隔离最干净团队复制方便多一层虚拟化磁盘占用更大已有 Docker 习惯或要做交付Windows 原生安装 vLLM不用虚拟化路径最直接官方支持实验性算子编译容易出问题只跑极小模型或者想尝鲜我个人推荐 WSL2。理由不复杂性能上它最接近原生 Linux而且 vLLM 官方文档里的常见问题、GitHub issue 基本都是围绕 Linux 环境你在 WSL2 里遇到问题照着 Linux 的解决方案改一改就能用。Docker 路线虽然隔离性好但 GPU 透传、镜像版本、磁盘空间这些变量叠加起来排查起来更费劲不适合新手起步。1.3 Qwen3-8B-FP8为什么选这个模型当案例Qwen3-8B 是通义千问第三代的 8B 参数模型指令跟随和代码能力都很能打8B 这个规模意味着它对单卡用户非常友好。FP8 是它的量化版本权重用 8 位浮点数E4M3存储相比 BF16 版本的 8B 模型权重文件直接减半显存占用明显下降推理时内存带宽压力也更小而质量损失在大部分场景下很难感知到。这套组合对 Windows vLLM 实战来说特别合适模型权重合计约 8GB 左右FP8 加载后显存占用更小16GB 显存能跑得比较宽松24GB 显存可以留出大量空间给 KV Cache 做长上下文。相比那些动辄需要多卡部署的大模型Qwen3-8B-FP8 在成本和效果之间平衡得很好作为第一个跑通的模型不会让你在硬件上就被劝退。2. 环境准备WSL2、驱动、Python环境一次配好2.1 开启WSL2并安装Ubuntu发行版在开始之前确认你的 Windows 版本。Windows 10 2004 及以上、Windows 11 都能直接用官方命令装 WSL2如果你的系统比较老建议先手动开启“适用于 Linux 的 Windows 子系统”和“虚拟机平台”这两个 Windows 功能再安装 WSL2 内核更新包。我个人最常用的方式是管理员身份打开 PowerShell执行wsl --install -d Ubuntu-22.04如果之前没有安装过 WSL这个命令会自动启用相关 Windows 功能、安装 WSL2 内核并下载 Ubuntu 发行版。整个过程可能需要重启一次。重启后第一次进入 Ubuntu 会让你设置用户名和密码这个用户默认有 sudo 权限后续大部分操作都要在这个 Linux 环境里完成。装完以后例行检查wsl -l -v输出结果里应该看到 Ubuntu 的 VERSION 列是 2。如果显示的版本是 1需要用下面命令把默认版本切到 2wsl --set-default-version 2这里有个很容易忽略的细节WSL2 和 WSL1 对 GPU 的支持完全不同只有 WSL2 才有真正的 GPU 透传能力切到 2 这一步别跳过。2.2 检查显卡驱动与CUDA环境WSL2 里不需要单独安装 NVIDIA 的 Linux 驱动这是一个让很多人意外的点。你只需要在 Windows 侧装好 NVIDIA 官方驱动WSL2 里的 nvidia-smi 会自动对应到同一个驱动层。装完驱动后进入 Ubuntu 终端执行nvidia-smi能看到显卡型号和驱动版本就说明 GPU 透传没问题。我踩过的一个坑是驱动太老vLLM 加载时直接报 CUDA 版本不兼容后来把驱动升级到最新版才消停。建议你在动手前就把驱动更新到 550 或更高版本省得后面排查。vLLM 的 pip 安装包已经自带了 CUDA runtime 相关的库所以你在 WSL2 里不需要手动安装完整的 CUDA Toolkit只要显卡驱动新到能支撑当前 CUDA 版本就行。这一点和原生 Linux 部署略有区别很多人在这里白白浪费了大量时间去装 CUDA其实装完 vLLM 之后CUDA 相关的东西基本都被 pip 依赖自动带上了。2.3 Python环境准备用uv管理依赖更省心WSL2 里通常自带 Python 3.10 或 3.12但直接拿系统 Python 装 vLLM 容易出现依赖冲突。我的习惯是先装 uv它是目前处理 Python 依赖速度最快、也最省心的工具之一。在 Ubuntu 的终端里执行curl -LsSf https://astral.sh/uv/install.sh | sh安装好后创建一个虚拟环境并激活uv venv .venv source .venv/bin/activate后续所有 pip 安装都走uv pip install不仅快还能避免很多 Python 包版本打架的问题。如果你更习惯 conda也不是不行但我实测下来 uv 在 WSL2 里体感更轻、装大包时不容易超时。2.4 显存、磁盘和基础资源检查开始部署之前建议先确认三件事显存、磁盘空间、内存。nvidia-smi看显存Qwen3-8B-FP8 权重约 8GB启动时 vLLM 还会根据你的设置划走一部分显存做 KV Cache所以 16GB 显存是起步线24GB 会比较舒服。磁盘方面模型仓库加运行日志至少预留 20GB而且强烈建议放在 WSL2 内部的 Linux 文件系统里不要放在/mnt/c这种 Windows 挂载盘上跨文件系统读写会让模型加载速度肉眼可见地变慢。内存建议至少有 16GB因为模型加载过程中需要先读入内存再拷贝到显存内存太小会出现看着像卡死、实际上在疯狂换页的表现。3. 安装vLLM与下载Qwen3-8B-FP8模型3.1 安装vLLM一行命令背后的版本选择在刚才创建并激活的虚拟环境里安装 vLLMuv pip install vllm默认会安装当前最新稳定版我写这篇实操时是 0.9.x。如果你希望更稳妥可以指定一个已知大版本号uv pip install vllm0.9,0.10官方 PyPI 上的 vLLM wheel 体积不小安装耗时较长。国内网络环境下如果下载慢或者超时可以临时切换到清华 PyPI 镜像uv pip install vllm -i https://pypi.tuna.tsinghua.edu.cn/simple装完以后验证版本python -c import vllm; print(vllm.__version__)能正常输出版本号说明 vLLM 主体安装成功。这里有一个非常关键的细节vLLM 和 PyTorch 的版本绑定关系比较强你不需要也不应该手动指定 torch 版本直接装 vllm 会让 pip 自动解析出配套的 torch。手动乱装 torch 很容易把环境搞崩回头排查依赖冲突才是最耗时间的。3.2 下载Qwen3-8B-FP8模型两条国内可用的路径模型推荐直接下载到 WSL2 内部路径用类似~/models/Qwen3-8B-FP8这种目录。第一条路径是使用 Hugging Face 的国内镜像站点 hf-mirror。通过环境变量把下载源指到镜像export HF_ENDPOINThttps://hf-mirror.com huggingface-cli download Qwen/Qwen3-8B-FP8 --local-dir ~/models/Qwen3-8B-FP8如果你没装 huggingface_hub先执行uv pip install huggingface_hub。第二条路径是 ModelScope。Qwen 系列在 ModelScope 上有官方仓库下载速度在国内相当乐观pip install modelscope modelscope download --model Qwen/Qwen3-8B-FP8 --local_dir ~/models/Qwen3-8B-FP8两条路我都实测过ModelScope 对国内网络更友好Hugging Face 镜像胜在模型目录结构和 vLLM 生态天然一致。下载完成后确认目录里至少有 config.json、tokenizer.json 和若干个 .safetensors 权重文件缺文件的话后续加载一定会报错。3.3 模型文件完整性与路径规划模型下载好以后我建议把路径固定在一个地方避免每次启动都找半天。比如统一放到~/models/下那么 vLLM 启动时直接用--model ~/models/Qwen3-8B-FP8指定本地路径即可不用每次写完整的 HF 仓库名。另外一个容易被忽略的点是vLLM 加载本地模型目录时会自动读取目录里的 config.json里面已经包含了 FP8 量化的配置信息。也就是说正常情况下你不需要手动指定--quantization fp8vLLM 会自己识别。这点和加载某些第三方量化模型时需要手动传参的体验不太一样对新手更友好。4. vLLM服务启动实战参数逐项拆解4.1 最小化启动命令先跑通再说在 WSL2 终端里确保虚拟环境已激活然后执行vllm serve ~/models/Qwen3-8B-FP8 \ --host 0.0.0.0 \ --port 8000如果一切正常你会看到 vLLM 先加载模型权重再初始化推理引擎最后输出类似下面的日志INFO: Started server process [12345] INFO: Application startup complete. INFO: Uvicorn running on http://0.0.0.0:8000看到Application startup complete就说明服务已经起来了。用浏览器打开http://localhost:8000再访问/health或/healthz路径通常能返回健康检查状态。不过“先跑通”的命令只是最小集实际使用中很少这样裸跑。你大概率会遇到显存不够用、上下文长度不合适、端口被占用等问题。下面我把关键参数逐个拆开讲你不需要全记住先按自己的硬件情况挑几个改动跑通一次后再回头细看就好。4.2 关键启动参数说明每个参数为什么值得调参数作用我的建议--model指定模型路径或 HF 仓库名本地路径更稳定建议用绝对路径--host/--port服务监听地址和端口默认 0.0.0.0:8000注意端口冲突--max-model-len模型最大上下文长度显存紧张时设 8192 或 16384 立省显存--gpu-memory-utilization允许 vLLM 占用显存的比例默认 0.9单卡共享机器可以降到 0.6-0.7--tensor-parallel-size使用几张卡做张量并行单卡千万别设大于 1多卡也要谨慎--quantization强制指定量化方式本模型可省异常时显式用fp8--served-model-name对外暴露的模型名称方便对接已有客户端配置--trust-remote-code允许加载仓库里的自定义代码部分模型需要Qwen 一般不需要--api-key为 API 增加访问密钥暴露公网时强烈建议开启之所以把--max-model-len单独拎出来说是因为这个参数对显存影响巨大。Qwen3-8B 原生支持 32K 上下文但如果你只是做日常问答、代码生成大部分请求的上下文也就是几千 token。把--max-model-len从 32768 降到 8192KV Cache 占用直接少一大截在 16GB 显存上体感非常明显。4.3 FP8量化在vLLM里的处理细节Qwen3-8B-FP8 的 config.json 里自带quantization_configvLLM 加载时会自动识别。如果你在日志中看到模型被当作 BF16 加载说明量化信息没被正确解析这时候可以显式指定vllm serve ~/models/Qwen3-8B-FP8 \ --quantization fp8 \ --kv-cache-dtype fp8_e4m3--kv-cache-dtype fp8_e4m3的作用是把 KV Cache 也切成 FP8 存储进一步压显存。这个选项在 Ada Lovelace 及以上架构的显卡上支持比较好如果你的显卡是 RTX 30 系建议先不开启实测一部分场景会有兼容性问题。另外注意FP8 权重在推理时会反量化回更高精度做计算所以它不会像整型量化那样明显牺牲模型质量这也是 FP8 这两年被大规模采用的原因之一。在 vLLM 里使用 FP8 模型你不需要改动任何业务代码API 层面和普通模型完全一致。4.4 启动日志怎么看快速判断服务健康状态刚开始跑的时候日志非常长很多人一刷屏就慌了。其实不需要逐行读重点盯这几类信息显存分配情况日志里会显示类似GPU memory usage: xxx或Number of GPU blocks如果这里的数字很小说明可用 KV Cache 空间不足并发能力会受限模型加载完成提示出现Load avg weights took ...表示权重加载完成这里时间太久的话要怀疑是不是模型放到了/mnt/c下Starting vLLM server at ...和Application startup complete这两行是服务可用的信号。如果启动过程中卡在某一步不动大概率就是网络问题还在下载或者显存不足。前者检查模型路径是否指向本地目录后者看 nvidia-smi 确认显存没被其他进程占满。4.5 让服务在后台运行nohup和tmuxWSL2 终端一旦关闭前台运行的 vLLM 服务也会跟着退出。为了避免反复重启我习惯用 nohup 把服务放到后台并把日志写进文件nohup vllm serve ~/models/Qwen3-8B-FP8 \ --host 0.0.0.0 \ --port 8000 \ --max-model-len 8192 \ vllm.log 21 要查日志就看tail -f vllm.log想杀掉服务就pkill -f vllm serve。这个操作方式在 Windows Terminal 里配合 WSL2 使用很顺手不需要额外装工具。5. 调用推理接口OpenAI兼容API从curl到SDK5.1 用curl快速验证30秒确认服务正常vLLM 启动后暴露的是 OpenAI 兼容 API所以最简单的验证方式就是 curl。打开一个新的终端Windows PowerShell 也可以因为 localhost 是通的curl http://localhost:8000/v1/chat/completions \ -H Content-Type: application/json \ -d { model: Qwen3-8B-FP8, messages: [ {role: user, content: 用一句话解释什么是PagedAttention} ], max_tokens: 128, temperature: 0.7 }返回 JSON 里会出现choices[0].message.content字段里面就是模型生成的回答。这一步能通说明整个服务链路已经问题不大了。如果你启动时指定了--served-model-name这里model字段要用你指定的名字。5.2 用Python requests调用不依赖额外库很多人写 demo 不想引入 OpenAI SDK那就直接用 requestsimport requests url http://localhost:8000/v1/chat/completions payload { model: Qwen3-8B-FP8, messages: [ {role: user, content: 写一段Python代码实现快速排序} ], max_tokens: 512, temperature: 0.3 } response requests.post(url, jsonpayload) data response.json() print(data[choices][0][message][content])注意返回结构里content是最终拼接好的完整回答。requests 的json参数会自动设置 Content-Type不用手动加 header这一点比 curl 命令省事。5.3 用OpenAI SDK调用复用现有代码如果你的项目本来就用了 OpenAI 的 Python SDK只需要改一下 base_urlfrom openai import OpenAI client OpenAI( api_keyEMPTY, base_urlhttp://localhost:8000/v1 ) completion client.chat.completions.create( modelQwen3-8B-FP8, messages[ {role: system, content: 你是一个乐于助人的助手。}, {role: user, content: 介绍一下Qwen3主力模型的特点} ] ) print(completion.choices[0].message.content)api_key 填一个占位字符串就行因为 vLLM 默认不校验密钥。如果你启动时设置了--api-key记得把这里换成真实密钥。这套写法最大的价值在于以后你想换成其他 OpenAI 兼容服务比如别的推理框架或云厂商接口代码几乎不用动。5.4 流式输出实战类ChatGPT打字机效果非流式接口要等模型完整生成完才返回长响应时会明显感受到延迟。流式输出可以让 token 一个接一个蹦出来体感和 ChatGPT 网页版接近。用 OpenAI SDK 的话只需加一个streamTruefrom openai import OpenAI client OpenAI( api_keyEMPTY, base_urlhttp://localhost:8000/v1 ) stream client.chat.completions.create( modelQwen3-8B-FP8, messages[ {role: user, content: 写一段500字左右的产品介绍} ], streamTrue ) for chunk in stream: delta chunk.choices[0].delta.content if delta: print(delta, end, flushTrue)底层原理是 SSEServer-Sent EventsvLLM 会把每个生成的 token 通过 HTTP 长连接实时推给客户端。对 Web 前端来说解析 SSE 流把内容渲染到页面就可以了。流式响应对长文本生成体验改善非常明显建议对接业务时优先考虑。6. 性能调优与Windows/WSL2踩坑实录6.1 性能和显存之间的取舍三个关键参数先说明一个原则vLLM 的性能不是某个参数单独决定的而是“显存预算、批次大小、上下文长度”三者之间权衡的结果。我建议按顺序调这三个参数--gpu-memory-utilization决定 vLLM 能占用多少显存。留太少KV Cache 不够并发能力上不去留太多会和桌面环境抢显存导致其他应用崩溃。我一般设 0.85。--max-model-len直接决定单请求最长上下文。不需要超长上下文时调低它给 KV Cache 腾空间效果立竿见影。--max-num-seqs控制一次推理 batch 里最多有多少个请求。默认值通常会比较保守显存宽裕时可以适度调高吞吐量随之上升。下面这组是我在 24GB 显存显卡上实测比较舒服的配置vllm serve ~/models/Qwen3-8B-FP8 \ --host 0.0.0.0 \ --port 8000 \ --max-model-len 16384 \ --gpu-memory-utilization 0.9 \ --max-num-seqs 64 \ --enable-prefix-caching--enable-prefix-caching开启后重复的 prompt 前缀比如系统提示词、固定模板会被缓存多轮对话场景下能省不少计算量。这个参数没有副作用建议常开。6.2 常见问题排查表遇到报错先看这张表现象可能原因解决办法启动报 CUDA out of memory显存不足或max-model-len太大调低--max-model-len降--gpu-memory-utilization关掉其他吃显存的应用加载模型时提示找不到量化配置模型目录不完整或 config.json 读取失败检查目录文件完整性或显式加--quantization fp8服务起来了但 curl 不返回端口被占用或请求地址错误换端口确认model字段与实际--served-model-name一致WSL2 内能访问但 Windows 浏览器打不开老版本 WSL2 网络模式不同新版本一般自动转发不行就用netsh interface portproxy做端口转发启动特别慢日志卡在读模型模型放在/mnt/c跨盘读取把模型挪到 WSL2 内部目录重新下载或复制多卡设置--tensor-parallel-size 2报 NCCL 错误WSL2 下多卡通信支持不稳定单卡先别开多卡或考虑 Docker Linux 环境Python 依赖冲突、torch 版本不对手动装了 torch重开虚拟环境直接uv pip install vllm让 pip 自动解析依赖6.3 WSL2里跑vLLM特有的三个坑第一个坑是显存不释放。Windows 桌面端一旦有进程加载了 CUDA 上下文即使程序退出了显存也可能被系统占用一段时间。vLLM 启动前先打开任务管理器看一眼如果显存被某个残留进程占着用wsl --shutdown重启一下 WSL2 实例状态会干净很多。第二个坑是/mnt/c文件系统性能很慢。Windows 的 NTFS 挂载到 WSL2 里走的是 9P 协议IO 性能远不如 WSL2 原生的 ext4。模型下载到 Linux 文件系统里看起来只是换个目录的事实际体验差异巨大模型放对了地方加载时间能差出一倍。所以我的习惯是模型一定放~/models绝不放/mnt/c/Users/xxx/...。第三个坑是 WSL2 的 IP 和端口转发问题。新版本 WSL2 默认使用镜像网络模式mirrored networkingWindows 侧直接访问 localhost 就能通。如果你遇到 Windows 侧始终访问不了 WSL2 里的服务可以先在 WSL2 里执行ip addr show eth0拿到 WSL2 的 IP再从 Windows 访问这个 IP 加端口实在不行再上端口转发。6.4 一个简单压测看看Qwen3-8B-FP8能跑多快配置好以后我想大家都会好奇模型到底跑多快。这里分享一组我自己的实测数据仅供参考硬件与配置场景实测结果RTX 4090 24GBmax-model-len16384单请求流式生成500 token 输出约 80-110 tokens/s同一配置并发 16 个请求批量推理整体吞吐总吞吐可以到 800 tokens/s2048 token prompt 预填充prefill 阶段约 4000-6000 tokens/s数据会随着输入长度、并发数、驱动版本有波动但趋势很明确单请求的速度取决于内存带宽并发时 Continuous Batching 能把吞吐量拉得很高。这也是 vLLM 在生产环境里真正的价值所在——它不是把单次生成做多快而是让 GPU 在大量请求面前不被浪费。如果你也想验证自己的环境可以用 Python 并发发十几个请求对比一下整体耗时就能直观感受到“批量处理”和“逐个排队”的巨大差异。这个测试不要在生产服务器上做本地开发机完全没问题。写到这里我发现自己每次在 Windows 上折腾这类工具最后都会得出同一个结论Windows 从来不是不能做只是很多坑需要人到场踩一遍才知道怎么绕。按我这套流程走下来你应该能在半小时到一小时左右跑通 Qwen3-8B-FP8然后再按自己的硬件条件微调那三个性能参数把它变成一台真正能用的本地模型服务。如果你在启动过程中遇到上面表格里没写到的报错建议优先把完整日志发到 vLLM 的 GitHub issue 里搜一搜很多问题都有现成的讨论和结论。最后再分享一个小技巧把启动命令和常用参数写成一个 shell 脚本放进 WSL2 的~/.local/bin里下次启动模型服务只需要一行命令不用再翻历史记录找参数了。