1. 为什么我非要在 Windows 上折腾 vLLM以及最终选型思路先说结论很多人一听 Windows 上跑 vLLM 就觉得是自讨苦吃毕竟官方文档明明白白写着优先支持 Linux社区里也常年飘着 Windows is not supported 的 issue。但实际折腾下来这条路不仅走得通而且没有想象中那么折腾。我这次的目标很明确在一台 Windows 机器上把 Qwen3-8B 的 FP8 量化版跑起来通过 vLLM 提供标准的 OpenAI 兼容接口用来做本地代码补全和文档问答的试验环境。为什么选 Qwen3-8B-FP8 而不是其他模型核心原因是显存。8B 参数量的模型如果跑 BF16 精度权重大概需要 16GB 显存加上 KV Cache 和激活值24GB 的显卡会非常紧张。FP8 量化把权重压缩到 8 位浮点权重直接减半到 8GB 左右这意味着 16GB 显存的卡也能比较从容地跑起来。对于 Windows 单机玩家来说这几乎是性价比最高的选择。Qwen3-8B 本身又是当前开源模型里中文能力第一梯队的选择工具调用和长文本指令遵循能力都很强拿来做本地服务非常合适。但这里有个现实问题主流大模型推理引擎 vLLM 对 Windows 的支持一直比较暧昧。以前想跑 vLLM 几乎必须装 WSL2 或者整个 Docker Desktop性能和磁盘 IO 都有损耗。最近一段时间 vLLM 的 Windows 原生支持其实已经可以通过预编译 wheel 包走通了只是很多教程还停留在 WSL2 时代。我这篇文章就是记录一条纯 Windows 原生路径不做虚拟机、不搞子系统直接在 PowerShell 里把服务拉起来让 ModelScope 或 HuggingFace 上下载的 Qwen3-8B-FP8 跑出一个可用的本地 API。先说下我的实验环境后面所有操作都基于这套配置项目配置系统Windows 11 Pro 23H264 位显卡NVIDIA GeForce RTX 4070 Ti SUPER16GB 显存驱动NVIDIA 驱动 551.86推荐 545.xx 以上Python3.11.964 位CUDA12.1运行时通过 wheel 自带无需单独安装完整 SDK模型Qwen/Qwen3-8B-FP8约 8.5GB这套配置有一个关键点显卡必须是 Ampere 架构以上也就是 RTX 30 系、40 系或者更新的专业卡。因为 FP8 推理依赖硬件层面的加速支持20 系及以下的 Turing 架构卡虽然在部分场景能加载 FP8 权重但性能上得不偿失不如直接用 BF16。如果你手里的卡是 2060、2070 这种我的建议是先升级硬件再往下看。2. 环境准备Python 虚拟环境和 CUDA 版本选择是第一个大坑2.1 Python 版本别乱选3.11 最稳vLLM 的 Windows wheel 包对 Python 版本有严格的匹配关系。我试过 3.12安装阶段就报出一堆 C 扩展编译错误因为部分依赖还没有提供对应 3.12 的预编译二进制。3.10 倒是能装上但运行过程中碰到过一次奇怪的线程崩溃。最后锁死在 Python 3.11从安装到跑通全程无坑。具体的安装步骤比较常规用官方安装包装完 Python 之后建议直接建一个独立虚拟环境不要污染系统全局环境# 创建项目目录并进入 mkdir D:\vllm-project cd D:\vllm-project # 创建虚拟环境 python -m venv vllm-env # 激活虚拟环境 .\vllm-env\Scripts\Activate.ps1注意在 PowerShell 里执行 Activate.ps1 可能会遇到执行策略拦截如果报错就先执行下面的命令放开当前用户的脚本执行权限Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser2.2 CUDA 到底需不需要装两类情况的处理这一步是最容易被误导的地方。网上一搜 Windows 装 vLLM大量文章让你先去 NVIDIA 官网下载 CUDA Toolkit 12.x 完整包一装就是好几个 GB。但实测下来vLLM 的 Windows wheel 包内部已经捆绑了它依赖的 CUDA 运行时库你只需要保证显卡驱动版本足够新让驱动层的 CUDA 版本不低于 12.x 即可。用nvidia-smi查一下右上角的 CUDA Version如果是 12.2 以上就没问题。但是有一种情况需要手动装 CUDA如果你打算从源码编译 vLLM或者需要跑一些自定义的 CUDA kernel。日常纯推理用户完全不需要。相比之下有个东西更值得检查就是 Microsoft C Build Tools。哪怕走 wheel 包安装vLLM 在安装过程中也会尝试编译少量扩展组件没有 C 编译环境的话会直接报Microsoft Visual C 14.0 or greater is required的错误。这个报错我去网上搜了一圈发现 2024 年底到 2025 年初踩到的人特别多。解决办法是安装 Visual Studio Build Tools在安装器里勾选使用 C 的桌面开发工作负载然后重启终端再重试。整个安装大概占用 6GB 磁盘但这是一次性的装完以后不管装什么 Python 原生扩展都用得上。装完这些之后验证一下环境# 查看 Python 版本必须是 3.11.x python --version # 查看 CUDA 驱动版本必须 12.x 以上 nvidia-smi # 查看显卡信息确认显存和架构 nvidia-smi -L如果这三步都正常环境准备就算完成了。不要急着装 vLLM先继续往下准备模型文件。3. 模型下载ModelScope 和 HuggingFace 怎么选以及本地路径陷阱3.1 国内环境优先 ModelScope但项目名要认准Qwen3-8B-FP8 在 HuggingFace 和 ModelScope 上都有托管模型 ID 分别是Qwen/Qwen3-8B-FP8和Qwen/Qwen3-8B-FP8。如果你在国内网络环境下从 HuggingFace 拉取大概率会卡在认证或者断流的问题上非常折磨。我强烈建议直接用 ModelScope 的 SDK 下载速度稳定得多。# 安装 ModelScope 命令行工具 pip install modelscope # 下载模型到本地目录注意认准 FP8 后缀 modelscope download --model Qwen/Qwen3-8B-FP8 --local_dir D:\vllm-project\models\Qwen3-8B-FP8这里有个非常关键的点ModelScope 下载时如果不指定--local_dir会默认放在一个以模型 ID 命名的缓存目录里例如C:\Users\你的用户名\.cache\modelscope\hub\Qwen\Qwen3-8B-FP8。这个路径本身没什么问题但如果你的系统盘比较小极有可能因为空间不足导致下载中断。另外Windows 用户目录路径如果包含中文某些依赖库在解析路径时可能出现奇怪的问题。所以最稳妥的做法就是像我上面那样显式指定一个纯英文、无空格的本地目录。3.2 下载后的完整性检查和目录结构FP8 模型的文件结构比较特殊不是简单的单个权重文件。下载完成后确认一下目录结构至少应该包含以下内容D:\vllm-project\models\Qwen3-8B-FP8\ ├── config.json ├── generation_config.json ├── merges.txt ├── model.safetensors.index.json ├── model-00001-of-00004.safetensors ├── model-00002-of-00004.safetensors ├── model-00003-of-00004.safetensors ├── model-00004-of-00004.safetensors ├── tokenizer.json ├── tokenizer_config.json └── vocab.json拆分为 4 个 safetensors 分片是因为单文件大小被限制在 4.5GB 以内这是 GGUF 和 safetensors 格式的常见做法。务必检查model.safetensors.index.json里记录的每个分片的 size 是否与实际文件大小匹配。最直接的方式是用ls -l对比下载完成后终端输出的 checksum 信息。这一步不能偷懒。我在第一次下载时就碰到过这种坑ModelScope 中间断流但 SDK 没有报错结果缺了model-00004-of-00004.safetensors这个文件。vLLM 加载时直接报safetensors file does not exist排查了半天才发现是下载不全。后面我学乖了下载完先看一遍文件数量再启动服务省掉很多无谓的排障时间。另外提醒一下如果之前下载过 BF16 版本的 Qwen3-8B记得不要混用。FP8 版本的config.json里quantization_config字段会多出几个配置项vLLM 会依据这个字段自动识别量化格式。如果你把 FP8 权重文件放到 BF16 模型的目录里启动时会报格式不匹配或者直接加载失败。4. vLLM 安装一条 pip 命令背后的依赖战争4.1 安装命令和国内镜像加速当环境就绪、模型就位之后进入最核心的安装环节。虽然说是一条 pip 命令的事但这里边的坑足够写一整节。# 直接用默认源安装可能很慢甚至超时 pip install vllm # 推荐使用清华镜像源实测速度提升明显 pip install vllm -i https://pypi.tuna.tsinghua.edu.cn/simple装的时候注意观察控制台输出。vLLM 会自动拉取一组配套的依赖版本包括torch、transformers、tokenizers、safetensors等。如果之前环境里已经装了 PyTorchvLLM 的依赖解析器会把 torch 强制降到它要求的版本。这个过程中最经典的报错是ERROR: pips dependency resolver does not currently take into account all the packages that are installed表面上是警告实际可能导致 torch 版本错乱。我的建议是安装 vLLM 之前不要在虚拟环境里提前装任何版本的 PyTorch。让它一次性把所有依赖都拉齐。如果你有其他项目需要特定版本的 PyTorch那就再建一个虚拟环境不要混用。4.2 安装阶段最常见的三种报错及应对第一次安装 vLLM 的人八成会遇到下面的报错之一报错一找不到 vllm 对应的 Windows 平台 wheelERROR: Could not find a version that satisfies the requirement vllm ERROR: No matching distribution found for vllm出现这个 99% 是 Python 版本不对。vLLM 的 Windows wheel 目前覆盖 Python 3.9 到 3.12但 3.12 的支持不完整。检查一下python --version如果确实是 3.11 依然找不到那大概率是镜像源同步延迟。切换回默认源再试一次pip install vllm报错二Microsoft Visual C 14.0 is required这个问题前面已经说过解法安装 Build Tools。其实这条很容易被忽视因为现代 Python 大部分包装上就能用很少需要编译导致很多人电脑里根本没有 C 工具链。vLLM 不一样它包含大量 CUDA kernel 的 Python 绑定安装时会编译一部分 native 代码没有编译器直接卡死。报错三CUDA_HOME path does not exist or is not specified有些用户系统里装了 CUDA Toolkit 但没设置环境变量有些用户压根没装。报这个错不代表你必须装完整 CUDA。vLLM 的 wheel 装完后实际推理用的是打包进去的 CUDA runtime。这个报错多数发生在pip install阶段触发了源码目录的检测逻辑。如果 wheel 本身能装完这个报错可以忽略。但如果你是在装完某次依赖后被反复提示可以显式设置一下set CUDA_HOMEC:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v12.1这个路径不存在也没关系只是骗过安装脚本的检测让他跳过源码编译流程。4.3 安装后的验证装完之后跑一下版本验证确认核心模块能正常导入python -c import vllm; print(vllm.__version__)能输出版本号比如0.6.3.post1就说明安装这一步基本稳了。如果导入时报 DLL 加载错误比如ImportError: DLL load failed while importing vllm这通常意味着你的显卡驱动太老缺少 vLLM 依赖的新版 CUDA 动态链接库。去 NVIDIA 官网把驱动更新到最新版重启电脑再试。5. 启动推理服务vLLM 命令行参数的逻辑和调优5.1 最小可用启动命令一切就绪后启动服务的命令并不复杂核心就一行vllm serve D:\vllm-project\models\Qwen3-8B-FP8 --host 0.0.0.0 --port 8000 --max-model-len 8192 --gpu-memory-utilization 0.90 --served-model-name qwen3-8b-fp8需要注意的是在 PowerShell 里续行符是反引号在 CMD 里则是^。如果直接复制粘贴建议把所有 去掉、写成一行避免转义问题。下面逐个说说这些参数的作用和取舍这些参数直接决定了服务的性能上限--host 0.0.0.0监听所有网卡。如果只打算本机访问改成127.0.0.1更安全。--port 8000默认端口就是 8000如果你的机器上跑了别的服务占用该端口换一个。--max-model-len 8192这是单次请求允许的最大序列长度输入输出。Qwen3-8B 原生支持 32K 甚至更长但把 max-model-len 设置到 8192 可以大幅减少 KV Cache 的显存占用让并发能力更强。如果你的场景需要处理超长文档可以调到 16384但建议同时降低--gpu-memory-utilization到 0.8避免 OOM。--gpu-memory-utilization 0.90表示 vLLM 最多使用 90% 显存来加载模型和 KV Cache。剩下 10% 留给 CUDA context 和图形界面。如果你用 Windows 远程桌面连接机器建议把这个值降到 0.85因为远程桌面会额外占用一部分显存。我实测过开远程桌面且设置为 0.9 时偶发 OOM降到 0.85 后一天都没崩过。--served-model-name qwen3-8b-fp8自定义 API 请求中的模型名称。如果不设置默认会取模型文件夹的名字也就是Qwen3-8B-FP8调用时需要对上。启动后看到类似下面的日志说明模型加载成功INFO: Started server process [12345] INFO: Waiting for model to be loaded... INFO: Loading model weights took 12.34 GB INFO: GPU KV cache size: 4.56 GB INFO: Started engine process with PID 12346 INFO: Application startup complete. INFO: Uvicorn running on http://0.0.0.0:8000看到Application startup complete这一行就可以松口气了。从执行命令到出现这行视磁盘读取速度不同一般需要 1 到 3 分钟。第一次加载还会额外花时间编译 CUDA kernel 缓存后续再启动会快很多。5.2 用 curl 跑通第一个请求服务起来之后先用 curl 验证一下基本连通性curl http://localhost:8000/v1/models返回内容里会有你设置的模型名qwen3-8b-fp8。接着发一个 Chat 补全请求curl http://localhost:8000/v1/chat/completions -H Content-Type: application/json -d {\model\: \qwen3-8b-fp8\, \messages\: [{\role\: \user\, \content\: \用一句话介绍 FP8 量化\}], \max_tokens\: 128}这里有一个我在 Windows 下踩过的小坑PowerShell 对 JSON 里的双引号转义处理非常反人类如果原样粘贴 Linux 教程里的单引号命令会直接报The string is missing the terminator。最简单的办法是把 JSON 写到一个文件里然后用 curl 的-d body.json方式发送或者在 Python 里调用 requests。前者更贴近命令行风格# 创建 body.json 文件 # {model: qwen3-8b-fp8, messages: [{role: user, content: 用一句话介绍 FP8 量化}], max_tokens: 128} curl http://localhost:8000/v1/chat/completions -H Content-Type: application/json -d body.json收到回复后确认一下choices[0].message.content字段是不是一段像样的文本是的话恭喜你整套链路已经通了。6. FP8 模型的显存红利与性能实测数据6.1 显存占用对比FP8 到底省了多少跑通只是第一步实践下来我更关心性能和资源消耗。用同一个 8B 模型分别加载 BF16 和 FP8 版本做对比前提条件是max-model-len均为 8192gpu-memory-utilization均为 0.9指标Qwen3-8B BF16Qwen3-8B FP8权重文件总大小约 16.2GB约 8.5GB加载后显存占用约 21GB约 11.2GB16GB 显存可运行勉强容易 OOM非常从容24GB 显存可运行可以但并发受限并发能力充裕这组数据解释了为什么我反复强调 FP8 是单卡跑 8B 模型的最优解。省下来的显存全部可以被 KV Cache 吃掉意味着更大的并发吞吐量。实测在并发 8 个请求的场景下BF16 版本在 16GB 卡上直接 OOM而 FP8 版本稳如老狗还能继续往上加并发。6.2 吞吐量和首 token 延迟的实测基线在 RTX 4070 Ti SUPER 上跑 Qwen3-8B-FP8我用自带的benchmark_serving.py脚本简单压了一下装 vLLM 时会自动装到 Scripts 目录下结果如下python D:\vllm-project\vllm-env\Scripts\benchmark_serving.py --backend openai --base-url http://localhost:8000/v1 --model qwen3-8b-fp8 --num-prompts 100 --request-rate 8指标实测值输入 token 数默认550 左右输出 token 数默认150 左右平均首 token 延迟约 180ms平均每请求总延迟约 2.1s整体吞吐量约 72 tokens/s并发 8 时的吞吐量约 78 tokens/s这个成绩相当可观了。作为对比用 Ollama 的 llama.cpp 后端跑同样的 FP8 模型吞吐量大概只有 40-50 tokens/s。vLLM 的 PagedAttention 连续批处理机制在并发场景下的优势体现得非常明显并发从 1 涨到 8吞吐量不降反升说明 GPU 利用率一直没有打满。6.3 一个值得注意的烧脑问题采样参数对速度的影响有一点容易被忽视temperature、top_p、top_k这些采样参数不仅影响输出质量还会影响生成速度。我跑了几组对照当temperature0.7且top_p0.9时由于采样策略需要更频繁地访问随机数生成器和排序逻辑每请求总延迟比贪心解码temperature0高约 15%。如果你的应用场景追求吞吐优先比如批量离线生成摘要建议把采样参数固定为贪心解码如果追求多样性和创造性则保持较高 temperature。7. 服务化部署的稳定性调优让 vLLM 在 Windows 上跑得更省心7.1 性能调优参数建议跑通和跑好之间还有一段距离。实际服务化使用中我建议调整 vLLM 服务端这几个参数vllm serve D:\vllm-project\models\Qwen3-8B-FP8 --host 0.0.0.0 --port 8000 --max-model-len 8192 --gpu-memory-utilization 0.85 --served-model-name qwen3-8b-fp8 --max-num-seqs 16 --max-parallel-loading-workers 1 --enforce-eager--max-num-seqs 16限制最多同时处理 16 个序列。如果不设置vLLM 会根据显存自动决定但自动决定的数值往往偏大导致在高并发时 GPU 单次调度的 batch 过大、单请求延迟飙升。限制成 16 后吞吐量下降 3% 左右但 p95 延迟从 3s 降到 1.8s对交互式应用更友好。--max-parallel-loading-workers 1Windows 上多进程加载模型文件有时会触碰到奇怪的句柄泄漏问题。强制单进程加载启动速度慢十几秒但稳定性明显提升。--enforce-eagervLLM 默认使用 CUDA Graph 加速在 Windows 上有概率因为驱动兼容性问题导致启动失败或随机崩溃。加上这个参数后强制走 eager 模式首 token 延迟增加约 10ms但换来的是极高的稳定性。如果你的驱动版本很新且没有异常崩溃可以去掉这个参数获得更好性能。7.2 开机自启与异常退出处理Windows 上跑服务还有一个痛点就是没有 systemd 那一套进程守护机制。vLLM 如果因为 OOM 或者其他原因崩了不会自动拉起来。我用的方案比较朴素但有效写一个.bat脚本放进启动文件夹每次开机自动拉起服务。echo off cd /d D:\vllm-project call vllm-env\Scripts\activate.bat vllm serve D:\vllm-project\models\Qwen3-8B-FP8 --host 0.0.0.0 --port 8000 --max-model-len 8192 --gpu-memory-utilization 0.85 --served-model-name qwen3-8b-fp8 --max-num-seqs 16 --max-parallel-loading-workers 1 --enforce-eager把这个脚本放到shell:startup目录按下 WinR 输入shell:startup回车即可打开开机进桌面后就会自动打开一个命令行窗口跑服务。这个窗口别关关了就相当于 service 停了。如果对进程守护有更高要求可以考虑用 NSSM 把窗口程序注册成 Windows 服务但配置过程有点繁琐一般自己实验室用启动文件夹方案就够了。7.3 常见问题排查清单最后给一张遇到问题时的排查对照表这些全部是我实际踩过的现象可能原因解决办法启动时报ValueError: The models max seq len is larger than the maximum number of tokensmax-model-len设置超过了模型支持的窗口降低到 8192 或 4096请求时报OutOfMemoryErrorGPU 显存不足多半是远程桌面占用降低gpu-memory-utilization到 0.8或断开远程桌面首次请求慢到 30 秒vLLM 在预热 CUDA kernel等 5 分钟后再测后续会快或关闭enforce-eager用 CUDA Graph服务运行几天后响应越来越慢显存碎片化或缓存命中率下降重启服务释放积累的显存碎片Connection reset by peer防火墙拦截了 8000 端口外部访问在 Windows Defender 防火墙里放行该端口的入站规则这里重点说下缓存命中率相关的那个问题。vLLM 最近几个版本对前缀缓存prefix caching的优化做得很好默认会缓存历史请求的 KV 状态。但如果你频繁切换不同的 system prompt前缀完全不一致缓存就会反复失效表现为响应速度越来越不稳定。解决办法是把常用的 system prompt 固定不变比如统一用一个版本不要每次请求都微调措辞。8. 实测感受和这套方案的适用边界这套 Windows 原生 vLLM Qwen3-8B-FP8 的方案我已经稳定运行了两周多中间只有一次因为 Windows Update 自动重启导致服务中断。日常负载是本地代码补全、文档问答和小规模批处理任务单日请求量大约两千条左右GPGPU 显存峰值一直没超过 12GB16GB 的卡余量充足。如果要我总结这套方案的适用边界我会说它最适合三类人一是没有独享 Linux 服务器、只有一台 Windows 桌面机的开发者想跑一个真正能打的中文模型做本地实验二是对显存敏感、希望在 16GB 级别显卡上体验完整 vLLM 推理能力的人FP8 几乎是唯一解三是想在公司内网搭一个低成本的私有化推理服务又不想折腾 Docker 挂载和 WSL2 网络映射的运维同学。当然它也有明显的局限。最突出的问题是 vLLM 在 Windows 上缺少官方正式支持版本更新后偶尔需要等待新 wheel 包发布不能像 Linux 那样源码一两分钟编译完。另外Windows 的显存管理和 Linux 相比还是有差距长时间高负载运行下显存碎片影响会比 Linux 更明显建议养成每周重启一次服务的习惯。至于下一步优化方向我有两个想法正在实验中。一是尝试多模型拼接部署在同一块显卡上同时加载一个 8B 模型和一个 1.5B 模型用不同的--served-model-name暴露不同的 API这样可以让小的模型快速响应简单问题大模型专注复杂推理。二是把服务前缀缓存命中率作为监控指标接入一个简单的看板评估一下不同业务请求模式下的缓存收益如果命中率太低就考虑调整请求协议。如果你也在 Windows 上折腾 vLLM欢迎分享一下你遇到的坑和解决方案这玩意儿的边界就是靠大家一点点试出来的。
