ascend-transformer-boost AllReduceOperation C++ Demo 实战指南：多卡通信算子的调用与验证

ascend-transformer-boost AllReduceOperation C++ Demo 实战指南：多卡通信算子的调用与验证

【免费下载链接】ascend-transformer-boost本项目是CANN提供的是一款高效、可靠的Transformer加速库，基于华为Ascend AI处理器，提供Transformer定制化场景的高性能融合算子。项目地址: https://gitcode.com/cann/ascend-transformer-boost

导读

本指南以 example/op_demo/all_reduce/README.md 为核心，完整讲解如何在 CANN / ascend-transformer-boost 加速库中通过 C++ 接口调用 AllReduceOperation 通信算子。AllReduce 是分布式训练与推理中频繁使用的集合通信原语，本 demo 以 8 卡多线程方式演示其典型调用流程。读完本文，你将掌握加速库通信算子的环境配置、参数含义、两阶段调用范式（Setup/Execute）与编译运行方法，并能结合源码理解 lccl / hccl 双后端的行为差异。

AllReduceOperation 与 Demo 概述

什么是 AllReduceOperation

在 Transformer 模型并行（如数据并行、张量并行）场景中，多张卡上的梯度或中间结果需要汇总并广播到所有参与卡。AllReduceOperation 正是加速库为此提供的集合通信算子：它把多张通信卡上的数据按指定规则（相加、取最大、取最小、相乘）归约后，再发送到每一张卡上。

从其参数定义可以看出，该算子的核心语义集中在 include/atb/infer_op_params.h 中的atb::infer::AllReduceParam结构体，参数注释明确写道："将多个通信卡上的数据进行计算，支持相加、取最大、最小、相乘四种计算，然后发送到每张卡上"。

Demo 目录内容

example/op_demo/all_reduce/目录下包含：

• README.md：本指南对应的原始使用说明；
• all_reduce_demo.cpp：完整的 C++ 调用示例源码。

示例采用单进程多线程的通信模式（COMM_MULTI_THREAD），一个进程内启动 8 个线程，分别对应 8 个 rank（设备），通过std::async并行执行 AllReduce，最终输出每个 rank 上归约后的结果。

环境准备：source 安装路径

运行 demo 前，需要先加载 CANN 与 NNAL（加速库）的安装环境。原文档给出的顺序如下：

1. 加载 CANN 工具包环境：

   source /usr/local/Ascend/ascend-toolkit/set_env.sh

   即source [cann安装路径]/set_env.sh，请按实际安装路径替换。

2. 加载 NNAL 加速库环境：

   source /usr/local/Ascend/nnal/atb/set_env.sh

   即source [nnal安装路径]/set_env.sh。

3. 如果使用的是加速库源码编译产物（而非安装包），则改为 source 源码编译输出目录下的环境脚本：

   source ./ascend-transformer-boost/output/atb/set_env.sh

   即source [加速库源码路径]/output/atb/set_env.sh。该路径对应仓库编译脚本输出目录output/atb/，其中包含了 atb 头文件与库文件的环境配置。

Demo 源码逐段解析

以下基于 all_reduce_demo.cpp 的完整代码展开。

线程参数与输入数据准备

每个线程通过Args结构体携带自己的 rank、stream、Context 与算子参数：

struct Args { int rankId; aclrtStream stream; atb::Context *context; atb::infer::AllReduceParam param; };

PrepareVariantPack负责构造atb::VariantPack——这是加速库统一的输入/输出张量包装结构。示例中张量 shape 为{2, 1024}，Host 侧数据初始化为 2.0，数据类型为ACL_FLOAT16，格式为ACL_FORMAT_ND：

std::vector<int64_t> shape = {2, 1024}; std::vector<float> xHostData(shape[0] * shape[1], 2.0); std::vector<float> outputHostData(shape[0] * shape[1], 0); atb::Tensor tensorX; CreateTensorFromVector(args.context, args.stream, xHostData, ACL_FLOAT16, aclFormat::ACL_FORMAT_ND, shape, tensorX); atb::Tensor tensorOutput; CreateTensorFromVector(args.context, args.stream, outputHostData, ACL_FLOAT16, aclFormat::ACL_FORMAT_ND, shape, tensorOutput); variantPack.inTensors = {tensorX}; variantPack.outTensors = {tensorOutput};

其中CreateTensorFromVector定义在 example/op_demo/demo_util.h，内部完成了"分配 Device 内存 + 拷贝 Host 数据 + 必要时调用 Elewise 的 cast Op 做数据类型转换"三步工作，是所有 demo 共用的工具函数。

