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

在正式使用 vLLM 之前，我们需要先搭建一个干净、可复现的运行环境。vLLM 是一个与 CUDA 深度绑定的推理引擎，它的安装过程并不复杂，但对 GPU 驱动、PyTorch 版本和 Python 版本有明确的约束。如果这些底层依赖不匹配，即使安装成功，运行时也可能出现“非法内存访问”或“无法加载模型”等难以排查的问题。本节将按照“硬件检查 → 环境准备 → 安装 → 验证”的顺序，带你完成整个搭建流程。

2.1 核心原理：vLLM 的依赖链

vLLM 的性能优势来源于其高度优化的 CUDA kernel（如 PagedAttention 的显存管理内核）。这意味着它并不是一个纯 Python 库，而是包含大量预编译的 CUDA 扩展。因此，安装 vLLM 本质上是在做一次“二进制兼容性匹配”：

  • GPU 驱动：必须支持目标 CUDA 版本（通常要求驱动版本 ≥ 525 以上，具体取决于 CUDA 12.x）。
  • PyTorch：vLLM 依赖 PyTorch 的 CUDA 运行时，且对 PyTorch 版本有严格范围（如 2.0+）。
  • CUDA 工具包：虽然 pip 安装会自动拉取预编译的 .so 文件，但编译源码时需要完整 CUDA 工具链。
  • Python：官方支持 3.8 ~ 3.12，但推荐 3.10/3.11（对最新特性支持最好）。

下图展示了 vLLM 安装后的核心依赖关系与数据流，帮助你理解为什么“驱动 → CUDA → PyTorch → vLLM”的层级顺序不可颠倒：

GPU 硬件层 NVIDIA GPU（Ampere/Ada/Hopper 架构） + 驱动版本 ≥ 525 CUDA 运行时层 CUDA 12.x / 11.8（由 PyTorch 自带或系统安装） PyTorch 层 PyTorch 2.x（cu118/cu121/cu124 版本） vLLM 推理引擎 PagedAttention CUDA kernel + 模型调度器 + 推理 API nvidia-smi 验证 nvcc --version 验证 python -c "import torch" vllm --version
关键认知：vLLM 的 pip 包在安装时会自动检测当前 PyTorch 的 CUDA 版本，并匹配对应的预编译内核。因此，先安装 PyTorch，再安装 vLLM 是官方推荐的顺序，可以避免很多二进制冲突。

2.2 方法流程：标准安装步骤

下面以 Ubuntu 20.04/22.04 + Python 3.10 + CUDA 12.1 为例，给出完整的安装命令序列。请根据你的实际环境调整版本号。

步骤 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-SXM4-40GB    Off  | 00000000:00:04.0 Off |                    0 |
# +-------------------------------+----------------------+----------------------+

如果 nvidia-smi 无法运行，说明驱动未安装或未正确加载。此时需要先安装 NVIDIA 驱动，再继续后续步骤。

步骤 2：创建虚拟环境（推荐）

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

# 或者使用 venv
# python3.10 -m venv vllm-env
# source vllm-env/bin/activate

步骤 3：安装 PyTorch（带 CUDA 支持）

# 以 CUDA 12.1 为例（根据 nvidia-smi 显示的 CUDA 版本选择）
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121

# 验证 PyTorch 是否识别 GPU
python -c "import torch; print(torch.cuda.is_available()); print(torch.cuda.get_device_name(0))"
# 期望输出：
# True
# NVIDIA A100-SXM4-40GB

步骤 4：安装 vLLM

# 直接安装最新稳定版
pip install vllm

# 如果需要特定版本（例如 0.6.0）
# pip install vllm==0.6.0

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

2.3 案例：在 A100 上完成安装并跑通推理

下面是一个完整的实操案例，展示从零到成功调用 vLLM 的完整链路。假设我们使用一台配置了 A100 40GB 的服务器。

环境信息：

  • 操作系统：Ubuntu 22.04
  • GPU：NVIDIA A100 40GB（驱动 535.104.05，CUDA 12.2）
  • Python：3.10（conda 环境）
  • PyTorch：2.1.2+cu121
  • vLLM：0.6.3.post1

安装完成后，我们用一个最小的离线推理脚本验证安装是否成功：

# test_vllm.py
from vllm import LLM, SamplingParams

# 加载一个较小的模型（如 Qwen2-1.5B-Instruct）
llm = LLM(model="Qwen/Qwen2-1.5B-Instruct", gpu_memory_utilization=0.6)

prompts = ["请用一句话解释什么是注意力机制？"]
sampling_params = SamplingParams(temperature=0.7, max_tokens=128)

outputs = llm.generate(prompts, sampling_params)
for output in outputs:
    print(output.outputs[0].text)
# 运行脚本
python test_vllm.py

# 期望输出（部分）：
# 注意力机制是一种让模型在处理序列时，能够动态地关注输入中不同部分重要性的技术...

如果上述脚本能正常输出文本，说明 vLLM 安装成功且 GPU 资源分配正常。如果出现 CUDA error: out of memory，可以调低 gpu_memory_utilization 参数（例如改为 0.4）。

2.4 常见误区与排障复盘

在安装 vLLM 的过程中，有几个高频问题值得特别留意。下表总结了典型错误、原因与解决方案：

错误现象 根本原因 解决方案
ImportError: libcuda.so.1: cannot open shared object file 系统 CUDA 驱动库路径未配置，或驱动未正确安装 检查 nvidia-smi；将 /usr/local/cuda/lib64 加入 LD_LIBRARY_PATH
RuntimeError: Found no NVIDIA driver on your system PyTorch 检测不到 GPU 驱动 重新安装 NVIDIA 驱动；确认 nvidia-smi 可运行
CUDA error: no kernel image is available for execution on the device PyTorch 的 CUDA 版本与 GPU 架构不匹配（如老 GPU 配新 CUDA） 降低 CUDA 版本（如 cu118）；或升级 GPU 驱动
ValueError: The model's max seq len is too large 模型配置的 max_position_embeddings 超过显存可容纳范围 减小 max_model_len 参数（如设为 2048）
安装时 pip 报 No matching distribution found Python 版本或平台不满足 vLLM 的 wheel 要求 使用 Python 3.10/3.11；确认系统为 Linux x86_64
重要提醒：不要使用 pip install vllm --force-reinstall 来“修复”问题，这可能会破坏 PyTorch 与 vLLM 的版本匹配关系。正确的做法是：先卸载全部相关包，再按顺序重新安装。

2.5 验证安装的完整检查清单

为了确保环境万无一失，建议按以下清单逐项确认：

  1. GPU 驱动：nvidia-smi 能显示 GPU 型号与驱动版本。
  2. CUDA 可用性：python -c "import torch; print(torch.cuda.is_available())" 输出 True。
  3. vLLM 版本：python -c "import vllm; print(vllm.__version__)" 能输出版本号。
  4. 显存预留：运行 vLLM 前，用 nvidia-smi 确认空闲显存 ≥ 模型大小 × 1.2（预留 KV cache 空间）。
  5. 离线推理：执行一次最小模型（如 Qwen2-0.5B）的生成，确认无报错。
← 上一章 📖 返回目录 下一章 →