HCCL HcclAllReduce 详解:AllReduce 集合通信算子接口、参数约束与源码执行链路
HCCL HcclAllReduce 详解:AllReduce 集合通信算子接口、参数约束与源码执行链路
本文为 CANN 集合通信库 HCCL(Huawei Collective Communication Library)的 HcclAllReduce 接口技术指南。AllReduce 是分布式训练中最高频的集合通信操作,本篇将完整覆盖该接口的函数原型、参数说明、各型号支持的数据类型与归约操作、返回值与约束条件,并结合仓库中的算子入口源码(src/ops/all_reduce/all_reduce.cc)、参数校验实现(src/ops/op_common/op_common.cc)和可运行的官方示例(examples/02_collectives/01_allreduce/main.cc),帮助读者既会用接口、又懂其底层校验与调度机制。读完后,你能够独立完成 AllReduce 的内存申请、通信域初始化、算子下发与结果验证,并理解接口内部从参数检查到算法执行的完整调用链。
功能说明与产品支持情况
集合通信算子 AllReduce 的操作接口:将通信域内所有节点的输入数据进行相加(或其他归约操作)后,再把结果发送到所有节点的输出 buffer,其中归约操作类型由 op 参数指定。
该接口在 HCCL 公共头文件 include/hccl.h 中以 extern "C" 形式声明,是 HCCL 对外 API 的一部分(通过 #include <hccl/hccl.h> 引入)。
产品支持情况(依据 HcclAllReduce 接口文档):
- Ascend 950PR/Ascend 950DT:支持
- Atlas A3 训练系列产品/Atlas A3 推理系列产品:支持
- Atlas A2 训练系列产品/Atlas A2 推理系列产品:支持
- Atlas 推理系列产品:支持
- Atlas 训练系列产品:支持
函数原型
HcclResult HcclAllReduce(void *sendBuf, void *recvBuf, uint64_t count, HcclDataType dataType, HcclReduceOp op, HcclComm comm, aclrtStream stream)
参数说明
| 参数名 | 输入/输出 | 描述 |
|---|---|---|
sendBuf |
输入 | 源数据 buffer 地址。 |
recvBuf |
输出 | 目的数据 buffer 地址,集合通信结果输出至此 buffer 中。 |
count |
输入 | 参与 allreduce 操作的数据个数,比如只有一个 int32 数据参与,则 count=1。 |
dataType |
输入 | allreduce 操作的数据类型(HcclDataType)。不同型号支持的数据类型不同,详见下文 dataType 说明。 |
op |
输入 | reduce 的操作类型(HcclReduceOp)。不同型号支持的操作类型不同,详见下文 op 说明。 |
comm |
输入 | 集合通信操作所在的通信域(HcclComm)。 |
stream |
输入 | 本 rank 所使用的任务流(aclrtStream)。 |
从源码实现看(src/ops/all_reduce/all_reduce.cc),接口入口首先记录入口日志,然后根据 HComm 版本与设备形态判断是否走内部兼容流程 HcclAllReduceInner,否则进入标准的 AllReduceInitAndCheck → AllReduceEntryLog → AllReduceOutPlace 执行路径。
dataType 说明
按产品型号划分的支持数据类型如下:
- 针对 Ascend 950PR/Ascend 950DT,支持数据类型:
int8、int16、int32、int64、uint64、float16、float32、float64、bfp16。 - 针对 Atlas A3 训练系列产品/Atlas A3 推理系列产品,支持数据类型:
int8、int16、int32、int64、float16、float32、bfp16。 - 针对 Atlas A2 训练系列产品/Atlas A2 推理系列产品,支持数据类型:
int8、int16、int32、int64、float16、float32、bfp16。需要注意,针对int64数据类型,性能会有一定的劣化。 - 针对 Atlas 训练系列产品,支持数据类型:
int8、int32、int64、float16、float32。 - 针对 Atlas 300I Duo 推理卡,支持数据类型:
int8、int16、int32、float16、float32。
源码层面,数据类型校验由 CheckDataType 完成:它会先检查是否为合法的 HcclDataType 枚举值;对于归约类算子(needReduce 为真),还维护了一个 REDUCE_UNSUPPORTED 集合(包含 uint8、uint16、uint32、int128、hif8、fp8e4m3、fp8e5m2、fp8e8m0),这些类型在 AllReduce 等归约场景中直接返回 HCCL_E_NOT_SUPPORT。
op 说明
按产品型号划分的支持归约操作如下(sum、prod、max、min):
- 针对 Ascend 950PR/Ascend 950DT,支持的操作类型为
sum、prod、max、min,其中prod操作不支持int16、bfp16数据类型。 - 针对 Atlas A3 训练系列产品/Atlas A3 推理系列产品,支持的操作类型为
sum、prod、max、min,其中prod操作不支持int16、bfp16数据类型。 - 针对 Atlas A2 训练系列产品/Atlas A2 推理系列产品,支持的操作类型为
sum、prod、max、min,其中prod操作不支持int16、bfp16数据类型。 - 针对 Atlas 训练系列产品,支持的操作类型为
sum、prod、max、min。 - 针对 Atlas 300I Duo 推理卡,支持的操作类型为
sum、prod、max、min,其中prod、max、min操作不支持int16数据类型。
源码中对应的校验函数为 CheckReduceOp:当 op 为 HCCL_REDUCE_PROD 时,会检查数据类型是否在支持列表中(int8、int32、int64、uint64、fp16、fp32、fp64),否则返回 HCCL_E_NOT_SUPPORT 并打印 EI0003 诊断信息。
count 的上限检查
count 并非任意取值都合法。从 CheckCount 的实现看,当 count 超过系统上限 SYS_MAX_COUNT 时会返回 HCCL_E_PARA 并输出错误日志。
返回值
接口返回 HcclResult 类型,各取值含义如下:
| 返回值 | 说明 |
|---|---|
HCCL_SUCCESS |
接口调用成功。 |
HCCL_E_PTR |
传入的指针参数为空,如 comm、sendBuf、recvBuf、stream 等为 nullptr。 |
HCCL_E_PARA |
传入的参数无效,如 count 超过上限等。 |
HCCL_E_NOT_SUPPORT |
操作不被支持,如 dataType 非法或当前型号不支持、prod 操作不支持 int16/bfp16 数据类型等。 |
HCCL_E_INTERNAL |
内部错误。 |
这些返回值与源码中的校验逻辑一一对应:CheckAllReduceInputPara(src/ops/all_reduce/all_reduce.cc)对 stream、comm、sendBuf、recvBuf 逐一做空指针检查,命中即上报 EI0003 并返回指针类错误;CheckCount 超限返回 HCCL_E_PARA;CheckDataType/CheckReduceOp 命中不支持组合返回 HCCL_E_NOT_SUPPORT。
约束说明
使用 HcclAllReduce 时必须遵守以下约束:
- 参数一致性:所有 rank 的
count、dataType、op均应相同。 - 单输入:每个 rank 只能有一个输入。
- 地址对齐要求:算子的输入输出地址(
sendBuf与recvBuf)根据不同的数据类型,应满足如下对齐要求:int8按照 1 Byte 地址对齐。int16、float16、bfp16按照 2 Byte 地址对齐。int32、float32按照 4 Byte 地址对齐。int64、uint64、float64按照 8 Byte 地址对齐。
- 串行下发:多个通信域下的所有通信算子在每个 Device 上需要保证串行下发,不允许乱序、多线程并发下发,也不支持线程重入。
- Context 一致:在同一 Device 上,同一通信域内的所有通信算子的下发线程需要使用相同的 Context。
- 对称内存与 sendBuf 污染风险:当通信域注册了对称内存时,
sendBuf指向的输入 buffer 会被作为对称窗口参与远端 rank 的直接读写,AllReduce 过程中部分算法会在sendBuf上就地完成归约(read+reduce),导致sendBuf中的数据被修改(污染)。因此用户需保证:- 调用
HcclAllReduce后,sendBuf中的数据不再作为原始输入使用; - 如需保留原始输入数据,请在调用前自行备份
sendBuf。
- 调用
从源码结构看,对称内存特性并非无条件开启:在 AllReduceOutPlaceCommon 中,只有通信引擎为 AICPU_TS、level0 拓扑为 MESH_1D、数据类型不为 int64/uint64/fp64、且归约操作不为 prod 时,param.supportSymmetricMemory 才可能置位;对特定的 Mesh 算法(如两级 Mesh NHR 或 Concurrent Mesh NHR)也会单独关闭该特性。这意味着该“sendBuf 被就地归约”的风险主要出现在对称内存生效的路径上,用户在训练框架封装层做 buffer 复用时尤需注意。
调用示例
接口文档给出的最小调用示例(节选自 HcclAllReduce.md):
// 申请集合通信操作的Device 内存
void *sendBuf = nullptr;
void *recvBuf = nullptr;
uint64_t count = 8;
size_t mallocSize = count * sizeof(float);
aclrtMalloc((void **)&sendBuf, mallocSize, ACL_MEM_MALLOC_HUGE_ONLY);
aclrtMalloc((void **)&recvBuf, mallocSize, ACL_MEM_MALLOC_HUGE_ONLY);
// 初始化通信域
uint32_t rankSize = 8;
HcclComm hcclComm;
HcclCommInitRootInfo(rankSize, &rootInfo, deviceId, &hcclComm);
// 创建任务流
aclrtStream stream;
aclrtCreateStream(&stream);
// 执行AllReduce,将通信域内所有节点的输入数据进行相加后,再把结果发送到所有节点的输出buffer
HcclAllReduce(sendBuf, recvBuf, count, HCCL_DATA_TYPE_FP32, HCCL_REDUCE_SUM, hcclComm, stream);
// 阻塞等待任务流中的集合通信任务执行完成
aclrtSynchronizeStream(stream);
// 释放资源
aclrtFree(sendBuf); // 释放Device侧内存
aclrtFree(recvBuf); // 释放Device侧内存
aclrtDestroyStream(stream); // 销毁任务流
HcclCommDestroy(hcclComm); // 销毁通信域
完整可运行示例
仓库提供了完整的 AllReduce 样例 examples/02_collectives/01_allreduce/main.cc(说明文档见 examples/02_collectives/01_allreduce/README.md),演示了单机 N 卡(N>=2)组网下的完整流程,关键步骤如下:
- 设备初始化与探测:
aclInit(NULL)后调用aclrtGetDeviceCount(&devCount)查询可用 NPU 数量。 - 生成 RootInfo:rank0 上调用
HcclGetRootInfo(rootInfo)生成 root 节点标识信息(包含 Device IP、Device ID 等),该信息需广播至集群内所有 rank 用于初始化通信域。 - 每设备一线程:每个线程先
aclrtSetDevice(device)绑定设备,然后aclrtMalloc申请 Device 内存、aclrtMallocHost+aclrtMemcpy准备输入数据(示例中初始化为 0~count-1 的递增序列),再通过HcclCommInitRootInfo(ctx->devCount, ctx->rootInfo, device, &hcclComm)初始化通信域。 - 下发 AllReduce:
HCCLCHECK(HcclAllReduce(sendBuf, recvBuf, count, HCCL_DATA_TYPE_FP32, HCCL_REDUCE_SUM, hcclComm, stream));
ACLCHECK(aclrtSynchronizeStream(stream));
- 结果回读与校验:将
recvBuf拷回 Host 打印。以 8 卡为例,每个 rank 的输入为 0~7,AllReduce(SUM) 后每个 rank 的结果均为 8 个 rank 对应位置之和,输出形如:
Found 8 NPU device(s) available
rankId: 0, output: [ 0 8 16 24 32 40 48 56 ]
rankId: 1, output: [ 0 8 16 24 32 40 48 56 ]
...(rankId 2~7 输出相同)
- 资源释放:
HcclCommDestroy销毁通信域,aclrtFree释放 Device 内存,aclrtDestroyStream销毁任务流,aclFinalize()去初始化设备。
编译运行方式(样例目录内):
# 设置 CANN 环境变量,以 root 用户默认安装路径为例
source /usr/local/Ascend/cann/set_env.sh
make
make test
说明:可通过设置
HCCL_OP_EXPANSION_MODE环境变量配置通信算子的展开模式,例如export HCCL_OP_EXPANSION_MODE=AI_CPU强制使用 AICPU 通信引擎,不同产品型号支持的范围以环境变量文档为准。
源码级执行链路剖析
以新版执行路径(HComm 版本 >= 9.0.0 且非兼容设备)为例,HcclAllReduce 的内部调用链如下:
1. 入口分发(all_reduce.cc)
入口先做 count == 0 的快速成功返回,再依次调用 AllReduceInitAndCheck(初始化环境配置 + 参数校验)、AllReduceEntryLog(接口交互日志,开启 HCCL_ENTRY_LOG_ENABLE 后记录 tag、buffer 地址、count、dataType、reduceOp、streamId、deviceId 等)、AllReduceOutPlace(实际执行)与 LogHcclExit(退出日志与耗时统计)。
2. 参数校验(AllReduceInitAndCheck)
依次完成:InitEnvConfig 解析环境变量 → CheckAllReduceInputPara 空指针检查 → HcclGetRankSize/HcclGetRankId/HcclGetCommName 获取通信域信息并生成算子 tag(AllReduce_%s 格式,相同算子可共享拓扑信息)→ CheckCount、CheckDataType(dataType, true)、CheckReduceOp(dataType, op)。校验失败时均带上 EI0003 诊断码上报,便于结合故障诊断文档定位问题。
3. 参数装配(FillAllReduceOpParam)
将 sendBuf/recvBuf/count/dataType/op 填入 OpParam,其中 inputSize = outputSize = count * DATATYPE_SIZE_TABLE[dataType],操作类型设为 HcclCMDType::HCCL_CMD_ALLREDUCE。
4. 引擎选择与算法执行(AllReduceOutPlaceCommon)
执行前会依次判断:CCU 快速下发路径(ShouldGoCcuFastLaunch)、AIV 引擎缓存回放(HcclAivCacheCheckAndReplay,命中则直接返回)、单 rank 场景(ranksize == 1 时走 SingleRankProc 本地处理)。常规多 rank 路径则调用 Selector(comm, param, topoInfo, algName) 依据拓扑信息选择算法,最终经 HcclExecOp 下发执行。
5. 算法执行器(src/ops/all_reduce/algorithm/executor/) AllReduce 的具体算法按执行器组织,从目录结构可见其覆盖了多种典型形态,例如:
ins_v2_all_reduce_sequence_executor*(含 AICPU 变体与 3 层拓扑变体):逐段式执行;ins_v2_all_reduce_two_shot_sole_executor:Two-Shot 算法(Reduce + Broadcast);ins_v2_all_reduce_parallel_executor、ins_v2_all_reduce_concurrent_executor:并行/并发执行形态;ins_v2_all_reduce_omnipipe_executor、ins_v2_all_reduce_omnipipe_2d_executor:Omnipipe 数据分片执行;ins_v2_all_reduce_order_preserved_executor、ins_v2_allreduce_sequence2die_executor:保序执行与双 die 形态。 算法模板按通信引擎进一步分为 aicpu、aiv、ccu 三个子目录,对应不同硬件通信引擎上的实现。
从源码结构看,接口文档中的“各型号能力差异”(数据类型、op 支持范围)与执行路径中的多重判断(HComm 版本、引擎类型、拓扑形态、对称内存)共同构成了 AllReduce 的实际行为边界:同一份调用代码在不同型号与组网下可能走不同执行器,但对外语义保持不变。
常见使用注意事项
- 异步语义:
HcclAllReduce是异步下发接口,返回HCCL_SUCCESS仅表示下发成功,不代表计算完成;必须通过aclrtSynchronizeStream(stream)等待任务流中的集合通信任务执行完毕后再使用recvBuf。 - 所有 rank 必须调用:集合通信要求通信域内所有 rank 都参与同一算子,且
count、dataType、op完全一致,否则会导致通信挂起或结果错误。 - buffer 复用风险:注册了对称内存时,部分算法会就地修改
sendBuf(详见上文对称内存约束),框架层复用输入 buffer 前建议显式备份或等待同步完成。 - 下发纪律:同一 Device 上多个通信域的算子必须串行下发,不允许乱序、多线程并发下发,也不支持线程重入;同一通信域内的算子下发需使用相同 Context。
- 返回码即诊断线索:
HCCL_E_PTR/HCCL_E_PARA/HCCL_E_NOT_SUPPORT分别对应空指针、参数超限、类型/操作不支持三类问题,源码中每类错误都附带 EI0003 上报信息,可结合 故障诊断文档 中的相应条目进一步定位。
相关文档
- 通信算子接口总览:包含
HcclBroadcast、HcclAllGather、HcclReduce、HcclScatter、HcclReduceScatter、HcclAlltoAll等其他集合通信与点对点算子接口文档。 - HCCL 头文件与库说明
- AllReduce 算子源码入口 与 执行器目录
- AllReduce 运行示例
