企业官网建设流程全解析

如果你手头是一台装着 Windows、插着 NVIDIA 显卡的机器，又想把 Qwen 这类开源模型以一个正经推理服务的形式跑起来，大概率会搜到一堆“请使用 Linux”的结论。这句话对了一半。vLLM 确实是 Linux 优先项目，原生 Windows 不支持 CUDA 推理，但“不支持原生”不等于“跑不了”。我前阵子刚好在 Windows 11 台式机上，用 WSL2 把 vLLM 部署服务完整跑通，加载的是 Qwen3-8B-FP8 模型，整条链路从零做到能对外提供 OpenAI 兼容 API，大致花了两小时。这篇文章就把完整过程、每个环节为什么这么选，以及我踩过的坑都写出来，给想在 Windows 上部署 vLLM 的朋友一条能直接抄的路线。

1. 为什么在 Windows 上跑 vLLM 要先选对运行环境

1.1 vLLM 的“Linux 基因”与 Windows 原生支持现状

vLLM 不是一个普通 Python 库，它内部有大量用 C++ 和 CUDA 编写的高性能 Kernel，涉及 PagedAttention、Continuous Batching 这些底层特性。官方 CI/CD 流水线也只围绕 Linux 环境构建，Windows 上的预编译 wheel 长期缺失。虽然现在pip install vllm在新版本中能碰到 Windows 相关包，但真正加载 GPU 模型、跑 CUDA 图的时候，问题会一个接一个冒出来。

关键的问题在于：Windows 原生环境缺乏 vLLM 依赖的那套 Linux ABI，FlashAttention 等第三方算子很难在 Windows 下编译。就算你想从源码编译，也需要 MSVC、CUDA Toolkit、LLVM 等等一堆东西对齐版本，稍有不慎就在 CMake 阶段失败。为了一个部署环境去折腾编译，投入产出比非常低。

所以我的第一个建议是：不要试图在原生 Windows 里硬装 vLLM，把思路切到“在 Windows 里跑一个轻量 Linux 环境”，这样你获得的是接近服务器体验的部署路径。

1.2 三条路线：WSL2、Docker Desktop、原生 pip

实际可操作的路线大概三条，我做了一个对比。

这里强调一个容易混淆的点：Docker Desktop 在 Windows 上加速容器时，默认就是借助 WSL2 后端工作的。也就是说，如果你的 Docker Desktop 能正常使用 GPU，底层其实已经有一个健康的 WSL2 环境了。绕了一圈，最后还是回到 WSL2。

1.3 为什么我选 WSL2 直装而不是 Docker

我自己最终选的是 WSL2 直装，原因很简单：单机单卡场景，没有容器调度需求。Docker 的多一层抽象确实干净，但镜像下载要好几个 GB，Windows 盘符和 WSL 文件系统之间的挂载还经常有 IO 性能问题。模型文件放在 /mnt/d 下，Docker 容器访问时速度不稳定，轻则加载慢，重则启动超时。

WSL2 直装 vLLM 有几个天然优势：可以随便用 conda 创建独立环境；模型文件可以直接放在 Linux 虚拟磁盘里，IO 性能接近裸机；出了问题可以直接看原始日志，不需要进容器翻。当然，如果你之后要把服务交付给其他人，或者需要在多台机器上复现同样环境，Docker 的优势就会体现出来。但作为“从零跑通”，WSL2 是最短路径。

2. WSL2 与 NVIDIA 驱动联调：环境准备阶段的几个关键细节

2.1 一条命令启用 WSL2 与版本检查

Windows 10 21H2 以上或 Windows 11 都支持wsl --install。以管理员身份打开 PowerShell，执行：

wsl --install -d Ubuntu-22.04

首次安装会自动启用“适用于 Linux 的 Windows 子系统”和“虚拟机平台”两个可选功能，重启后继续安装。装完以后建议立刻确认版本：在 PowerShell 里执行wsl -l -v，如果看到 Ubuntu 的 VERSION 列是 2，说明一切正常；如果显示 1，执行wsl --set-version Ubuntu-22.04 2手动转换。

