从 MCCL 2.1 迁移到 MCCL 2.4

1. 文档目的

本文用于指导外部用户从 MCCL 2.1 升级到 MCCL 2.4，重点说明：

2.4 相对 2.1 的主要能力变化
应用侧需要重点关注的兼容性影响
推荐的升级与验证方式
典型新能力与示例入口

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

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

2. 升级收益概览

与 2.1 相比，2.4 的主要提升集中在以下几个方面：

集合通信与通信器能力更完整：在 2.1 的基础能力之外，补充了更完整的通信器配置、生命周期管理、扩展与查询能力
主机侧管理能力增强：支持通信器能力查询、通信器内存管理、对称窗口辅助查询和 RMA signal
对称内存与 device API 相关能力更丰富：可在主机侧更方便地探测 LSA、GIN、Host RMA 和窗口属性
示例、构建与交付更完整：示例覆盖面更广，CMake 查找和版本查询能力更完善

3. 升级影响摘要

维度	MCCL 2.1	MCCL 2.4	升级影响
版本基线	2.1	2.4	建议按完整版本升级，不建议只替换单个动态库
交付与构建	旧版目录和交付内容较简	安装、示例、版本查询和 CMake 查找更完整	自动化脚本若依赖旧目录结构，需要同步调整
集合通信接口	以传统 collectives 和基础 P2P 为主	除传统能力外，还补充 alltoall、gather、scatter 等更完整接口族	应用可以减少部分自实现的 send/recv 组合逻辑
通信器管理	基础初始化/销毁为主	支持配置初始化、Finalize、Revoke、Split、Shrink、Grow、属性查询	复杂拓扑、动态成员和容错场景可获得更强支持
缓冲区与窗口	基础注册能力	窗口注册、用户指针查询、LSA 指针查询、通信器内存统计更完整	对称窗口与主机侧辅助管理更容易实现
主机侧 RMA	无公开 signal 接口	支持 `mcclPutSignal`、`mcclSignal`、`mcclWaitSignal`	需要显式管理窗口、signal 索引和上下文
类型与配置结构	结构体字段较少	`mcclConfig_t`、属性结构和内存统计类型更完整	建议统一使用官方 initializer，避免手写旧布局

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

4.1 接口面整体比 2.1 更大

从 2.1 升级到 2.4，不只是小修小补，而是跨越多个阶段的能力扩展。应用通常会遇到以下变化：

可以继续使用传统 collectives 和 Send/Recv
可以逐步接入更完整的通信器管理、窗口和主机侧管理能力
原先依赖应用侧自拼装的一些逻辑，可能可以被公共 API 替代

4.2 结构体初始化方式需要统一

2.4 中多个结构体都采用了带 size/magic/version 的可扩展设计。建议统一使用：

MCCL_CONFIG_INITIALIZER
MCCL_COMM_PROPERTIES_INITIALIZER
MCCL_DEV_COMM_REQUIREMENTS_INITIALIZER

不建议：

手写结构体字面量
假设结构体字段数量固定
沿用 2.1 时期的裸 memset + 局部赋值 方式而不重新检查字段

4.3 需要重点关注的新增能力

2.4 中较重要的增量能力包括：

通信器属性查询：mcclCommQueryProperties
通信器动态扩容：mcclCommGetUniqueId、mcclCommGrow
通信器内存管理：mcclCommSuspend、mcclCommResume、mcclCommMemStats
对称窗口辅助接口：mcclWinGetUserPtr、mcclGetLsaDevicePointer
RMA signal：mcclPutSignal、mcclSignal、mcclWaitSignal

4.4 部分能力有明确前提

以下能力需要应用侧先探测平台能力，再决定是否启用：

mcclGetLsaDevicePointer：需要对称窗口和 device API/LSA 能力
mcclWinGetUserPtr：对不支持对称窗口辅助路径的平台存在特殊 fallback 行为
mcclCommSuspend / mcclCommResume / mcclCommMemStats：依赖通信器内存管理启用，且不支持 split/share 通信器
mcclPutSignal / mcclSignal / mcclWaitSignal：依赖对称窗口和 Host RMA 路径

4.5 主机侧管理操作需要串行化

涉及通信器内存管理和窗口管理的 host API，需要在同一通信器上进行外部串行化。不要并发混用：

collectives / mcclSend / mcclRecv
mcclCommSuspend
mcclCommResume
mcclCommMemStats
mcclCommWindowRegister
mcclCommWindowDeregister

5. 从 2.1 到 2.4 的主要能力差异