通信域与算子参数配置

在main中，demo 固定使用 8 卡（DEV_NUM = 8），并为每个 rank 完成设备设置、Context/Stream 创建以及参数填充：

static const int DEV_NUM = 8; // 通信设备数量 static const std::string ALL_REDUCE_TYPE = "sum"; // 通信计算类型 static const std::string BACKEND = "lccl"; // 通信计算后端 for (int rankId = 0; rankId < DEV_NUM; rankId++) { CHECK_STATUS(aclrtSetDevice(rankId)); CHECK_STATUS(atb::CreateContext(&(args[rankId].context))); CHECK_STATUS(aclrtCreateStream(&(args[rankId].stream))); args[rankId].context->SetExecuteStream(args[rankId].stream); atb::infer::AllReduceParam &param = args[rankId].param; param.rank = rankId; param.rankSize = DEV_NUM; param.allReduceType = ALL_REDUCE_TYPE; param.backend = BACKEND; param.commMode = atb::infer::CommMode::COMM_MULTI_THREAD; param.commDomain = "domain0"; // 单通信域demo }

随后通过std::async启动 8 个线程并发执行RunAllReduceOp，最后统一get()等待结果并检查错误码。

算子两阶段调用范式

RunAllReduceOp展示了加速库算子的标准调用流程，这也是本 demo 最值得复用的工程模式：

1. 创建设备上下文：aclrtSetDevice(rankId)；
2. 创建算子：atb::CreateOperation(args.param, &allReduceOp)，其中param为AllReduceParam；
3. 第一阶段 Setup：allReduceOp->Setup(variantPack, workspaceSize, args.context)——对输入/输出张量做形状与数据类型校验，并计算出所需的 workspace 大小；
4. 申请 workspace：根据workspaceSize调用aclrtMalloc申请 Device 侧工作空间；
5. 第二阶段 Execute：allReduceOp->Execute(variantPack, workspacePtr, workspaceSize, args.context)——真正下发执行通信算子；
6. 流同步与资源释放：aclrtSynchronizeStream等待执行完成，随后依次释放 inTensors/outTensors/workspace 的 Device 内存，atb::DestroyOperation销毁算子，aclrtDestroyStream与atb::DestroyContext清理流和上下文，最后aclrtResetDevice复位设备。

该"Setup 算 workspace → Execute 执行"的两阶段设计是加速库所有算子的统一接口契约，适用于后续编写任何自定义算子调用代码。

编译与运行

在完成环境 source 之后，直接执行：

bash build.sh

即可编译并运行 demo。注意：仓库中该目录未附带 build.sh 的独立实现，若需手动编译，请参考 README 中关于 C++ ABI 的说明。

cxx_abi 注意事项

demo 依赖的加速库编译时使用的 C++ ABI 版本必须与用户编译 demo 时保持一致，否则链接阶段会出现符号不匹配错误：

• 使用cxx_abi=0（默认）时，编译需设置D_GLIBCXX_USE_CXX11_ABI=0：

  g++ -D_GLIBCXX_USE_CXX11_ABI=0 -I ...

• 使用cxx_abi=1时，改为：

  g++ -D_GLIBCXX_USE_CXX11_ABI=1 -I ...

-I ...处需要按set_env.sh实际导出的路径补充 atb 头文件（如atb/atb_infer.h、atb/operation.h、atb/types.h，这些在 include/atb 目录下）与 ACL 头文件，并链接对应的库文件。

AllReduceParam 参数详解

下表根据 include/atb/infer_op_params.h 中AllReduceParam的完整定义整理：

通信域异常退出处理

AllReduceParam的注释中还给出了一个重要的运维注意事项：多用户并发使用通信算子时，需要使用环境变量ATB_SHARE_MEMORY_NAME_SUFFIX区分共享内存，避免初始化信息同步冲突；当通信算子异常退出后，需要清理残留数据：

rm -rf /dev/shm/sem.lccl* rm -rf /dev/shm/sem.hccl* ipcrm -a

源码级验证：参数校验与双后端实现

参数合法性校验

src/ops/ops_infer/all_reduce/all_reduce_operation.cpp 中的CheckAllReduceParamValidity会在CreateOperation时对参数做严格校验，与 README 及参数定义相互印证：