有个坑值得提一下：部分主板默认关闭虚拟化。如果你在启动 WSL 时遇到 0x80370102 错误，去 BIOS 里把 Intel VT-x / AMD SVM 打开再回来。这类问题发生在第一次开机阶段，容易误判成系统问题，实际上纯硬件开关的事。

2.2 确认 GPU 透传：nvidia-smi 怎么才算成功

进入 WSL2 之后，第一件事是运行nvidia-smi。成功的关键是你不需要、也不应该在 WSL2 里手动安装 NVIDIA 的 Linux 驱动，直接复用 Windows 侧的 NVIDIA 驱动即可。WSL2 会自动把 GPU 通过/dev/dxg透传给 Linux 环境。

预期输出里能看到 Windows 侧同款显卡型号，以及和 Windows 驱动对应的 Driver Version、CUDA Version。还能看到一个细节：进程列表里几乎没有正在运行的图形程序，只有 WSL 相关进程，这说明 GPU 已经正确透传。

有个小经验：如果 nvidia-smi 提示找不到命令，可以手动把 WSL 库目录加进 PATH：

echo 'export PATH=/usr/lib/wsl/lib:$PATH' >> ~/.bashrc source ~/.bashrc

2.3 用 .wslconfig 控制内存与网络模式

WSL2 默认会根据 Windows 物理内存按比例分配资源，对跑大模型来说不够“可控”。在%UserProfile%\.wslconfig文件里写清楚限制，会舒服很多：

[wsl2] memory=16GB processors=8 swap=8GB networkingMode=mirrored

设置完要在 PowerShell 里执行wsl --shutdown再重新进 WSL，配置才会生效。networkingMode=mirrored是 Windows 11 22H2 之后支持的特性，它让 WSL 内的服务可以直接通过 localhost 访问，省去很多端口映射的麻烦。如果你用的是 Windows 10，或者遇到 WSL 网络栈不太稳的情况，后面我会讲怎么用 WSL 的 IP 替代 localhost。

3. 创建 Python 环境并安装 vLLM：版本坑与网络源配置

3.1 Python 版本选型与 conda 环境

vLLM 对 Python 版本有明确要求，太高或太低都会碰到 wheel 缺失。我试下来最稳的是 Python 3.11，3.10 也完全没问题，3.12 在较新版本 vLLM 上虽然能用，但确定一些老版本依赖时比较麻烦。

环境隔离强烈建议用 conda，省心。在 WSL2 里装 Miniconda：

wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh bash Miniconda3-latest-Linux-x86_64.sh

装完重开终端，创建虚拟环境：

conda create -n vllm python=3.11 -y conda activate vllm

后续所有操作都在vllm这个环境里进行，不会污染系统 Python。

3.2 pip 安装 vLLM 与换源注意事项

激活环境后，先升级 pip，再装 vLLM：

pip install -U pip pip install vllm

安装过程会拉取 PyTorch、transformers、flashinfer 等一堆依赖，体量不小。vLLM 的 Linux wheel 已经自带 CUDA runtime，所以不需要额外安装 CUDA Toolkit。这一点让很多人误解，以为要在 WSL2 里再装一份完整 CUDA，其实完全没必要。

国内网络环境下，为了加快下载，可以给 pip 配置清华源：

pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

但有一点要注意：清华源偶尔会对个别 nvidia 系列依赖同步不全，如果安装中报某个nvidia-*包找不到，去掉镜像源，临时换回官方源重试即可。装完以后验证一下：

python -c "import vllm; print(vllm.__version__)"

能打出版本号，说明基础环境已经通了。此时可以顺手安装配套工具：

pip install modelscope huggingface_hub openai

3.3 模型文件放哪里：WSL 虚拟盘还是 Windows 盘

这个决策直接影响加载速度。WSL2 的 Linux 文件系统位于 ext4 虚拟磁盘里，读写性能接近原生；Windows 盘符（/mnt/d、/mnt/c）本质是跨文件系统的网络式挂载，IO 损耗明显。模型权重文件动辄十几个 GB，首轮加载时要从磁盘读进显存，用 /mnt/d 明显更慢。

