第二章 开发环境搭建：GPU驱动安装、CUDA Toolkit配置、cuDNN与NCCL安装

别小看环境搭建这一步。很多跑单细胞分析的朋友，拿到 GPU 服务器第一件事就是装个 conda 然后 pip install 一路到底，结果跑一个晚上出个「CUDA driver version is insufficient」—— 那种挫败感，我懂。其实环境搭对了，后面可以省一半的 debug 时间。

这一章我们就从底层到上层，把 GPU 计算栈的每一层都理清楚。你会看到驱动、CUDA 工具包、cuDNN 和 NCCL 各自扮演什么角色，它们之间怎么依赖，我自己踩过哪些坑。

核心原则：版本匹配 —— 驱动要支持 CUDA 版本，CUDA 版本要配套 cuDNN 和 NCCL。少一个版本对不上，就会报奇奇怪怪的错误。

2.1 GPU 驱动安装

先说驱动。驱动是 GPU 和操作系统之间的桥梁。没有驱动，CUDA 再牛也调不动 GPU。

我个人习惯用 NVIDIA 官方提供的 runfile 安装，比包管理器里的版本新，而且能手动指定内核模块参数。不过第一次装的同学，用包管理器也完全 OK。

2.1.1 检查当前硬件和驱动

# 查看 GPU 型号，确认有 NVIDIA 显卡
lspci | grep -i nvidia

# 如果已经装了驱动，看版本
nvidia-smi

nvidia-smi 输出里，第一行就是 driver version。比如 Driver Version: 535.129.03。这个版本号决定了你能装哪个 CUDA Toolkit（后面会讲）。

2.1.2 安装驱动（推荐 runfile 方式）

# 1. 卸载旧驱动（如果存在）
sudo apt-get purge nvidia-* -y

# 2. 禁用 nouveau 驱动（开源版，会冲突）
echo "blacklist nouveau" | sudo tee /etc/modprobe.d/blacklist-nvidia-nouveau.conf
sudo update-initramfs -u

# 3. 重启后，下载对应驱动 runfile
wget https://us.download.nvidia.com/XFree86/Linux-x86_64/535.129.03/NVIDIA-Linux-x86_64-535.129.03.run

# 4. 给执行权限，然后运行
chmod +x NVIDIA-Linux-x86_64-535.129.03.run
sudo ./NVIDIA-Linux-x86_64-535.129.03.run

我曾经在安装过程中选了「Install 32-bit compatibility libraries」，结果后面编译某些库时符号冲突。建议不勾这个，除非你明确需要。

2.1.3 验证驱动

nvidia-smi

如果能正常显示 GPU 温度、功耗和进程信息，驱动就装好了。

2.2 CUDA Toolkit 配置

CUDA Toolkit 提供编译器 nvcc、CUDA 运行时库和数学库。它不是驱动，但依赖驱动的版本支持。

2.2.1 选择 CUDA 版本

这里有个经验法则：先查你的项目（比如 scvi-tools、rapids-singlecell）要求的 CUDA 版本。我建议选次新稳定版（比如现在 CUDA 12.x 已经很稳，但有些包还在 11.8 上跑）。

项目 / 框架建议 CUDA 版本驱动最低版本
PyTorch 2.x + cuDNN12.1 / 11.8530.30+
RAPIDS (cuDF/cuML)11.8520.61+
TensorFlow 2.15+11.8520.61+
Spark + GPU 加速12.0525.60+

2.2.2 安装 CUDA Toolkit

NVIDIA 官方提供了 network installer 和 local installer。我推荐 local runfile，一次下载后可以在多台机器复用。

# 以 CUDA 12.1 为例
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

# 安装时注意：不要勾选 Driver（我们已经装过），只选 Toolkit 和 Samples

安装完成后，把 CUDA 的 bin 和 lib64 添加进环境变量：

# 在 ~/.bashrc 或 ~/.zshrc 里添加
export PATH=/usr/local/cuda-12.1/bin:$PATH
export LD_LIBRARY_PATH=/usr/local/cuda-12.1/lib64:$LD_LIBRARY_PATH

一个小技巧： 用 update-alternatives 管理多个 CUDA 版本，方便切换。具体命令：sudo update-alternatives --install /usr/local/cuda cuda /usr/local/cuda-12.1 121

2.2.3 验证 CUDA 环境

