CANN ops-nn aclnnScatterMul 算子全解析:两段式接口、参数约束与 NPU 内核实现
CANN ops-nn aclnnScatterMul 算子全解析:两段式接口、参数约束与 NPU 内核实现
aclnnScatterMul 是 CANN ops-nn 算子库中实现原地"按索引连乘更新"(Scatter-Multiply)的神经网络类算子,兼容 tf.compat.v1.scatter_mul 语义,可在 Ascend 950 系列产品上以 ND 格式对 FLOAT16/FLOAT32/INT32/INT8/UINT8 张量做确定性计算。本文以 index/scatter_mul/docs/aclnnScatterMul.md 为骨架,结合 index/scatter_mul 目录下的算子定义、shape 推导、tiling、kernel 与测试代码,完整讲解该算子的功能语义、两段式 aclnn 接口调用方法、入参约束、错误码,以及其基于共享 scatter-reduce 公共组件的多核实现原理,帮助你直接上手在 NPU 上调用该算子并理解其内部行为。
功能与计算语义
aclnnScatterMul 实现的是"逐切片连乘"的原地更新:将 updates 中的值按索引张量 indices 指向的位置,逐个乘到 varRef 的对应切片上。若多个 updates 值命中 varRef 的同一个切片,这些值会依次在该切片上连乘(这与 scatter-add 的连加语义完全对应)。其数学规则为:
几个关键语义要点:
- 原地(in-place)更新:输出复用输入
varRef的内存,无需单独分配输出张量;从源码结构看,算子定义中输出名同样为var,且与输入共享内存。 - 与 TensorFlow 对齐:功能上兼容
tf.compat.v1.scatter_mul,仓库中 index/scatter_mul/framework/scatter_mul_tf_plugin.cpp 通过REGISTER_CUSTOM_OP("ScatterMul")+OriginOpType("ScatterMul")将 TF 侧同名算子自动映射到本算子(AutoMappingByOpFn),便于 TF 图直接下沉到 NPU。 - 索引越界处理:
indices中越界索引(小于 0 或大于等于varRef首维大小)会被静默跳过、不做更新;这一点同时体现在 index/scatter_mul/tests/assets/golden.py 的 golden 实现中(valid = (idx_flat >= 0) & (idx_flat < var_first)先过滤再归约)。 - 空张量支持:
varRef、indices、updates均支持空 Tensor;当varRef或updates无元素时,scatter 属于 no-op,原样返回varRef。
产品支持情况
根据 index/scatter_mul/docs/aclnnScatterMul.md 的声明,aclnnScatterMul 当前仅在以下产品上支持,其余产品线暂不支持:
| 产品 | 是否支持 |
|---|---|
| Ascend 950PR / Ascend 950DT | 支持 |
| Atlas A3 训练系列产品 / Atlas A3 推理系列产品 | 不支持 |
| Atlas A2 训练系列产品 / Atlas A2 推理系列产品 | 不支持 |
| Atlas 200I/500 A2 推理产品 | 不支持 |
| Atlas 推理系列产品 | 不支持 |
| Atlas 训练系列产品 | 不支持 |
从实现侧看,index/scatter_mul/op_host/scatter_mul_def.cpp 中仅注册了 AICore().AddConfig("ascend950", aicoreConfig) 的核配置,kernel 目录下也只有 index/scatter_mul/op_kernel/arch35 架构实现,与上表"仅 950 系列支持"的结论一致。需要注意:产品支持矩阵可能随版本演进调整,实际以所安装 CANN 版本的算子能力声明为准。
两段式接口调用模型
aclnnScatterMul 遵循 CANN aclnn 算子的两段式接口规范(详见 docs/zh/context/two_phase_api.md):
- 先调用
aclnnScatterMulGetWorkspaceSize完成入参校验,并返回两块信息:计算所需 workspace 大小(workspaceSize)与封装了算子计算流程的执行器(executor); - 再调用
aclnnScatterMul真正下发计算,此时传入第一段获取的 workspace 与 executor。
函数原型如下:
aclnnStatus aclnnScatterMulGetWorkspaceSize(
aclTensor *varRef,
const aclTensor *indices,
const aclTensor *updates,
bool useLocking,
uint64_t *workspaceSize,
aclOpExecutor **executor)
aclnnStatus aclnnScatterMul(
void *workspace,
uint64_t workspaceSize,
aclOpExecutor *executor,
aclrtStream stream)
第一段接口完成全部入参校验(指针、dtype、shape 约束),若校验不通过则直接返回错误码,不会生成执行器;第二段接口只负责按执行器在指定 Stream 上执行算子。这种设计把"昂贵的参数校验与任务编排"和"轻量的任务下发"解耦,便于上层框架复用 executor 或做流式调度。
aclnnScatterMulGetWorkspaceSize 详解
参数说明
| 参数名 | 输入/输出 | 描述 | 使用说明 | 数据类型 | 数据格式 | 维度(shape) | 非连续Tensor |
|---|---|---|---|---|---|---|---|
| varRef | 输入/输出 | 公式中的输入 varRef,要进行更新的初始张量,原地更新 | - | FLOAT16、FLOAT32、INT32、INT8、UINT8 | ND | 1-8 | √ |
| indices | 输入 | 公式中的输入 indices,要更新的索引位置 | 索引值取值范围为 [0, varRef.shape[0])(varRef.shape[0] 为首维大小) |
INT32、INT64 | ND | 1-8 | √ |
| updates | 输入 | 公式中的输入 updates,要乘到 varRef 中的更新值 | - | FLOAT16、FLOAT32、INT32、INT8、UINT8 | ND | 1-8 | √ |
| useLocking | 输入 | 是否对更新加锁,该参数不生效 | - | BOOL | - | - | - |
| workspaceSize | 输出 | 返回需要在 Device 侧申请的 workspace 大小 | - | - | - | - | - |
| executor | 输出 | 返回 op 执行器,包含算子计算流程 | - | - | - | - | - |
参数要点:
varRef、updates的 dtype 范围一致(FLOAT16/FLOAT32/INT32/INT8/UINT8),且二者 dtype 必须相同;indices支持 INT32/INT64 两种索引精度。- 三个 Tensor 均支持 非连续(non-contiguous)Tensor(以 strides 描述内存布局的视图),相关概念可参考 docs/zh/context/non_contiguous_tensor.md。
useLocking为兼容 TF 接口保留的入参,当前实现中不生效(该参数与 index/scatter_mul/op_host/scatter_mul_def.cpp 中Attr("use_locking").AttrType(OPTIONAL).Bool(false)的可选属性对应,默认值为 false)。workspaceSize可能为 0(当算子不需要额外 workspace 时),调用侧需按返回值条件性地申请内存。
返回值与错误码
第一段接口返回 aclnnStatus 状态码,完整状态码定义参见 docs/zh/context/aclnn_return_code.md。aclnnScatterMulGetWorkspaceSize 阶段可出现的错误码如下:
| 返回值 | 错误码 | 描述 |
|---|---|---|
| ACLNN_ERR_PARAM_NULLPTR | 161001 | 传入的 varRef、indices、updates 是空指针 |
| ACLNN_ERR_PARAM_INVALID | 161002 | varRef、indices、updates 的数据类型不在支持范围之内 |
| ACLNN_ERR_PARAM_INVALID | 161002 | varRef、updates 的 dtype 不一致 |
| ACLNN_ERR_INNER_TILING_ERROR | 561002 | updates 的 shape 不满足对应 shape 约束 |
其中 161002 的两种触发场景(dtype 越界、varRef 与 updates dtype 不一致)正好对应上文"参数要点"中的前两条约束;561002 则对应下文的 shape 约束(updates.shape = indices.shape + varRef.shape[1:]),该错误在 tiling 阶段(形状推导)被捕获。
aclnnScatterMul 详解
参数说明
| 参数名 | 输入/输出 | 描述 |
|---|---|---|
| workspace | 输入 | 在 Device 侧申请的 workspace 内存地址 |
| workspaceSize | 输入 | 在 Device 侧申请的 workspace 大小,由第一段接口 aclnnScatterMulGetWorkspaceSize 获取 |
| executor | 输入 | op 执行器,包含了算子计算流程 |
| stream | 输入 | 指定执行任务的 Stream |
返回值
同样返回 aclnnStatus 状态码(参见 docs/zh/context/aclnn_return_code.md)。第二段接口的常见失败场景包括 workspace 内存非法或 stream 无效等运行时错误,编码为 ACLNN_ERR_INNER_* 系列运行时错误码。
约束说明
- dtype 约束:
varRef与updates的数据类型必须一致;indices必须是 INT32 或 INT64。 - shape 约束:必须满足
updates.shape = indices.shape + varRef.shape<a href="https://link.gitcode.com/i/3691dc8da76c8a1d45cdbb91847a193f" target="_blank">1:],即indices的每个标量索引对应varRef中的一个"切片"(sliceSize = varRef 去掉首维后的元素个数),updates与该切片逐元素相乘。该约束在 [index/scatter_mul/op_host/scatter_mul_infershape.cpp 的 shape 推导中体现:输出 shape 直接拷贝输入varRef的 shape(原地语义),而updates的合法性由 tiling 阶段的形状检查保证。 - 确定性计算:aclnnScatterMul 默认是确定性实现(确定性计算相关概念见 docs/zh/context/determinism_compute.md),即相同输入在多次运行中产生逐位一致的结果,这一点对调试与结果复现非常友好。
调用示例
下面的示例代码完整演示了 aclnnScatterMul 的调用流程,与 index/scatter_mul/examples/arch35/test_aclnn_scatter_mul.cpp 一致,具体编译与运行方法参考 docs/zh/context/compile_and_run_sample.md。
#include <iostream>
#include <vector>
#include "acl/acl.h"
#include "aclnnop/aclnn_scatter_mul.h"
#define CHECK_RET(cond, return_expr) \
do { \
if (!(cond)) { \
return_expr; \
} \
} while (0)
#define LOG_PRINT(message, ...) \
do { \
printf(message, ##__VA_ARGS__); \
} while (0)
int64_t GetShapeSize(const std::vector<int64_t>& shape) {
int64_t shapeSize = 1;
for (auto i : shape) {
shapeSize *= i;
}
return shapeSize;
}
int Init(int32_t deviceId, aclrtStream* stream) {
// 固定写法,资源初始化
auto ret = aclInit(nullptr);
CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclInit failed. ERROR: %d\n", ret); return ret);
ret = aclrtSetDevice(deviceId);
CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclrtSetDevice failed. ERROR: %d\n", ret); return ret);
ret = aclrtCreateStream(stream);
CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclrtCreateStream failed. ERROR: %d\n", ret); return ret);
return 0;
}
template <typename T>
int CreateAclTensor(const std::vector<T>& hostData, const std::vector<int64_t>& shape, void** deviceAddr,
aclDataType dataType, aclTensor** tensor) {
auto size = GetShapeSize(shape) * sizeof(T);
// 调用aclrtMalloc申请device侧内存
auto ret = aclrtMalloc(deviceAddr, size, ACL_MEM_MALLOC_HUGE_FIRST);
CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclrtMalloc failed. ERROR: %d\n", ret); return ret);
// 调用aclrtMemcpy将host侧数据拷贝到device侧内存上
ret = aclrtMemcpy(*deviceAddr, size, hostData.data(), size, ACL_MEMCPY_HOST_TO_DEVICE);
CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclrtMemcpy failed. ERROR: %d\n", ret); return ret);
// 计算连续tensor的strides
std::vector<int64_t> strides(shape.size(), 1);
for (int64_t i = shape.size() - 2; i >= 0; i--) {
strides[i] = shape[i + 1] * strides[i + 1];
}
// 调用aclCreateTensor接口创建aclTensor
*tensor = aclCreateTensor(shape.data(), shape.size(), dataType, strides.data(), 0, aclFormat::ACL_FORMAT_ND,
shape.data(), shape.size(), *deviceAddr);
return 0;
}
int main() {
// 1. (固定写法)device/stream初始化,参考acl API手册
// 根据自己的实际device填写deviceId
int32_t deviceId = 0;
aclrtStream stream;
auto ret = Init(deviceId, &stream);
CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("Init acl failed. ERROR: %d\n", ret); return ret);
// 2. 构造输入与输出,需要根据API的接口自定义构造
std::vector<int64_t> varRefShape = {3, 2};
std::vector<int64_t> indicesShape = {2};
std::vector<int64_t> updatesShape = {2, 2};
void* varRefDeviceAddr = nullptr;
void* indicesDeviceAddr = nullptr;
void* updatesDeviceAddr = nullptr;
aclTensor* varRef = nullptr;
aclTensor* indices = nullptr;
aclTensor* updates = nullptr;
std::vector<float> varRefHostData = {1, 2, 3, 4, 5, 6};
std::vector<int32_t> indicesHostData = {0, 2};
std::vector<float> updatesHostData = {10, 20, 30, 40};
bool useLocking = false;
// 创建varRef aclTensor
ret = CreateAclTensor(varRefHostData, varRefShape, &varRefDeviceAddr, aclDataType::ACL_FLOAT, &varRef);
CHECK_RET(ret == ACL_SUCCESS, return ret);
// 创建indices aclTensor
ret = CreateAclTensor(indicesHostData, indicesShape, &indicesDeviceAddr, aclDataType::ACL_INT32, &indices);
CHECK_RET(ret == ACL_SUCCESS, return ret);
// 创建updates aclTensor
ret = CreateAclTensor(updatesHostData, updatesShape, &updatesDeviceAddr, aclDataType::ACL_FLOAT, &updates);
CHECK_RET(ret == ACL_SUCCESS, return ret);
// 3. 调用CANN算子库API,需要修改为具体的API名称
uint64_t workspaceSize = 0;
aclOpExecutor* executor;
// 调用aclnnScatterMul第一段接口
ret = aclnnScatterMulGetWorkspaceSize(varRef, indices, updates, useLocking, &workspaceSize, &executor);
CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclnnScatterMulGetWorkspaceSize failed. ERROR: %d\n", ret); return ret);
// 根据第一段接口计算出的workspaceSize申请device内存
void* workspaceAddr = nullptr;
if (workspaceSize > 0) {
ret = aclrtMalloc(&workspaceAddr, workspaceSize, ACL_MEM_MALLOC_HUGE_FIRST);
CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("allocate workspace failed. ERROR: %d\n", ret); return ret);
}
// 调用aclnnScatterMul第二段接口
ret = aclnnScatterMul(workspaceAddr, workspaceSize, executor, stream);
CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclnnScatterMul failed. ERROR: %d\n", ret); return ret);
// 4. (固定写法)同步等待任务执行结束
ret = aclrtSynchronizeStream(stream);
CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclrtSynchronizeStream failed. ERROR: %d\n", ret); return ret);
// 5. 获取输出的值,将device侧内存上的结果拷贝至host侧,需要根据具体API的接口定义修改
auto size = GetShapeSize(varRefShape);
std::vector<float> resultData(size, 0);
ret = aclrtMemcpy(resultData.data(), resultData.size() * sizeof(resultData[0]), varRefDeviceAddr,
size * sizeof(resultData[0]), ACL_MEMCPY_DEVICE_TO_HOST);
CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("copy result from device to host failed. ERROR: %d\n", ret); return ret);
for (int64_t i = 0; i < size; i++) {
LOG_PRINT("result[%ld] is: %f\n", i, resultData[i]);
}
// 6. 释放aclTensor,需要根据具体API的接口定义修改
aclDestroyTensor(varRef);
aclDestroyTensor(indices);
aclDestroyTensor(updates);
// 7. 释放device资源,需要根据具体API的接口定义参数
aclrtFree(varRefDeviceAddr);
aclrtFree(indicesDeviceAddr);
aclrtFree(updatesDeviceAddr);
if (workspaceSize > 0) {
aclrtFree(workspaceAddr);
}
aclrtDestroyStream(stream);
aclrtResetDevice(deviceId);
aclFinalize();
return 0;
}
示例运行结果推导
该示例的输入为:
varRef:shape{3, 2},数据[[1, 2], [3, 4], [5, 6]];indices:shape{2},数据[0, 2];updates:shape{2, 2},数据[[10, 20], [30, 40]]。
代入公式 varRef[indices[i], ...] *= updates[i, ...]:
i = 0:varRef[0] = [1, 2] × [10, 20] = [10, 40];i = 1:varRef[2] = [5, 6] × [30, 40] = [150, 240];- 未命中的第 1 行
[3, 4]保持原值。
因此程序最终输出应为:result[0]=10, result[1]=40, result[2]=3, result[3]=4, result[4]=150, result[5]=240。
调用流程拆解
- 初始化(固定写法):
aclInit→aclrtSetDevice→aclrtCreateStream,准备 Device 与 Stream 上下文; - 构造 aclTensor:用
aclrtMalloc申请 Device 内存、aclrtMemcpy把 Host 数据拷入,再计算连续张量的 strides,最后用aclCreateTensor以 ND 格式 创建aclTensor描述(示例中的CreateAclTensor模板函数可复用于其他 aclnn 算子); - 两段式调用:先
aclnnScatterMulGetWorkspaceSize拿workspaceSize与executor,按需aclrtMallocworkspace,再aclnnScatterMul下发计算; - 同步等待:
aclrtSynchronizeStream保证计算完成后再回拷结果; - 结果回拷:因是原地更新,直接从
varRefDeviceAddr把结果拷回 Host 打印; - 资源释放:
aclDestroyTensor销毁张量描述,aclrtFree释放 Device 内存(含条件性释放 workspace),最后销毁 Stream、重置 Device、aclFinalize。
源码级实现原理
算子注册与属性定义
index/scatter_mul/op_host/scatter_mul_def.cpp 中通过 OP_ADD(ScatterMul) 注册算子定义:
- 输入
var、indices、updates与输出var均为REQUIRED;输入输出张量均支持 ND 格式; - 属性
use_locking为可选 BOOL,默认false(对应 aclnn 层的useLocking参数); - 配置了动态编译静态标记、动态 rank 支持、动态 shape 支持,
ExtendCfgInfo("opFile.value", "scatter_mul")指定 kernel 文件; - 仅注册了
ascend950的 AICore 配置,与"仅 950 系列支持"的产品矩阵一致。
原地语义的 shape 推导
index/scatter_mul/op_host/scatter_mul_infershape.cpp 的 InferShape4ScatterMul 将输出 shape 直接赋值为输入 var 的 shape,InferDataType4ScatterMul 将输出 dtype 赋值为输入 var 的 dtype——这就是"原地更新、输出复用输入内存"在图编译阶段的体现。这与 aclnn 层"输出即 varRef 本身、无需额外分配输出张量"的接口设计完全对应。
Tiling:共享 scatter-reduce 公共路径
index/scatter_mul/op_host/arch35/scatter_mul_tiling.cpp 将 tiling 直接委托给公共组件 ScatterReduceCommonTiling(位于 index/scatter_reduce_common),并调用 context->SetScheduleMode(1) 设置批调度模式。从代码注释看,这是因为 kernel 的 sort 归约路径使用 SyncAll 全核同步,需要保证所有核以同一批次启动,避免跨核依赖时序问题。公共 tiling 会负责:空张量放行(no-op)、切片宽度(sliceSize)计算、以及在不同数据规模下选择"单核标量路径"或"排序 + 多核切分路径"。
Kernel:SIMT 分发与确定性归约
kernel 入口 index/scatter_mul/op_kernel/arch35/scatter_mul.cpp 通过 ScatterReduceSimt<DTYPE_VAR, DTYPE_INDICES, int64_t, MODE_MUL> 模板实例化,将 ScatterMul 作为 MODE_MUL 归约模式接入公共的 ScatterReduceSimt 框架(index/scatter_reduce_common/op_kernel/arch35/scatter_reduce_common_simt.h):
- 执行模式:
KERNEL_TYPE_AIV_ONLY,即由 AIV(向量/标量核)单独执行; - 计算路径分发:
Process()中根据数据规模分发到两条路径——sliceSize >= 2的列切分路径,以及sliceSize == 1的标量路径;大 M(索引条目很多)场景走"radix sort 排序 + 计数均衡多核切分",保证对同一目标切片的多次更新按序连乘,从而保证确定性; - 子字宽类型处理:对 INT8/UINT8 等子 32 位类型,通过
SubwordWidenToI32(UNPACK4_B8加宽、按符号修正)提到 int32 累加,计算结束后由SubwordNarrowFromI32(PACK4_B32窄回)还原,累加链全程在 int32 上进行;对 FLOAT16 则按 ACC 类型提升到 float 计算,仅在输出时窄回一次。这与 index/scatter_mul/op_host/scatter_mul_def.cpp 头部注释中"sub-32-bit 通过外围字 atomic CAS 以 fp32/int32 内部精度归约"的说明一致。
测试与精度验证
index/scatter_mul/tests/assets/golden.py 为 scatter_mul 提供了 kernel、GEIR、aclnn、e2e(TF 前端)四条通路的 golden 与三方对标实现:
- kernel/aclnn 通路:golden 用
torch.Tensor.index_reduce_(0, idx, upd, "prod", include_self=True)实现连乘语义(相比纯 numpy 连乘,避免与被测 kernel 犯同类错误而掩盖精度短板);浮点精度判据为cross_check(L1 级),整型(INT32/INT8/UINT8)判据为binary_equal位级相等; - 三方对标逻辑:复刻内核的"加宽 → 链式归约 → 窄回"算法(
_tp_widen/_tp_narrow),tf腿则把var包装为tf.Variable后调用tf.compat.v1.scatter_mul(ref-variable 语义),并同样先滤除越界索引; - e2e 通路:验证
tf.compat.v1.scatter_mul前端到本算子的连通性。
此外 index/scatter_mul/tests/ut/op_host 下提供了 test_scatter_mul_tiling.cpp 与 test_scatter_mul_infershape.cpp 单测,分别覆盖 tiling 参数生成与 shape/dtype 推导逻辑。
小结
aclnnScatterMul 是 CANN ops-nn 中语义简单但实现精巧的原地 scatter 系列算子:接口层采用标准两段式 aclnn 模型,约束集中在 dtype 一致性与 updates.shape = indices.shape + varRef.shape[1:] 的 shape 规则上;实现层则复用 scatter-reduce 公共框架,通过排序 + 多核切分保证重复索引连乘的确定性,并通过加宽/窄回策略兼顾 FP16 与子字宽整型的精度。对于需要在 Ascend 950 上做"按索引连乘更新"(例如稀疏梯度聚合、变量原地更新)的场景,可直接参照本文示例接入;更深入的公共组件细节可继续阅读 index/scatter_reduce_common 目录下的 tiling 与 kernel 实现。