4、CUDA与驱动安装：CUDA版本选择、NVIDIA驱动安装与验证、兼容性检查

在部署 vLLM 之前，必须先让 GPU 计算栈处于可用状态。vLLM 本身是一个 Python 库，但它依赖 CUDA 运行时来调用 GPU 的并行计算能力。很多初学者在安装 vLLM 时遇到“CUDA error: no kernel image is available for execution on the device”或“torch.cuda.is_available() 返回 False”，根源往往不是 vLLM 本身，而是 CUDA 与 NVIDIA 驱动版本不匹配。本节将梳理从驱动到 CUDA 工具包的完整安装与验证路径。

4.1 核心原理：驱动、CUDA Toolkit 与运行时 API 的关系

要理解版本选择，必须先分清三个层次：NVIDIA 驱动（Driver）、CUDA Toolkit 和 CUDA 运行时（Runtime API）。驱动运行在操作系统内核态，是唯一直接与 GPU 硬件通信的软件层；CUDA Toolkit 是开发包，包含编译器（nvcc）、库文件（如 cuBLAS、cuDNN）和头文件；而 PyTorch / vLLM 实际链接的是 CUDA 运行时库（libcudart.so）和 CUDA 驱动 API（libcuda.so）。

关键点在于：驱动是向下兼容的。只要驱动版本足够新，它就能支持所有旧版本的 CUDA Toolkit。例如，驱动版本 535.104 官方支持 CUDA 12.2，但它同样可以运行用 CUDA 11.8 编译的 PyTorch 二进制包。因此，安装策略应该是：先装新驱动，再装与 PyTorch 预编译包匹配的 CUDA 版本，而不是反过来。

核心结论：驱动版本决定 GPU 硬件能被识别；CUDA Toolkit 版本决定编译和运行时的 API 兼容性；PyTorch 的预编译 wheel 决定了 vLLM 实际使用的 CUDA 运行时版本。三者必须满足：驱动版本 ≥ CUDA Toolkit 最低要求，且 PyTorch 的 CUDA 版本与 Toolkit 主版本一致。
应用层：vLLM / PyTorch 调用 torch.cuda API → 链接 libcudart.so（CUDA Runtime） CUDA Toolkit 层（版本：11.8 / 12.1 / 12.4） 包含 nvcc 编译器、cuBLAS、cuDNN、libcudart.so NVIDIA 驱动层（版本：535.104 / 550.54） 内核态驱动，直接与 GPU 硬件通信，向下兼容所有旧 CUDA GPU 硬件（A100 / H100 / V100 / RTX 4090） 兼容性检查 驱动 ≥ Toolkit Toolkit ≈ PyTorch 软件栈

4.2 CUDA 版本选择：先看 PyTorch，再看驱动

vLLM 官方发布的预编译 wheel 通常针对特定 CUDA 版本构建。例如，vLLM 0.6.x 的官方镜像默认基于 CUDA 12.1 构建，而部分社区版本支持 CUDA 11.8。因此，选择 CUDA 版本的第一步是查看你要安装的 vLLM 版本要求：

# 查看 vLLM 官方对 CUDA 版本的支持矩阵（以 0.6.3 为例）
pip index versions vllm | head -20
# 或直接访问 GitHub Releases 页面查看对应 wheel 的构建信息

第二步是确认你的 GPU 算力（Compute Capability）。不同架构的 GPU 需要不同的 CUDA 版本支持：

GPU 架构 代表型号 算力 最低 CUDA 版本 推荐 CUDA 版本
Ampere A100, RTX 3090 8.0 / 8.6 11.0 11.8 或 12.1
Hopper H100, H800 9.0 11.8 12.1 或 12.4
Ada Lovelace RTX 4090, L40S 8.9 11.8 12.1
Volta V100, T4 7.0 / 7.5 10.0 11.8（最高支持）

选择策略总结：优先选择 PyTorch 官方预编译包支持的 CUDA 版本。例如，PyTorch 2.3 官方提供 cu118 和 cu121 两个版本，那么你就应该选择 CUDA 11.8 或 12.1，而不是去安装最新的 CUDA 12.4。因为即使你安装了 CUDA 12.4，PyTorch 的 wheel 仍然是链接到 12.1 的运行时，多出来的 Toolkit 版本并不会被使用。

4.3 NVIDIA 驱动安装与验证

驱动安装有两种主流方式：包管理器安装（推荐生产环境）和 runfile 安装（推荐特殊定制场景）。以下以 Ubuntu 22.04 为例，展示最稳妥的安装流程。

4.3.1 使用 apt 安装（推荐）

# 1. 检测 GPU 型号
lspci | grep -i nvidia

# 2. 添加 NVIDIA 官方驱动源
sudo add-apt-repository ppa:graphics-drivers/ppa
sudo apt update

# 3. 查看可用驱动版本
ubuntu-drivers devices

# 4. 安装推荐版本（通常带 recommended 标记）
sudo apt install -y nvidia-driver-550