我的做法是：如果 Windows 侧 C 盘空间足够，就在 WSL 家目录下建models目录，把模型放在/home/用户名/models；只有当空间实在紧张时才放到 Windows D 盘。加载完成后服务常驻内存，慢一点影响不大，但第一次启动的等待体验差很多。

顺便看一下空间：

df -h ~

WSL 虚拟磁盘默认放在 C 盘，如果空间不够，可以考虑用wsl --manage <发行版> --move迁移，或者直接放到 /mnt/d 上，二选一。

4. 拿到 Qwen3-8B-FP8 权重并理解 FP8 量化

4.1 FP8 量化的本质：e4m3、显存收益与精度损失

Qwen3-8B 如果以 BF16 精度存储，权重部分大约要 16GB 左右，对 16GB 显存的显卡已经相当紧张，加载完几乎没有空间留给 KV Cache 和中间激活。FP8 量化把每个权重从 2 字节压到 1 字节，整体权重缩到 8GB 上下，显存压力骤降。

FP8 最常见的格式是 E4M3：4 位指数、3 位尾数。相比 INT8，它的动态范围更大；相比 BF16，精度略有损失，但部署到生成任务上，质量下降通常很难感知。这也是越来越多模型选择 FP8 作为主流发布格式的原因。你需要知道，FP8 在 vLLM 里不是通过--dtype fp8参数启用的，而是由模型目录里的量化配置自动识别，或通过--quantization fp8显式指定。

另一个实际收益是显存余量变大后，vLLM 可以给 KV Cache 分配更多空间，支持更大的并发和更长的上下文。这也是为什么我选 FP8 版本而不是 BF16 原版。如果你的显卡是 24GB 显存，BF16 也能跑，但留给批处理的空间会小很多；16GB 显存的话，FP8 几乎是必须的。

4.2 从 Hugging Face 或 ModelScope 拉取模型权重

模型权重下载方式主要有两种。Hugging Face 直接下载：

export HF_ENDPOINT=https://hf-mirror.com huggingface-cli download Qwen/Qwen3-8B-FP8 --local-dir ./models/Qwen3-8B-FP8

如果你在国内，HF_ENDPOINT这步能明显提速，不加的话经常卡到超时。另一种方式是 ModelScope：

modelscope download --model Qwen/Qwen3-8B-FP8 --local_dir ./models/Qwen3-8B-FP8

ModelScope 的模型 ID 规则和 Hugging Face 基本一致，部分仓库目录能直接对应。下载完以后，一定要确认目录里有config.json和若干个.safetensors文件。safetensors 文件经常被拆成好几个 5GB 左右的分片，缺一个都会在加载时报文件不存在的错误。

4.3 vLLM 如何识别 FP8 权重与参数注意事项

当 vLLM 加载模型时，它首先读取config.json中的quantization_config字段，如果里面已经声明了 FP8 量化器，它就会自动按量化权重的方式加载。所以很多时候启动命令里不加--quantization fp8也能识别；加上则是显式指定，遇到 config 信息不完整的情况更稳妥。

如果权重被当作普通模型加载，最常见的结果是报告 shape mismatch 或 dtype 错误。这种情况通常是权重文件与配置不匹配，比如下载了 FP8 权重，但config.json被误替换成了 BF16 版本。建议下载完不要去手动改模型目录里任何文件，保持原样最安全。

vLLM 启动时的执行顺序值得了解一下：先读取模型配置，再分配显存，然后分片加载权重，接着初始化 KV Cache 池，最后才启动 API 服务监听端口。很多新手一看日志没立刻出现 “Starting vLLM server” 就以为卡住了，其实只是前面这几个阶段还没走完，尤其是第一次运行还要编译 CUDA Graph，等待时间会明显偏长。

5. 启动 vLLM 服务并验证 OpenAI 兼容接口

5.1 最小启动命令与参数逐条说明

在vllm环境里执行：