nvcc --version

# 编译个 sample 测试
cd /usr/local/cuda-12.1/samples/1_Utilities/deviceQuery
make
./deviceQuery

看到 Result = PASS 就说明 CUDA Toolkit 工作正常。

2.3 cuDNN 与 NCCL 安装

cuDNN 是深度神经网络的加速库，NCCL 是多 GPU 通信的优化库。空间单细胞分析中，cuDNN 用在神经网络模型（如 scVI）里计算卷积或全连接层，NCCL 用在多卡并行训练时做梯度同步。

2.3.1 cuDNN 安装

cuDNN 现在从 NVIDIA 官网下载需要注册账号。下载后是一个 tar 包，解压后复制头文件和库到 CUDA 目录就行。

# 以 cuDNN for CUDA 12.x 为例
tar -xzvf cudnn-linux-x86_64-8.9.7.29_cuda12-archive.tar.xz

# 复制到 CUDA 目录
sudo cp cudnn-*-archive/include/cudnn*.h /usr/local/cuda-12.1/include/
sudo cp -P cudnn-*-archive/lib/libcudnn* /usr/local/cuda-12.1/lib64/

# 给权限
sudo chmod a+r /usr/local/cuda-12.1/include/cudnn*.h /usr/local/cuda-12.1/lib64/libcudnn*

验证 cuDNN 版本：

cat /usr/local/cuda-12.1/include/cudnn_version.h | grep CUDNN_MAJOR -A 2

2.3.2 NCCL 安装

NCCL 可以从 NVIDIA 官方仓库 apt 安装，也可以源码编译。我建议用 deb 包，简单快捷。

# 添加 NVIDIA 仓库密钥
sudo apt-key adv --fetch-keys https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2204/x86_64/3bf863cc.pub

# 添加仓库
sudo add-apt-repository "deb https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2204/x86_64/"

# 安装 NCCL
sudo apt update
sudo apt install libnccl2 libnccl-dev

注意： NCCL 版本也要和 CUDA 版本对应。运行 dpkg -l | grep nccl 可以查看已安装版本。我之前遇到过 NCCL 版本高了，结果 cuDF 报段错误，退回 2.18.3 才解决。

2.4 整体验证：一个简单的 GPU 计算范例

最后，我们写一个小程序，确认驱动、CUDA、cuDNN 和 NCCL 全部衔接正常。

#include <cuda_runtime.h>
#include <cudnn.h>
#include <nccl.h>
#include <stdio.h>

int main() {
    int driverVersion = 0;
    cudaDriverGetVersion(&driverVersion);
    printf("CUDA Driver Version: %d\n", driverVersion);

    cudnnHandle_t cudnn;
    cudnnCreate(&cudnn);
    printf("cuDNN handle created successfully.\n");

    ncclComm_t comm;
    ncclUniqueId id;
    ncclGetUniqueId(&id);
    printf("NCCL unique ID generated.\n");

    cudnnDestroy(cudnn);
    return 0;
}
# 编译命令（需要 nvcc）
nvcc -o env_test env_test.cu -lcudnn -lnccl
./env_test

如果所有库都能正常加载，控制台会输出三行信息，没有任何错误。

至此，你的 GPU 计算栈就完整了。 驱动 → CUDA Toolkit → cuDNN → NCCL，每一层都经过验证。后续安装任何单细胞分析工具（比如 rapids-singlecell、scvi-tools）时，只要环境变量指向同一个 CUDA 目录，就不会有兼容性问题。

GPU 计算栈层次依赖图 GPU 驱动 (nvidia-smi, Driver API) 通过内核模块与硬件交互 依赖 CUDA Toolkit (nvcc, cuBLAS, cuSPARSE, 运行时) 编译 & 运行时基础设施 调用 调用 cuDNN 深度神经网络核心加速库 NCCL 多 GPU 通信优化库 空间单细胞分析工具 (scVI, RAPIDS, SpaGCN, …) 箭头方向表示「依赖下层接口」。安装时必须自底向上，验证时建议自顶向下。

我的个人习惯： 每次装完环境，都会保留一个 env_test.cu 文件在 ~/cuda_checks 目录下。配新机器时直接编译运行，十分钟就能确认全部组件是否就绪。别等到跑任务报错了才排查环境问题，能省不少时间。

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