从 MCCL 2.1 迁移到 MCCL 2.3

1. 文档目的

本文用于指导外部用户将 MCCL 从 2.1 版本升级到 2.3 版本，并说明升级收益、兼容性影响、推荐实施步骤、验证方法和回退建议。

本文基于以下版本基线整理：

源版本：MCCL 2.1
目标版本：MCCL 2.3

2. 升级收益概览

与 2.1 相比，2.3 版本的主要提升如下：

对外公共 API 能力增强：新增更完整的通信器管理、故障处理、缓冲区注册和集合通信能力
安装、构建、打包和版本查询流程更清晰：便于交付、部署和定位问题
对调优和诊断场景的支持增强：版本查询信息更完整，错误反馈更丰富
保留常用 MCCL_* 运行时环境变量用法：已有调优脚本可以较低成本迁移
对外符号收敛到标准 mccl 接口*：降低误用内部符号带来的兼容性风险

3. 升级影响摘要

维度	MCCL 2.1	MCCL 2.3	升级影响
版本基线	2.1	2.3	建议按完整版本进行升级验证，不建议仅替换单个 .so 文件
交付包命名	mccl_2.1.4-1+musa1.0_...	mccl_2.3-1+musa3.1_...	2.3 交付默认面向更高版本的 MUSA 软件栈，升级前需确认驱动、Toolkit 与编译环境
构建入口	旧版 benchmark/ + 根目录 setup.sh	新版 tools/mccl-test/ + setup.sh	若已有自动化脚本依赖旧目录结构，需要同步调整
安装内容	安装 lib/、include/、cmake/、bin/*	安装 lib/、include/、cmake/、bin/mccl_version	若依赖旧包中的其他二进制文件，需重新确认交付内容
公共头文件	mccl.h，并带有 mccl_net.h	扩展后的 mccl.h	若应用依赖 mccl_net.h 或内部扩展接口，升级前需做兼容性评估
集合通信接口	含 mcclAllToAllv、mcclBatchAllToAllv	新增 mcclAlltoAll、mcclGather、mcclScatter，移除 mcclAllToAllv、mcclBatchAllToAllv	使用被移除接口的应用需要修改代码并重新编译
通信器管理	基础初始化/销毁能力	新增 Config 初始化、Finalize、Revoke、Split、Shrink、Scalable Init	大规模训练、容错和通信域拆分场景可获得更强能力
错误与诊断	基础错误字符串和版本查询	新增 mcclGetLastError、mcclRemoteError、mcclInProgress，mccl_version 输出更丰富	监控、日志和故障排查脚本建议同步适配
符号可见性	历史实现中可能暴露更多非标准符号	明确仅对外暴露 mccl* 符号	若历史程序绕过公共头文件直接链接内部符号，升级后会失效

4. 对应用侧最重要的兼容性变化

4.1 新增的主要能力

2.3 版本新增了以下对外能力：

通信器配置初始化：mcclCommInitRankConfig
大规模初始化：mcclCommInitRankScalable
通信器生命周期管理：mcclCommFinalize、mcclCommRevoke
通信域管理：mcclCommSplit、mcclCommShrink
缓冲区注册：mcclCommRegister、mcclCommDeregister
额外集合通信：mcclAlltoAll、mcclGather、mcclScatter
组调用模拟：mcclGroupSimulateEnd
更细粒度错误查询：mcclGetLastError

如果当前应用只使用 AllReduce、Broadcast、ReduceScatter、AllGather、Send/Recv 等常规能力，通常不需要修改业务逻辑即可完成升级验证。

4.2 需要重点排查的兼容性风险

以下情况在升级时需要重点检查：

应用使用了 mcclAllToAllv 或 mcclBatchAllToAllv
应用直接包含或调用 mccl_net.h 相关能力
应用通过 dlsym 或其他方式访问非 mccl* 内部符号
自动化脚本写死了旧目录，如 benchmark/、pkg/
日志分析或运维脚本依赖旧版 mccl_version 输出格式

其中最关键的是接口兼容性：mcclAllToAllv 和 mcclBatchAllToAllv 这两个接口在 2.3 对外头文件中不再提供。若用户代码依赖这两个接口，建议结合业务模型改造为：

可等量切分场景：优先改造为 mcclAlltoAll
不等量切分场景：在应用层自行拆分消息或重新设计数据分发逻辑

4.3 运行时环境变量兼容性

2.3 仍保留了常见的 MCCL_* 调优方式，现有脚本一般可继续沿用，例如：

MCCL_PROTOS
MCCL_ALGOS
MCCL_IB_GID_INDEX
MCCL_NET_SHARED_BUFFERS

5. 升级前准备

建议在正式升级前完成以下检查：

确认目标环境已安装并验证 MUSA 驱动、MUSA Toolkit、mtml
多机场景确认 MPI 运行环境已就绪，推荐提前验证 mpirun --version
若使用 IB 或 RoCE，先通过 ibstat 等命令确认链路状态正常
备份现网使用中的 MCCL 2.1 安装目录、交付包和启动脚本
盘点业务代码中是否使用了已移除接口、内部符号或旧路径

6. 推荐升级方式

建议采用 "并行安装 + 验证通过后切换" 的方式，而不是直接覆盖旧版本。

6.1 解压交付包

tar -Jxvf mccl_2.3+mp_<arch>.txz
cd mccl_2.3+mp_<arch>

6.2 安装到独立目录

./install.sh -d /opt/mccl/2.3
export LD_LIBRARY_PATH=/opt/mccl/2.3/lib:$LD_LIBRARY_PATH
export PATH=/opt/mccl/2.3/bin:$PATH

这样可以保留旧版 2.1 安装目录，便于验证失败时快速回退。

6.3 重新编译应用

建议所有依赖 MCCL 的应用在升级后重新编译并重新链接，而不是沿用旧版编译产物直接运行。建议检查：

头文件引用路径是否仍然正确
是否依赖已删除接口
是否依赖旧版目录结构或旧版测试工具路径

7. 升级后的验证建议

7.1 版本确认

mccl_version

2.3 版本的 mccl_version 输出信息更完整，通常会包含：

MCCL 版本号
编译架构
代码分支、提交号、提交时间等版本追踪信息

7.2 单机功能验证

如果交付包中包含测试程序，可执行：

cd mccl-test/build
./all_reduce_perf -b 1M -e 1024M -f 2 -g 1

关注以下结果：

程序可正常启动并完成通信
未出现初始化失败、异步错误或超时
带宽和时延表现与预期一致，且不低于现网可接受阈值

7.3 多机功能验证

OpenMPI 示例：

mpirun --allow-run-as-root \
  --mca btl_tcp_if_include bond0 \
  -hostfile ./hostfile_with_openmpi \
  -x LD_LIBRARY_PATH=/opt/mccl/2.3/lib:/usr/local/musa/lib:/usr/local/lib \
  -x MCCL_PROTOS=2 \
  -x MCCL_NET_SHARED_BUFFERS=0 \
  -x MCCL_ALGOS=1 \
  -x MCCL_IB_GID_INDEX=3 \
  ./all_reduce_perf -b 1M -e 1024M -f 2 -g 1

MPICH 示例：

mpirun -hostfile ./hostfile_with_mpich \
  -env LD_LIBRARY_PATH=/opt/mccl/2.3/lib:/usr/local/musa/lib:/usr/local/lib \
  -env MCCL_PROTOS=2 \
  -env MCCL_NET_SHARED_BUFFERS=0 \
  -env MCCL_ALGOS=1 \
  -env MCCL_IB_GID_INDEX=3 \
  ./all_reduce_perf -b 1M -e 1024M -f 2 -g 1

多机验证建议至少覆盖：

单节点多卡
双节点或多节点 AllReduce
现网实际使用的数据类型与消息规模
现网使用的主要环境变量组合

8. 回退建议

如果升级验证未通过，建议按以下方式回退：

恢复旧版 2.1 的 LD_LIBRARY_PATH 和 PATH
重新指向旧版安装目录或重新安装 2.1 交付包
恢复旧版启动脚本、hostfile 和调优参数
重新执行单机和多机冒烟验证，确认业务恢复正常

建议保留以下回退资产：

2.1 安装包
2.1 安装目录
2.1 业务启动命令
2.1 现网生效的 MCCL_* 环境变量配置

注意：2.3 安装脚本支持卸载库文件、头文件和 CMake 文件。若使用独立安装前缀，回退时建议同时人工检查并清理目标目录下残留的 bin/mccl_version 文件，避免多版本混用。

9. 升级结论

对于仅使用标准 MCCL 集合通信接口、并通过公共头文件和标准动态库集成的用户，MCCL 2.1 升级到 2.3 的总体改造成本可控，推荐通过并行安装和完整验证后升级。

以下用户建议优先安排专项兼容性验证：

使用 mcclAllToAllv 或 mcclBatchAllToAllv 的用户
依赖 mccl_net.h 或内部扩展接口的用户
自动化脚本依赖旧目录结构或旧打包方式的用户
对版本输出格式、监控告警和故障注入流程有定制化依赖的用户

总体上，2.3 在接口完整性、可诊断性、通信器生命周期管理和工程化交付方面都明显优于 2.1，建议作为后续外部交付的主推版本。

附录：API 使用变更详情

初始化

mcclGroupStart();
for (int i=0; i<ngpus; i++) {
  musaSetDevice(i);
  mcclCommInitRank(comms+i, ngpus, id, i);
}
mcclGroupEnd();

通信

mcclGroupStart();
for (int i=0; i<nLocalDevs; i++) {
  mcclAllReduce(..., comm[i], stream[i]);
}
mcclGroupEnd();

计数

现在作为参数提供的计数类型是 size_t 而不是整数。

AllGather 和 ReduceScatter 的原地使用

有关更多信息，请参见 "原地操作"。

AllGather 参数顺序

AllGather 函数的参数顺序已经重新排列。原型从：

mcclResult_t mcclAllGather(const void* sendbuff, int count, mcclDataType_t datatype,
    void* recvbuff, mcclComm_t comm, musaStream_t stream);

变为：

mcclResult_t mcclAllGather(const void* sendbuff, void* recvbuff, size_t sendcount,
    mcclDataType_t datatype, mcclComm_t comm, musaStream_t stream);

recvbuff 参数被移动到 sendbuff 后面，以与其他操作保持一致。

数据类型

MCCL 2.3 中添加了新的数据类型。MCCL 2.1 中存在的数据类型没有变化，仍然可以在 MCCL 2.3 中使用。

错误代码

错误代码已经合并到 mcclInvalidArgument 类别中，并已简化。创建了一个新的 mcclInvalidUsage 代码，以涵盖新的编程错误。

1. 文档目的​

2. 升级收益概览​

3. 升级影响摘要​

4. 对应用侧最重要的兼容性变化​

4.1 新增的主要能力​

4.2 需要重点排查的兼容性风险​

4.3 运行时环境变量兼容性​

5. 升级前准备​

6. 推荐升级方式​

6.1 解压交付包​

6.2 安装到独立目录​

6.3 重新编译应用​

7. 升级后的验证建议​

7.1 版本确认​

7.2 单机功能验证​

7.3 多机功能验证​

8. 回退建议​

9. 升级结论​

附录：API 使用变更详情​

初始化​

通信​

计数​

AllGather 和 ReduceScatter 的原地使用​

AllGather 参数顺序​

数据类型​

错误代码​

这篇文章对您有帮助吗？