# vLLM-Windows-Installing-Script

**Repository Path**: zhider/vLLM-Windows-Installing-Script

## Basic Information

- **Project Name**: vLLM-Windows-Installing-Script
- **Description**: 在Windows中自动安装vLLM及其依赖，面向国内网络环境。
- **Primary Language**: Python
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-05
- **Last Updated**: 2026-06-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# vLLM Windows 自动安装工具

在 Windows 系统上自动安装 [vLLM](https://github.com/vllm-project/vllm) 0.21.0 + CUDA 13.2 的一键式解决方案。Release 版中包含嵌入式 Python 3.12.10 便携环境，无需预装 Python，开箱即用。

## 主要特性

- **完全便携** — Release 版中包含嵌入式 Python 3.12.10，无需系统级 Python
- **一键安装** — 双击 `install.bat` 即可自动完成全部安装
- **清华镜像加速** — 默认使用清华大学 PyPI 镜像，下载速度快

## 前提条件

| 依赖 | 说明 |
| --- | --- |
| **NVIDIA GPU** | 支持 CUDA 的 NVIDIA 显卡（计算能力 7.0+ 推荐） |
| **NVIDIA 驱动** | 支持 CUDA 13.x 的驱动版本 |
| **磁盘空间** | 约 10 GB（包含 Python、PyTorch、vLLM 及全部依赖） |

## 快速开始

### 1. 获取项目

```bash
git clone https://github.com/your-username/vllm-windows-self-setup.git
cd vllm-windows-self-setup
```

或直接下载 ZIP 压缩包并解压。

### 2. 运行安装

**方式一：自包含 Python标准安装**

双击 `install.bat`。

安装过程分为 4 个步骤：

```
[1/4] 安装 pip...         → 使用 get-pip.py 为嵌入式 Python 安装 pip
[2/4] 安装 setuptools...  → 安装 setuptools==80.10.2
[3/4] 安装 Python 包...   → 从 PyPI 清华镜像安装 150+ 个依赖包
[4/4] 下载 Python 包...   → 下载 vLLM、PyTorch、FlashInfer 等外部 Wheel
```

安装成功后会自动进入虚拟环境命令行（提示符显示 `(vllm)`）。

**方式二：使用 uv（更快）**

如果已安装 [uv](https://github.com/astral-sh/uv)，可运行 `install_uv.bat`，利用 uv 的并行下载能力加速安装。

### 3. 激活环境

如果退出后需要重新进入环境，双击 `activate.bat` 即可。

```bash
# 激活后提示符变为 (vllm)
(vllm) D:\path\to\vllm-windows-self-setup>
```

### 4. 验证安装

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

应输出 `0.21.0`。

```bash
python -c "import torch; print(torch.__version__); print(torch.cuda.is_available())"
```

应输出 `2.11.0+cu130` 和 `True`（如果有 NVIDIA GPU）。

## 目录结构

```
vllm-windows-self-setup/
├── activate.bat               # 激活 vLLM 便携环境
├── install.bat                # 一键安装脚本（入口）
├── install_activated.bat      # 在已激活环境中的安装脚本
├── install_uv.bat             # 使用 uv 的安装脚本
├── downloade_outer.py         # 外部 Wheel 下载器（vLLM、PyTorch 等）
├── get-pip.py                 # pip 安装引导程序
├── req-pypi.txt               # PyPI 依赖清单（150+ 个包）
├── req-outer.txt              # 外部 Wheel 下载地址清单
├── python-3.12.10-embed-amd64/ # 嵌入式 Python 3.12.10 便携环境
│   ├── python.exe
│   ├── python312.dll
│   ├── python312._pth
│   ├── Scripts/               # pip 等可执行文件安装目录
│   └── Lib/                   # 标准库
└── pkgs/                      # （安装后生成）下载的 Wheel 包缓存
```

## 安装原理

### 工作流程

```
install.bat
    │
    ├── 1. 设置环境变量
    │   ├── PYTHONPATH=           → 清空，防止污染
    │   ├── PYTHONHOME=           → 清空，强制使用嵌入式 Python
    │   ├── PYTHONUSERBASE=       → 清空，禁用用户 site-packages
    │   ├── PYTHONNOUSERSITE=1    → 禁用系统 site-packages
    │   ├── PATH 指向嵌入式 Python
    │   └── cd 到脚本所在目录
    │
    ├── 2. 安装 pip
    │   └── python get-pip.py     → 为嵌入式 Python 安装 pip 26.1.2
    │
    ├── 3. 安装 setuptools
    │   └── pip install setuptools==80.10.2
    │
    ├── 4. 安装 PyPI 依赖
    │   └── pip install -r req-pypi.txt --no-deps
    │       ├── 使用清华镜像加速
    │       └── --no-deps 禁用自动依赖解析，完全依赖清单保证一致性
    │
    ├── 5. 下载外部 Wheel
    │   └── python downloade_outer.py
    │       ├── 读取 req-outer.txt 中的 URL
    │       ├── 下载到 pkgs/ 目录缓存
    │       └── 自动 pip install 每个 Wheel
    │
    └── 6. 进入 vLLM 环境
        └── cmd 提示符显示 (vllm)
```

### 依赖来源

| 来源 | 镜像/仓库 | 内容 |
| --- | --- | --- |
| **req-pypi.txt** | `https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple` | 150+ 个常规 PyPI 包 |
| **req-outer.txt** | GitHub Releases / NJU 镜像 | vLLM、PyTorch、TorchAudio、TorchVision、FlashInfer |

### 环境隔离

嵌入式 Python 通过以下机制实现完全隔离：
- `python312._pth` — 控制模块搜索路径，不搜索注册表和环境变量
- 清空 `PYTHONPATH` / `PYTHONHOME` / `PYTHONUSERBASE`
- 设置 `PYTHONNOUSERSITE=1` — 完全禁用系统 site-packages


## 可用脚本

| 命令 | 说明 |
| --- | --- |
| `install.bat` | 一键安装主脚本（推荐） |
| `install_uv.bat` | 使用 uv 包管理器的安装脚本 |
| `install_activated.bat` | 已激活环境中的安装脚本 |
| `activate.bat` | 激活便携 Python 环境 |

## 验证与测试

### 基础验证

```bash
# 检查 Python 版本
python --version
# 输出: Python 3.12.10

# 检查 vLLM
python -c "import vllm; print(vllm.__version__)"
# 输出: 0.21.0

# 检查 PyTorch CUDA
python -c "import torch; print(f'PyTorch: {torch.__version__}'); print(f'CUDA available: {torch.cuda.is_available()}'); print(f'GPU count: {torch.cuda.device_count()}')"

# 检查 GPU 信息
python -c "import torch; [print(f'GPU {i}: {torch.cuda.get_device_name(i)}') for i in range(torch.cuda.device_count())]"
```

### 运行 vLLM 推理测试

```python
# test_vllm.py
from vllm import LLM, SamplingParams

# 加载模型
llm = LLM(model="Qwen/Qwen2.5-1.5B-Instruct")

# 配置采样参数
sampling_params = SamplingParams(temperature=0.7, top_p=0.9, max_tokens=512)

# 推理
outputs = llm.generate(["Hello, what is AI?"], sampling_params)

# 输出结果
for output in outputs:
    print(f"Prompt: {output.prompt}")
    print(f"Generated: {output.outputs[0].text}")
```

## 常见问题

### Q: 安装过程中下载失败/超时

A: 国内网络访问 GitHub Release 可能不稳定。`downloade_outer.py` 已内置 `gh-proxy.org` 代理，如果仍然失败：
- 手动从 `req-outer.txt` 中的 URL 下载对应 Wheel 文件
- 放入 `pkgs/` 目录
- 重新运行 `install.bat`

### Q: 找不到 CUDA / `torch.cuda.is_available()` 返回 `False`

A: 确保：
1. 安装了支持 CUDA 13.x 的 NVIDIA 驱动（版本 ≥ 550.0）
2. 驱动已正确识别 GPU（`nvidia-smi` 命令可查看）

### Q: 如何更换 PyPI 镜像源？

A: 编辑 `install.bat`，将 `-i` 参数后的 URL 替换为其他镜像源，例如：
- 阿里云: `https://mirrors.aliyun.com/pypi/simple`
- 华为云: `https://mirrors.huaweicloud.com/repository/pypi/simple`
- 豆瓣: `https://pypi.doubanio.com/simple`

### Q: 如何卸载？

A: 直接删除整个 `vllm-windows-self-setup` 目录即可。所有文件均为便携式，不会在系统中留下痕迹。

## 许可

本项目中的脚本和配置文件采用 MIT 许可。vLLM、PyTorch、FlashInfer 等第三方组件遵循其各自的许可协议。

## 致谢

- [vLLM](https://github.com/vllm-project/vllm) — 高性能 LLM 推理引擎
- [SystemPanic/vllm-windows](https://github.com/SystemPanic/vllm-windows) — vLLM Windows 移植版
- [SystemPanic/flashinfer-windows](https://github.com/SystemPanic/flashinfer-windows) — FlashInfer Windows 移植版
- 清华大学 TUNA 镜像站 — PyPI 镜像加速
- 南京大学 NJU 镜像站 — PyTorch CUDA Wheel 镜像