• backend必须是hccl或lccl，否则报ERROR_INVALID_PARAM；
• allReduceType必须是sum/prod/max/min之一；
• lccl 后端不支持prod；Atlas 推理系列产品上 lccl 也不可用（Is310P()判断）；
• 在 Ascend 950 平台仅支持 hccl 后端，且不支持prod；
• lccl 后端不支持 int64 数据类型，hccl 在部分产品/归约类型组合下对 int16、bf16、int64 有限制（见DtypeCheck）；
• 量化 AllReduce（quantType非 UNQUANT）要求allReduceType为sum、输出类型为ACL_FLOAT16，且 hccl 后端不支持量化。

AllReduceOperation::InferShapeImpl表明输出 shape 与输入保持一致，量化场景下仅修改输出 dtype。GetInputNum在量化模式下返回 3（输入 + scale + offset），非量化模式返回 1，量化校验要求输入最后一维为 16 的整数倍、offset shape 为 1、per-channel 模式下 scale 形状为[1, n]或[n]且通道数不超过4194304 (2^22)。

Runner 分发机制

AllReduceOperation::CreateRunner展示了算子执行体的分发逻辑：hccl 后端构造AllReduceHcclRunner，lccl 后端构造AllReduceLcclRunner，二者分别继承自 hccl_runner.h 与 lccl_runner.h 框架，类的声明见 all_reduce_hccl_runner.h 和 all_reduce_lccl_runner.h。hccl runner 支持三种构造方式：默认（由加速库创建通信域）、基于 rankTableFile、基于外部传入的hcclComm，对应多进程与多线程等不同通信场景。

产品支持情况与运行限制

原文档明确指出：本算子在 Atlas A2/A3 系列与 Atlas 推理系列产品上的实现有所区别，all_reduce_demo.cpp仅支持在Atlas A2/A3 系列产品上运行。这一结论与源码相互印证：

• demo 默认使用lccl后端与COMM_MULTI_THREAD模式，而源码中 lccl 后端在 Atlas 推理系列（Is310P）上会被直接拒绝；
• 推理系列产品仅支持 hccl 后端（参数注释与源码双重确认）；
• 此外，Ascend 950 平台仅支持 hccl，Atlas 800I A2 推理产品单机 16 卡拓扑下 lccl 只支持 16 卡全量拓扑通信或单节点内任意卡通信。

因此，在部署该 demo 前请先确认硬件型号属于 Atlas A2/A3 系列，并在推理系列产品上改用 hccl 后端 + 多进程（COMM_MULTI_PROCESS）方式调用。

数据生成与测试验证

README 强调：示例中生成的数据不代表实际场景（所有 rank 的输入被简单地初始化为 2.0），仅用于演示调用链路。如需面向真实场景的数据生成与精度验证，请参考仓库根目录下的 Python 用例目录：

tests/apitest/opstest/python/operations/all_reduce/

该目录下按后端与拓扑维度覆盖了多种用例，可用于交叉验证 C++ demo 的行为：

• hccl 后端：test_hccl_all_reduce_operation.py（单机）、test_hccl_all_reduce_operation_multi_server.py（多机）、test_hccl_multicomm.py/test_hccl_multicomm2.py（多通信域）；
• lccl 后端：test_lccl_all_reduce_operation.py、test_lccl_all_reduce_operation_910C.py（910C 平台）、test_lccl_all_reduce_2comm4rank.py、test_lccl_all_reduce_3multicomm.py、test_lccl_all_reduce_4comm2rank.py（多通信域 + 多 rank 组合）。

这些用例覆盖了单机/多机、单通信域/多通信域、2/3/4 个通信域等拓扑，是理解 AllReduce 在不同拓扑下行为的绝佳参考。

总结

本文围绕example/op_demo/all_reduce/的 README 与示例源码，系统梳理了在 ascend-transformer-boost 中调用 AllReduceOperation 的完整路径：从环境 source、AllReduceParam各字段语义，到 Setup/Execute 两阶段调用、双后端（hccl/lccl）差异与产品限制。结合 all_reduce_operation.cpp 的参数校验与 runner 分发实现，你可以在此基础上快速改造出适合自身硬件拓扑与通信模式的 AllReduce 调用代码，并借助 tests/apitest/opstest/python/operations/all_reduce/ 中的 Python 用例进行数据与精度对照。

【免费下载链接】ascend-transformer-boost本项目是CANN提供的是一款高效、可靠的Transformer加速库，基于华为Ascend AI处理器，提供Transformer定制化场景的高性能融合算子。项目地址: https://gitcode.com/cann/ascend-transformer-boost