📚 课程目录第4章 GPU加速项目环境搭建

4. GPU加速项目环境搭建

GPU加速项目的环境搭建，本质上是把一条从硬件到框架的软件栈逐层对齐。这条栈自下而上依次是：GPU硬件与内核态驱动、用户态CUDA运行时与工具链、通信库NCCL、深度学习加速库cuDNN，最后才是PyTorch、TensorFlow等框架。任何一层版本错配，都会在训练启动或首次集合通信时暴露为难以定位的错误。因此本节不按“装完一个再装下一个”的线性思路讲，而是先讲清版本约束关系，再分别给出裸金属与容器两条落地路径，最后给出可执行的验证方法。

一、先确定版本矩阵，再动手安装

安装前必须先锁定三组约束。第一组是驱动与CUDA Toolkit的兼容关系：NVIDIA驱动向下兼容多个CUDA版本，但每个驱动版本有支持的最高CUDA运行时版本。例如驱动版本535.x可支持到CUDA 12.2，若强行安装CUDA 12.4的Toolkit，运行时会报“CUDA driver version is insufficient for CUDA runtime version”。第二组是CUDA与cuDNN的匹配：cuDNN 8.9.x对应CUDA 11.8与12.x分支，cuDNN 9.x则要求CUDA 12及以上，且cuDNN 9把部分API拆分为独立子库。第三组是NCCL与CUDA的匹配：NCCL 2.19以上版本对CUDA 12有明确支持，多卡训练前必须确认NCCL版本不低于框架要求的下限。

一个可直接参考的示例组合（属于合理假设的教学示例，非实测结论）：驱动550.54.15、CUDA Toolkit 12.4、cuDNN 9.1.0、NCCL 2.21.5、PyTorch 2.4。这套组合在CUDA 12.4分支内自洽，适合作为新项目的起点。若项目已有历史代码依赖CUDA 11.8，则应整体回退到驱动535、cuDNN 8.9.7、NCCL 2.18的组合，不要混搭。

二、裸金属环境安装顺序

裸金属安装遵循“先驱动、后Toolkit、再库”的顺序。驱动安装推荐使用发行版仓库方式，便于后续内核升级后自动重建模块：

# Ubuntu 22.04 示例
sudo apt update
sudo apt install -y nvidia-driver-550
sudo reboot
nvidia-smi   # 确认驱动加载，右上角显示 CUDA Version: 12.4

注意nvidia-smi右上角显示的CUDA Version是驱动支持的最高运行时版本，并不代表已安装该版本Toolkit。随后安装CUDA Toolkit，建议使用runfile或官方apt源，避免与系统自带驱动冲突：

wget https://developer.download.nvidia.com/compute/cuda/12.4.0/local_installers/cuda_12.4.0_550.54.15_linux.run
sudo sh cuda_12.4.0_550.54.15_linux.run --toolkit --silent --override
echo 'export PATH=/usr/local/cuda-12.4/bin:$PATH' >> ~/.bashrc
echo 'export LD_LIBRARY_PATH=/usr/local/cuda-12.4/lib64:$LD_LIBRARY_PATH' >> ~/.bashrc
source ~/.bashrc
nvcc -V   # 应输出 release 12.4

cuDNN与NCCL在CUDA 12时代推荐用apt安装，便于版本管理。cuDNN 9把运行时拆成多个包，需一并安装：

sudo apt install -y libcudnn9-cuda-12 libcudnn9-dev-cuda-12
sudo apt install -y libnccl2 libnccl-dev

安装完成后，用ldconfig -p | grep cudnn和ldconfig -p | grep nccl确认动态库已被系统识别。若使用源码编译的框架，还需保证CUDA_HOME指向/usr/local/cuda-12.4。

三、容器化环境：更可控的交付方式

容器化路径的核心优势是把驱动留在宿主机、把CUDA运行时与库封进镜像，从而让同一镜像在多台机器上行为一致。前提是宿主机已装好驱动，并安装NVIDIA Container Toolkit：

sudo apt install -y nvidia-container-toolkit
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

docker run --rm --gpus all nvidia/cuda:12.4.0-cudnn9-devel-ubuntu22.04 nvidia-smi

若命令能正常打印GPU信息，说明容器已能访问设备。生产镜像建议基于nvidia/cuda:12.4.0-cudnn9-runtime，再按需安装NCCL与框架，避免把devel镜像的编译工具链带入运行时。多机训练时，容器需以--ipc=host或足够大的--shm-size启动，否则NCCL共享内存通信会失败。

四、基础可用性验证

验证要覆盖四个层次，缺一不可。第一层是设备可见性：nvidia-smi -L应列出全部GPU。第二层是CUDA运行时可用：编译并运行一个最小向量加法程序，确认cudaMalloc与核函数启动成功。第三层是cuDNN可用：用PyTorch执行一次卷积前向，观察是否报cuDNN相关错误。第四层是NCCL可用：用两卡执行一次all_reduce。

# NCCL 两卡 all_reduce 验证（示例）
python -c "
import torch, torch.distributed as dist
dist.init_process_group('nccl', init_method='tcp://127.0.0.1:29500', rank=0, world_size=2)
t = torch.ones(4, device='cuda:0')
dist.all_reduce(t)
print('all_reduce ok:', t.cpu().tolist())
"

若输出all_reduce ok: [2.0, 2.0, 2.0, 2.0]，说明NCCL通信链路正常。若卡住不动，优先检查NCCL_DEBUG=INFO日志中的拓扑识别结果，常见原因是容器共享内存不足或网卡未正确暴露。

建议把上述验证脚本固化为一个check_env.sh，在每次环境变更后执行一次。版本矩阵、驱动版本、库版本与验证结果一并记录，便于后续排障时快速比对。

不要在同一个环境中混装多个CUDA Toolkit版本并随意切换LD_LIBRARY_PATH。运行时库与编译期头文件版本不一致，往往在训练数小时后才以非法内存访问的形式暴露，排查成本极高。

环境搭建完成的判断标准不是“命令都执行成功”，而是四层验证全部通过、且版本矩阵自洽。做到这一点，后续的模型训练与性能调优才有稳定的基线。