CANN ops-nn aclnnScatterMul 算子全解析:两段式接口、参数约束与 NPU 内核实现

原创2026-09-21 12:50:521,697 阅读
文章标签:人工智能深度学习算子库高性能计算模型量化AscendCANN

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 的连加语义完全对应)。其数学规则为:

varRef[indices[i], ...]=varRef[indices[i], ...]×updates[i, ...]varRef[indices[i],\ ...] = varRef[indices[i],\ ...] \times updates[i,\ ...]

几个关键语义要点:

  • 原地(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):

  1. 先调用 aclnnScatterMulGetWorkspaceSize 完成入参校验,并返回两块信息:计算所需 workspace 大小(workspaceSize)与封装了算子计算流程的执行器(executor);
  2. 再调用 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。

调用流程拆解

  1. 初始化(固定写法):aclInit → aclrtSetDevice → aclrtCreateStream,准备 Device 与 Stream 上下文;
  2. 构造 aclTensor:用 aclrtMalloc 申请 Device 内存、aclrtMemcpy 把 Host 数据拷入,再计算连续张量的 strides,最后用 aclCreateTensor 以 ND 格式 创建 aclTensor 描述(示例中的 CreateAclTensor 模板函数可复用于其他 aclnn 算子);
  3. 两段式调用:先 aclnnScatterMulGetWorkspaceSize 拿 workspaceSize 与 executor,按需 aclrtMalloc workspace,再 aclnnScatterMul 下发计算;
  4. 同步等待:aclrtSynchronizeStream 保证计算完成后再回拷结果;
  5. 结果回拷:因是原地更新,直接从 varRefDeviceAddr 把结果拷回 Host 打印;
  6. 资源释放: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 实现。

登录后查看全文
ops-nn