1. 为什么非要在 Windows 上跑 vLLM先搞清楚这事到底卡在哪说实话vLLM 官方从来没有正式支持过 Windows。你去翻 vLLM 的 GitHub issues能看到一长串 Windows 相关的讨论从 2023 年就有人提到 2025 年了还在提。核心原因不在 vLLM 本身的 Python 代码而在它依赖的两个底层组件上NCCLNVIDIA 的集合通信库官方只提供 Linux 二进制包Windows 上根本没有正式版本。你在 Windows 裸机上装 vLLM编译 torch 的分布式组件时就会卡在这里。PagedAttention 的自定义 CUDA kernelvLLM 最核心的显存管理机制依赖大量手写 CUDA kernel这些 kernel 在 Linux 上适配最充分Windows 上虽然能编译一部分但总有一些 op 过不去。那 Windows 用户就完全没戏了吗不是。现在的主流解法是用 Docker Desktop 的 WSL2 backend把 Linux 内核塞进 Windows然后在 WSL2 里跑 Linux 版的 vLLM。这本质上还是 Linux 部署但你的操作界面、文件系统、日常使用习惯都在 Windows 这边所以从体验上说是“在 Windows 上跑 vLLM”完全没毛病。还有一种野路子是在本机装 WSL2然后直接在 WSL2 distro 里用 pip 安装 vLLM。这条路的问题在于你需要自己搞定 CUDA toolkit、GCC、Python 环境而且每次 WSL2 小版本更新后可能有各种动态库对不上的问题。我在本地踩过一次libnccl.so.2 not found折腾了快两个小时后来切到 Docker 方案后才算消停。两条路线的简单对比我放在下面对比项Docker Desktop WSL2原生 WSL2 pip 安装环境隔离好镜像即环境一般依赖宿主 distro 状态CUDA 依赖由镜像预置基本不用管需要手动安装 CUDA toolkit升级迁移换镜像 tag 即可需要重新建虚拟环境性能损耗极小GPU 直通极小GPU 直通适合人群想快速跑通、专注推理想同时改 vLLM 源码做二次开发我个人推荐绝大多数人选择 Docker Desktop。下面所有步骤都基于这条路。注意如果你手头是 NVIDIA 显卡需要保证驱动版本不低于 535.x因为后续要用到 CUDA 12.x 的容器。WSL2 环境下 GPU 驱动直接复用 Windows 的驱动不需要在 WSL2 里再装一遍这一点是 WSL2 最大的便利。2. 开跑前的硬件与软件准备FP8 模型的显存账要算清楚2.1 Qwen3-8B-FP8 到底需要多少显存先算一笔账。Qwen3-8B 基础版本大约 8.2B 参数如果用 BF16 加载光权重就要 8.2 × 2 16.4GB加上 KV cache 和推理中间激活值24GB 显存的卡跑起来非常紧张上下文稍长就直接 OOM。FP8 版本把每个权重压缩到 1 字节权重大约 8.2GB。注意这个 8.2GB 是近似值实际 checkpoint 里除了权重还有部分模块保持 BF16比如 embedding 层、norm 层所以总量大概在 8.5GB 左右。但这仍然比 BF16 省了一半还多给 KV cache 和激活值留出了充足空间。算上以下开销CUDA context约 500MB1GB取决于 CUDA 版本。KV cache这个是动态的跟 max-model-len 和并发数直接相关。推理激活值跟 batch size 有关。我的实测建议12GB 显存能跑但很勉强16GB 显存舒适24GB 显存可以放开手脚开长上下文和高并发。12GB 卡如果不做任何优化max-model-len 超过 8192 就容易 OOM。如果你想更精细地估算vLLM 提供了--max-model-len参数来约束 KV cache 的最大长度比如设置为 32768 就表示最多缓存 32K 个 token 的 KV。KV cache 的计算公式比较繁琐但可以简单按“每 token 每层大约需要 num_heads * head_dim * 2 bytesFP16 * 2K和V”来粗略估计。实际部署时我更建议直接设一个保守值然后根据显存占用逐步调大。2.2 Docker Desktop 安装中最容易忽略的两个设置Docker Desktop 的安装本身没有太多坑但有两个设置直接影响后面的 vLLM 运行第一个是WSL2 backend 必须启用。安装完成后打开 Docker Desktop 的 Settings → General确认 Use the WSL 2 based engine 是勾选的。这一步如果漏了后面--gpus all直接用不了。第二个是Resources 内存分配。Windows 里 Docker Desktop 默认只给 WSL2 分配一部分内存如果你机器是 32GB 内存默认分给 WSL2 的可能只有 8GB 左右。vLLM 在加载模型和做 prefill 时 CPU 内存也会占用不少建议在 Settings → Resources → Advanced 里把内存调到物理内存的一半以上。我自己是 64GB 内存的机器分给 WSL2 32GB跑起来很稳。如果要微调 WSL2 的内存、CPU、swap可以在C:\Users\你的用户名\.wslconfig文件里写[wsl2] memory32GB processors8 swap16GB改完后在 PowerShell 里执行wsl --shutdown然后重新打开 Docker Desktop 才生效。这个文件不存在就自己创建存在就追加。2.3 镜像版本与 CUDA 版本怎么对照vLLM 官方镜像的 tag 规则很简单vllm/vllm-openai:latest是最新版也可以选带 CUDA 版本标识的 tag。我在部署时倾向用固定版本而不是 latest避免过了一段时间镜像更新导致行为变化、排查问题时无从下手。关于 CUDA 版本官方镜像里的 CUDA 12.1 / 12.4 是预置好的不需要你在宿主机装 CUDA。只要 Windows 的 NVIDIA 驱动足够新容器里就能正常调用 GPU 资源。经验分享如果拉镜像时总超时先检查 Docker 的 Registry mirrors 是否配置好。国内网络环境下给 Docker Desktop 配置一个可用的镜像加速器能节省大量时间。3. 一步步跑通 Qwen3-8B-FP8从拉镜像到发起第一次推理3.1 准备模型文件在 Windows 侧下载挂载进容器vLLM 本身不会帮你下载 Hugging Face 上的模型需要先把模型下载到本地。这里有个 Windows 下的小技巧直接在你熟悉的 Windows 目录下下载然后用 Docker 的目录挂载把模型目录映射到容器里这样不需要把几十 GB 的模型文件塞进 WSL2 的虚拟磁盘里。我用的是hf-mirror.com这个镜像站下载模型原因是国内的网络环境下直连 Hugging Face 通常很慢甚至不通而 hf-mirror 是纯 HTTPS 加速镜像配置环境变量即可不需要额外装任何东西。在你准备好的模型目录执行# Windows PowerShell 或 CMD 均可推荐 PowerShell $env:HF_ENDPOINT https://hf-mirror.com # 先用 huggingface_hub 下载确保已经安装了 huggingface_hub pip install huggingface_hub # 下载整个仓库的 snapshot而不是单个文件 hf download Qwen/Qwen3-8B-FP8 --local-dir D:\models\Qwen3-8B-FP8注意hf download是 huggingface_hub 新版命令老版本的命令是huggingface-cli download。如果遇到命令不存在升级 huggingface_hub 即可。下载完成后你的目录下应该有几个关键的 safetensors 文件通常是多个分片、config.json、generation_config.json以及一个 tokenizer 相关文件。建议检查一下目录里的config.json中quantization_config字段确认它标记了quant_method: fp8。这一步能确保后续 vLLM 自动识别这是 FP8 检查点而不是当成普通模型加载。3.2 启动容器关键参数逐项拆解模型准备好后执行下面的命令启动 vLLM 服务。我用的镜像是vllm/vllm-openai:v0.6.6.post1一个我在生产环境验证过的稳定版本。docker run -d --gpus all --shm-size16g -p 8000:8000 -v D:\models:/models --name vllm-qwen3 vllm/vllm-openai:v0.6.6.post1 --model /models/Qwen3-8B-FP8 --max-model-len 32768 --gpu-memory-utilization 0.9 --port 8000逐个参数解释免得你出错--gpus all让容器使用宿主机所有可用的 GPU。Docker Desktop 的 WSL2 backend 会自动把 GPU 透传给容器。--shm-size16g设置容器的共享内存为 16GB。这个参数很关键vLLM 的 tokenizer、预处理、以及多卡通信都要用共享内存默认 64MB 是远远不够的。不加这个参数启动后推理时很容易报 shared memory 相关错误。-v D:\models:/models把 Windows 侧的D:\models目录挂载到容器的/models容器内看到的/models/Qwen3-8B-FP8就是 Windows 上的模型文件。--model /models/Qwen3-8B-FP8指定模型路径。--max-model-len 32768最大上下文长度设为 32K token。如果显存紧张可以调到 16384节省 KV cache 的占用。--gpu-memory-utilization 0.9限制 vLLM 最大使用 90% 的显存。留 10% 给 CUDA context 和临时缓冲避免 OOM。启动后先看日志docker logs -f vllm-qwen3看到像下面这样的输出说明服务已经就绪INFO 06-15 10:23:45 engine.py:215] init engine (profile, create kv cache, warmup) INFO 06-15 10:23:50 engine.py:291] init engine took 5.2 seconds INFO 06-15 10:23:50 api_server.py:612] Starting vLLM API server on http://0.0.0.0:8000日志里还会打一行Using fp8 checkpoint之类的信息这代表 vLLM 正确识别了 FP8 格式。看到这行你的模型就已经加载成功了。3.3 写一个最简单的 OpenAI 兼容调用脚本验证推理vLLM 启动后对外提供的是 OpenAI 风格的 API所以测试方法可以完全复用 OpenAI SDK。先在宿主机上装好openai库pip install openai然后写一个验证脚本test_qwen3.pyfrom openai import OpenAI client OpenAI( base_urlhttp://localhost:8000/v1, api_keyEMPTY # vLLM 本地服务不校验 key随便填 ) response client.chat.completions.create( model/models/Qwen3-8B-FP8, messages[ {role: system, content: 你是一个简洁的助手。}, {role: user, content: 用一句话解释 FP8 是什么。} ], temperature0.7, max_tokens256, ) print(response.choices[0].message.content)运行python test_qwen3.py只要返回了正常的中文/英文文本整个链路就算通了一半。我用 Qwen3-8B-FP8 实测短问题的首 token 延迟在 RTX 4090 上大概是80~150ms这个量级生成速度在100200 tokens/s之间具体看输入长度和并发量。另外也可以通过 curl 快速验证curl http://localhost:8000/v1/models返回的 JSON 里会有你当前加载的模型 ID、最大上下文长度等元信息。3.4 如果你想用 OpenAI 流式输出上面的脚本是非流式调用等整个回复生成完才返回。实际项目中尤其是做 Chat 类应用时更常用流式方式让用户看到逐字输出。把stream参数设为True就能启用from openai import OpenAI client OpenAI(base_urlhttp://localhost:8000/v1, api_keyEMPTY) stream client.chat.completions.create( model/models/Qwen3-8B-FP8, messages[{role: user, content: 写一首关于夏天的短诗}], streamTrue, ) for chunk in stream: if chunk.choices[0].delta.content: print(chunk.choices[0].delta.content, end, flushTrue)这部分实现其实不需要 vLLM 做任何额外配置它原生兼容 OpenAI 的流式协议。4. 实测中躲不开的稳定性与性能调优问题4.1 共享内存不足导致的崩溃完整排查链路第一次跑 vLLM 时我遇到过一个经典问题这里完整复盘一下排查链路帮你以后遇到类似问题能快速定位。现象是容器启动时日志显示模型加载正常但一旦我发送请求、进入 prefill 阶段服务就崩了Docker 容器直接退出docker logs最后几行报RuntimeError: CUDA error: out of memory或者一些奇怪的 shared memory 错误。开始我以为是显存不够于是把--gpu-memory-utilization从 0.9 调到 0.7重新跑结果还是崩。后来我仔细看日志发现崩之前有一行提示说/dev/shm空间不足。这才意识到问题不在显存而在共享内存。Docker 容器默认的/dev/shm只有 64MBvLLM 的张量并行通信、数据集缓存、某些 tokenizer 后处理都会往共享内存里写数据。64MB 对一个小模型可能够了但对 8B 模型和 32K 上下文来说完全不够。解决方式就是我前面提到的--shm-size16g。加上这个参数后重启容器问题直接消失。这里也建议大家以后写 Docker 启动命令时只要容器里涉及大模型推理--shm-size至少给 8GB否则迟早踩这个坑。再补一个容易混淆的坑如果你在 WSL2 的 Ubuntu 里直接运行free -h看到的 shared 内存并不是 Docker 容器里的/dev/shm这两个是不同维度的概念。排查共享内存问题一定要进容器里看docker exec -it vllm-qwen3 df -h /dev/shm如果输出显示容量是你设的 16GB说明共享内存没问题了。4.2 从 32K 上下文到高并发max-num-seqs 与 kv-cache-dtype默认情况下vLLM 会根据显存自动计算能缓存多少 token 的 KV cache也会自动决定 batch 大小。但默认策略偏保守实际使用中可以手动微调--max-num-seqs 64最多同时处理 64 个序列。这个值越大GPU 利用率越高但单请求的延迟也会略微上升。如果只是自己用设 1632 就够如果要对外提供服务64 以上更合适。--kv-cache-dtype fp8把 KV cache 以 FP8 存储。Qwen3-8B-FP8 本身就是 FP8 权重如果你把 KV cache 也压成 FP8显存占用还能进一步降低。代价是极端长上下文时精度有一定损失但日常对话场景几乎感觉不到差异。这个参数在 24GB 显存上开 32K 上下文时特别有用实测能多出约 20% 的可用 KV cache 空间。列一个我在 4090 上实测过的一组配置供参考docker run -d --gpus all \ --shm-size16g \ -p 8000:8000 \ -v D:\models:/models \ --name vllm-qwen3-optimized \ vllm/vllm-openai:v0.6.6.post1 \ --model /models/Qwen3-8B-FP8 \ --max-model-len 32768 \ --gpu-memory-utilization 0.92 \ --max-num-seqs 32 \ --kv-cache-dtype fp8跑 16 并发压测每个请求都是 128 输入长度、128 输出长度时吞吐量大约能到12001500 tokens/s的聚合速度单用户体感还是很快的。当然具体数字会受输入长度、显存频率等因素影响但方向上不会错。4.3 换显卡时要留意的架构差异FP8 加速不是所有显卡都同样出色的。NVIDIA 的 FP8 推理加速在 Ada Lovelace 架构RTX 40 系和 Hopper 架构H100、H200上支持最好。如果你用的是 RTX 30 系列Ampere 架构虽然能加载 FP8 模型但某些算子会走降级路径实际速度不一定比 BF16 版本快多少。我在 3080Ti 上对比过 Qwen3-8B-FP8 和 BF16 的速度两者差距非常小FP8 几乎没占到架构优势。所以如果你手头是 RTX 30 系可以考虑直接用 BF16 版本模型反而少一道转换。如果是 RTX 40 系、RTX 50 系或企业级 Hopper 卡FP8 才真正值得用。4.4 日志里出现NCCL字样时不必慌张启动 vLLM 时日志经常会有类似INFO 06-15 10:20:11 [pynccl.py:113] vllm is using nccl2.30.7很多新手看到 NCCL 就觉得要出问题其实这只是 vLLM 打印当前使用的 NCCL 版本信息。只要你的部署不是多节点分布式推理NCCL 只是用来做单机多卡或 GPU 通信的底层库。单卡场景下看到这行完全可以忽略。如果你需要多卡推理就要注意在 Docker 的 WSL2 backend 下多卡通信要求所有 GPU 在同一个 WSL2 实例内可见。Docker Desktop 默认情况下是能把多张卡都透传进去的你可以用nvidia-smi检查容器内部是否能看到全部 GPU。5. 对比过 LM Studio 和 SGLang 之后我为什么还是选了 vLLM5.1 vLLM 与 LM Studio 的定位差异LM Studio 是很多 Windows 用户接触本地大模型的第一个工具图形界面 一键加载模型 本地聊天体验确实很友好。但它的定位是桌面应用不是推理服务框架。你很难用 LM Studio 把它做成一个稳定的 API 服务给其他程序调用并发处理能力也有限本质上是单用户、单会话的桌面工具。vLLM 则是一个可以服务化的推理引擎。它能做到同时服务多个应用提供标准的 OpenAI 兼容 API。高并发请求下通过 continuous batching 提升吞吐量。精细控制 KV cache、上下文长度、量化格式。支持vllm serve一条命令直接起服务。一句话总结如果你只是在自己电脑上聊天玩LM Studio 够了如果你的目标是给项目提供本地推理服务vLLM 是更合适的底座。5.2 vLLM 与 SGLang 的取舍SGLang 在 20242025 年热度不低它主打的是RadixAttention技术对前缀缓存如 system prompt 复用、few-shot 公共前缀有很强的加速效果。如果你的应用场景是大量用户共享同一段超长 system promptSGLang 可能比 vLLM 更有优势。但对大多数人来说vLLM 的生态成熟度更高社区大遇到问题容易搜到解决方案。支持各种量化方式GPTQ、AWQ、FP8、TPU、XPU。兼容 OpenAI API 最完善很多开发框架直接内置了 vLLM 适配层。我个人的项目大多属于“快速部署、稳定服务、与现有 Python 服务集成”这一类vLLM 的简单直接正好对胃口。如果你有极端的前缀复用场景再考虑 SGLang 不迟。5.3 什么时候真的不适合用 vLLMvLLM 也不是万能的。下面几个场景我建议换方案单次短请求、低并发的内部工具如果只是偶尔调几次模型vLLM 常驻内存占用显存比较浪费LM Studio 或 Ollama 更轻量。老显卡10 系、20 系vLLM 对这些老架构的 kernel 支持不完整可能连跑都跑不起来。需要深度定制 sampler 逻辑vLLM 对 sampling 参数的支持很完善但如果你要做的采样逻辑非常小众比如逐 token 自定义拒绝采样那用 Transformers 或 LLM 库自己写更灵活。6. 更平滑的 Windows 部署细节与避坑清单6.1 端口占用与重启策略8000这个端口经常会被其他本地服务占用。如果启动容器后访问http://localhost:8000没反应先执行netstat -ano | findstr :8000如果看到端口占用最简单的办法是改 vLLM 的监听端口比如映射到8001docker run -d ... -p 8001:8000 ...另外建议启动容器时加上--restart unless-stopped这样 Docker 重启后容器会自动恢复不用手动去起。配合--name参数后续管理也方便。6.2 Windows 防火墙的干扰在 Windows 上通过localhost访问 Docker 映射出来的端口通常没问题但如果你在同一局域网内的另一台设备上访问这台机器的 vLLM 服务就需要检查 Windows 防火墙了。解决办法是控制面板 → Windows Defender 防火墙 → 允许应用或功能通过防火墙 → 勾选 Docker Desktop Backend 和 Vmmem 相关的网络访问权限。如果不放心可以临时跑一条 curl 验证curl http://Windows机器的IP:8000/v1/models如果通了说明网络打通了如果没通重点查防火墙和你路由器是否允许局域网访问。6.3 模型加载太慢preload 选项了解一下如果你每次重启容器后都要等十几秒甚至几十秒加载模型可以给 vLLM 加一个--enable-prefix-caching参数。这个参数主要优化的是多个请求间公共前缀的 KV cache 复用对单请求场景帮助不大但对 service prompt 很长、多轮对话频繁的项目很有用。另外如果你的 Windows 是有 SSD 的把模型放在 SSD 上能明显缩短 checkpoint 读取时间。vLLM 加载模型时要完整读一遍权重文件从机械硬盘读能从 2~3 分钟延长到 10 分钟以上这个经验值得记住。6.4 最终跑通之后把所有命令固化成脚本最后分享一个提效小技巧不要每次部署都手动输入那一长串 docker run 命令。把启动命令保存成start-qwen3.bat放桌面内容就一行docker start vllm-qwen3以及一个deploy-qwen3.bat用于首次部署docker run -d --gpus all --shm-size16g -p 8000:8000 -v D:\models:/models --restart unless-stopped --name vllm-qwen3 vllm/vllm-openai:v0.6.6.post1 --model /models/Qwen3-8B-FP8 --max-model-len 32768 --gpu-memory-utilization 0.9以后再想启动服务双击脚本就行不用再回忆那一大串参数。这也是我从多次折腾里沉淀下来的习惯凡是验证过能跑通的命令立刻固化成脚本省得下次手抖删错一个参数排查半天。实际部署中我再次体会到Windows 上跑 vLLM 最大的门槛不在 vLLM 本身而在于把 Docker Desktop、WSL2 backend 和 NVIDIA GPU 透传这三者协调好。一旦这个环境稳定下来后面的模型加载、推理、调优都跟在 Linux 上没有任何区别。希望这篇能帮你少走一些我趟过的弯路。 Windows上部署vLLM跑Qwen3-8B-FP8：Docker+WSL2全攻略
1. 为什么非要在 Windows 上跑 vLLM先搞清楚这事到底卡在哪说实话vLLM 官方从来没有正式支持过 Windows。你去翻 vLLM 的 GitHub issues能看到一长串 Windows 相关的讨论从 2023 年就有人提到 2025 年了还在提。核心原因不在 vLLM 本身的 Python 代码而在它依赖的两个底层组件上NCCLNVIDIA 的集合通信库官方只提供 Linux 二进制包Windows 上根本没有正式版本。你在 Windows 裸机上装 vLLM编译 torch 的分布式组件时就会卡在这里。PagedAttention 的自定义 CUDA kernelvLLM 最核心的显存管理机制依赖大量手写 CUDA kernel这些 kernel 在 Linux 上适配最充分Windows 上虽然能编译一部分但总有一些 op 过不去。那 Windows 用户就完全没戏了吗不是。现在的主流解法是用 Docker Desktop 的 WSL2 backend把 Linux 内核塞进 Windows然后在 WSL2 里跑 Linux 版的 vLLM。这本质上还是 Linux 部署但你的操作界面、文件系统、日常使用习惯都在 Windows 这边所以从体验上说是“在 Windows 上跑 vLLM”完全没毛病。还有一种野路子是在本机装 WSL2然后直接在 WSL2 distro 里用 pip 安装 vLLM。这条路的问题在于你需要自己搞定 CUDA toolkit、GCC、Python 环境而且每次 WSL2 小版本更新后可能有各种动态库对不上的问题。我在本地踩过一次libnccl.so.2 not found折腾了快两个小时后来切到 Docker 方案后才算消停。两条路线的简单对比我放在下面对比项Docker Desktop WSL2原生 WSL2 pip 安装环境隔离好镜像即环境一般依赖宿主 distro 状态CUDA 依赖由镜像预置基本不用管需要手动安装 CUDA toolkit升级迁移换镜像 tag 即可需要重新建虚拟环境性能损耗极小GPU 直通极小GPU 直通适合人群想快速跑通、专注推理想同时改 vLLM 源码做二次开发我个人推荐绝大多数人选择 Docker Desktop。下面所有步骤都基于这条路。注意如果你手头是 NVIDIA 显卡需要保证驱动版本不低于 535.x因为后续要用到 CUDA 12.x 的容器。WSL2 环境下 GPU 驱动直接复用 Windows 的驱动不需要在 WSL2 里再装一遍这一点是 WSL2 最大的便利。2. 开跑前的硬件与软件准备FP8 模型的显存账要算清楚2.1 Qwen3-8B-FP8 到底需要多少显存先算一笔账。Qwen3-8B 基础版本大约 8.2B 参数如果用 BF16 加载光权重就要 8.2 × 2 16.4GB加上 KV cache 和推理中间激活值24GB 显存的卡跑起来非常紧张上下文稍长就直接 OOM。FP8 版本把每个权重压缩到 1 字节权重大约 8.2GB。注意这个 8.2GB 是近似值实际 checkpoint 里除了权重还有部分模块保持 BF16比如 embedding 层、norm 层所以总量大概在 8.5GB 左右。但这仍然比 BF16 省了一半还多给 KV cache 和激活值留出了充足空间。算上以下开销CUDA context约 500MB1GB取决于 CUDA 版本。KV cache这个是动态的跟 max-model-len 和并发数直接相关。推理激活值跟 batch size 有关。我的实测建议12GB 显存能跑但很勉强16GB 显存舒适24GB 显存可以放开手脚开长上下文和高并发。12GB 卡如果不做任何优化max-model-len 超过 8192 就容易 OOM。如果你想更精细地估算vLLM 提供了--max-model-len参数来约束 KV cache 的最大长度比如设置为 32768 就表示最多缓存 32K 个 token 的 KV。KV cache 的计算公式比较繁琐但可以简单按“每 token 每层大约需要 num_heads * head_dim * 2 bytesFP16 * 2K和V”来粗略估计。实际部署时我更建议直接设一个保守值然后根据显存占用逐步调大。2.2 Docker Desktop 安装中最容易忽略的两个设置Docker Desktop 的安装本身没有太多坑但有两个设置直接影响后面的 vLLM 运行第一个是WSL2 backend 必须启用。安装完成后打开 Docker Desktop 的 Settings → General确认 Use the WSL 2 based engine 是勾选的。这一步如果漏了后面--gpus all直接用不了。第二个是Resources 内存分配。Windows 里 Docker Desktop 默认只给 WSL2 分配一部分内存如果你机器是 32GB 内存默认分给 WSL2 的可能只有 8GB 左右。vLLM 在加载模型和做 prefill 时 CPU 内存也会占用不少建议在 Settings → Resources → Advanced 里把内存调到物理内存的一半以上。我自己是 64GB 内存的机器分给 WSL2 32GB跑起来很稳。如果要微调 WSL2 的内存、CPU、swap可以在C:\Users\你的用户名\.wslconfig文件里写[wsl2] memory32GB processors8 swap16GB改完后在 PowerShell 里执行wsl --shutdown然后重新打开 Docker Desktop 才生效。这个文件不存在就自己创建存在就追加。2.3 镜像版本与 CUDA 版本怎么对照vLLM 官方镜像的 tag 规则很简单vllm/vllm-openai:latest是最新版也可以选带 CUDA 版本标识的 tag。我在部署时倾向用固定版本而不是 latest避免过了一段时间镜像更新导致行为变化、排查问题时无从下手。关于 CUDA 版本官方镜像里的 CUDA 12.1 / 12.4 是预置好的不需要你在宿主机装 CUDA。只要 Windows 的 NVIDIA 驱动足够新容器里就能正常调用 GPU 资源。经验分享如果拉镜像时总超时先检查 Docker 的 Registry mirrors 是否配置好。国内网络环境下给 Docker Desktop 配置一个可用的镜像加速器能节省大量时间。3. 一步步跑通 Qwen3-8B-FP8从拉镜像到发起第一次推理3.1 准备模型文件在 Windows 侧下载挂载进容器vLLM 本身不会帮你下载 Hugging Face 上的模型需要先把模型下载到本地。这里有个 Windows 下的小技巧直接在你熟悉的 Windows 目录下下载然后用 Docker 的目录挂载把模型目录映射到容器里这样不需要把几十 GB 的模型文件塞进 WSL2 的虚拟磁盘里。我用的是hf-mirror.com这个镜像站下载模型原因是国内的网络环境下直连 Hugging Face 通常很慢甚至不通而 hf-mirror 是纯 HTTPS 加速镜像配置环境变量即可不需要额外装任何东西。在你准备好的模型目录执行# Windows PowerShell 或 CMD 均可推荐 PowerShell $env:HF_ENDPOINT https://hf-mirror.com # 先用 huggingface_hub 下载确保已经安装了 huggingface_hub pip install huggingface_hub # 下载整个仓库的 snapshot而不是单个文件 hf download Qwen/Qwen3-8B-FP8 --local-dir D:\models\Qwen3-8B-FP8注意hf download是 huggingface_hub 新版命令老版本的命令是huggingface-cli download。如果遇到命令不存在升级 huggingface_hub 即可。下载完成后你的目录下应该有几个关键的 safetensors 文件通常是多个分片、config.json、generation_config.json以及一个 tokenizer 相关文件。建议检查一下目录里的config.json中quantization_config字段确认它标记了quant_method: fp8。这一步能确保后续 vLLM 自动识别这是 FP8 检查点而不是当成普通模型加载。3.2 启动容器关键参数逐项拆解模型准备好后执行下面的命令启动 vLLM 服务。我用的镜像是vllm/vllm-openai:v0.6.6.post1一个我在生产环境验证过的稳定版本。docker run -d --gpus all --shm-size16g -p 8000:8000 -v D:\models:/models --name vllm-qwen3 vllm/vllm-openai:v0.6.6.post1 --model /models/Qwen3-8B-FP8 --max-model-len 32768 --gpu-memory-utilization 0.9 --port 8000逐个参数解释免得你出错--gpus all让容器使用宿主机所有可用的 GPU。Docker Desktop 的 WSL2 backend 会自动把 GPU 透传给容器。--shm-size16g设置容器的共享内存为 16GB。这个参数很关键vLLM 的 tokenizer、预处理、以及多卡通信都要用共享内存默认 64MB 是远远不够的。不加这个参数启动后推理时很容易报 shared memory 相关错误。-v D:\models:/models把 Windows 侧的D:\models目录挂载到容器的/models容器内看到的/models/Qwen3-8B-FP8就是 Windows 上的模型文件。--model /models/Qwen3-8B-FP8指定模型路径。--max-model-len 32768最大上下文长度设为 32K token。如果显存紧张可以调到 16384节省 KV cache 的占用。--gpu-memory-utilization 0.9限制 vLLM 最大使用 90% 的显存。留 10% 给 CUDA context 和临时缓冲避免 OOM。启动后先看日志docker logs -f vllm-qwen3看到像下面这样的输出说明服务已经就绪INFO 06-15 10:23:45 engine.py:215] init engine (profile, create kv cache, warmup) INFO 06-15 10:23:50 engine.py:291] init engine took 5.2 seconds INFO 06-15 10:23:50 api_server.py:612] Starting vLLM API server on http://0.0.0.0:8000日志里还会打一行Using fp8 checkpoint之类的信息这代表 vLLM 正确识别了 FP8 格式。看到这行你的模型就已经加载成功了。3.3 写一个最简单的 OpenAI 兼容调用脚本验证推理vLLM 启动后对外提供的是 OpenAI 风格的 API所以测试方法可以完全复用 OpenAI SDK。先在宿主机上装好openai库pip install openai然后写一个验证脚本test_qwen3.pyfrom openai import OpenAI client OpenAI( base_urlhttp://localhost:8000/v1, api_keyEMPTY # vLLM 本地服务不校验 key随便填 ) response client.chat.completions.create( model/models/Qwen3-8B-FP8, messages[ {role: system, content: 你是一个简洁的助手。}, {role: user, content: 用一句话解释 FP8 是什么。} ], temperature0.7, max_tokens256, ) print(response.choices[0].message.content)运行python test_qwen3.py只要返回了正常的中文/英文文本整个链路就算通了一半。我用 Qwen3-8B-FP8 实测短问题的首 token 延迟在 RTX 4090 上大概是80~150ms这个量级生成速度在100200 tokens/s之间具体看输入长度和并发量。另外也可以通过 curl 快速验证curl http://localhost:8000/v1/models返回的 JSON 里会有你当前加载的模型 ID、最大上下文长度等元信息。3.4 如果你想用 OpenAI 流式输出上面的脚本是非流式调用等整个回复生成完才返回。实际项目中尤其是做 Chat 类应用时更常用流式方式让用户看到逐字输出。把stream参数设为True就能启用from openai import OpenAI client OpenAI(base_urlhttp://localhost:8000/v1, api_keyEMPTY) stream client.chat.completions.create( model/models/Qwen3-8B-FP8, messages[{role: user, content: 写一首关于夏天的短诗}], streamTrue, ) for chunk in stream: if chunk.choices[0].delta.content: print(chunk.choices[0].delta.content, end, flushTrue)这部分实现其实不需要 vLLM 做任何额外配置它原生兼容 OpenAI 的流式协议。4. 实测中躲不开的稳定性与性能调优问题4.1 共享内存不足导致的崩溃完整排查链路第一次跑 vLLM 时我遇到过一个经典问题这里完整复盘一下排查链路帮你以后遇到类似问题能快速定位。现象是容器启动时日志显示模型加载正常但一旦我发送请求、进入 prefill 阶段服务就崩了Docker 容器直接退出docker logs最后几行报RuntimeError: CUDA error: out of memory或者一些奇怪的 shared memory 错误。开始我以为是显存不够于是把--gpu-memory-utilization从 0.9 调到 0.7重新跑结果还是崩。后来我仔细看日志发现崩之前有一行提示说/dev/shm空间不足。这才意识到问题不在显存而在共享内存。Docker 容器默认的/dev/shm只有 64MBvLLM 的张量并行通信、数据集缓存、某些 tokenizer 后处理都会往共享内存里写数据。64MB 对一个小模型可能够了但对 8B 模型和 32K 上下文来说完全不够。解决方式就是我前面提到的--shm-size16g。加上这个参数后重启容器问题直接消失。这里也建议大家以后写 Docker 启动命令时只要容器里涉及大模型推理--shm-size至少给 8GB否则迟早踩这个坑。再补一个容易混淆的坑如果你在 WSL2 的 Ubuntu 里直接运行free -h看到的 shared 内存并不是 Docker 容器里的/dev/shm这两个是不同维度的概念。排查共享内存问题一定要进容器里看docker exec -it vllm-qwen3 df -h /dev/shm如果输出显示容量是你设的 16GB说明共享内存没问题了。4.2 从 32K 上下文到高并发max-num-seqs 与 kv-cache-dtype默认情况下vLLM 会根据显存自动计算能缓存多少 token 的 KV cache也会自动决定 batch 大小。但默认策略偏保守实际使用中可以手动微调--max-num-seqs 64最多同时处理 64 个序列。这个值越大GPU 利用率越高但单请求的延迟也会略微上升。如果只是自己用设 1632 就够如果要对外提供服务64 以上更合适。--kv-cache-dtype fp8把 KV cache 以 FP8 存储。Qwen3-8B-FP8 本身就是 FP8 权重如果你把 KV cache 也压成 FP8显存占用还能进一步降低。代价是极端长上下文时精度有一定损失但日常对话场景几乎感觉不到差异。这个参数在 24GB 显存上开 32K 上下文时特别有用实测能多出约 20% 的可用 KV cache 空间。列一个我在 4090 上实测过的一组配置供参考docker run -d --gpus all \ --shm-size16g \ -p 8000:8000 \ -v D:\models:/models \ --name vllm-qwen3-optimized \ vllm/vllm-openai:v0.6.6.post1 \ --model /models/Qwen3-8B-FP8 \ --max-model-len 32768 \ --gpu-memory-utilization 0.92 \ --max-num-seqs 32 \ --kv-cache-dtype fp8跑 16 并发压测每个请求都是 128 输入长度、128 输出长度时吞吐量大约能到12001500 tokens/s的聚合速度单用户体感还是很快的。当然具体数字会受输入长度、显存频率等因素影响但方向上不会错。4.3 换显卡时要留意的架构差异FP8 加速不是所有显卡都同样出色的。NVIDIA 的 FP8 推理加速在 Ada Lovelace 架构RTX 40 系和 Hopper 架构H100、H200上支持最好。如果你用的是 RTX 30 系列Ampere 架构虽然能加载 FP8 模型但某些算子会走降级路径实际速度不一定比 BF16 版本快多少。我在 3080Ti 上对比过 Qwen3-8B-FP8 和 BF16 的速度两者差距非常小FP8 几乎没占到架构优势。所以如果你手头是 RTX 30 系可以考虑直接用 BF16 版本模型反而少一道转换。如果是 RTX 40 系、RTX 50 系或企业级 Hopper 卡FP8 才真正值得用。4.4 日志里出现NCCL字样时不必慌张启动 vLLM 时日志经常会有类似INFO 06-15 10:20:11 [pynccl.py:113] vllm is using nccl2.30.7很多新手看到 NCCL 就觉得要出问题其实这只是 vLLM 打印当前使用的 NCCL 版本信息。只要你的部署不是多节点分布式推理NCCL 只是用来做单机多卡或 GPU 通信的底层库。单卡场景下看到这行完全可以忽略。如果你需要多卡推理就要注意在 Docker 的 WSL2 backend 下多卡通信要求所有 GPU 在同一个 WSL2 实例内可见。Docker Desktop 默认情况下是能把多张卡都透传进去的你可以用nvidia-smi检查容器内部是否能看到全部 GPU。5. 对比过 LM Studio 和 SGLang 之后我为什么还是选了 vLLM5.1 vLLM 与 LM Studio 的定位差异LM Studio 是很多 Windows 用户接触本地大模型的第一个工具图形界面 一键加载模型 本地聊天体验确实很友好。但它的定位是桌面应用不是推理服务框架。你很难用 LM Studio 把它做成一个稳定的 API 服务给其他程序调用并发处理能力也有限本质上是单用户、单会话的桌面工具。vLLM 则是一个可以服务化的推理引擎。它能做到同时服务多个应用提供标准的 OpenAI 兼容 API。高并发请求下通过 continuous batching 提升吞吐量。精细控制 KV cache、上下文长度、量化格式。支持vllm serve一条命令直接起服务。一句话总结如果你只是在自己电脑上聊天玩LM Studio 够了如果你的目标是给项目提供本地推理服务vLLM 是更合适的底座。5.2 vLLM 与 SGLang 的取舍SGLang 在 20242025 年热度不低它主打的是RadixAttention技术对前缀缓存如 system prompt 复用、few-shot 公共前缀有很强的加速效果。如果你的应用场景是大量用户共享同一段超长 system promptSGLang 可能比 vLLM 更有优势。但对大多数人来说vLLM 的生态成熟度更高社区大遇到问题容易搜到解决方案。支持各种量化方式GPTQ、AWQ、FP8、TPU、XPU。兼容 OpenAI API 最完善很多开发框架直接内置了 vLLM 适配层。我个人的项目大多属于“快速部署、稳定服务、与现有 Python 服务集成”这一类vLLM 的简单直接正好对胃口。如果你有极端的前缀复用场景再考虑 SGLang 不迟。5.3 什么时候真的不适合用 vLLMvLLM 也不是万能的。下面几个场景我建议换方案单次短请求、低并发的内部工具如果只是偶尔调几次模型vLLM 常驻内存占用显存比较浪费LM Studio 或 Ollama 更轻量。老显卡10 系、20 系vLLM 对这些老架构的 kernel 支持不完整可能连跑都跑不起来。需要深度定制 sampler 逻辑vLLM 对 sampling 参数的支持很完善但如果你要做的采样逻辑非常小众比如逐 token 自定义拒绝采样那用 Transformers 或 LLM 库自己写更灵活。6. 更平滑的 Windows 部署细节与避坑清单6.1 端口占用与重启策略8000这个端口经常会被其他本地服务占用。如果启动容器后访问http://localhost:8000没反应先执行netstat -ano | findstr :8000如果看到端口占用最简单的办法是改 vLLM 的监听端口比如映射到8001docker run -d ... -p 8001:8000 ...另外建议启动容器时加上--restart unless-stopped这样 Docker 重启后容器会自动恢复不用手动去起。配合--name参数后续管理也方便。6.2 Windows 防火墙的干扰在 Windows 上通过localhost访问 Docker 映射出来的端口通常没问题但如果你在同一局域网内的另一台设备上访问这台机器的 vLLM 服务就需要检查 Windows 防火墙了。解决办法是控制面板 → Windows Defender 防火墙 → 允许应用或功能通过防火墙 → 勾选 Docker Desktop Backend 和 Vmmem 相关的网络访问权限。如果不放心可以临时跑一条 curl 验证curl http://Windows机器的IP:8000/v1/models如果通了说明网络打通了如果没通重点查防火墙和你路由器是否允许局域网访问。6.3 模型加载太慢preload 选项了解一下如果你每次重启容器后都要等十几秒甚至几十秒加载模型可以给 vLLM 加一个--enable-prefix-caching参数。这个参数主要优化的是多个请求间公共前缀的 KV cache 复用对单请求场景帮助不大但对 service prompt 很长、多轮对话频繁的项目很有用。另外如果你的 Windows 是有 SSD 的把模型放在 SSD 上能明显缩短 checkpoint 读取时间。vLLM 加载模型时要完整读一遍权重文件从机械硬盘读能从 2~3 分钟延长到 10 分钟以上这个经验值得记住。6.4 最终跑通之后把所有命令固化成脚本最后分享一个提效小技巧不要每次部署都手动输入那一长串 docker run 命令。把启动命令保存成start-qwen3.bat放桌面内容就一行docker start vllm-qwen3以及一个deploy-qwen3.bat用于首次部署docker run -d --gpus all --shm-size16g -p 8000:8000 -v D:\models:/models --restart unless-stopped --name vllm-qwen3 vllm/vllm-openai:v0.6.6.post1 --model /models/Qwen3-8B-FP8 --max-model-len 32768 --gpu-memory-utilization 0.9以后再想启动服务双击脚本就行不用再回忆那一大串参数。这也是我从多次折腾里沉淀下来的习惯凡是验证过能跑通的命令立刻固化成脚本省得下次手抖删错一个参数排查半天。实际部署中我再次体会到Windows 上跑 vLLM 最大的门槛不在 vLLM 本身而在于把 Docker Desktop、WSL2 backend 和 NVIDIA GPU 透传这三者协调好。一旦这个环境稳定下来后面的模型加载、推理、调优都跟在 Linux 上没有任何区别。希望这篇能帮你少走一些我趟过的弯路。