4、环境搭建：NCCL与NVSHMEM的安装、版本兼容性检查、CUDA环境配置

好，咱们进入实操环节。

说实话，环境搭建这块，我见过太多人卡在这里了。不是装不上，就是装上了跑不起来。你想想看，NCCL 和 NVSHMEM 都是跟 CUDA 深度绑定的东西，版本一不对，整个集群就罢工。我个人习惯是，动手之前先把版本兼容性理清楚，不然后面全是坑。

4.1 版本兼容性：先看这张表

为什么先讲兼容性？因为 NCCL 和 NVSHMEM 对 CUDA 版本有严格依赖。我曾经在一个项目里，直接把 NCCL 2.12 装到了 CUDA 11.0 上，结果编译倒是过了，一跑就段错误。查了两天才发现是 ABI 不兼容。

下面这张表是我自己整理的，你可以直接拿来用：

NVSHMEM 版本 推荐 NCCL 版本 支持 CUDA 版本 备注
2.8.x 2.15.x - 2.18.x 11.8, 12.0, 12.1 稳定版，推荐生产使用
2.9.x 2.19.x - 2.21.x 12.2, 12.3 新增了 NVLink 优化
3.0.x 2.22.x+ 12.4+ 实验性，我还没在生产用过
⚠️ 注意： 不要混用不同大版本的 NCCL 和 NVSHMEM。比如 NCCL 2.18 配 NVSHMEM 3.0，大概率会链接失败。

4.2 CUDA 环境配置：基础中的基础

嗯，这里要注意。CUDA 环境配置不只是装个驱动那么简单。

我建议你按这个顺序来：

  1. 确认驱动版本：运行 nvidia-smi，看右上角的 CUDA Version。这个版本必须 >= 你后面要装的 CUDA Toolkit 版本。
  2. 安装 CUDA Toolkit：去 NVIDIA 官网下载 runfile 或者 deb 包。我个人习惯用 runfile，因为可以指定安装路径，方便多版本共存。
  3. 设置环境变量：把下面这几行加到你的 ~/.bashrc 里：
export CUDA_HOME=/usr/local/cuda-12.2
export PATH=$CUDA_HOME/bin:$PATH
export LD_LIBRARY_PATH=$CUDA_HOME/lib64:$LD_LIBRARY_PATH

然后 source ~/.bashrc，再跑 nvcc --version 确认一下。

💡 小技巧： 我习惯在 /usr/local 下保留多个 CUDA 版本，比如 cuda-11.8、cuda-12.2，然后用软链接 cuda 指向当前要用的那个。切换版本只需要改一下软链接，不用改环境变量。

4.3 NCCL 安装：两种方式

NCCL 的安装其实不复杂。我一般用两种方式：

方式一：apt 安装（推荐）

如果你用的是 Ubuntu，直接加 NVIDIA 的 apt 源：

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/ /"
sudo apt update
sudo apt install libnccl2 libnccl-dev

这种方式最省心，依赖会自动处理。

方式二：源码编译（灵活）

如果你需要定制 NCCL 的编译选项，比如开启 NVLink 支持或者调整 ring 算法，那就得自己编译了：

git clone https://github.com/NVIDIA/nccl.git
cd nccl
make -j src.build CUDA_HOME=/usr/local/cuda-12.2
sudo make install

编译的时候注意看日志，我遇到过因为 GCC 版本太低导致编译失败的情况。建议用 GCC 9 以上。

4.4 NVSHMEM 安装：依赖检查是关键

NVSHMEM 的安装比 NCCL 稍微麻烦一点。它依赖 NCCL 和 CUDA，而且对 MPI 也有要求。

我的安装步骤：

  1. 先装好 NCCL（上面已经讲了）
  2. 安装 MPI：推荐 OpenMPI 4.x 或 MPICH 3.x。我习惯用 OpenMPI：
sudo apt install openmpi-bin openmpi-common libopenmpi-dev
  1. 下载 NVSHMEM 源码：从 GitHub 上 clone：
git clone https://github.com/NVIDIA/nvshmem.git
cd nvshmem
  1. 编译安装：
make -j CUDA_HOME=/usr/local/cuda-12.2 NCCL_HOME=/usr/local/nccl MPI_HOME=/usr/lib/x86_64-linux-gnu/openmpi
sudo make install
⚠️ 注意： 编译时如果报错找不到 nccl.h，说明 NCCL_HOME 路径不对。你可以用 find / -name "nccl.h" 2>/dev/null 找到实际路径。

4.5 验证安装：跑个测试

装完了别急着用，先验证一下。我一般跑两个测试：

测试 NCCL：

# 进入 NCCL 的测试目录
cd /opt/nccl-tests
./build/all_reduce_perf -b 8 -e 128M -f 2 -g 4

如果能看到带宽数据，说明 NCCL 工作正常。

测试 NVSHMEM：

# 进入 NVSHMEM 的测试目录
cd /opt/nvshmem/tests
mpirun -np 4 ./simple_put

输出里没有报错，就说明环境搭好了。

💡 避坑指南： 我曾经在测试 NVSHMEM 时，发现 simple_put 一直卡住。后来排查发现是 MPI 版本不对——NVSHMEM 2.8 要求 OpenMPI 4.0.5 以上，而我装的是 4.0.3。升级 MPI 后问题解决。

4.6 知识体系总览

下面这张图，帮你把整个环境搭建的逻辑串起来：

NVSHMEM + NCCL 环境搭建知识体系 CUDA Toolkit NCCL MPI (OpenMPI/MPICH) NVSHMEM 验证：NCCL 测试 + NVSHMEM 测试 依赖关系：CUDA → NCCL + MPI → NVSHMEM → 验证

说白了，整个流程就是：先打好地基（CUDA），再砌墙（NCCL 和 MPI），最后盖屋顶（NVSHMEM）。每一步都验证通过，才能保证后面跑分布式训练时不掉链子。

公众号:蓝海资料掘金营，微信deep3321

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