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

2. 环境搭建

在深入多模型批处理调度策略之前，必须先构建一个稳定、可复现的vLLM运行环境。本章节将围绕GPU驱动与CUDA环境确认、vLLM安装、多模型部署前的环境验证三个核心环节展开，确保后续所有调度实验建立在可靠的基础上。

2.1 核心原理：vLLM对GPU环境的依赖关系

vLLM是一个高度依赖GPU算力的推理引擎，其性能发挥取决于三层环境的协同：物理驱动层（NVIDIA驱动）、运行时层（CUDA Toolkit与cuDNN）、Python依赖层（PyTorch与vLLM）。这三层必须版本匹配，否则会出现“装上了但跑不起来”或“能跑但性能极差”的问题。

特别需要注意的是，vLLM通过PagedAttention技术管理KV Cache，该技术依赖GPU的显存寻址能力。如果CUDA版本过旧或驱动不兼容，PagedAttention的显存分配会失败，直接导致进程崩溃。因此，环境搭建的核心原则是：先确认硬件驱动，再安装软件栈，最后用最小模型验证。

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

以下步骤在Ubuntu 20.04/22.04 + NVIDIA GPU环境下验证通过。如果使用Docker，可直接跳至2.2.4节。

2.2.1 确认GPU驱动与CUDA版本

首先执行以下命令，确认物理环境是否满足vLLM的最低要求：

# 检查GPU型号与驱动
nvidia-smi

# 输出示例（关键信息）：
# +-----------------------------------------------------------------------------+
# | NVIDIA-SMI 535.154.05   Driver Version: 535.154.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 |                 0 |
# +-------------------------------+----------------------+----------------------+

# 检查CUDA编译器版本
nvcc --version
# 如果提示 nvcc 不存在，说明未安装CUDA Toolkit，需要单独安装

常见误区：很多人以为 nvidia-smi 显示的CUDA版本就是系统已安装的CUDA Toolkit版本。实际上，nvidia-smi 显示的是驱动支持的最高CUDA版本，而非实际安装的版本。vLLM编译时需要 nvcc 可用的CUDA Toolkit，因此必须单独确认 nvcc --version。

2.2.2 安装CUDA Toolkit（如缺失）

如果 nvcc 不可用，需要从NVIDIA官网下载对应版本的CUDA Toolkit。推荐使用runfile方式安装，便于管理路径：

# 以CUDA 12.1为例（下载链接请从NVIDIA官网获取最新）
wget https://developer.download.nvidia.com/compute/cuda/12.1.1/local_installers/cuda_12.1.1_530.30.02_linux.run
sudo sh cuda_12.1.1_530.30.02_linux.run --toolkit --silent --override

# 添加环境变量
echo 'export PATH=/usr/local/cuda-12.1/bin:$PATH' >> ~/.bashrc
echo 'export LD_LIBRARY_PATH=/usr/local/cuda-12.1/lib64:$LD_LIBRARY_PATH' >> ~/.bashrc
source ~/.bashrc

# 验证
nvcc --version

2.2.3 创建Python虚拟环境并安装vLLM

强烈建议使用 conda 或 venv 创建独立环境，避免依赖冲突。vLLM对Python版本要求为 3.8 ~ 3.11：

# 创建conda环境
conda create -n vllm-env python=3.10 -y
conda activate vllm-env

# 安装PyTorch（根据CUDA版本选择对应命令）
# CUDA 12.1:
pip install torch==2.1.2 torchvision==0.16.2 --index-url https://download.pytorch.org/whl/cu121

# 安装vLLM（最新稳定版）
pip install vllm

# 验证安装
python -c "import vllm; print(vllm.__version__)"

2.2.4 使用Docker快速部署（推荐生产环境）

Docker方式可以完全规避驱动和CUDA版本匹配问题，官方镜像已预装所有依赖：

# 拉取vLLM官方镜像（包含CUDA 12.1 + PyTorch + vLLM）
docker pull vllm/vllm-openai:latest

# 启动容器并挂载模型目录
docker run --gpus all \
  -v /data/models:/models \
  -p 8000:8000 \
  --ipc=host \
  --name vllm-test \
  vllm/vllm-openai:latest \
  --model /models/Qwen2.5-7B-Instruct \
  --served-model-name qwen2.5-7b

2.3 案例：多模型批处理前的环境验证清单

在正式进行多模型调度之前，必须完成以下六项验证。每一项都对应后续实验的关键环节，缺一不可。

验证项	命令/操作	预期结果	失败排查方向
GPU驱动	`nvidia-smi`	显示GPU型号，驱动≥535	重装NVIDIA驱动
CUDA Toolkit	`nvcc --version`	显示CUDA 11.8/12.x	安装对应版本Toolkit
PyTorch GPU	`python -c "import torch; print(torch.cuda.is_available())"`	输出 `True`	重装匹配CUDA的PyTorch
vLLM导入	`python -c "import vllm; print(vllm.__version__)"`	输出版本号，无报错	检查Python版本、依赖冲突
显存分配	`python -c "from vllm import LLM; llm = LLM(model='facebook/opt-125m')"`	模型加载成功，显存占用正常	检查显存是否被其他进程占用
推理延迟	调用 `llm.generate(["Hello"])`	响应时间 < 2s	检查GPU频率、CPU瓶颈

  实操建议：对于多模型批处理场景，建议在验证阶段就同时加载两个不同规模的模型（如7B和13B），确认显存分配和GPU利用率正常。这能提前暴露显存碎片化或OOM问题，避免后续调度实验中断。

2.4 误区与复盘：环境搭建中的典型问题

根据社区反馈和实际教学经验，以下三个问题出现频率最高，值得提前规避：

误区一：盲目使用最新版CUDA。vLLM的某些版本对CUDA 12.2+支持不完善，可能导致PagedAttention编译失败。建议优先使用vLLM官方文档中标注的经过验证的CUDA版本（目前为11.8和12.1）。
误区二：忽略共享显存（Shared Memory）配置。多模型批处理时，如果容器或进程的共享内存设置过小（默认64MB），会导致vLLM的tokenizer并行处理崩溃。Docker启动时务必添加 --ipc=host 或 --shm-size=10g。
误区三：用CPU环境测试GPU代码。部分开发者为了快速验证语法，在无GPU的机器上运行 import vllm，虽然导入成功，但实际推理时会抛出 CUDA error: no kernel image available。务必在GPU机器上完成最终验证。

复盘一次真实故障：某学员在A100上安装vLLM 0.4.2后，加载模型时出现 RuntimeError: CUDA error: out of memory。排查后发现，其PyTorch版本为2.0.0（对应CUDA 11.7），而vLLM 0.4.2要求CUDA ≥ 11.8。升级PyTorch至2.1.0（cu121）后问题解决。这再次印证了版本匹配是环境搭建的第一要务。