vllm serve Qwen/Qwen3-8B-FP8 \ --quantization fp8 \ --gpu-memory-utilization 0.90 \ --max-model-len 16384 \ --max-num-seqs 64 \ --port 8000

逐条拆解一下参数意义：

• Qwen/Qwen3-8B-FP8：模型 ID。如果你已经下载到本地，也可以换成./models/Qwen3-8B-FP8这类本地路径。
• --quantization fp8：显式声明加载 FP8 权重。config 自动识别时可不加，但显式写出来更保险。
• --gpu-memory-utilization 0.90：允许 vLLM 使用 90% 的显存。不能设成 1.0，因为 Windows 桌面本身也会占用少量显存。
• --max-model-len 16384：限制最大上下文长度。Qwen3 系列支持长上下文，但显存有限时不要开太高，先跑通再慢慢加。
• --max-num-seqs 64：允许同时参与批处理的最大序列数。数值越大吞吐越高，但显存占用也会增加。
• --port 8000：对外服务的端口。

如果模型放在本地目录，比如./models/Qwen3-8B-FP8，那么 API 里的 model 字段也应该写成相同字符串，vLLM 会直接把它当作展示名称。否则调用接口时会收到 Model not found 的报错。

5.2 用 curl 和 Python 调用接口

先看服务是否正常响应，请求/v1/models：

curl http://localhost:8000/v1/models

正常会返回一个包含模型 name 的 JSON。接下来做一次真正的对话补全：

curl http://localhost:8000/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{ "model": "Qwen/Qwen3-8B-FP8", "messages": [ {"role": "user", "content": "用一句话介绍什么是 FP8 量化"} ], "max_tokens": 512, "temperature": 0.7 }'

返回 JSON 中的choices[0].message.content就是模型回复。浏览器访问http://localhost:8000/docs还能打开 Swagger UI，查看所有可用的接口定义。

如果你更习惯用 Python，安装openai库后可以直接对接：

from openai import OpenAI client = OpenAI(base_url="http://localhost:8000/v1", api_key="EMPTY") resp = client.chat.completions.create( model="Qwen/Qwen3-8B-FP8", messages=[{"role": "user", "content": "你好"}], max_tokens=128, ) print(resp.choices[0].message.content)

这里的 api_key 随便填一个占位符即可，vLLM 不会校验它。

5.3 日志中的性能指标怎么看

vLLM 启动日志里会打印 GPU 内存总量、可用内存、KV Cache 池大小等关键信息。例如能看到类似GPU memory: 23.62 GiB和KV cache size: 13.50 GiB这行，它们能帮你判断当前配置下还有多少余量。

每完成一次请求，终端还会滚动输出请求状：Prompt: 12 tokens, Generated: 34 tokens之类。更完整的性能指标在/metrics端点，Prometheus 可以直接抓取，里面有tokens_generated_total、request_success_total等计数器。你不需要一开始就上监控，但跑服务后观察这些数字，能比凭感觉调参准确得多。

关于速度，我先说结论：不要拿“每秒生成多少 token”当唯一 KPI。在我这张 4090 上，单并发时生成阶段大概在 100 到 150 token/s 之间，首 token 延迟几十到一两百毫秒；并发跑上去后，总吞吐会明显提升，但单个请求的延迟也会相应增加。这个数字仅供参考，显卡、驱动、上下文长度不同都会造成很大差异。

5.4 启动与调用过程中最常见的错误

端口被占用的概率很高，尤其是你之前跑过其他服务。检查方式：

ss -ltnp | grep 8000

有进程占着就直接换端口，启动命令换成--port 8001，curl 请求一并改掉。

OOM 是最常见的问题，报错信息通常类似CUDA out of memory。优先降低--gpu-memory-utilization到 0.85，同时调低--max-model-len。显存实在不够时，可以加一个--enforce-eager参数禁用 CUDA Graph，牺牲一点吞吐换稳定性。

如果你在 WSL2 里 curl 能通，但 Windows 浏览器访问 localhost 失败，多半是网络模式的问题。可以先执行wsl hostname -I拿到 WSL 的 IP，再用http://IP:8000访问。Windows 11 上更推荐在.wslconfig里打开networkingMode=mirrored，让两者 localhost 共用，从根上解决这个别扭问题。

