【笔记】在 Windows 上安装 Python-vLLM

SystemPanic/vllm-windows：用于 LLM（Windows 构建和内核）的高吞吐量和内存效率推理和服务引擎

在 Windows 上安装 vLLM 有两种方式，分别是通过已发布的 wheel 包安装和从源码构建安装，具体步骤如下：

一、通过现有发布的 wheel 包安装（推荐）

发布 v0.11.0 ·SystemPanic/vllm-windows

vllm-0.11.0+cu124-cp312-cp312-win_amd64.whl

1. 确认版本兼容性
   确保你的 Python、PyTorch 和 CUDA 版本与 wheel 包要求一致（版本信息会在发布版本中注明）。
2. 下载 wheel 包
   从 最新发布页面 下载作者提供的版本（经测试：torch 和 CUDA 版本高于发布版，也能安装成功，但安装过程中会大量拉取安装其他依赖，可能会导致部分依赖被安装成与环境中其他库相冲突的版本，如 triton_windows、xformers 等，后期可能需要手动修复冲突）。

安装 wheel 包
打开命令行，使用 pip 安装下载的 wheel 文件：

pip install vllm-0.11.0+cu124-cp312-cp312-win_amd64.whl 

（注意替换为实际下载的 wheel 文件路径和文件名）

二、从源码构建安装（不推荐）

前置要求

• 安装 Visual Studio 2019 或更高版本（需用于编译环境）。
• 安装 CUDA 并配置环境变量（如 CUDA_ROOT、CUDA_HOME 或 CUDA_PATH，确保系统能识别 CUDA 路径）。

步骤

安装依赖并构建

# 安装指定版本的 PyTorch（以 CUDA 12.6 为例，需与你的 CUDA 版本匹配） 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 # 构建并安装 vLLM pip install . --no-build-isolation 

设置环境变量
必要的环境变量配置：

set DISTUTILS_USE_SDK=1 set VLLM_TARGET_DEVICE=cuda set MAX_JOBS=10 # 并行编译的 CPU 线程数，可根据实际情况调整 

（可选）如需启用 cuDNN、cuSPARSELt 等功能，需额外设置对应路径：

# 启用 cuDNN（替换为实际安装路径） set USE_CUDNN=1 set CUDNN_LIBRARY_PATH=PATH_TO_CUDNN_INSTALL_DIR\lib\CUDNN_CUDA_VERSION\x64 set CUDNN_INCLUDE_PATH=PATH_TO_CUDNN_INSTALL_DIR\include\CUDNN_CUDA_VERSION # 启用 cuSPARSELt（替换为实际安装路径） set USE_CUSPARSELT=1 set CUSPARSELT_INCLUDE_PATH=PATH_TO_CUSPARSELT_INSTALL_DIR\include set CUSPARSELT_LIBRARY_PATH=PATH_TO_CUSPARSELT_INSTALL_DIR\lib 

配置 Visual Studio 编译环境
运行 Visual Studio 的 vcvarsall.bat 以初始化 x64 编译环境（替换为你的 VS 安装路径）：

VISUAL_STUDIO_INSTALL_PATH\VC\Auxiliary\Build\vcvarsall.bat x64 

打开命令行并克隆仓库

# 克隆 vllm-windows 仓库（指定分支） git clone --single-branch --branch vllm-for-windows https://github.com/SystemPanic/vllm-windows.git cd vllm-windows 

注意事项

• 从源码构建时，Flash Attention v3 默认在 Windows 上禁用（因编译时间过长），如需强制启用，可设置环境变量 set VLLM_FORCE_FA3_WINDOWS_BUILD=1。
• 确保所有路径中的占位符（如 PATH_TO_CUDNN_INSTALL_DIR）替换为实际安装路径。
• 若遇到编译或安装错误，建议检查依赖版本兼容性，并参考官方仓库的 issue 或文档进一步排查。