2. 环境搭建

2.1 环境准备的核心原则

vLLM 是一个依赖 GPU 高性能计算能力的推理引擎，其吞吐优势建立在 CUDA 生态的底层算子优化之上。因此，环境搭建的核心原则是：先驱动、再 CUDA、后 Python 包。驱动决定了 GPU 能否被操作系统识别，CUDA 工具链决定了 PyTorch 能否调用 GPU 算子，而 vLLM 本身则通过 PyTorch 与 CUDA 运行时交互。三者版本必须形成一条兼容链，任何一环脱节都会导致推理时出现“非法内存访问”或“算子不存在”等难以排查的错误。

2.2 安装步骤详解

步骤一：确认 GPU 驱动与 CUDA 版本

在安装任何 Python 包之前，首先确认物理机 GPU 驱动是否已正确加载。执行以下命令：

nvidia-smi

输出应包含 GPU 型号、显存容量以及右上角的 CUDA Version 字段。该字段表示当前驱动支持的最高 CUDA 版本，而非系统已安装的 CUDA 工具包版本。例如，若显示 CUDA Version: 12.2，则说明驱动足以支持 CUDA 12.x 的 PyTorch 预编译包。

若 nvidia-smi 提示命令不存在，则需要先安装 NVIDIA 驱动。在 Ubuntu 系统上可通过以下方式安装：

sudo apt update
sudo apt install nvidia-driver-535
sudo reboot

安装完成后再次运行 nvidia-smi，确认 GPU 已被识别。

步骤二：安装 CUDA 工具包（可选但推荐）

虽然 PyTorch 的 pip 包会自带 CUDA 运行时库，但编译自定义算子或使用某些扩展功能时仍需要完整的 CUDA 工具包。推荐安装与 PyTorch 编译版本一致的 CUDA：

wget https://developer.download.nvidia.com/compute/cuda/12.1.0/local_installers/cuda_12.1.0_530.30.02_linux.run
sudo sh cuda_12.1.0_530.30.02_linux.run --toolkit --silent --override

安装后配置环境变量：

export PATH=/usr/local/cuda-12.1/bin:$PATH
export LD_LIBRARY_PATH=/usr/local/cuda-12.1/lib64:$LD_LIBRARY_PATH

验证 CUDA 工具包是否安装成功：

nvcc --version

步骤三：创建 Python 虚拟环境并安装 PyTorch

强烈推荐使用 conda 或 venv 创建独立环境，避免系统 Python 环境被污染：

conda create -n vllm-env python=3.10 -y
conda activate vllm-env

# 安装与 CUDA 12.1 匹配的 PyTorch
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121

验证 PyTorch 能否调用 GPU：

python -c "import torch; print(torch.__version__); print(torch.cuda.is_available()); print(torch.cuda.get_device_name(0))"

预期输出类似：

2.1.2+cu121
True
NVIDIA GeForce RTX 3090

步骤四：安装 vLLM

在 PyTorch 验证通过后，直接通过 pip 安装 vLLM：

pip install vllm

若网络环境受限，可使用国内镜像源加速：

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

安装完成后，检查 vLLM 版本：

python -m vllm --version

2.3 安装验证与冒烟测试

环境是否真正可用，不能只看安装日志。建议执行一次完整的小模型推理冒烟测试，验证 GPU 算子、显存管理、调度器三个核心组件是否正常工作。

使用 facebook/opt-125m 这样的小模型进行测试（约 500MB），既能快速验证环境，又不会占用过多显存：

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=50))
print(output[0].outputs[0].text)
"

若输出为一段通顺的英文文本且无报错，说明 vLLM 已能正常调用 GPU 完成推理。此时可进一步查看 GPU 显存占用情况：

nvidia-smi

应能看到 Python 进程占用了约 40% 的显存（由 gpu_memory_utilization=0.4 控制）。

2.4 环境配置清单与常见问题复盘