ascend-transformer-boost ReduceScatter 算子解析:参数约束、Runner 决策与 HCCL/LCCL 双后端执行路径
ascend-transformer-boost ReduceScatter 算子解析:参数约束、Runner 决策与 HCCL/LCCL 双后端执行路径
本文基于仓库中 reduce_scatter 路由文档(.agent/knowledge/routing/reduce_scatter.md)及其关联知识条目,系统梳理 ascend-transformer-boost(ATB)集合通信算子 ReduceScatter 的实现全貌:包括 6 个源文件的角色与推荐阅读顺序、ReduceScatterParam 各参数的取值约束、CreateRunner() 的后端决策逻辑,以及 HCCL/LCCL 两条执行路径的底层调用。读完后你可以掌握该算子的张量形状要求(输入首维必须为 rankSize 整数倍)、数据类型限制(按芯片与后端的差异矩阵)以及多卡通信域的创建方式,为在多 Ascend NPU 上部署张量并行归约-分发操作提供可直接落地的参考。
1. 算子定位与文件清单
ReduceScatter 是 ATB 提供的推理侧(infer 分类)集合通信算子:对通信组内各卡的输入张量先做归约(Reduce),再将结果按 rank 切片分发给各卡(Scatter),是张量并行(Tensor Parallelism)中"列并行输出后聚合"这一典型通信模式的底层支撑。从 ATB 的知识条目看,其 Pipeline 被概括为:"Reduce 后 Scatter 到各卡,HCCL/LCCL 双通道",复杂度分级为 S 级(结构最简的通信算子之一),预估阅读时间为 3~5 分钟。
路由文档给出了该算子完整的 6 文件清单,全部位于 src/ops/ops_infer/reduce_scatter/ 目录下:
| # | 文件 | 角色 |
|---|---|---|
| 1 | reduce_scatter_hccl_runner.cpp | HCCL 后端 Runner 源码 |
| 2 | reduce_scatter_hccl_runner.h | HCCL 后端 Runner 头文件 |
| 3 | reduce_scatter_lccl_runner.cpp | LCCL 后端 Runner 源码 |
| 4 | reduce_scatter_lccl_runner.h | LCCL 后端 Runner 头文件 |
| 5 | reduce_scatter_operation.cpp | Operation 定义 |
| 6 | reduce_scatter_operation.h | Operation 定义 |
路由文档推荐的阅读顺序也印证了这套"Operation 为入口、Runner 为执行"的结构:
reduce_scatter_operation.h—— 了解输入输出数量、InferShape 签名;reduce_scatter_operation.cpp——CreateRunner()决策逻辑;reduce_scatter_hccl_runner.cpp/.h—— HCCL 通道辅助文件;reduce_scatter_lccl_runner.cpp/.h—— LCCL 通道辅助文件。
与路由文档中"Runner 类型: OpsRunner, Operation、ACLNN: no"的记录一致:该算子通过 Operation 接口(atb::CreateOperation)构建,不走 ACLNN 执行通道,也不注册为可独立调度的 OpsRunner 之外的形态——从 reduce_scatter_operation.h 可以看到 ReduceScatterOperation 直接继承 OperationBase,实现了 InferShapeImpl、CreateRunner、InferShapeCheckImpl、SetupCheckImpl、GetParamJson 等虚函数。
2. 参数结构 ReduceScatterParam 与取值约束
ReduceScatterParam 定义于 include/atb/infer_op_params.h,是用户构建该算子的唯一入参。各字段含义与约束如下:
| 参数 | 类型 / 默认值 | 说明 |
|---|---|---|
rank |
int,默认 0 |
当前卡所属通信编号,需满足 0 ≤ rank < rankSize |
rankSize |
int,默认 0 |
通信的卡数量 |
rankRoot |
int,默认 0 |
主通信编号,需满足 0 ≤ rankRoot < rankSize |
reduceType |
string,默认 "sum" |
归约类型,仅支持 sum / prod / max / min,受芯片与后端限制(见下文) |
hcclComm |
HcclComm,默认 nullptr |
HCCL 通信域指针。默认为空时由加速库为用户创建;用户可自行管理通信域并传入指针,加速库将直接使用传入的通信域执行通信算子 |
commMode |
CommMode,默认 COMM_MULTI_PROCESS |
通信模式,多进程/多线程两种 |
backend |
string,默认 "lccl" |
通信后端指示。当 backend 为 lccl 且机器拓扑为 Atlas 800I A2 推理产品单机 16 卡时,只支持 16 卡全量拓扑通信或单节点内任意卡通信 |
rankTableFile |
string |
集群信息的配置文件路径(HCCL 专用,用于以集群文件方式建域) |
commDomain |
string |
通信 device 组用通信域名标识,多通信域时使用。backend 为 lccl 且 commMode 为多进程时,需要设置为 0–65535 的数字 |
rsv |
uint8_t[64],默认 0 |
预留参数,创建算子时会做 RSV 校验(OP_PARAM_RSV_CHECK) |
参数层面的两条通用注意事项(见头文件注释):
- 多用户同时使用时,需要通过
ATB_SHARE_MEMORY_NAME_SUFFIX环境变量区分共享内存,以保证初始化信息同步; - 通信算子异常退出时会残留共享内存数据,需手动清理后再继续使用:
rm -rf /dev/shm/sem.lccl*
rm -rf /dev/shm/sem.hccl*
ipcrm -a
2.1 创建阶段(CreateOperation)的参数校验矩阵
reduce_scatter_operation.cpp 中的 CreateOperation 工厂函数在构造算子前会做一层集中校验,形成一张清晰的"约束矩阵":
- backend 白名单:仅接受
"hccl"或"lccl",其他值直接返回ERROR_INVALID_PARAM; - Atlas 300I Duo(310P)产品不支持:
GetSingleton<Config>().Is310P()为真时拒绝创建; - Ascend 950 平台的特化约束:backend 只允许
hccl,且reduceType不支持"prod"; - reduceType 白名单:必须为
sum、prod、max、min之一; - LCCL 不支持 prod:
backend == "lccl"且reduceType == "prod"时报错; - 分布式初始化检查:调用
OperationUtil::DistributedInitCheck,校验 rank/rankSize/rankRoot 等通信基本参数合法性。
2.2 张量形状与数据类型检查
Operation 层还做了两级张量检查:
- InferShapeCheckImpl(reduce_scatter_operation.cpp):输入张量第 0 维必须是
rankSize的整数倍;随后按后端做 dtype 检查——- HCCL 通道:910A 上不支持
int16、bf16;910B 上仅在reduceType == "prod"时不支持int16、bf16(即 910B 的 sum/max/min 归约可接受 bf16); - LCCL 通道:不支持
int64;
- HCCL 通道:910A 上不支持
- SetupCheckImpl(reduce_scatter_operation.cpp):输入与输出的维度数(dimNum)必须一致,且
inTensor.dims[0] == rankSize * outTensor.dims[0]——这正是 ReduceScatter"归约后按 rank 切分首维"的语义约束。
形状推导逻辑非常直接:InferShapeImpl 中输出形状完全继承输入形状,仅将第 0 维改写为 inTensor.dims<a href="https://link.gitcode.com/i/e9f9478c3245056801baae89f915f4fa" target="_blank">0] / rankSize([reduce_scatter_operation.cpp)。输入输出数量均为 1(IN_TENSOR_NUM = 1,OUT_TENSOR_NUM = 1)。
3. CreateRunner:后端决策逻辑
路由文档将 reduce_scatter_operation.cpp 列为第 2 优先级阅读文件,核心就是 CreateRunner() 的三路分派(reduce_scatter_operation.cpp):
std::shared_ptr<Runner> ReduceScatterOperation::CreateRunner(Context &context) const
{
(void)context;
if (param_.backend == "lccl") {
return std::make_shared<ReduceScatterLcclRunner>(param_, context);
} else if (param_.backend == "hccl") {
if (param_.hcclComm == nullptr) {
return std::make_shared<ReduceScatterHcclRunner>(param_, !param_.rankTableFile.empty());
} else {
return std::make_shared<ReduceScatterHcclRunner>(param_, param_.hcclComm);
}
}
// ...
}
可以看到 HCCL 通道内部又细分出三种 Runner 构造形态(与 reduce_scatter_hccl_runner.h 的三个构造函数一一对应):
- 自管理建域(rankSize 参数式):
hcclComm == nullptr且rankTableFile为空时,Runner 构造时向基类HcclRunner传入rank、rankSize、rankRoot、commDomain,由加速库自行初始化通信域; - 自管理建域(集群文件式):
hcclComm == nullptr且rankTableFile非空时,改为传入rankTableFile路径,以 HCCL 集群配置文件方式建域; - 用户持有通信域:
hcclComm != nullptr时,Runner 直接以外部传入的HcclComm初始化,加速库只负责执行、不负责通信域生命周期管理。
这种"一个 Operation、三种 HCCL 建域姿势 + 一种 LCCL 通道"的结构,是该算子 Runner 类型在路由文档中被标注为 Operation 的由来。
4. HCCL 执行路径
ReduceScatterHcclRunner::ExecuteImpl 的实现(reduce_scatter_hccl_runner.cpp)是典型的"前置检查 + 单次 HCCL 调用":
Status ReduceScatterHcclRunner::ExecuteImpl(RunnerVariantPack &runnerVariantPack)
{
if (!hcclComm_) {
ATB_LOG(ERROR) << "hcclComm is null, rank: " << param_.rank;
return ERROR_INTERNAL_ERROR;
}
if (!runnerVariantPack.inTensors[0].deviceData || !runnerVariantPack.outTensors[0].deviceData) {
ATB_LOG(ERROR) << " device tensor is null";
return ERROR_INVALID_PARAM;
}
HcclResult ret = HcclReduceScatter(
runnerVariantPack.inTensors.at(0).deviceData, runnerVariantPack.outTensors.at(0).deviceData,
Utils::GetTensorNumel(runnerVariantPack.outTensors[0]), GetHcclDtype(runnerVariantPack.inTensors[0].desc.dtype),
GetAllReduceType(param_.reduceType), hcclComm_.get(), GetExecuteStream(runnerVariantPack.context));
if (ret != HCCL_SUCCESS) {
ATB_LOG(ERROR) << "ReduceScatter hccl Execute failed, ret: " << ret;
return ConvertHcclResultToStatus(ret);
}
return NO_ERROR;
}
几个值得注意的实现细节:
- 元素个数
count取的是输出张量的numel(Utils::GetTensorNumel(outTensors[0])),即每卡本地产出的切片大小,与 HCCL 对 ReduceScatter 的 count 语义一致; - 数据类型通过
GetHcclDtype由 ATB dtype 映射为 HCCL dtype,归约类型通过GetAllReduceType将字符串"sum"/"prod"/"max"/"min"映射为 HCCL 枚举; - 执行流通过
GetExecuteStream(context)从运行上下文获取,保证通信操作挂载到调用方指定的 stream 上,与图中前后算子正确同步; - 失败路径统一经
ConvertHcclResultToStatus转成 ATBStatus返回,便于上层按统一错误码处理。
文件末尾的 REG_RUNNER_TYPE(ReduceScatterHcclRunner) 将 Runner 注册进 ATB 的 Runner 类型系统,支撑 Runner 的序列化/反序列化与缓存复用。
5. LCCL 执行路径
LCCL 通道面向卡内/机内多核场景,ReduceScatterLcclRunner 的构造(reduce_scatter_lccl_runner.cpp)将 param.rank、param.rankSize、param.commMode、param.commDomain 一并交给 LcclRunner 基类完成通信组初始化,并持有运行 Context。其 ExecuteImpl:
int ret = lccl_->ReduceScatter(runnerVariantPack.inTensors.at(0).deviceData,
runnerVariantPack.outTensors.at(0).deviceData,
Utils::GetTensorNumel(runnerVariantPack.outTensors.at(0)),
GetHcclDtype(runnerVariantPack.inTensors[0].desc.dtype),
GetAllReduceType(param_.reduceType), GetExecuteStream(runnerVariantPack.context));
与 HCCL 路径对称,但有两点差异:
- 空指针检查针对的是
lccl_(LCCL 通信组句柄),失败返回ERROR_COMM_EMPTY; - 对
Lcal::LCAL_ERROR_PARA_CHECK_FAIL单独给出诊断日志:"LCCL_PARALLEL should be 0 or false",提示用户按 infer_op_params.h 中commDomain的注释正确管理LCCL_PARALLEL环境变量——多通信域并发场景下需置 1/true,使用结束后需恢复为 0/false,否则会影响基础场景性能。
另外从源码结构看,LCCL 通道没有 rankTableFile 建域方式(该参数仅参与 HCCL Runner 的构造分派),LCCL 的通信拓扑由 rank/rankSize/commMode/commDomain 四元组加进程内共享内存机制描述,这也与参数注释中"多进程时 commDomain 需为 0–65535 的数字"的要求相吻合。
6. 使用要点与适用前提
结合路由文档、参数头文件与 Operation 源码,使用该算子时的关键前提可以归纳为:
- 芯片与平台:Atlas 300I Duo(310P)推理产品不支持;Ascend 950 上仅支持 HCCL 后端且不支持
prod归约;910A/910B 的 bf16/int16 限制见第 2.2 节矩阵; - 形状契约:输入首维必须是
rankSize整数倍,输出首维即输入首维除以rankSize,其余维不变; - 通信域管理:HCCL 可三选一(rankSize 参数式自管理 / 集群文件式自管理 / 用户传入
hcclComm);LCCL 走多进程或多线程commMode,多通信域需配置commDomain; - 参数合法性:
rank/rankSize/rankRoot满足区间约束,rsv保持全 0,reduceType在四值白名单内且与 backend/芯片兼容; - 异常退出恢复:多用户环境设置
ATB_SHARE_MEMORY_NAME_SUFFIX隔离;通信算子异常退出后清理/dev/shm下残留信号量与 System V 资源(命令见第 2 节)。
7. 相关文件索引
知识条目还提示了两个近亲算子可作为延伸阅读:all_reduce(Reduce + Broadcast,结果各卡全量相同)与 all_gather(Gather 无 Reduce,结果按维拼接),三者共同构成 ATB 集合通信算子族,源码分别位于 src/ops/ops_infer/all_reduce/ 与 src/ops/ops_infer/all_gather/。