📚 课程目录第2章环境搭建

2、环境搭建：安装vLLM、依赖项、GPU要求、验证安装

2.1 环境准备的核心原则

在动手安装vLLM之前，需要先明确一个关键认知：vLLM不是纯CPU推理框架，它高度依赖GPU的显存带宽和计算能力。虽然vLLM在CPU上也能运行（用于调试），但实际生产环境中的吞吐量优势完全建立在NVIDIA GPU的CUDA生态之上。因此，环境搭建的第一原则是——先确认GPU，再安装软件，避免在硬件不满足要求时浪费大量时间排查编译错误。

vLLM的安装路径主要分为两种：预编译wheel包安装（推荐）和源码编译安装（需要定制或开发时使用）。对于绝大多数入门场景，直接使用pip安装预编译包即可，无需从源码编译，这能显著降低环境搭建的复杂度。

版本匹配提示：vLLM对Python版本和CUDA版本有严格约束。当前主流版本要求Python 3.9～3.12，CUDA 11.8或12.1+。安装前务必使用 python --version 和 nvidia-smi 确认版本，避免后续出现“找不到CUDA驱动”或“算子编译失败”的报错。

2.2 安装步骤详解

2.2.1 第一步：检查GPU与驱动

打开终端，执行以下命令确认GPU状态：

# 查看GPU型号、驱动版本、CUDA版本
nvidia-smi

# 输出示例（关键信息）：
# +-----------------------------------------------------------------------------+
# | NVIDIA-SMI 535.104.05   Driver Version: 535.104.05   CUDA Version: 12.2     |
# |-------------------------------+----------------------+----------------------+
# | GPU  Name        Persistence-M| Bus-Id        Disp.A | Volatile Uncorr. ECC |
# |   0  NVIDIA A100-PCIE-40GB    | On  | 00000000:3B:00.0 |  Off                 |
# +-------------------------------+----------------------+----------------------+
# | 40GB  On  | 00000000:3B:00.0  | Off | 0 | N/A |
# +-------------------------------+----------------------+----------------------+

重点关注三个信息：GPU型号（决定算力等级）、Driver Version（需≥525）、CUDA Version（这是驱动支持的最高CUDA版本，而非当前激活的CUDA）。如果驱动版本过低，需要先升级NVIDIA驱动。

2.2.2 第二步：创建Python虚拟环境

强烈建议使用虚拟环境隔离vLLM及其依赖，避免污染系统Python环境。推荐使用conda或venv：

# 使用conda创建环境（推荐）
conda create -n vllm-env python=3.10 -y
conda activate vllm-env

# 或使用venv（Python自带）
python -m venv vllm-env
source vllm-env/bin/activate  # Linux/Mac
# vllm-env\Scripts\activate   # Windows

2.2.3 第三步：安装vLLM

激活虚拟环境后，直接使用pip安装预编译包：

# 安装最新稳定版
pip install vllm

# 如需安装特定版本（例如0.6.3）
pip install vllm==0.6.3

# 如需安装CPU版本（仅调试用，性能极低）
pip install vllm-cpu

安装过程中，pip会自动拉取以下核心依赖：torch（PyTorch）、transformers（HuggingFace模型库）、fastapi（API服务）、uvicorn（ASGI服务器）、pydantic（数据校验）、openai（OpenAI兼容接口）等。如果网络环境不佳，可以配置国内镜像源加速：

pip install vllm -i https://pypi.tuna.tsinghua.edu.cn/simple

2.3 验证安装是否成功

安装完成后，必须进行功能验证，确保vLLM能正常导入并识别GPU。执行以下Python代码：

# 验证vLLM版本和GPU可用性
python -c "
import vllm
print('vLLM版本:', vllm.__version__)

from vllm import LLM
# 使用一个极小模型测试（约100MB）
llm = LLM(model='facebook/opt-125m', gpu_memory_utilization=0.3)
output = llm.generate(['Hello, my name is'])
print('生成结果:', output[0].outputs[0].text)
print('✅ vLLM安装成功，GPU推理正常！')
"

如果输出类似以下内容，说明安装成功：

vLLM版本: 0.6.3.post1
INFO 06-10 15:30:22 llm_engine.py:162] Initializing an LLM engine with config:
model='facebook/opt-125m', dtype=torch.float16, max_num_seqs=256, ...
INFO 06-10 15:30:25 model_runner.py:512] Loading model weights took 0.45 GB
生成结果:  I am a language model
✅ vLLM安装成功，GPU推理正常！

常见验证失败场景：如果出现 CUDA error: no kernel image is available for execution on the device，说明vLLM的预编译包与你的GPU架构不匹配（例如在较老的Pascal架构GPU上运行）。此时需要从源码编译，或更换GPU。如果出现 torch.cuda.OutOfMemoryError，说明显存不足，需要减小 gpu_memory_utilization 参数或更换更大显存的GPU。

2.4 依赖项清单与版本要求

下表汇总了vLLM的核心依赖项及其作用，方便排查问题时快速定位：

依赖项	版本要求	作用说明
Python	3.9 ~ 3.12	vLLM运行的基础解释器
PyTorch	≥2.0.0（推荐2.1+）	深度学习张量计算与GPU算子调度
transformers	≥4.36.0	加载HuggingFace预训练模型与分词器
CUDA Toolkit	11.8 / 12.1+	GPU并行计算库，vLLM的PagedAttention依赖
NVIDIA驱动	≥525.60.13	驱动GPU硬件，必须与CUDA版本兼容
fastapi / uvicorn	最新版即可	提供OpenAI兼容的RESTful API服务
pydantic	≥2.0	请求参数的数据校验与序列化
ray	≥2.5（多GPU时）	分布式推理的集群管理与调度

2.5 常见安装误区与复盘

  误区一：忽略CUDA版本匹配。很多初学者直接 pip install vllm，却不知道vLLM的预编译包是针对特定CUDA版本编译的。如果系统CUDA是11.8，而vLLM包要求12.1，就会出现“找不到libcudart.so”或“CUDA driver version is insufficient”的错误。正确做法是：先查看 nvidia-smi 中的CUDA版本，再选择对应的vLLM版本。例如CUDA 11.8对应 pip install vllm==0.4.2，CUDA 12.1+对应最新版。

  误区二：在系统Python中直接安装。不使用虚拟环境会导致依赖冲突，例如系统已有旧版torch，vLLM安装时强制升级torch，可能破坏其他项目的运行环境。更严重的是，如果系统Python是3.8或3.13，vLLM直接拒绝安装。务必使用conda或venv创建独立环境。

  误区三：忽略显存预留。vLLM默认会占用GPU约90%的显存（通过 gpu_memory_utilization 参数控制）。如果GPU同时运行其他任务（如Jupyter Notebook的GPU内核），会导致OOM。建议在验证时显式设置 gpu_memory_utilization=0.5，为其他进程预留空间。

复盘建议：如果安装过程中遇到问题，不要盲目重装。先执行 pip list | grep -E "torch|vllm|transformers" 查看已安装版本，再检查 nvidia-smi 的驱动状态。90%的安装问题都可以归结为“版本不匹配”或“驱动过旧”两类原因。按照“硬件→驱动→CUDA→Python→vLLM”的层级顺序逐层排查，能最快定位问题根源。