玩本地大模型推理、搭建私有 LLM 服务，vLLM 绝对是当下最优选择之一！依托 PagedAttention 核心技术，vLLM 相比原生 Transformers 推理速度提升 10~20 倍，显存利用率大幅拉高，支持连续批处理、流式输出，是本地部署大模型、压测推理性能的刚需工具。
很多小伙伴卡在 Windows 安装环节：官方默认优先支持 Linux，Windows 原生安装各种报错、编译失败、CUDA 不兼容、依赖冲突。今天给大家带来Windows 双安装方案，兼顾新手懒人版（WSL2）和原生刚需版，全程实操、零废话，附最全避坑方案。
前置结论（必看）：vLLM 官方并未完整适配 Windows 原生环境，生产/稳定使用优先选 WSL2 子系统方案；仅测试、轻量化使用可选择 Windows 原生编译安装。
一、环境前置要求
1. 硬件要求
- 显卡：NVIDIA 独立显卡（必须支持 CUDA），显存 ≥4G（7B 模型最低门槛，13B 模型建议 8G 以上）
- 系统：Windows 10 2004 版本以上 / Windows 11
2. 软件前置依赖
- Python：3.9~3.12（严格匹配，过高/过低都会编译报错）
- CUDA Toolkit：12.1/12.4（vLLM 主流适配版本，推荐 12.4）
- Git：用于拉取源码（原生编译必备）
- VS 生成工具：Visual Studio Build Tools（Windows 编译 C++ 内核必备）
3. 环境检查命令
打开 CMD/PowerShell 依次执行，确认环境正常：
python --version
nvcc --version
git --version二、方案一：WSL2 安装 vLLM（推荐！稳定无坑）
这是官方推荐 Windows 部署方案，完美兼容 vLLM 所有功能，无编译报错、CUDA 适配完整、性能接近原生 Linux，适合绝大多数用户。
1. 安装 WSL2 + Ubuntu
以管理员身份打开 PowerShell，执行一键安装命令：
wsl --install命令执行完成后重启电脑，自动安装 Ubuntu 子系统，设置用户名和密码即可。
重启后验证 WSL 状态：
wsl --status2. WSL2 配置 CUDA 支持
Windows 端已安装 NVIDIA 显卡驱动即可，WSL2 会自动继承显卡能力，无需单独装驱动。进入 WSL 终端，更新基础依赖：
sudo apt update && sudo apt upgrade -y
sudo apt install python3 python3-pip python3-venv -y3. 新建虚拟环境（核心避坑）
必须使用虚拟环境隔离依赖，避免系统包冲突：
# 创建虚拟环境
python3 -m venv venv-vllm
# 激活环境
source venv-vllm/bin/activate4. 一键安装 vLLM
WSL2 直接安装 CUDA 适配版，无需手动编译：
pip install vllm[cuda] -i https://pypi.tuna.tsinghua.edu.cn/simple等待 2~5 分钟安装完成，无报错即为成功。
5. 启动 vLLM 模型服务
以通义千问、Llama 系列模型为例，执行启动命令，可根据模型参数自行修改：
vllm serve 你的模型路径 \
--served-model-name my-llm \
--max-model-len 8192 \
--trust-remote-code \
--port 8000启动成功后，终端显示服务地址 http://localhost:8000，支持 OpenAI 接口调用、流式对话。
三、方案二：Windows 原生安装 vLLM（源码编译）
适合不想装 WSL2、仅本地测试的用户，原生安装需要手动编译内核，步骤稍复杂，且部分高级功能（部分加速插件）可能不兼容。
1. 安装编译必备工具
安装 Visual Studio Build Tools，勾选「桌面开发使用 C++」组件，安装完成后重启终端。
同时确认 CUDA12.4 已配置系统环境变量。
2. 拉取 vLLM 官方源码
git clone https://github.com/vllm-project/vllm.git
cd vllm3. 创建并激活 Windows 虚拟环境
python -m venv venv-vllm
.\venv-vllm\Scripts\activate4. 安装编译依赖
# 安装基础构建依赖
pip install -r requirements/build.txt
# 安装 Windows 专属依赖
pip install -r requirements/windows.txt
# 复用本地 PyTorch 避免重装
python use_existing_torch.py5. 源码编译安装
pip install . --no-build-isolation编译过程约 5~10 分钟，耐心等待，无报错即安装成功。
6. 验证安装
vllm --version输出版本号代表安装完成。
四、常见报错 & 终极避坑指南
1. 依赖版本冲突（numpy/typing-extensions 报错）
Windows 原生安装高频问题，直接卸载冲突包重装即可：
pip uninstall numpy typing-extensions -y
pip install vllm[cuda]2. CUDA not found / 编译内核失败
原因：CUDA 版本不匹配、未配置环境变量、未安装 VS 编译工具。
解决方案：固定安装 CUDA12.4，重启电脑生效，确保 C++ 编译工具完整安装。
3. 显存溢出 OOM
解决方案：启动命令添加参数，限制序列数、降低上下文长度：
--max-num-seqs 2 --max-model-len 40964. 原生安装 FlashAttention 编译失败
Windows 原生默认禁用 FlashAttention3，属于正常现象，不影响基础推理功能，无需修复。
五、两种方案对比总结
| 方案 | 优点 | 缺点 | 适用场景 |
|---|---|---|---|
| WSL2 安装 | 稳定无报错、功能完整、官方适配、性能拉满 | 需安装子系统，占用少量磁盘空间 | 日常部署、服务搭建、长期使用（首选） |
| Windows 原生安装 | 无需虚拟机、直接本地运行 | 编译复杂、功能阉割、报错多、稳定性差 | 临时测试、快速体验 |
六、写在最后
vLLM 作为大模型推理加速神器，在本地部署、私有化服务、批量推理场景下优势无可替代。Windows 用户不用硬啃原生编译，WSL2 方案省时省力、零坑稳定，完全可以满足绝大多数使用需求。
后续会更新 vLLM 量化模型部署、多模型热切换、接口二次开发、性能调优全套教程，需要的小伙伴可以点赞收藏，持续跟进！
福利提示：评论区留言可获取 Windows vLLM 一键启动脚本、常用模型启动参数模板，开箱即用！
