2、环境准备：安装vLLM、配置GPU环境、验证安装版本

在动手实践vLLM版本升级之前，必须先搭建一个干净、可控、可复现的实验环境。很多升级后出现的“性能下降”或“启动报错”，根源往往不在vLLM本身，而是GPU驱动、CUDA运行时、Python包依赖或容器镜像之间版本错配。本节将按照“GPU驱动与容器检查 → Python虚拟环境创建 → vLLM安装 → 版本与功能验证”的顺序，完成环境准备，并重点说明如何避免常见的环境陷阱。

2.1 核心原理：vLLM运行时的三层依赖关系

vLLM不是一个纯Python库，它通过PyTorch调用CUDA内核，而CUDA运行时又依赖GPU驱动。因此，环境是否健康取决于以下三层是否匹配：

• 物理层（GPU驱动）：NVIDIA驱动与GPU型号对应，驱动版本决定了支持的最高CUDA版本。例如，驱动版本≥525时才能支持CUDA 12.0。
• 运行时层（CUDA/PyTorch）：vLLM针对特定CUDA版本编译了算子（如FlashAttention、PagedAttention）。PyTorch的CUDA版本必须与vLLM的预编译轮子兼容。
• 应用层（Python包）：vLLM对Python版本、transformers、tokenizers等库有明确要求。版本过旧或过新都可能触发兼容性错误。

下图展示了这三层依赖关系以及验证命令的对应位置，帮助你在排查问题时快速定位故障层：

2.2 方法流程：从零搭建vLLM实验环境

以下流程假设你使用Linux服务器（Ubuntu 20.04/22.04）并拥有root或sudo权限。若使用Docker，可跳过步骤1和2，直接拉取官方镜像 vllm/vllm-openai。

步骤1：检查GPU驱动与硬件

# 查看GPU型号与驱动信息
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 |                  Off |
# +-------------------------------+----------------------+----------------------+

如果 nvidia-smi 报错或显示“No devices were found”，请先安装匹配的NVIDIA驱动，不要继续后续步骤。

步骤2：创建Python虚拟环境

推荐使用 conda 或 python -m venv 创建独立环境，避免污染系统Python。以下以conda为例：

# 创建Python 3.10环境（vLLM 0.6+ 推荐）
conda create -n vllm_env python=3.10 -y
conda activate vllm_env

# 升级pip并安装PyTorch（以CUDA 12.1为例）
pip install --upgrade pip
pip install torch==2.1.2 torchvision==0.16.2 torchaudio==2.1.2 --index-url https://download.pytorch.org/whl/cu121

步骤3：安装vLLM

# 安装vLLM（推荐使用pip获取预编译轮子）
pip install vllm

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

# 如需从源码安装（用于开发调试，不推荐生产环境）
# git clone https://github.com/vllm-project/vllm.git
# cd vllm
# pip install -e .

步骤4：验证安装版本与功能

# 检查vLLM版本
python -c "import vllm; print('vLLM版本:', vllm.__version__)"

# 检查CUDA是否可用
python -c "import torch; print('CUDA可用:', torch.cuda.is_available()); print('CUDA版本:', torch.version.cuda)"

# 运行最小推理测试（使用OPT-125M模型）
python -c "
from vllm import LLM, SamplingParams
llm = LLM(model='facebook/opt-125m', gpu_memory_utilization=0.4)
output = llm.generate(['Hello, my name is'], SamplingParams(max_tokens=20))
print(output[0].outputs[0].text)
"

如果上述命令均成功执行，说明环境已就绪。若最后一步推理测试报错，请检查GPU显存是否足够（建议≥8GB）以及 gpu_memory_utilization 参数是否设置合理。

2.3 案例：一次典型的版本升级环境准备

假设你当前环境为 vLLM 0.4.2 + PyTorch 2.0.1 + CUDA 11.8，需要升级到 vLLM 0.6.3 + PyTorch 2.2.1 + CUDA 12.1。以下是完整的操作序列：

2.4 误区与复盘：环境准备中的常见陷阱

根据社区反馈和实际项目经验，以下环境问题最容易导致vLLM升级失败或性能异常：

• 误区1：忽略驱动版本上限。驱动版本过旧时，即使安装了新版CUDA工具包，vLLM仍无法调用GPU。复盘：升级前务必确认驱动支持目标CUDA版本，必要时先升级驱动。
• 误区2：在系统Python中直接安装。系统Python常被其他项目占用，依赖冲突难以排查。复盘：始终使用虚拟环境，并记录 pip freeze 快照。
• 误区3：混用不同CUDA版本的PyTorch和vLLM。例如PyTorch使用cu118编译，而vLLM使用cu121轮子，会导致“undefined symbol”错误。复盘：统一使用同一CUDA版本（如cu121）的轮子。
• 误区4：显存不足导致推理测试失败。vLLM默认会占用约90%的显存，小显存GPU（如8GB）容易OOM。复盘：设置 gpu_memory_utilization=0.4 或使用更小的测试模型。
• 误区5：升级后未清理旧缓存。PyTorch的JIT缓存或vLLM的编译缓存可能导致新版本加载旧内核。复盘：升级后删除 ~/.cache/torch 和 ~/.cache/vllm 目录。