6. 实测调优与踩坑记录：显存、旧卡与工具选型

6.1 显存不够时的参数调整清单

不同显存档位，启动参数不能一套模板用到底。我整理了一个按经验推荐的配置表，供参考。

注意 Windows 桌面、浏览器、IDE 都会吃显存。WSL2 里 vLLM 看到的总显存有时候会小于显卡物理显存，就是因为 Windows 侧还有占用。遇到启动时显存不够，可以先关掉占显存的应用，再回头调参数。

6.2 FP8 在旧显卡上的真实表现

FP8 量化在计算层面对显卡有要求。RTX 40 系（Ada Lovelace）之后才有原生 FP8 Tensor Core 加速，在 30 系及更老的显卡上，vLLM 只能做 weights-only FP8，也就是把权重反量化回 BF16 再参与计算。这种模式下，FP8 的主要收益是省显存，而不是提速度。如果你的显卡恰好是 30 系且显存充裕，跑 BF16 原版权重可能更快，FP8 的意义就没那么大。

我实测过 3080 上加载 FP8 权重，显存占用确实低，但生成速度与 BF16 版本相比没有优势，甚至在某些 Kernel 路径下略有下降。如果加载时报当前架构不支持的 kernel 错误，果断放弃 FP8，换成 BF16 原版权重是更省事的选择。选型逻辑很简单：显存是瓶颈，用 FP8；算力是瓶颈，用 BF16。

6.3 vLLM 和 ollama、LM Studio 的定位差异

很多人在本地跑模型时，会先接触 ollama 或 LM Studio。这些工具确实友好，但和 vLLM 定位完全不同。ollama 底层是 llama.cpp，对 GGUF 格式支持最好，显存不足时可以切 CPU 做 Offload，但并发能力和编程式控制相对弱。LM Studio 更偏图形化桌面应用，适合逐个模型聊天，不适合作为服务长期对外提供接口。

vLLM 的价值在于：它是为“服务化部署”设计的。Continuous Batching 能动态聚合并发请求，PagedAttention 让 KV Cache 管理更高效，对外直接提供 OpenAI 兼容接口，这正是做应用后端最需要的。如果你只是自己聊天，ollama 完全够用，没必要为了用 vLLM 而用 vLLM；但如果你要接一个多用户应用，或者要跑自动化评测、批处理任务，vLLM 才是更专业的选择。

6.4 把服务长跑下去的细节

WSL2 里没有传统意义上的开机自启服务，重启 Windows 后 vLLM 不会自己跑起来。最简单的做法是用 nohup 放到后台，日志重定向到文件：

nohup vllm serve Qwen/Qwen3-8B-FP8 \ --quantization fp8 \ --gpu-memory-utilization 0.90 \ --max-model-len 16384 \ --max-num-seqs 64 \ --port 8000 > vllm.log 2>&1 &

日志文件里能看到每次请求的记录，排查问题比盯着 SSH 窗口方便得多。如果你希望 Windows 开机后自动进入 WSL 并启动模型服务，可以考虑配置计划任务，触发命令是wsl -d Ubuntu-22.04 -u 你的用户名 -- bash -lc "source ~/miniconda3/etc/profile.d/conda.sh && conda activate vllm && nohup vllm serve ..."。我第一次跑通后就把启动命令存成了run_vllm.sh，后续每次部署只需要执行这个脚本，省去重复查参数的时间。

最后分享一个小习惯：第一次跑通后，不要急着压测并发，先拿默认参数跑几个真实请求，确认生成质量符合预期，再逐步调大max-num-seqs和max-model-len。我在 4090 上从 16 并发调到 64 并发时，观察到的总吞吐有明显提升，但单请求首 token 延迟也从几十毫秒涨到了几百毫秒。所谓调优，本质上就是在吞吐、内存和延迟之间找平衡点，而找到这个点的唯一办法，就是对照日志和监控里的真实数据做判断。