HCCL AllReduce 集合通信示例详解:从单机多卡环境搭建到 HcclAllReduce 接口源码剖析
HCCL AllReduce 集合通信示例详解:从单机多卡环境搭建到 HcclAllReduce 接口源码剖析
导读
本文基于 CANN HCCL(华为集合通信库)开源仓库中的官方示例 examples/02_collectives/01_allreduce,完整讲解如何在单机多卡(N >= 2)环境上编译、运行一个最基础的 AllReduce 集合通信程序:从设备探测、rootinfo 通信域初始化,到调用 HcclAllReduce() 完成全量归约并验证结果。读完本文,你将掌握 HCCL 集合通信程序的标准编写范式(ACL 内存管理 + 通信域初始化 + 算子下发 + 结果回拷),理解 HcclAllReduce() 接口每个参数的语义、支持的数据类型与归约操作约束,并能通过仓库源码追溯到算子内部的参数校验与算法选择流程。
AllReduce 语义示意:通信域内所有 rank 的输入数据经过归约(此处为相加)后,结果发送到所有 rank 的输出 buffer。图片来源 HcclAllReduce 接口参考。
一、示例概览:一个最小的 AllReduce 程序
该示例位于仓库 examples/02_collectives/01_allreduce 目录,演示了调用 HcclAllReduce() 执行 AllReduce 操作所需的完整流程,包含以下功能点:
-
设备检测:通过
aclrtGetDeviceCount()查询可用设备数量; -
生成 rootinfo 标识:将 rank 0 作为 root 节点,通过
HcclGetRootInfo()生成 root 节点的 rootinfo 标识信息;rootinfo 标识信息主要包含 Device IP、Device ID 等信息,此信息需广播至集群内所有 rank 用来初始化通信域。
-
在每个线程中,基于 rootinfo 标识信息通过
HcclCommInitRootInfo()初始化通信域; -
调用
HcclAllReduce(),将通信域内所有 rank 的输入数据进行相加后,再把结果发送到所有节点,并打印结果。
这种"单进程内多线程 + rootinfo"的通信域初始化方式,是 HCCL 单机多卡场景(尤其是容器内无外部通信框架协助建链时)的典型用法:进程内每个线程绑定一块 Device,线程之间通过共享同一份 rootinfo 完成全集群建链。
目录结构
├── main.cc # 样例源文件
├── Makefile # 编译/构建配置文件
└── all_reduce # 编译生成的可执行文件
二、环境准备
环境要求
本样例支持以下产品,组网为单机 N 卡(N >= 2):
- Ascend 950PR / Ascend 950DT
- Atlas A3 训练系列产品 / Atlas A3 推理系列产品
- Atlas A2 训练系列产品
- Atlas 训练系列产品 / Atlas 推理系列产品
配置环境变量
编译链接 HCCL 程序需要 CANN 工具链环境,以 root 用户默认安装路径为例:
source /usr/local/Ascend/cann/set_env.sh
该脚本会导出 ASCEND_HOME_PATH 等关键变量。Makefile 中通过 ASCEND_HOME_PATH 定位 CANN 的 include 与 lib64 目录(详见下文"编译配置解析"),若未设置该变量,make 会直接报错提示先执行 source。
三、编译与运行
在示例代码目录下执行如下命令:
make
make test
make:编译生成可执行文件all_reduce;make test:运行该可执行文件。
注意:可通过设置
HCCL_OP_EXPANSION_MODE环境变量配置通信算子的展开模式,不同产品型号支持的范围可参考仓库内 环境变量列表 中该环境变量的使用方法(对应文档为 HCCL_OP_EXPANSION_MODE.md)。# 设置通信算子的展开模式为 AI CPU 通信引擎 export HCCL_OP_EXPANSION_MODE=AI_CPU
编译配置解析(Makefile)
Makefile(examples/02_collectives/01_allreduce/Makefile)展示了 HCCL 应用的标准链接方式:
ASCEND_INC_DIR = ${ASCEND_HOME_PATH}/include
ASCEND_LIB_DIR = ${ASCEND_HOME_PATH}/lib64
LIBS = -L$(ASCEND_LIB_DIR) -lhccl -lascendcl
INCS = -I$(ASCEND_INC_DIR)
TARGET = all_reduce
all:
g++ $(CXXFLAGS) $(SOURCES) $(INCS) $(LIBS) -o ${TARGET}
其中 -lhccl 链接 HCCL 集合通信库,-lascendcl 链接 ACL(Ascend Computing Language)运行时库,头文件目录指向 hccl/hccl.h 与 acl/acl.h 所在位置。编译选项启用了 -std=c++17、-Werror、-fstack-protector-strong、-fPIE -pie、-O2 以及 -Wl,-z,relro / -Wl,-z,now 等安全加固参数,与仓库整体安全编译规范一致。
四、源码逐段解析
示例源码 main.cc 约 140 行,逻辑清晰,可拆解为四个阶段。先看两个关键的宏,它们在后续所有 ACL/HCCL 接口调用中充当统一错误检查:
#define ACLCHECK(ret) ... // acl 接口返回值非 ACL_SUCCESS 即报错返回
#define HCCLCHECK(ret) ... // hccl 接口返回值非 HCCL_SUCCESS 即报错返回
阶段一:主线程初始化设备与生成 rootinfo(main 函数)
ACLCHECK(aclInit(NULL)); // 设备资源初始化
uint32_t devCount;
ACLCHECK(aclrtGetDeviceCount(&devCount)); // 查询设备数量
std::cout << "Found " << devCount << " NPU device(s) available" << std::endl;
int32_t rootRank = 0;
ACLCHECK(aclrtSetDevice(rootRank)); // 当前线程切换到 rank0 设备
void* rootInfoBuf = nullptr;
ACLCHECK(aclrtMallocHost(&rootInfoBuf, sizeof(HcclRootInfo)));
HcclRootInfo* rootInfo = (HcclRootInfo*)rootInfoBuf;
HCCLCHECK(HcclGetRootInfo(rootInfo)); // 生成 Root 节点信息
关键点:HcclGetRootInfo() 必须在 root 设备(此处为 device 0)上调用,生成的 HcclRootInfo 中包含建链所需的 Device IP、Device ID 等信息,随后各线程共用同一份 rootInfo 去初始化各自设备上的通信域——这正是单进程多线程场景下避免重复建链的标准做法。
阶段二:多线程并发执行 Sample(main 函数)
std::vector<std::thread> threads(devCount);
std::vector<ThreadContext> args(devCount);
for (uint32_t i = 0; i < devCount; i++) {
args[i].rootInfo = rootInfo;
args[i].device = i; // 每个线程绑定一块设备
args[i].devCount = devCount; // 通信域规模 = 设备数
threads[i] = std::thread(Sample, (void*)&args[i]);
}
for (uint32_t i = 0; i < devCount; i++) {
threads[i].join();
}
每个线程负责一块 NPU,devCount 既表示设备数量,也作为参与 AllReduce 的数据元素个数(count = devCount),这样输出数组的每一列恰好就是"所有 rank 对应位置之和"。
阶段三:线程内准备数据并初始化通信域(Sample 函数)
ACLCHECK(aclrtSetDevice(static_cast<int32_t>(device))); // 设置当前线程操作的设备
ACLCHECK(aclrtMalloc(&sendBuf, mallocSize, ACL_MEM_MALLOC_HUGE_ONLY)); // 申请 Device 内存
ACLCHECK(aclrtMalloc(&recvBuf, mallocSize, ACL_MEM_MALLOC_HUGE_ONLY));
...
float* tmpHostBuff = static_cast<float*>(hostBuf);
for (uint64_t i = 0; i < count; ++i) {
tmpHostBuff[i] = static_cast<float>(i); // 输入数据初始化为 0,1,2,… 递增序列
}
ACLCHECK(aclrtMemcpy(sendBuf, mallocSize, hostBuf, mallocSize, ACL_MEMCPY_HOST_TO_DEVICE));
ACLCHECK(aclrtFreeHost(hostBuf));
HcclComm hcclComm;
HCCLCHECK(HcclCommInitRootInfo(ctx->devCount, ctx->rootInfo, device, &hcclComm)); // 初始化通信域
这段代码体现了 HCCL 编程的两条铁律:
- Device 内存必须由 ACL 接口分配:
aclrtMalloc(..., ACL_MEM_MALLOC_HUGE_ONLY)申请大页内存,集合通信数据必须位于 Device 侧(sendBuf/recvBuf); - Host 数据需显式拷入 Device:先用
aclrtMallocHost申请 Host 锁页内存填充数据,再经aclrtMemcpy以ACL_MEMCPY_HOST_TO_DEVICE方向拷入 sendBuf。
HcclCommInitRootInfo(rankSize, rootInfo, deviceId, &hcclComm) 的参数含义为:通信域规模(= 设备数)、rootinfo 标识、本 rank 所在设备号、输出的通信域句柄。
阶段四:下发 AllReduce 算子并取回结果
aclrtStream stream;
ACLCHECK(aclrtCreateStream(&stream)); // 创建任务流
// 执行 AllReduce:将通信域内所有节点的 sendBuf 相加后,结果发送到所有节点的 recvBuf
HCCLCHECK(HcclAllReduce(sendBuf, recvBuf, count, HCCL_DATA_TYPE_FP32, HCCL_REDUCE_SUM, hcclComm, stream));
ACLCHECK(aclrtSynchronizeStream(stream)); // 阻塞等待任务流中的集合通信任务执行完成
std::this_thread::sleep_for(std::chrono::seconds(device)); // 错峰打印,避免输出交错
void* resultBuff;
ACLCHECK(aclrtMallocHost(&resultBuff, mallocSize));
ACLCHECK(aclrtMemcpy(resultBuff, mallocSize, recvBuf, mallocSize, ACL_MEMCPY_DEVICE_TO_HOST)); // 结果拷回 Host
...
HcclAllReduce 是异步接口:算子被提交到指定 stream 后立即返回,必须通过 aclrtSynchronizeStream(stream) 等待执行完成,之后才能安全地将 recvBuf 拷回 Host 打印。每个 rank 通过 sleep_for(device) 秒错峰输出,避免 8 个线程同时打印造成输出交错。
阶段五:资源释放
HCCLCHECK(HcclCommDestroy(hcclComm)); // 销毁通信域
ACLCHECK(aclrtFree(sendBuf)); // 释放 Device 侧内存
ACLCHECK(aclrtFree(recvBuf)); // 释放 Device 侧内存
ACLCHECK(aclrtDestroyStream(stream)); // 销毁任务流
主线程最后还会释放 rootInfoBuf 并调用 aclFinalize() 完成设备去初始化。资源释放顺序与申请顺序相反,属于标准 RAII 式清理。
五、HcclAllReduce 接口详解
示例的核心调用为 HcclAllReduce,其完整接口定义在 include/hccl.h 中声明,函数原型如下:
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 枚举) |
| op | 输入 | Reduce 的操作类型(HcclReduceOp 枚举) |
| comm | 输入 | 集合通信操作所在的通信域 |
| stream | 输入 | 本 rank 所使用的 stream |
不同产品支持的数据类型(dataType)
| 产品型号 | 支持的数据类型 |
|---|---|
| Ascend 950PR / Ascend 950DT | int8、int16、int32、int64、uint64、float16、float32、float64、bfp16 |
| Atlas A3 训练系列 / A3 推理系列 | int8、int16、int32、int64、float16、float32、bfp16 |
| Atlas A2 训练系列 | int8、int16、int32、int64、float16、float32、bfp16(int64 性能有一定劣化) |
| Atlas 训练系列 | int8、int32、int64、float16、float32 |
| Atlas 300I Duo 推理卡 | int8、int16、int32、float16、float32 |
不同产品支持的归约操作(op)
| 产品型号 | 支持的归约操作 |
|---|---|
| Ascend 950PR / 950DT | sum、prod、max、min(prod 不支持 int16、bfp16) |
| Atlas A3 训练系列 / A3 推理系列 | sum、prod、max、min(prod 不支持 int16、bfp16) |
| 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) |
返回值
返回值类型为 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 | 内部错误 |
使用约束
- 所有 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 上需要保证串行下发,不允许乱序、多线程并发下发,也不支持线程重入;
- 在同一 Device 上,同一通信域内的所有通信算子的下发线程需要使用相同的 Context;
- 当通信域注册了对称内存时,sendBuf 指向的输入 buffer 会被作为对称窗口参与远端 rank 的直接读写,AllReduce 过程中部分算法会在 sendBuf 上就地完成归约(read+reduce),导致 sendBuf 中的数据被修改(污染),因此调用
HcclAllReduce后 sendBuf 中的数据不应再作为原始输入使用;如需保留原始输入,请在调用前自行备份。
六、算子展开模式:HCCL_OP_EXPANSION_MODE 深入说明
示例文档中特别提示可通过 HCCL_OP_EXPANSION_MODE 环境变量控制通信算子展开模式,仓库内完整说明见 HCCL_OP_EXPANSION_MODE.md。该变量决定了 AllReduce 这类通信算子在哪种计算单元上展开执行,直接关系到性能与功能范围:
export HCCL_OP_EXPANSION_MODE="AI_CPU"
以示例支持的 Ascend 950PR/950DT 为例,可选配置包括:
- AI_CPU:通信算子在 AI CPU 展开,Device 侧根据硬件型号自动选择相应的调度器,支持 Broadcast、Reduce、AllReduce、Scatter、ReduceScatter、AllGather、AlltoAll、Send/Recv 等全量算子。该配置将在后续版本废弃,由 AICPU_TS 代替;
- AICPU_TS(默认值):在 AI CPU 展开,使用 STARS 调度器调度运行,功能与 AI_CPU 完全一致;
- AICPU_CacheDisable:关闭 HCCL 算子的 AI CPU cache 特性(cache 指同一通信算子第二次执行时复用首次执行结果以节省展开开销),在通信数据量频繁变化的服务场景中建议配置以减小显存开销;
- AIV:通信算子在 Vector Core 展开并执行,仅支持对称组网、推理特性,AllReduce 在此模式下数据类型支持 int8、int16、int32、int64、float16、float32、bfp16;
- CCU_MS / CCU_SCHED:通信算子在 CCU 展开(Ascend 950PR 不支持 CCU_MS),使用 CcuBuffer 中转或调度模式传输;当 CCU 资源不足时系统会自动切换为 AI_CPU 模式。
不同产品型号的默认值与支持范围不同:例如 Atlas A3 系列默认值为 AI_CPU,Atlas A2 训练系列默认值为 HOST。若设置了不支持的环境变量,部分型号(950 系列)会直接报错,部分型号(A3、A2 等)则回退使用默认值。此外,若通过 HcclCommConfig 的 hcclOpExpansionMode 参数配置了通信域粒度的展开模式,则以通信域粒度的配置优先。
七、源码视角:HcclAllReduce 在 HCCL 内部的执行路径
示例调用的 HcclAllReduce 在仓库中的实现位于 src/ops/all_reduce/all_reduce.cc,其内部流程可以印证示例文档中的约束说明:
- 兼容路径判断:当 HCCL 版本低于 9.0.0 时直接走
HcclAllReduceInner老流程; - 入口环境解析与参数校验:
AllReduceInitAndCheck()先调用InitEnvConfig()解析环境变量(即上文HCCL_OP_EXPANSION_MODE等),再通过CheckAllReduceInputPara()校验 comm/sendBuf/recvBuf/stream 非空(对应返回码 HCCL_E_PTR),随后校验 rankSize、userRank、CheckCount(count)、CheckDataType(dataType)与CheckReduceOp(dataType, op)(对应 HCCL_E_PARA / HCCL_E_NOT_SUPPORT); - 执行引擎分流:
AllReduceOutPlaceCommon()中先通过HcclGetOpExpansionMode()获取展开模式,按 AIV(带 AI CPU cache 命中检查)/ CCU 快速启动 / 默认 AICPU 等引擎分发;若rankSize == 1则进入单卡流程SingleRankProc; - 算法选择与执行:
Selector()根据拓扑信息(TopoInfoWithNetLayerDetails)与数据量选择具体算法,随后HcclExecOp()真正下发执行。
算法选择器 all_reduce_auto_selector.cc 中的常数值直观展示了"数据量驱动算法决策"的细节,例如:
constexpr u64 AR_ONESHOT_1D_MAX_DATA_SIZE = 16 * 1024; // 16KB 以下可走单发 1D 算法
constexpr u64 AR_AICPU_1D_MAX_DATA_SIZE = 32 * 1024 * 1024; // 32MB 为 AI CPU 1D 算法上限
constexpr u64 AR_FLATTEN_MAX_DATA_SIZE = 512 * 1024; // 512KB 以下可展平处理
constexpr u32 AR_CCU_MAX_RANK_SIZE = 64; // CCU 模式通信域规模上限
示例中 8 个 rank、每个 rank 8 个 float(32 字节)属于典型的小数据量场景,从选择器源码看会命中单发/小数据量快速路径。这些算法(Ring、Mesh、NHR、PipeLine 等)的细节可进一步参考 docs/zh/user_guide/coll_algo_intro 中的算法介绍。
八、运行结果与验证
每个 rank 的输入数据初始化为 0~7,即 rank i 的第 j 个元素值为 j。经过 AllReduce(SUM)后,每个 rank 的结果是所有 rank 对应位置数据的和(8 个 rank 的数据相加),例如第 0 列为 0×8=0、第 1 列为 1×8=8,依此类推:
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, output: [ 0 8 16 24 32 40 48 56 ]
rankId: 3, output: [ 0 8 16 24 32 40 48 56 ]
rankId: 4, output: [ 0 8 16 24 32 40 48 56 ]
rankId: 5, output: [ 0 8 16 24 32 40 48 56 ]
rankId: 6, output: [ 0 8 16 24 32 40 48 56 ]
rankId: 7, output: [ 0 8 16 24 32 40 48 56 ]
验证要点:
- 数值正确性:每个 rank 的输出完全相同,且第 j 列 = j × rank 数(此处为 8),符合 AllReduce 的"全量归约 + 全量广播"语义;
- rank 一致性:8 行输出一致,说明通信域内所有 rank 的归约结果已正确同步到每个节点的 recvBuf。
九、从示例到实战的扩展路径
掌握本示例后,可沿着以下方向继续深入(均可在仓库中找到对应材料):
- 其他集合通信算子:本示例是 examples/02_collectives 系列的一个样例,同目录下还有 Broadcast、AllGather、ReduceScatter、Reduce、AlltoAll、AlltoAllV、AlltoAllVC、Scatter 等样例,均沿用"设备探测 → rootinfo 建域 → 算子下发 → 结果回拷"的统一范式;
- 点对点通信:Send/Recv 与 BatchSendRecv 的完整示例见 examples/01_point_to_point;
- AI 框架集成:PyTorch / TensorFlow 侧调用 HCCL 的参考见 examples/03_ai_framework;
- 接口参考:AllReduce 接口的完整约束、对齐要求与调用示例见 HcclAllReduce.md,集合通信接口总览见 comm_op_interface;
- 环境变量体系:
HCCL_OP_EXPANSION_MODE之外,HCCL_BUFFSIZE、HCCL_ALGO、HCCL_DETERMINISTIC等通信行为相关环境变量见 hccl_env 目录。
总结
本示例是理解 HCCL 集合通信编程的最佳起点:它以最少的代码量覆盖了"ACL 设备管理 + rootinfo 通信域初始化 + 多线程多卡并发 + AllReduce 下发 + 异步等待 + 结果验证"的完整链路。结合仓库内的接口参考文档与 all_reduce.cc 源码,开发者既能获得可编译运行的真实范例,也能深入理解参数校验、展开模式选择与算法调度等底层机制,为后续编写多机场景或生产级集合通信程序打下坚实基础。