5.1 通信器与生命周期管理

2.4 相比 2.1，通信器管理能力显著增强，常见能力包括：

mcclCommInitRankConfig
mcclCommInitRankScalable
mcclCommFinalize
mcclCommRevoke
mcclCommSplit
mcclCommShrink
mcclCommQueryProperties
mcclCommGetUniqueId
mcclCommGrow

适用场景：

大规模初始化
通信域拆分与收缩
动态成员扩展
运行时能力探测

5.2 集合通信与点对点

2.4 相比 2.1 提供了更完整的集合通信接口族，文档与示例中已经覆盖：

mcclAlltoAll
mcclGather
mcclScatter

此外，还支持基于窗口的 RMA signal 流程：

mcclPutSignal
mcclSignal
mcclWaitSignal

5.3 对称窗口与主机侧辅助接口

除了窗口注册本身，2.4 还提供了更完整的辅助接口：

mcclWinGetUserPtr
mcclGetLsaDevicePointer

它们适合：

调试窗口与用户缓冲区映射关系
构造或验证 LSA 可见地址

5.4 通信器内存管理

2.4 提供了通信器级别的内存管理能力：

mcclCommSuspend
mcclCommResume
mcclCommMemStats
mcclCommMemStat_t

适合：

采集通信器逻辑内存统计
在资源敏感场景中挂起/恢复通信器托管资源

6. 推荐升级方式

建议采用“并行安装 + 重新编译 + 冒烟验证”的方式升级。

6.1 安装到独立目录

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

6.2 重新编译应用

建议所有依赖 MCCL 的程序重新编译并重新链接，重点检查：

是否统一使用官方 initializer
是否依赖 2.1 时期的旧目录结构或旧脚本路径
是否需要接入更完整的通信器、窗口或 RMA 能力

7. 升级后的验证建议

7.1 版本与安装验证

mccl_version

建议同时验证：

include/mccl.h
lib/libmccl.so
cmake/FindMCCL.cmake

7.2 基础通信回归

建议至少覆盖：

单机多卡 AllReduce
多机 AllReduce
现网主要消息规模与数据类型

7.3 主要能力专项验证

建议按需增加以下验证项：

通信器查询：examples/01_communicators/04_comm_query_properties
动态扩容：examples/01_communicators/05_comm_grow
通信器内存管理：examples/01_communicators/07_comm_manage_memory
LSA 指针查询：examples/05_symmetric_memory/02_get_lsa_device_pointer
窗口用户指针：examples/05_symmetric_memory/03_win_get_user_ptr
RMA signal：examples/08_rma/01_signal

8. 回退建议

如果升级验证未通过，建议：

恢复旧版安装目录对应的 LD_LIBRARY_PATH、PATH 和启动脚本
恢复旧版应用编译产物
恢复旧版工程依赖路径
重新执行基础通信冒烟验证

建议保留以下回退资产：

2.1 安装包和安装目录
2.1 对应的应用编译产物
2.1 的 hostfile、环境变量和启动命令

9. 升级结论

从 MCCL 2.1 升级到 2.4，收益主要体现在接口完整性、通信器管理能力和主机侧辅助管理能力上。

推荐优先升级的场景：

需要更完整的通信器生命周期和域管理
需要运行时探测设备 API / GIN / LSA / Host RMA 能力
需要动态扩容通信器
需要主机侧管理对称窗口或通信器内存
需要基于 signal 的 RMA 流程

建议专项验证的场景：

自己手写了 mcclConfig_t / mcclDevCommRequirements_t 初始化代码
使用 Device API 和对称窗口
有严格的资源占用控制需求，准备启用 suspend/resume
需要把新能力集成到长期运行服务中

1. 文档目的​

2. 升级收益概览​

3. 升级影响摘要​

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

4.1 接口面整体比 2.1 更大​

4.2 结构体初始化方式需要统一​

4.3 需要重点关注的新增能力​

4.4 部分能力有明确前提​

4.5 主机侧管理操作需要串行化​

5. 从 2.1 到 2.4 的主要能力差异​

5.1 通信器与生命周期管理​

5.2 集合通信与点对点​

5.3 对称窗口与主机侧辅助接口​

5.4 通信器内存管理​

6. 推荐升级方式​

6.1 安装到独立目录​

6.2 重新编译应用​

7. 升级后的验证建议​

7.1 版本与安装验证​

7.2 基础通信回归​

7.3 主要能力专项验证​

8. 回退建议​

9. 升级结论​

这篇文章对您有帮助吗？