Windows 环境下 vLLM 安装与构建指南
在 Windows 系统上部署 vLLM 引擎，目前主要有两种路径：使用预编译的 wheel 包直接安装，或者从源码进行构建。前者适合快速验证，后者则能提供更灵活的控制权。
一、通过 Wheel 包安装（推荐）
这种方式最便捷，但需要确保本地环境与发布包的版本要求匹配。
1. 确认版本兼容性
下载前请核对 Python、PyTorch 和 CUDA 的版本。发布页面通常会注明支持的版本范围。虽然有时高版本也能安装成功，但可能会拉取大量依赖，导致 triton_windows、xformers 等库与现有环境冲突，后期修复成本较高。
2. 下载并安装
前往 GitHub 发布页获取最新的 wheel 文件。以 v0.11.0 为例：
在终端中执行 pip 安装命令，记得替换为实际的文件路径：
pip install vllm-0.11.0+cu124-cp312-cp312-win_amd64.whl
安装完成后，建议检查基础导入是否正常。
二、从源码构建安装
如果你需要特定功能或想深入理解底层，可以选择源码构建。这通常比较耗时，且对开发环境有明确要求。
前置准备
- Visual Studio：需安装 2019 或更高版本，用于 C++ 编译。
- CUDA：安装对应版本的 CUDA Toolkit，并确保环境变量（如
CUDA_ROOT、CUDA_HOME）配置正确，让系统能识别路径。
构建步骤
1. 克隆仓库与初始化
首先克隆支持 Windows 的分支：
git clone --single-branch --branch vllm-for-windows https://github.com/SystemPanic/vllm-windows.git
cd vllm-windows
2. 安装依赖
根据你本地的 CUDA 版本安装对应的 PyTorch。例如 CUDA 12.6：
pip install torch==2.7.1+cu126 torchaudio==2.7.1+cu126 torchvision==0.22.1+cu126 --index-url https://download.pytorch.org/whl/cu126
如果环境中已有兼容的 PyTorch，可以运行脚本来复用：
python use_existing_torch.py
接着安装构建所需的依赖：
pip install -r requirements/build.txt
pip install -r requirements/windows.txt
3. 设置编译环境
构建前需要配置关键的环境变量。特别是并行编译线程数，可根据 CPU 核心数调整：
set DISTUTILS_USE_SDK=1
set VLLM_TARGET_DEVICE=cuda
set MAX_JOBS=10
如果需要启用 cuDNN 或 cuSPARSELt 加速，还需指定具体路径：
# 示例：启用 cuDNN
set USE_CUDNN=1
set CUDNN_LIBRARY_PATH=C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v12.4\lib\x64
set CUDNN_INCLUDE_PATH=C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v12.4\include
然后初始化 Visual Studio 的 x64 编译环境（路径需根据你的实际安装位置修改）：
"C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\VC\Auxiliary\Build\vcvarsall.bat" x64
4. 开始构建
最后执行安装命令，注意加上 --no-build-isolation 参数以避免隔离环境导致的依赖问题：
pip install . --no-build-isolation
注意事项
- Flash Attention v3：默认情况下在 Windows 上会被禁用，因为编译时间过长。若必须启用，可设置环境变量
VLLM_FORCE_FA3_WINDOWS_BUILD=1。 - 路径占位符：所有示例中的路径（如
PATH_TO_CUDNN_INSTALL_DIR）都必须替换为你机器上的真实路径。 - 错误排查：遇到编译失败时，优先检查依赖版本是否匹配，并参考官方仓库的 Issue 列表寻找解决方案。
