说句实在话，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 比，综合体验也不稳定，所以我的建议非常直接：生产环境用 Linux，Windows 上想快速体验就用 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，需要用下面命令把默认版本切到 2：
wsl --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：一行命令背后的版本选择
在刚才创建并激活的虚拟环境里安装 vLLM：
uv pip install vllm默认会安装当前最新稳定版，我写这篇实操时是 0.9.x。如果你希望更稳妥，可以指定一个已知大版本号：
uv pip install "vllm>=0.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_ENDPOINT=https://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 fp8，vLLM 会自己识别。这点和加载某些第三方量化模型时需要手动传参的体验不太一样，对新手更友好。
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 降到 8192，KV Cache 占用直接少一大截，在 16GB 显存上体感非常明显。
4.3 FP8量化在vLLM里的处理细节
Qwen3-8B-FP8 的 config.json 里自带quantization_config，vLLM 加载时会自动识别。如果你在日志中看到模型被当作 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和tmux
WSL2 终端一旦关闭，前台运行的 vLLM 服务也会跟着退出。为了避免反复重启，我习惯用 nohup 把服务放到后台，并把日志写进文件：
nohup vllm serve ~/models/Qwen3-8B-FP8 \ --host 0.0.0.0 \ --port 8000 \ --max-model-len 8192 \ > vllm.log 2>&1 &要查日志就看tail -f vllm.log，想杀掉服务就pkill -f "vllm serve"。这个操作方式在 Windows Terminal 里配合 WSL2 使用很顺手，不需要额外装工具。
5. 调用推理接口：OpenAI兼容API从curl到SDK
5.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，那就直接用 requests：
import 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, json=payload) data = response.json() print(data["choices"][0]["message"]["content"])注意返回结构里content是最终拼接好的完整回答。requests 的json=参数会自动设置 Content-Type，不用手动加 header，这一点比 curl 命令省事。
5.3 用OpenAI SDK调用：复用现有代码
如果你的项目本来就用了 OpenAI 的 Python SDK，只需要改一下 base_url：
from openai import OpenAI client = OpenAI( api_key="EMPTY", base_url="http://localhost:8000/v1" ) completion = client.chat.completions.create( model="Qwen3-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 的话，只需加一个stream=True：
from openai import OpenAI client = OpenAI( api_key="EMPTY", base_url="http://localhost:8000/v1" ) stream = client.chat.completions.create( model="Qwen3-8B-FP8", messages=[ {"role": "user", "content": "写一段500字左右的产品介绍"} ], stream=True ) for chunk in stream: delta = chunk.choices[0].delta.content if delta: print(delta, end="", flush=True)底层原理是 SSE（Server-Sent Events），vLLM 会把每个生成的 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 networking），Windows 侧直接访问 localhost 就能通。如果你遇到 Windows 侧始终访问不了 WSL2 里的服务，可以先在 WSL2 里执行ip addr show eth0拿到 WSL2 的 IP，再从 Windows 访问这个 IP 加端口；实在不行再上端口转发。
6.4 一个简单压测：看看Qwen3-8B-FP8能跑多快
配置好以后，我想大家都会好奇模型到底跑多快。这里分享一组我自己的实测数据，仅供参考：
| 硬件与配置 | 场景 | 实测结果 |
|---|---|---|
| RTX 4090 24GB，max-model-len=16384 | 单请求流式生成，500 token 输出 | 约 80-110 tokens/s |
| 同一配置，并发 16 个请求 | 批量推理，整体吞吐 | 总吞吐可以到 800+ tokens/s |
| 2048 token prompt 预填充 | prefill 阶段 | 约 4000-6000 tokens/s |
数据会随着输入长度、并发数、驱动版本有波动，但趋势很明确：单请求的速度取决于内存带宽，并发时 Continuous Batching 能把吞吐量拉得很高。这也是 vLLM 在生产环境里真正的价值所在——它不是把单次生成做多快，而是让 GPU 在大量请求面前不被浪费。
如果你也想验证自己的环境，可以用 Python 并发发十几个请求，对比一下整体耗时，就能直观感受到“批量处理”和“逐个排队”的巨大差异。这个测试不要在生产服务器上做，本地开发机完全没问题。
写到这里，我发现自己每次在 Windows 上折腾这类工具，最后都会得出同一个结论：Windows 从来不是不能做，只是很多坑需要人到场踩一遍才知道怎么绕。按我这套流程走下来，你应该能在半小时到一小时左右跑通 Qwen3-8B-FP8，然后再按自己的硬件条件微调那三个性能参数，把它变成一台真正能用的本地模型服务。如果你在启动过程中遇到上面表格里没写到的报错，建议优先把完整日志发到 vLLM 的 GitHub issue 里搜一搜，很多问题都有现成的讨论和结论。最后再分享一个小技巧：把启动命令和常用参数写成一个 shell 脚本放进 WSL2 的~/.local/bin里，下次启动模型服务只需要一行命令，不用再翻历史记录找参数了。
