1. 先弄懂为什么 Windows 上跑 vLLM 不能选“原生安装”把 vLLM 和 Qwen3-8B-FP8 搬到 Windows 上这件事我前后折腾了两周。先说结论vLLM 官方明确只支持 LinuxWindows 上要么靠 WSL2要么靠 Docker Desktop想直接pip install vllm然后在 cmd 里跑通基本会卡在各种底层依赖上。这篇文章把我验证过的一套完整流程整理出来从驱动检查、WSL2 环境、模型权重下载到 vLLM 的 Docker 启动命令和请求测试适合手里有一块 NVIDIA 显卡、想在本机跑一个 OpenAI 兼容接口出来玩或做本地实验的读者。1.1 vLLM 不是“装不上”而是官方根本没做 Windows 适配很多人第一次接触 vLLM 会误以为它和 PyTorch 一样pip 装完就能跑。实际上 vLLM 的底层非常依赖 CUDA 生态里那一套 Linux 原生的东西NCCL 多卡通信、共享内存、PageAttention 的显存管理还有 FlashAttention 那一类高性能算子。这些组件在 Windows 上要么没有官方 wheel要么行为差异很大。即便你强行编译或者用社区补丁一旦跑多并发请求崩溃率和奇怪行为会把调试成本拉到完全不可接受的程度。我这里不推荐用“民间 Windows 版 vLLM”还有一个原因vLLM 迭代太快社区补丁往往停留在某个旧版本。你为了跑一个最新模型可能需要同时适配新版内核和新版量化格式旧补丁根本跟不上。与其在 Windows 原生环境里反复挣扎不如直接承认“vLLM 是为 Linux 设计的”然后让 Windows 在底层套一层真正的 Linux 环境。1.2 两条可行路线WSL2 Docker 与裸 WSL2 环境我在实战中验证过两条路线分别适合不同的人路线AWSL2 Docker Desktop。这是最接近“官方推荐姿势”的方案。vLLM 官方持续发布vllm/vllm-openai镜像里面 CUDA、NCCL、依赖版本全给你锁好了。你只需要把模型目录挂载进去一条docker run就能起服务。好处是环境隔离清垃圾方便和 Linux 服务器上的部署方式完全一致。路线B直接在 WSL2 的 Ubuntu 里创建 Python 虚拟环境手动pip install vllm。这个方案灵活适合你要改 vLLM 源码、调试底层内核的场景。但代价是你得自己处理 CUDA torch 版本匹配、FlashAttention 编译、NCCL 依赖等一堆问题。如果只是想把模型跑起来提供 API路线B 的时间成本明显更高。两条路线的对比如下对比项WSL2 Docker裸 WSL2 环境首次启动难度低一条命令中高依赖较多环境和宿主机隔离好一般GPU 透传通过 WSL2 直接透传通过 WSL2 直接透传后续环境清理删容器即可需要自己管 venv 和包与生产环境一致性高较高自定义 vLLM 源码较麻烦方便我最后选择的是路线A。本文后续也以 WSL2 Docker Desktop 为主线。它不是我拍脑袋选的而是实际对比后确认Docker 镜像把“版本地狱”挡在外面Windows 上最容易出问题的 CUDA 依赖链全部由官方镜像保管我只要保证驱动和 WSL2 正确就能稳定复现。2. 硬件、驱动与 WSL2把底层环境一次配好这一节不做后面前功尽弃。很多人在 Windows 上跑 vLLM 失败根本不是模型或命令问题而是 WSL2 没把显卡透传进去驱动版本太老或者虚拟磁盘放在了系统盘导致空间不足。2.1 显卡门槛显存第一算力第二Qwen3-8B-FP8 的权重文件大约 8.5GB。注意这只是权重本身占用的显存KV cache、CUDA context、中间激活值都会额外吃显存。我实测下来至少 16GB 显存才能比较舒服地跑 32K 上下文如果你只有 12GB就要把上下文压到 8K 或者 16K并调低并发。显存和显卡的参考组合如下显卡显存能否跑 Qwen3-8B-FP8建议RTX 3060 12G12GB勉强能跑上下文限制在 8K 内RTX 4070/408016GB可以32K 上下文低并发RTX 409024GB非常舒服128K 上下文也有余量RTX 5090 / A600032GB宽裕推荐还要考虑 FP8 算子支持问题。NVIDIA Ada 架构也就是 RTX 40 系列原生支持 FP8 运算跑官方 FP8 权重效率最高。RTX 30 系列基于 Ampere 架构虽然能加载 FP8 权重但底层算子可能需要反量化到更高精度再计算吞吐会有损失。如果你只有 30 系显卡也别急着放弃跑还是能跑只是别期待 40 系那种速度。2.2 驱动安装Windows 一个驱动WSL2 里直接复用这里有个让很多人困惑的点WSL2 里的 Linux 需不需要单独装 NVIDIA 驱动答案是“不需要”。Windows 上的 NVIDIA 驱动本身已经包含了一部分 WSL2 GPU 透传能力你在 Windows 侧装好驱动WSL2 内部通过/dev/dxg设备直接访问 GPU。我安装驱动的顺序是这样的在 Windows 上卸载旧驱动去 NVIDIA 官网下载最新的 Game Ready 或 Studio 驱动。Studio 驱动在某些场景下更稳。安装完重启确保nvidia-smi在 Windows 的 cmd 或 PowerShell 里能正常输出。打开 WSL2 终端执行nvidia-smi。如果能看到和 Windows 一致的显卡型号和驱动版本说明透传没问题如果提示找不到命令先装nvidia-utils或者确认 WSL2 是否已更新到新版本。驱动版本太老会出现一个很典型的错误启动 vLLM 时显示CUDA error: no kernel image is available或者the provided PTX was not compiled。这类问题通常不是代码错误而是驱动太旧适配不了新版 CUDA runtime。遇到这种报错先去把 Windows 驱动升级到最新再重新跑 Docker 容器。2.3 WSL2 安装和把虚拟磁盘搬到非系统盘WSL2 的默认安装位置在 C 盘而 Qwen3 系列模型动辄 8GB 以上加上后续可能还有其他模型C 盘很容易被塞满。我建议一开始就把 WSL2 迁到其他盘。先安装 Ubuntu 发行版wsl --install -d Ubuntu-22.04装完后重启一次。接着把系统导出再导入到 D 盘wsl --export Ubuntu-22.04 D:\wsl-ubuntu.tar wsl --unregister Ubuntu-22.04 wsl --import Ubuntu-22.04 D:\WSL\Ubuntu22.04 D:\wsl-ubuntu.tar --version 2注意一点通过wsl --import导入的发行版默认用户是 root。这会影响文件权限尤其是挂载 Docker 卷的时候可能出现Permission denied。解决方法是进入 WSL 后手动修改默认用户。另外强烈建议在 Windows 用户目录下写一个.wslconfig文件内容类似这样[wsl2] memory20GB processors8 swap16GB localhostForwardingtrue这里的 memory 是 WSL2 能使用的最大内存。如果主机一共 32GB 内存我给 WSL2 分 20GB 是比较合适的既能让 vLLM 加载模型时缓一口气又不会把 Windows 桌面环境挤到卡死。swap 给 16GB 是为了防止加载权重时内存短暂冲高导致进程被杀。localhostForwarding 保持 true后面用http://localhost:8000访问服务就靠它。我还想强调一个经验模型下载缓存和 Hugging Face 的临时目录一定不要放在/mnt/c这种跨系统挂载路径上。WSL2 访问 Windows 文件系统是通过 9P 协议速度慢而且对文件锁、软链接的支持不够好。把所有模型文件、HF 缓存放在 WSL2 原生文件系统里比如/home/yourname/models跑起来会顺畅很多。3. 模型权重准备Qwen3-8B-FP8 从哪下载、怎么放到容器里模型准备这步看似简单但很多人恰恰在这里翻车。下载下来的目录结构不对、放的路径不对、或者把模型放在 Windows 文件系统再挂载导致 Docker 读不了都会让后面的启动白折腾。3.1 Qwen3-8B-FP8 和普通 BF16 版本的区别Qwen3-8B 本身有 BF16 版本显存占用约 16GB 左右。FP8 版本相当于把权重压缩成 8 位浮点显存需求直接减半模型的config.json里会包含量化配置并在权重文件名或张量结构上体现 FP8 格式。FP8 的优势不只是省显存推理吞吐通常也会提升因为更少的数据需要从显存搬运到计算单元。代价是精度有极小损失但对对话、代码生成这类任务实际输出质量几乎感知不到差异。vLLM 对 FP8 权重的支持已经很成熟你不需要自己先把模型量化直接用官方给出的 FP8 checkpoint 就行。这里有个容易忽略的点不要拿着一个 BF16 的pytorch_model.bin然后在启动参数里强行加--quantization fp8。vLLM 的 fp8 量化标志针对的是已经做好的 FP8 权重或者需要配合特定量化工具链使用。对一个普通 BF16 权重做错误转换轻则启动变慢重则直接报“weight shape mismatch”或者乱码输出。3.2 下载权重的两种可靠方式我推荐直接用命令行下载不会出现浏览器断点续传的问题。先创建模型目录mkdir -p ~/models/Qwen3-8B-FP8如果网络环境允许直接访问 Hugging Face用huggingface-cli下载pip install -U huggingface-cli[cli] HF_ENDPOINThttps://hf-mirror.com huggingface-cli download Qwen/Qwen3-8B-FP8 --local-dir ~/models/Qwen3-8B-FP8第二个方案是使用 ModelScope国内访问体验更好很多情况下速度更快pip install -U modelscope modelscope download --model Qwen/Qwen3-8B-FP8 --local_dir ~/models/Qwen3-8B-FP8两种方式下载完模型目录里应该包含config.json、generation_config.json、tokenizer.json、tokenizer_config.json以及若干.safetensors分片文件。检查一下config.json里的quantization_config字段能看到quant_method: fp8之类的信息这代表权重确实是 FP8 格式。3.3 目录挂载的路径映射和权限问题Docker 容器内部是 Linux 文件系统Windows 的 D 盘在 WSL2 里被挂载为/mnt/d。所以如果你的模型放在D:\models\Qwen3-8B-FP8在 Docker 命令里挂载时就要写-v /mnt/d/models/Qwen3-8B-FP8:/models/Qwen3-8B-FP8容器的/models/Qwen3-8B-FP8就对应 Windows 上的D:\models\Qwen3-8B-FP8。但我个人更推荐把模型放在 WSL2 自己的文件系统里比如~/models/Qwen3-8B-FP8然后挂载-v ~/models/Qwen3-8B-FP8:/models/Qwen3-8B-FP8原因前面提过WSL2 访问 Windows 盘性能差而且权限处理容易出幺蛾子。如果项目文件在 Windows 盘但运行环境只需要读权重那我可以接受如果既要读又要写比如未来要做 LoRA 微调那还是乖乖放到 Linux 目录里。权限问题也值得多说一句。Docker 容器内进程通常以非 root 用户运行如果模型文件权限是rw-------且属主是 root容器读取时就会报Permission denied。在 WSL2 里执行一次chmod -R arX ~/models/Qwen3-8B-FP8确保模型文件对所有人可读目录可进入。这个操作很小但能省掉无数莫名其妙的启动失败。4. 启动 vLLM 服务命令拆解和第一行日志怎么看环境准备好、模型下载好之后就进入最关键的启动环节。我会把一条完整的docker run命令拆开讲清楚因为很多人只会复制粘贴一旦报错就不知道从哪改。4.1 最小可用的 docker run 命令直接看命令docker run --gpus all -p 8000:8000 --shm-size 16g \ -v ~/models/Qwen3-8B-FP8:/models/Qwen3-8B-FP8 \ vllm/vllm-openai:latest \ --model /models/Qwen3-8B-FP8 \ --served-model-name Qwen3-8B-FP8 \ --quantization fp8 \ --max-model-len 32768 \ --gpu-memory-utilization 0.88 \ --trust-remote-code \ --host 0.0.0.0逐段解释--gpus all让 Docker 使用宿主机所有 GPU。在 WSL2 后端下这句会自动把所有可见的 NVIDIA GPU 传给容器。-p 8000:8000把容器内的 8000 端口映射到 Windows。这样你在 Windows 浏览器里访问http://localhost:8000就能到达 vLLM。--shm-size 16g设置容器共享内存。vLLM 的多进程数据加载会用到共享内存默认 64MB 在这个场景下经常不够。-v ~/models/Qwen3-8B-FP8:/models/Qwen3-8B-FP8把模型目录挂进容器。vllm/vllm-openai:latest官方镜像里面已经包含启动入口。latest标签可能不太确定但胜在保持最新适合学习环境。真要生产长期跑建议固定到某个明确的版本号。--model /models/Qwen3-8B-FP8告诉 vLLM 从容器内哪个路径加载模型。--served-model-name Qwen3-8B-FP8对外提供服务的模型名。这个很重要因为后续 API 请求里model字段必须填它否则会报模型不存在。--quantization fp8显式声明权重是 FP8 格式让 vLLM 走对应的量化加载路径。--max-model-len 32768最大序列长度。Qwen3-8B 支持长上下文但和显存直接挂钩先设 32K 是稳妥起步值。--gpu-memory-utilization 0.88允许 vLLM 使用 88% 的显存。剩下 12% 留给 CUDA context 和 Windows 图形环境本身。--trust-remote-code某些 tokenizer 或 config 里的自定义 Python 代码需要这个参数才能加载。--host 0.0.0.0监听所有网络接口保证 WSL2 端口转发能正常工作。我建议第一次启动时不要加太多高级参数先把最小命令跑通再根据自己的显卡和并发需求去优化。4.2 为什么这些参数要这么设--gpu-memory-utilization不是越高越好。我之前贪心设到 0.98结果 Windows 桌面一开窗口显存不足导致 vLLM 直接 OOM。保留 10% 到 15% 的空余尤其 Windows 还要同时跑图形界面非常有必要。--max-model-len是很多人忽略的关键参数。Qwen3-8B 官方支持 128K 上下文但如果你直接设 128KKV cache 占用的显存会非常惊人。在 24GB 显存的显卡上也可能直接启动失败。我给出的 32768 是一个在“可用性”和“长文本能力”之间比较平衡的初始值。等后面确认吞吐和显存占用没问题了再根据实际需求往上调。--served-model-name在某些教程里被忽略了但它和后面的 API 调用强相关。很多人在测试时明明服务起来了却报“model not found”就是因为客户端传的模型名和这里不一致。设置一个固定名称能省掉后续所有客户端配置的麻烦。4.3 看到这些日志说明服务正在正常启动vLLM 启动时需要加载模型权重、CUDA 内核、初始化 KV cache整个过程根据磁盘速度和显卡性能通常需要 1 到 3 分钟。日志里出现这一行是正常的[pynccl.py:113] vllm is using nccl2.30.7很多单卡用户在论坛里看到 nccl 字样就以为要配多卡其实不是。这是 vLLM 内部初始化进程通信组件的正常输出单卡也会走这段逻辑不用管。接着会出现类似这样的内容INFO: Started server process INFO: Waiting for application startup. INFO: Application startup complete. INFO: Uvicorn running on http://0.0.0.0:8000看到Application startup complete就说明服务已经起来了。这时不要急着关终端保持窗口在那。然后另开一个 PowerShell 窗口执行curl http://localhost:8000/v1/models如果输出一段包含模型 ID 的 JSON说明 Windows 到 WSL2 的端口转发也正常服务已经可以被外部调用了。5. 请求验证、显存观察与并发参数调优服务启动成功只是开始。接下来要确认它真的能生成内容并且要了解自己的显卡资源到底用到了什么程度否则并发一上来还是会崩。5.1 用 curl 跑一次完整的 chat completions在 PowerShell 或 WSL2 里执行curl http://localhost:8000/v1/chat/completions \ -H Content-Type: application/json \ -d { model: Qwen3-8B-FP8, messages: [ {role: user, content: 用一句话介绍 Qwen3} ], max_tokens: 256 }如果返回 JSON 里有choices[0].message.content字段并且内容是一句通顺的中文说明整个链路是通的。用 Python 调用也很简单OpenAI SDK 直连from openai import OpenAI client OpenAI( base_urlhttp://localhost:8000/v1, api_keynot-needed ) resp client.chat.completions.create( modelQwen3-8B-FP8, messages[{role: user, content: 写一段 80 字的欢迎词}], max_tokens256 ) print(resp.choices[0].message.content)这里api_key随便填一个占位符就行因为 vLLM 默认不校验密钥。如果后面要放到局域网或者公网给其他人用一定要加上--api-key参数开启鉴权不能裸奔。另外注意 Qwen3 系列默认有可能启动思考模式返回内容里除了content还会带一段reasoning_content。如果你的业务只需要直接答案可以在请求体里把enable_thinking设为false。不同版本 vLLM 对这个参数的支持略有差别如果传了报参数错误就先去查当前版本的接口说明。5.2 怎么在 Windows 下监控显存和吞吐服务运行期间在 WSL2 终端执行watch -n 1 nvidia-smi这个命令每秒刷新一次显存占用、温度、功耗和 GPU 利用率。你发一个并发请求过去就能看到 GPU-Util 从 0% 跳到 70% 甚至 100%同时显存 Usage 保持在某个高位。这能帮你确认 vLLM 是否真的在用 GPU 计算而不是莫名其妙地退回了 CPU。想看 vLLM 本身的性能指标可以直接访问http://localhost:8000/metrics这是 Prometheus 格式的指标端点。重点看vllm:generation_tokens_total、vllm:e2e_request_latency_seconds这类指标。你连续发几个请求再刷新 metrics能看到每秒钟生成的 token 数变化。对于一个 8B 量化模型在 RTX 4090 上单请求通常能达到每秒 50 到 100 token 的生成速度具体取决于输出长度和max-model-len的设置。如果发现吞吐特别低先看nvidia-smi里的 GPU Utilization。如果显存占满但 GPU-Util 很低说明不是计算瓶颈而是请求队列没满、单条请求太小或者 batch 太小。这时候可以试着提高并发请求数让 vLLM 使用 continuous batching 把多请求拼在一起处理。5.3 并发参数怎么调vLLM 默认的调度器已经比较保守。想要提升吞吐可以在启动命令里追加几个参数--max-num-seqs 32 --max-num-batched-tokens 8192--max-num-seqs控制同时最多处理多少个序列。设 32 表示最多同时拼 32 个请求进一个 batch。如果你的显存只有 16GB设 16 或 24 更稳妥。--max-num-batched-tokens控制一次 batch 内最多包含多少 token值越大单次前向计算的规模越大吞吐通常越高但也更吃显存。我的调优步骤是先用最小命令启动确认单请求正常。并发请求从 1 加到 8观察吞吐是否线性增长。如果吞吐不再增长或者显存快满就降低--max-model-len而不是继续加大并发。处理长文本时把--max-model-len调大但并发降下来。记住一个原则显存总是有限的长上下文和高峰期之间要做取舍。优先保障业务场景的核心需求不要在单卡上指望兼顾所有指标。6. 踩坑记录端口冲突、OOM 这一串问题的排查思路这里把我实际踩过、以及在多个交流群里帮人看过的典型问题集中列一下。每条我都给出排查链路而不是直接甩一个“改配置”的结论。6.1 nvidia-smi 在 WSL2 里看不到 GPU症状Windows 里nvidia-smi正常但 WSL2 里执行nvidia-smi报错或者只能看到 CPU。排查顺序确认 WSL 版本是 2wsl -l -v。如果是 WSL1wsl --set-version distro 2升级。检查驱动。打开 Windows 的“设置 - 应用 - 可选功能”或 NVIDIA 控制面板确认驱动版本在 535 或更高。执行wsl --update把 WSL 内核更新到最新。如果还不显示试试在 PowerShell 里执行wsl --shutdown然后重新进入 WSL。WSL2 的 GPU 透传依赖/dev/dxg设备这个设备由 Windows 驱动提供。驱动一旦识别不了容器内无论如何都不可能用 GPU。所以这一条一定要排在最前面解决。6.2 容器启动后一直打印 nccl 初始化或 shared memory 相关问题我在第一版的命令里没有加--shm-size结果多轮调用后 vLLM 突然挂掉日志里出现类似Bus error的报错。很多人遇到这个问题会误以为是显存不足其实是共享内存被撑爆了。排查方法很简单在容器启动命令里加--shm-size 16g然后重新启动。如果你用的是 compose 文件同样在shm_size字段里设置。加了之后这个问题基本不会再出现。6.3 端口 8000 被占用症状启动时报[Errno 98] Address already in use或者访问localhost:8000发现跳到了另一个服务。在 PowerShell 里执行netstat -ano | findstr :8000找到占用 8000 端口的 PID然后taskkill /PID 1234 /F如果觉得这个端口被频繁占用也可以直接把映射改成-p 8001:8000然后用http://localhost:8001访问。没必要在这上面硬刚。6.4 WSL2 内存突然吃满、系统卡死vLLM 启动阶段需要把权重读入内存并做可能的格式转换瞬时内存占用可能达到权重体积的两到三倍。Qwen3-8B-FP8 权重约 8.5GB启动瞬间内存冲到 20GB 左右是正常的。如果你.wslconfig里给 WSL2 的内存太少系统会因为 OOM 直接把 vLLM 进程杀掉。日志里不一定出现 Python traceback可能只有一句Killed。排查方法dmesg | tail -50如果里面有Out of memory: Killed process字样就是内存不够。解决办法是给.wslconfig加内存和 swap以及把--max-model-len调低减少 KV cache 的内存开销。6.5 加载 FP8 权重时提示格式不匹配或不同 quantization症状模型目录里有 safetensors但 vLLM 报weight_shape not match或直接说无法识别量化方式。这通常是因为模型仓库下错了或者把 BF16 仓库当成 FP8 仓库。去模型目录检查config.json看quantization_config是否包含quant_method: fp8。如果没有说明权重本身不是 FP8不要再加--quantization fp8启动要么下载正确的 FP8 仓库要么移除量化参数跑 BF16 版本。6.6 从局域网访问不到服务http://localhost:8000能从本机访问但局域网其他机器访问超时。这是 Windows 防火墙或者端口转发的问题。最直接的办法是给docker run加上--host 0.0.0.0确保 vLLM 在容器里监听所有网卡。然后检查 Windows 防火墙看 8000 端口是否被拦截。如果用的是 WSL2很多时候只要确认.wslconfig里localhostForwardingtrue本机访问就通了。如果要局域网访问最好把服务映射到 Windows 宿主 IP 上并手动添加防火墙入站规则。我自己在使用过程中最大的体会是Windows 上部署 vLLM真正的问题从来不是 vLLM 本身而是 WSL2、驱动、端口转发这些外围环境。只要把外围问题理清楚后半段就和在 Linux 服务器上完全一样了。如果你想长期在本地跑模型建议把启动命令保存成一个start-vllm.bat里面写好参数每次直接双击运行。模型可以多下几个版本权重放在独立目录通过修改挂载路径来切换就不用反复拉镜像了。
Windows 跑 vLLM 部署 Qwen3-8B-FP8：WSL2 + Docker 完整实战
1. 先弄懂为什么 Windows 上跑 vLLM 不能选“原生安装”把 vLLM 和 Qwen3-8B-FP8 搬到 Windows 上这件事我前后折腾了两周。先说结论vLLM 官方明确只支持 LinuxWindows 上要么靠 WSL2要么靠 Docker Desktop想直接pip install vllm然后在 cmd 里跑通基本会卡在各种底层依赖上。这篇文章把我验证过的一套完整流程整理出来从驱动检查、WSL2 环境、模型权重下载到 vLLM 的 Docker 启动命令和请求测试适合手里有一块 NVIDIA 显卡、想在本机跑一个 OpenAI 兼容接口出来玩或做本地实验的读者。1.1 vLLM 不是“装不上”而是官方根本没做 Windows 适配很多人第一次接触 vLLM 会误以为它和 PyTorch 一样pip 装完就能跑。实际上 vLLM 的底层非常依赖 CUDA 生态里那一套 Linux 原生的东西NCCL 多卡通信、共享内存、PageAttention 的显存管理还有 FlashAttention 那一类高性能算子。这些组件在 Windows 上要么没有官方 wheel要么行为差异很大。即便你强行编译或者用社区补丁一旦跑多并发请求崩溃率和奇怪行为会把调试成本拉到完全不可接受的程度。我这里不推荐用“民间 Windows 版 vLLM”还有一个原因vLLM 迭代太快社区补丁往往停留在某个旧版本。你为了跑一个最新模型可能需要同时适配新版内核和新版量化格式旧补丁根本跟不上。与其在 Windows 原生环境里反复挣扎不如直接承认“vLLM 是为 Linux 设计的”然后让 Windows 在底层套一层真正的 Linux 环境。1.2 两条可行路线WSL2 Docker 与裸 WSL2 环境我在实战中验证过两条路线分别适合不同的人路线AWSL2 Docker Desktop。这是最接近“官方推荐姿势”的方案。vLLM 官方持续发布vllm/vllm-openai镜像里面 CUDA、NCCL、依赖版本全给你锁好了。你只需要把模型目录挂载进去一条docker run就能起服务。好处是环境隔离清垃圾方便和 Linux 服务器上的部署方式完全一致。路线B直接在 WSL2 的 Ubuntu 里创建 Python 虚拟环境手动pip install vllm。这个方案灵活适合你要改 vLLM 源码、调试底层内核的场景。但代价是你得自己处理 CUDA torch 版本匹配、FlashAttention 编译、NCCL 依赖等一堆问题。如果只是想把模型跑起来提供 API路线B 的时间成本明显更高。两条路线的对比如下对比项WSL2 Docker裸 WSL2 环境首次启动难度低一条命令中高依赖较多环境和宿主机隔离好一般GPU 透传通过 WSL2 直接透传通过 WSL2 直接透传后续环境清理删容器即可需要自己管 venv 和包与生产环境一致性高较高自定义 vLLM 源码较麻烦方便我最后选择的是路线A。本文后续也以 WSL2 Docker Desktop 为主线。它不是我拍脑袋选的而是实际对比后确认Docker 镜像把“版本地狱”挡在外面Windows 上最容易出问题的 CUDA 依赖链全部由官方镜像保管我只要保证驱动和 WSL2 正确就能稳定复现。2. 硬件、驱动与 WSL2把底层环境一次配好这一节不做后面前功尽弃。很多人在 Windows 上跑 vLLM 失败根本不是模型或命令问题而是 WSL2 没把显卡透传进去驱动版本太老或者虚拟磁盘放在了系统盘导致空间不足。2.1 显卡门槛显存第一算力第二Qwen3-8B-FP8 的权重文件大约 8.5GB。注意这只是权重本身占用的显存KV cache、CUDA context、中间激活值都会额外吃显存。我实测下来至少 16GB 显存才能比较舒服地跑 32K 上下文如果你只有 12GB就要把上下文压到 8K 或者 16K并调低并发。显存和显卡的参考组合如下显卡显存能否跑 Qwen3-8B-FP8建议RTX 3060 12G12GB勉强能跑上下文限制在 8K 内RTX 4070/408016GB可以32K 上下文低并发RTX 409024GB非常舒服128K 上下文也有余量RTX 5090 / A600032GB宽裕推荐还要考虑 FP8 算子支持问题。NVIDIA Ada 架构也就是 RTX 40 系列原生支持 FP8 运算跑官方 FP8 权重效率最高。RTX 30 系列基于 Ampere 架构虽然能加载 FP8 权重但底层算子可能需要反量化到更高精度再计算吞吐会有损失。如果你只有 30 系显卡也别急着放弃跑还是能跑只是别期待 40 系那种速度。2.2 驱动安装Windows 一个驱动WSL2 里直接复用这里有个让很多人困惑的点WSL2 里的 Linux 需不需要单独装 NVIDIA 驱动答案是“不需要”。Windows 上的 NVIDIA 驱动本身已经包含了一部分 WSL2 GPU 透传能力你在 Windows 侧装好驱动WSL2 内部通过/dev/dxg设备直接访问 GPU。我安装驱动的顺序是这样的在 Windows 上卸载旧驱动去 NVIDIA 官网下载最新的 Game Ready 或 Studio 驱动。Studio 驱动在某些场景下更稳。安装完重启确保nvidia-smi在 Windows 的 cmd 或 PowerShell 里能正常输出。打开 WSL2 终端执行nvidia-smi。如果能看到和 Windows 一致的显卡型号和驱动版本说明透传没问题如果提示找不到命令先装nvidia-utils或者确认 WSL2 是否已更新到新版本。驱动版本太老会出现一个很典型的错误启动 vLLM 时显示CUDA error: no kernel image is available或者the provided PTX was not compiled。这类问题通常不是代码错误而是驱动太旧适配不了新版 CUDA runtime。遇到这种报错先去把 Windows 驱动升级到最新再重新跑 Docker 容器。2.3 WSL2 安装和把虚拟磁盘搬到非系统盘WSL2 的默认安装位置在 C 盘而 Qwen3 系列模型动辄 8GB 以上加上后续可能还有其他模型C 盘很容易被塞满。我建议一开始就把 WSL2 迁到其他盘。先安装 Ubuntu 发行版wsl --install -d Ubuntu-22.04装完后重启一次。接着把系统导出再导入到 D 盘wsl --export Ubuntu-22.04 D:\wsl-ubuntu.tar wsl --unregister Ubuntu-22.04 wsl --import Ubuntu-22.04 D:\WSL\Ubuntu22.04 D:\wsl-ubuntu.tar --version 2注意一点通过wsl --import导入的发行版默认用户是 root。这会影响文件权限尤其是挂载 Docker 卷的时候可能出现Permission denied。解决方法是进入 WSL 后手动修改默认用户。另外强烈建议在 Windows 用户目录下写一个.wslconfig文件内容类似这样[wsl2] memory20GB processors8 swap16GB localhostForwardingtrue这里的 memory 是 WSL2 能使用的最大内存。如果主机一共 32GB 内存我给 WSL2 分 20GB 是比较合适的既能让 vLLM 加载模型时缓一口气又不会把 Windows 桌面环境挤到卡死。swap 给 16GB 是为了防止加载权重时内存短暂冲高导致进程被杀。localhostForwarding 保持 true后面用http://localhost:8000访问服务就靠它。我还想强调一个经验模型下载缓存和 Hugging Face 的临时目录一定不要放在/mnt/c这种跨系统挂载路径上。WSL2 访问 Windows 文件系统是通过 9P 协议速度慢而且对文件锁、软链接的支持不够好。把所有模型文件、HF 缓存放在 WSL2 原生文件系统里比如/home/yourname/models跑起来会顺畅很多。3. 模型权重准备Qwen3-8B-FP8 从哪下载、怎么放到容器里模型准备这步看似简单但很多人恰恰在这里翻车。下载下来的目录结构不对、放的路径不对、或者把模型放在 Windows 文件系统再挂载导致 Docker 读不了都会让后面的启动白折腾。3.1 Qwen3-8B-FP8 和普通 BF16 版本的区别Qwen3-8B 本身有 BF16 版本显存占用约 16GB 左右。FP8 版本相当于把权重压缩成 8 位浮点显存需求直接减半模型的config.json里会包含量化配置并在权重文件名或张量结构上体现 FP8 格式。FP8 的优势不只是省显存推理吞吐通常也会提升因为更少的数据需要从显存搬运到计算单元。代价是精度有极小损失但对对话、代码生成这类任务实际输出质量几乎感知不到差异。vLLM 对 FP8 权重的支持已经很成熟你不需要自己先把模型量化直接用官方给出的 FP8 checkpoint 就行。这里有个容易忽略的点不要拿着一个 BF16 的pytorch_model.bin然后在启动参数里强行加--quantization fp8。vLLM 的 fp8 量化标志针对的是已经做好的 FP8 权重或者需要配合特定量化工具链使用。对一个普通 BF16 权重做错误转换轻则启动变慢重则直接报“weight shape mismatch”或者乱码输出。3.2 下载权重的两种可靠方式我推荐直接用命令行下载不会出现浏览器断点续传的问题。先创建模型目录mkdir -p ~/models/Qwen3-8B-FP8如果网络环境允许直接访问 Hugging Face用huggingface-cli下载pip install -U huggingface-cli[cli] HF_ENDPOINThttps://hf-mirror.com huggingface-cli download Qwen/Qwen3-8B-FP8 --local-dir ~/models/Qwen3-8B-FP8第二个方案是使用 ModelScope国内访问体验更好很多情况下速度更快pip install -U modelscope modelscope download --model Qwen/Qwen3-8B-FP8 --local_dir ~/models/Qwen3-8B-FP8两种方式下载完模型目录里应该包含config.json、generation_config.json、tokenizer.json、tokenizer_config.json以及若干.safetensors分片文件。检查一下config.json里的quantization_config字段能看到quant_method: fp8之类的信息这代表权重确实是 FP8 格式。3.3 目录挂载的路径映射和权限问题Docker 容器内部是 Linux 文件系统Windows 的 D 盘在 WSL2 里被挂载为/mnt/d。所以如果你的模型放在D:\models\Qwen3-8B-FP8在 Docker 命令里挂载时就要写-v /mnt/d/models/Qwen3-8B-FP8:/models/Qwen3-8B-FP8容器的/models/Qwen3-8B-FP8就对应 Windows 上的D:\models\Qwen3-8B-FP8。但我个人更推荐把模型放在 WSL2 自己的文件系统里比如~/models/Qwen3-8B-FP8然后挂载-v ~/models/Qwen3-8B-FP8:/models/Qwen3-8B-FP8原因前面提过WSL2 访问 Windows 盘性能差而且权限处理容易出幺蛾子。如果项目文件在 Windows 盘但运行环境只需要读权重那我可以接受如果既要读又要写比如未来要做 LoRA 微调那还是乖乖放到 Linux 目录里。权限问题也值得多说一句。Docker 容器内进程通常以非 root 用户运行如果模型文件权限是rw-------且属主是 root容器读取时就会报Permission denied。在 WSL2 里执行一次chmod -R arX ~/models/Qwen3-8B-FP8确保模型文件对所有人可读目录可进入。这个操作很小但能省掉无数莫名其妙的启动失败。4. 启动 vLLM 服务命令拆解和第一行日志怎么看环境准备好、模型下载好之后就进入最关键的启动环节。我会把一条完整的docker run命令拆开讲清楚因为很多人只会复制粘贴一旦报错就不知道从哪改。4.1 最小可用的 docker run 命令直接看命令docker run --gpus all -p 8000:8000 --shm-size 16g \ -v ~/models/Qwen3-8B-FP8:/models/Qwen3-8B-FP8 \ vllm/vllm-openai:latest \ --model /models/Qwen3-8B-FP8 \ --served-model-name Qwen3-8B-FP8 \ --quantization fp8 \ --max-model-len 32768 \ --gpu-memory-utilization 0.88 \ --trust-remote-code \ --host 0.0.0.0逐段解释--gpus all让 Docker 使用宿主机所有 GPU。在 WSL2 后端下这句会自动把所有可见的 NVIDIA GPU 传给容器。-p 8000:8000把容器内的 8000 端口映射到 Windows。这样你在 Windows 浏览器里访问http://localhost:8000就能到达 vLLM。--shm-size 16g设置容器共享内存。vLLM 的多进程数据加载会用到共享内存默认 64MB 在这个场景下经常不够。-v ~/models/Qwen3-8B-FP8:/models/Qwen3-8B-FP8把模型目录挂进容器。vllm/vllm-openai:latest官方镜像里面已经包含启动入口。latest标签可能不太确定但胜在保持最新适合学习环境。真要生产长期跑建议固定到某个明确的版本号。--model /models/Qwen3-8B-FP8告诉 vLLM 从容器内哪个路径加载模型。--served-model-name Qwen3-8B-FP8对外提供服务的模型名。这个很重要因为后续 API 请求里model字段必须填它否则会报模型不存在。--quantization fp8显式声明权重是 FP8 格式让 vLLM 走对应的量化加载路径。--max-model-len 32768最大序列长度。Qwen3-8B 支持长上下文但和显存直接挂钩先设 32K 是稳妥起步值。--gpu-memory-utilization 0.88允许 vLLM 使用 88% 的显存。剩下 12% 留给 CUDA context 和 Windows 图形环境本身。--trust-remote-code某些 tokenizer 或 config 里的自定义 Python 代码需要这个参数才能加载。--host 0.0.0.0监听所有网络接口保证 WSL2 端口转发能正常工作。我建议第一次启动时不要加太多高级参数先把最小命令跑通再根据自己的显卡和并发需求去优化。4.2 为什么这些参数要这么设--gpu-memory-utilization不是越高越好。我之前贪心设到 0.98结果 Windows 桌面一开窗口显存不足导致 vLLM 直接 OOM。保留 10% 到 15% 的空余尤其 Windows 还要同时跑图形界面非常有必要。--max-model-len是很多人忽略的关键参数。Qwen3-8B 官方支持 128K 上下文但如果你直接设 128KKV cache 占用的显存会非常惊人。在 24GB 显存的显卡上也可能直接启动失败。我给出的 32768 是一个在“可用性”和“长文本能力”之间比较平衡的初始值。等后面确认吞吐和显存占用没问题了再根据实际需求往上调。--served-model-name在某些教程里被忽略了但它和后面的 API 调用强相关。很多人在测试时明明服务起来了却报“model not found”就是因为客户端传的模型名和这里不一致。设置一个固定名称能省掉后续所有客户端配置的麻烦。4.3 看到这些日志说明服务正在正常启动vLLM 启动时需要加载模型权重、CUDA 内核、初始化 KV cache整个过程根据磁盘速度和显卡性能通常需要 1 到 3 分钟。日志里出现这一行是正常的[pynccl.py:113] vllm is using nccl2.30.7很多单卡用户在论坛里看到 nccl 字样就以为要配多卡其实不是。这是 vLLM 内部初始化进程通信组件的正常输出单卡也会走这段逻辑不用管。接着会出现类似这样的内容INFO: Started server process INFO: Waiting for application startup. INFO: Application startup complete. INFO: Uvicorn running on http://0.0.0.0:8000看到Application startup complete就说明服务已经起来了。这时不要急着关终端保持窗口在那。然后另开一个 PowerShell 窗口执行curl http://localhost:8000/v1/models如果输出一段包含模型 ID 的 JSON说明 Windows 到 WSL2 的端口转发也正常服务已经可以被外部调用了。5. 请求验证、显存观察与并发参数调优服务启动成功只是开始。接下来要确认它真的能生成内容并且要了解自己的显卡资源到底用到了什么程度否则并发一上来还是会崩。5.1 用 curl 跑一次完整的 chat completions在 PowerShell 或 WSL2 里执行curl http://localhost:8000/v1/chat/completions \ -H Content-Type: application/json \ -d { model: Qwen3-8B-FP8, messages: [ {role: user, content: 用一句话介绍 Qwen3} ], max_tokens: 256 }如果返回 JSON 里有choices[0].message.content字段并且内容是一句通顺的中文说明整个链路是通的。用 Python 调用也很简单OpenAI SDK 直连from openai import OpenAI client OpenAI( base_urlhttp://localhost:8000/v1, api_keynot-needed ) resp client.chat.completions.create( modelQwen3-8B-FP8, messages[{role: user, content: 写一段 80 字的欢迎词}], max_tokens256 ) print(resp.choices[0].message.content)这里api_key随便填一个占位符就行因为 vLLM 默认不校验密钥。如果后面要放到局域网或者公网给其他人用一定要加上--api-key参数开启鉴权不能裸奔。另外注意 Qwen3 系列默认有可能启动思考模式返回内容里除了content还会带一段reasoning_content。如果你的业务只需要直接答案可以在请求体里把enable_thinking设为false。不同版本 vLLM 对这个参数的支持略有差别如果传了报参数错误就先去查当前版本的接口说明。5.2 怎么在 Windows 下监控显存和吞吐服务运行期间在 WSL2 终端执行watch -n 1 nvidia-smi这个命令每秒刷新一次显存占用、温度、功耗和 GPU 利用率。你发一个并发请求过去就能看到 GPU-Util 从 0% 跳到 70% 甚至 100%同时显存 Usage 保持在某个高位。这能帮你确认 vLLM 是否真的在用 GPU 计算而不是莫名其妙地退回了 CPU。想看 vLLM 本身的性能指标可以直接访问http://localhost:8000/metrics这是 Prometheus 格式的指标端点。重点看vllm:generation_tokens_total、vllm:e2e_request_latency_seconds这类指标。你连续发几个请求再刷新 metrics能看到每秒钟生成的 token 数变化。对于一个 8B 量化模型在 RTX 4090 上单请求通常能达到每秒 50 到 100 token 的生成速度具体取决于输出长度和max-model-len的设置。如果发现吞吐特别低先看nvidia-smi里的 GPU Utilization。如果显存占满但 GPU-Util 很低说明不是计算瓶颈而是请求队列没满、单条请求太小或者 batch 太小。这时候可以试着提高并发请求数让 vLLM 使用 continuous batching 把多请求拼在一起处理。5.3 并发参数怎么调vLLM 默认的调度器已经比较保守。想要提升吞吐可以在启动命令里追加几个参数--max-num-seqs 32 --max-num-batched-tokens 8192--max-num-seqs控制同时最多处理多少个序列。设 32 表示最多同时拼 32 个请求进一个 batch。如果你的显存只有 16GB设 16 或 24 更稳妥。--max-num-batched-tokens控制一次 batch 内最多包含多少 token值越大单次前向计算的规模越大吞吐通常越高但也更吃显存。我的调优步骤是先用最小命令启动确认单请求正常。并发请求从 1 加到 8观察吞吐是否线性增长。如果吞吐不再增长或者显存快满就降低--max-model-len而不是继续加大并发。处理长文本时把--max-model-len调大但并发降下来。记住一个原则显存总是有限的长上下文和高峰期之间要做取舍。优先保障业务场景的核心需求不要在单卡上指望兼顾所有指标。6. 踩坑记录端口冲突、OOM 这一串问题的排查思路这里把我实际踩过、以及在多个交流群里帮人看过的典型问题集中列一下。每条我都给出排查链路而不是直接甩一个“改配置”的结论。6.1 nvidia-smi 在 WSL2 里看不到 GPU症状Windows 里nvidia-smi正常但 WSL2 里执行nvidia-smi报错或者只能看到 CPU。排查顺序确认 WSL 版本是 2wsl -l -v。如果是 WSL1wsl --set-version distro 2升级。检查驱动。打开 Windows 的“设置 - 应用 - 可选功能”或 NVIDIA 控制面板确认驱动版本在 535 或更高。执行wsl --update把 WSL 内核更新到最新。如果还不显示试试在 PowerShell 里执行wsl --shutdown然后重新进入 WSL。WSL2 的 GPU 透传依赖/dev/dxg设备这个设备由 Windows 驱动提供。驱动一旦识别不了容器内无论如何都不可能用 GPU。所以这一条一定要排在最前面解决。6.2 容器启动后一直打印 nccl 初始化或 shared memory 相关问题我在第一版的命令里没有加--shm-size结果多轮调用后 vLLM 突然挂掉日志里出现类似Bus error的报错。很多人遇到这个问题会误以为是显存不足其实是共享内存被撑爆了。排查方法很简单在容器启动命令里加--shm-size 16g然后重新启动。如果你用的是 compose 文件同样在shm_size字段里设置。加了之后这个问题基本不会再出现。6.3 端口 8000 被占用症状启动时报[Errno 98] Address already in use或者访问localhost:8000发现跳到了另一个服务。在 PowerShell 里执行netstat -ano | findstr :8000找到占用 8000 端口的 PID然后taskkill /PID 1234 /F如果觉得这个端口被频繁占用也可以直接把映射改成-p 8001:8000然后用http://localhost:8001访问。没必要在这上面硬刚。6.4 WSL2 内存突然吃满、系统卡死vLLM 启动阶段需要把权重读入内存并做可能的格式转换瞬时内存占用可能达到权重体积的两到三倍。Qwen3-8B-FP8 权重约 8.5GB启动瞬间内存冲到 20GB 左右是正常的。如果你.wslconfig里给 WSL2 的内存太少系统会因为 OOM 直接把 vLLM 进程杀掉。日志里不一定出现 Python traceback可能只有一句Killed。排查方法dmesg | tail -50如果里面有Out of memory: Killed process字样就是内存不够。解决办法是给.wslconfig加内存和 swap以及把--max-model-len调低减少 KV cache 的内存开销。6.5 加载 FP8 权重时提示格式不匹配或不同 quantization症状模型目录里有 safetensors但 vLLM 报weight_shape not match或直接说无法识别量化方式。这通常是因为模型仓库下错了或者把 BF16 仓库当成 FP8 仓库。去模型目录检查config.json看quantization_config是否包含quant_method: fp8。如果没有说明权重本身不是 FP8不要再加--quantization fp8启动要么下载正确的 FP8 仓库要么移除量化参数跑 BF16 版本。6.6 从局域网访问不到服务http://localhost:8000能从本机访问但局域网其他机器访问超时。这是 Windows 防火墙或者端口转发的问题。最直接的办法是给docker run加上--host 0.0.0.0确保 vLLM 在容器里监听所有网卡。然后检查 Windows 防火墙看 8000 端口是否被拦截。如果用的是 WSL2很多时候只要确认.wslconfig里localhostForwardingtrue本机访问就通了。如果要局域网访问最好把服务映射到 Windows 宿主 IP 上并手动添加防火墙入站规则。我自己在使用过程中最大的体会是Windows 上部署 vLLM真正的问题从来不是 vLLM 本身而是 WSL2、驱动、端口转发这些外围环境。只要把外围问题理清楚后半段就和在 Linux 服务器上完全一样了。如果你想长期在本地跑模型建议把启动命令保存成一个start-vllm.bat里面写好参数每次直接双击运行。模型可以多下几个版本权重放在独立目录通过修改挂载路径来切换就不用反复拉镜像了。
