Windows 通过 WSL2 部署 vLLM 的关键步骤

在 Windows 上部署 vLLM，比较稳妥的方式是通过 WSL2 跑 Linux 环境，再把推理服务暴露给 Windows 侧的客户端。这样可以保留 Windows 的日常使用体验，同时利用 Linux 生态里的 CUDA、PyTorch 和 vLLM。

Windows + WSL2 + vLLM 部署栈

为什么不用纯 Windows 环境

vLLM 的核心依赖和主流部署经验都更偏 Linux。直接在 Windows 原生环境里折腾，容易遇到 CUDA、PyTorch、编译依赖、包版本不匹配等问题。

WSL2 的优势是：

使用 Linux Python 生态。
Windows 侧仍然可以正常管理文件和客户端。
NVIDIA 驱动可以透传给 WSL2。
服务可以通过 localhost 被 Windows 应用访问。

因此更推荐的架构是：Windows 管理桌面和文件，WSL2 承担推理运行时。

部署架构

Windows 宿主机
├─ NVIDIA 驱动
├─ 模型文件目录
├─ Cherry Studio / 浏览器 / API 客户端
└─ WSL2 Ubuntu
   ├─ CUDA Toolkit
   ├─ Miniconda / Python
   ├─ vLLM
   └─ OpenAI 兼容 API 服务

关键点是：Windows 侧安装支持 WSL2 的 NVIDIA 驱动，Linux 侧安装 CUDA Toolkit 和 Python 环境，然后用 vLLM 启动推理服务。

基本步骤

启用 WSL2。
安装 Ubuntu 发行版。
在 Windows 侧安装 NVIDIA 驱动。
在 WSL2 中确认 nvidia-smi 可用。
安装 Miniconda，创建独立 Python 环境。
安装 vLLM。
下载模型到 Windows 分区或 WSL2 文件系统。
启动 OpenAI 兼容 API。
在 Cherry Studio 等客户端中配置本地 API 地址。

检查 GPU：

nvidia-smi

创建环境：

conda create -n vllm python=3.12 -y
conda activate vllm
pip install vllm

启动服务：

python -m vllm.entrypoints.openai.api_server \
  --model /mnt/d/Models/Qwen2.5-7B-Instruct \
  --host 0.0.0.0 \
  --port 8000

Windows 侧访问：

http://localhost:8000/v1

显存参考

模型	FP16 显存参考	推荐 GPU
Qwen2.5-1.5B	约 3 GB	RTX 2060+
Qwen2.5-3B	约 6 GB	RTX 3060 / 4060
Qwen2.5-7B	约 14 GB	RTX 3090 / 4090
Qwen2.5-14B	约 28 GB	双卡 3090 或 A100

实际占用会受上下文长度、并发、量化方式和 KV cache 影响。显存不够时，优先降低 max-model-len，或选择 AWQ/GPTQ 等量化模型。

示例：

python -m vllm.entrypoints.openai.api_server \
  --model /mnt/d/Models/Qwen2.5-7B-Instruct-AWQ \
  --max-model-len 8192 \
  --gpu-memory-utilization 0.85 \
  --port 8000

客户端接入

vLLM 提供 OpenAI 兼容 API，因此可以接入很多客户端。以 Cherry Studio 为例，通常填写：

配置项	值
API Base	`http://localhost:8000/v1`
API Key	本地服务可填任意占位
Model	与 vLLM 启动模型名一致

如果 Windows 侧访问不到服务，先检查：

vLLM 是否仍在运行。
是否监听 0.0.0.0 而不是只监听 WSL 内部地址。
防火墙是否拦截。
WSL2 网络是否异常。

常见避坑

问题	处理方式
`nvidia-smi` 不可用	检查 Windows NVIDIA 驱动和 WSL2 版本
pip 下载慢	使用国内镜像源
模型下载慢	尝试 ModelScope 或提前离线下载
显存不足	降低上下文长度、换小模型或使用量化
WSL 磁盘膨胀	配置 sparse VHD，并定期清理缓存
首次回答慢	模型加载和 KV cache 初始化需要时间

本地部署的价值不只是省 API 费用，更重要的是保留数据在本机，并且可以和本地知识库、桌面客户端、开发工具组合成自己的 AI 工作流。

但它不适合所有人。如果只是日常问答，云端模型更省心；如果你需要隐私、可控成本、开源模型实验和本地工具链集成，vLLM 才值得投入部署成本。