# 5. 重启系统
sudo reboot

4.3.2 验证驱动是否安装成功

# 检查驱动版本
nvidia-smi

# 输出示例：
# +-----------------------------------------------------------------------------+
# | NVIDIA-SMI 550.54.15    Driver Version: 550.54.15    CUDA Version: 12.4    |
# |-------------------------------+----------------------+----------------------+
# | GPU  Name        Persistence-M| Bus-Id        Disp.A | Volatile Uncorr. ECC |
# | Fan  Temp  Perf  Pwr:Usage/Cap|         Memory-Usage | GPU-Util  Compute M. |
# |===============================+======================+======================|
# |   0  NVIDIA A100-SXM4-40GB    Off  | 00000000:00:04.0 Off |                    0 |
# | N/A   32C    P0    42W / 400W |      0MiB / 40960MiB |      0%      Default |
# +-------------------------------+----------------------+----------------------+

注意 nvidia-smi 输出中的 CUDA Version 字段，它表示当前驱动支持的最高 CUDA 版本，而不是你已安装的 CUDA Toolkit 版本。例如驱动 550.54 显示 CUDA 12.4，意味着它向下兼容所有 ≤12.4 的 CUDA 版本。

验证技巧：如果 nvidia-smi 能正常显示 GPU 信息，说明驱动已正确安装。此时可以进一步运行 nvidia-smi -L 列出所有 GPU 的 UUID，用于确认多卡环境下的设备识别。

4.4 CUDA Toolkit 安装与兼容性检查

安装 CUDA Toolkit 时，建议使用 runfile 方式，因为它不会覆盖系统已有的驱动。以下以 CUDA 12.1 为例：

# 下载 CUDA 12.1 runfile（约 3GB）
wget https://developer.download.nvidia.com/compute/cuda/12.1.1/local_installers/cuda_12.1.1_530.30.02_linux.run

# 执行安装，只安装 Toolkit，不安装驱动
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 版本
nvcc --version

安装完成后，必须进行端到端兼容性检查。很多用户只验证了 nvcc --version 就认为 CUDA 装好了，但 vLLM 实际使用的是 PyTorch 自带的 CUDA 运行时，因此还需要验证 PyTorch 能否正确调用 GPU：

# 创建虚拟环境并安装 PyTorch（以 cu121 为例）
python -m venv vllm-env
source vllm-env/bin/activate
pip install torch==2.3.0 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.5 常见误区与排障复盘

误区一：安装了最新 CUDA 12.4 就万事大吉。
实际上，如果 PyTorch 是 cu118 版本，它链接的是 CUDA 11.8 的运行时库，与 12.4 的 Toolkit 无关。此时 torch.cuda.is_available() 可能返回 True，但运行 vLLM 时会出现 undefined symbol: cudaGraphExecUpdate 之类的错误，因为 PyTorch 的 libtorch_cuda.so 需要特定版本的 libcudart.so。
误区二：驱动版本越新越好。
新驱动通常修复了安全漏洞并支持新 GPU，但偶尔会引入回归问题。例如，某些 535 系列驱动在 V100 上会导致 NCCL 通信性能下降。建议使用 nvidia-smi --query-gpu=driver_version --format=csv 记录当前驱动，并在升级前备份。

以下是一个典型的排障流程，当 vLLM 启动时报 CUDA 错误时，按顺序检查：

  1. 检查驱动：nvidia-smi 是否正常显示 GPU？如果显示 "No devices were found"，说明驱动未正确加载，检查 dmesg | grep -i nvidia 查看内核日志。
  2. 检查 PyTorch 的 CUDA 版本：python -c "import torch; print(torch.version.cuda)"，确认与 vLLM 要求的版本一致。
  3. 检查 CUDA 运行时库冲突：ldd $(python -c "import torch; print(torch.__file__)") | grep cudart，查看实际链接的 libcudart.so 路径。
  4. 检查 GPU 算力兼容性：python -c "import torch; print(torch.cuda.get_device_capability(0))"，如果返回 (8, 0) 表示 A100，而 vLLM 的 wheel 是针对 sm_90 编译的，则无法运行。
最佳实践清单：
  • 生产环境使用 nvidia-driver-550 或更高版本，确保支持 CUDA 12.x
  • CUDA Toolkit 版本与 PyTorch 的 torch.version.cuda 保持一致
  • 使用虚拟环境隔离 Python 依赖，避免系统级 CUDA 污染
  • 安装 vLLM 前，先运行 python -m vllm.entrypoints.openai.api_server --model facebook/opt-125m 做最小化验证
  • 记录 nvidia-smi 输出和 nvcc --version 到部署文档，便于后续排障

最后，建议在安装 vLLM 之前，将上述所有验证命令整合为一个脚本，输出关键版本信息。这样在后续遇到问题时，可以快速定位是驱动、CUDA 还是 PyTorch 层面的问题，避免在错误的方向上浪费时间。

← 上一章 📖 返回目录 下一章 →