CANN ops-nn ScatterNdUpdate 算子开发指南:aclnnScatterNdUpdate 两段式接口原理与完整调用示例

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

CANN ops-nn ScatterNdUpdate 算子开发指南:aclnnScatterNdUpdate 两段式接口原理与完整调用示例

本文围绕 CANN ops-nn 仓库中 ScatterNdUpdate 算子 的 aclnnScatterNdUpdate 接口文档 展开,系统讲解该算子的功能语义、产品支持范围、两段式 aclnn 接口的参数与约束,并结合 op_api、op_host、op_kernel 源码与 ST 测试用例,深入剖析其底层实现路径。读完本文,你将掌握如何在 NPU 上通过 aclnnScatterNdUpdateGetWorkspaceSize + aclnnScatterNdUpdate 两段式接口正确完成张量局部更新,并理解 shape 推导规则、非连续 Tensor 优化路径与不同芯片架构上的实现差异。

功能说明:按索引就地更新张量元素

ScatterNdUpdate 的功能是将 updates 张量中的值,按照 indices 指定的索引,逐个更新到目标张量 varRef 中,更新操作在 varRef 上就地完成,因此 varRef 既是输入也是输出。

用公式可以更精确地描述其语义(见 README):

ref[indices[k]] = updates[k]

其中:

  • ref(对应接口入参 varRef)是一个维度为 P 的张量;
  • indices 是一个维度为 Q 的整型索引张量,其 shape 必须为 [d_0, ..., d_{Q-2}, K],其中 0 < K <= P,K 表示每个索引向量的维度数;
  • updates 是一个维度为 Q-1+P-K 的张量,其 shape 为 [d_0, ..., d_{Q-2}, ref.shape[K], ..., ref.shape[P-1]]。

通俗地说:indices 的最后一维(大小为 K)的每一行给出 varRef 中一个“锚点”的多维坐标,updates 中对应位置的数据块会被整体写入该锚点及其后随维度所张成的子区域。这与 scatter_nd_add/scatter_nd 系列算子的区别在于:ScatterNdUpdate 是覆盖式更新(赋值),而非累加。

产品支持情况

该算子在 CANN ops-nn 中按芯片型号区分支持范围(见 aclnnScatterNdUpdate.md 与 README):

产品型号 是否支持
Ascend 950PR / Ascend 950DT 支持
Atlas A3 训练系列产品 / Atlas A3 推理系列产品 支持
Atlas A2 训练系列产品 / Atlas A2 推理系列产品 支持
Atlas 200I/500 A2 推理产品 不支持
Atlas 推理系列产品 不支持
Atlas 训练系列产品 不支持

在算子定义文件 scatter_nd_update_def.cpp 中可以看到,该算子通过 AICore().AddConfig(...) 注册了 ascend950、ascend350、ascend910b、ascend910_93 四类 AICore 配置,与上述支持矩阵一致;其中 ascend910b/ascend910_93(对应 Atlas A2/A3 系列)与 ascend950(Ascend 950 系列)使用了不同的数据类型配置与 opFile 实现(scatter_nd_update 与 scatter_nd_update_apt)。

两段式接口设计:先算 workspace,再执行计算

aclnnScatterNdUpdate 遵循 CANN aclnn 算子库通用的两段式接口约定(机制说明见 two_phase_api.md):必须先调用第一段接口 aclnnScatterNdUpdateGetWorkspaceSize 获取计算所需 workspace 大小以及包含算子计算流程的执行器(executor),再调用第二段接口 aclnnScatterNdUpdate 真正下发计算。

两段接口的 C++ 函数原型如下:

aclnnStatus aclnnScatterNdUpdateGetWorkspaceSize(
  aclTensor*       varRef,
  const aclTensor* indices,
  const aclTensor* updates,
  uint64_t*        workspaceSize,
  aclOpExecutor**  executor)
aclnnStatus aclnnScatterNdUpdate(
  void*          workspace,
  uint64_t       workspaceSize,
  aclOpExecutor* executor,
  aclrtStream    stream)

第一段接口在 host 侧完成入参校验、算子路由与 workspace 大小估算;第二段接口则在指定 stream 上异步执行计算。这样的设计把“计算资源预算”和“实际执行”解耦,便于上层框架统一管理 Device 侧内存。

第一段接口 aclnnScatterNdUpdateGetWorkspaceSize 参数详解

参数说明

参数名 输入/输出 描述 使用说明 数据类型 数据格式 维度(shape) 非连续Tensor
varRef(aclTensor*) 输入/输出 被更新的目标张量 数据类型需要与 updates 一致 FLOAT16、BFLOAT16、FLOAT32、INT64、BOOL、INT8、UINT8、FLOAT8_E4M3FN、FLOAT8_E5M2、HIFLOAT8 ND 1-8 √
indices(aclTensor*) 输入 指定的索引张量 indices 中的索引数据不支持越界 INT32、INT64 ND - √
updates(aclTensor*) 输入 更新的数据张量 数据类型需要与 varRef 一致 FLOAT16、BFLOAT16、FLOAT32、INT64、BOOL、INT8、UINT8、FLOAT8_E4M3FN、FLOAT8_E5M2、HIFLOAT8 ND - √
workspaceSize(uint64_t*) 输出 返回需要在 Device 侧申请的 workspace 大小 - - - - -
executor(aclOpExecutor**) 输出 返回 op 执行器,包含了算子计算流程 - - - - -

需要特别留意的是分平台的 dtype 差异:在 Atlas A3 训练/推理系列产品、Atlas A2 训练/推理系列产品上,FLOAT8_E4M3FN、FLOAT8_E5M2、HIFLOAT8 三种数据类型不支持。这一约束在 aclnn_scatter_nd_update.cpp 中体现为三份平台相关的 dtype 支持列表:

  • ASCEND910_DTYPE_DTYPE_SUPPORT_LIST:FLOAT、FLOAT16、BOOL;
  • ASCEND910B_DTYPE_DTYPE_SUPPORT_LIST:FLOAT、FLOAT16、BOOL、INT16、BF16、INT64、INT8、INT32;
  • ASCEND950_DTYPE_DTYPE_SUPPORT_LIST:FLOAT、FLOAT16、BOOL、BF16、INT64、INT8、FLOAT8_E5M2、FLOAT8_E4M3FN、HIFLOAT8、UINT8;
  • INDEX_DTYPE_SUPPORT_LIST:INT64、INT32(indices 全局通用)。

GetDtypeSupportList() 会根据 GetCurrentPlatformInfo().GetCurNpuArch() 与 SoC 版本自动选择对应的支持列表,CheckDtypeValid() 再据此校验 varRef/updates 与 indices 的数据类型,并强制要求 varRef 与 updates 数据类型一致。

返回值

第一段接口返回 aclnnStatus 状态码,具体定义参见 aclnn 返回码说明。第一段接口完成入参校验,出现以下场景时报错:

返回值 错误码 描述
ACLNN_ERR_PARAM_NULLPTR 161001 传入的 varRef、indices、updates 是空指针
ACLNN_ERR_PARAM_INVALID 161002 / 561103 varRef、indices、updates 的 shape 不符合要求
ACLNN_ERR_PARAM_INVALID 161002 / 561103 varRef、indices、updates 的数据类型不在支持的范围之内

源码中的校验逻辑与此对应:CheckParams() 先通过 CheckNotNull() 对三个 Tensor 做空指针检查(对应 ACLNN_ERR_PARAM_NULLPTR),再通过 CheckDtypeValid() 做 dtype 支持范围检查与 varRef/updates 一致性检查(对应 ACLNN_ERR_PARAM_INVALID)。此外,接口入口处还会检查三个 Tensor 的维度数是否超过 8 维上限(MAX_DIM_NUM = 8,超限仅记录告警日志);若任一输入为空 Tensor(IsEmpty()),则直接返回 workspaceSize = 0 并成功退出。

第二段接口 aclnnScatterNdUpdate 参数详解

参数名 输入/输出 描述
workspace 输入 在 Device 侧申请的 workspace 内存地址
workspaceSize 输入 在 Device 侧申请的 workspace 大小,由第一段接口 aclnnScatterNdUpdateGetWorkspaceSize 获取
executor 输入 op 执行器,包含了算子计算流程
stream 输入 指定执行任务的 Stream

第二段接口的实现非常简洁,其核心调用链为:

aclnnStatus aclnnScatterNdUpdate(void* workspace, uint64_t workspaceSize,
                                 aclOpExecutor* executor, aclrtStream stream)
{
    L2_DFX_PHASE_2(aclnnScatterNdUpdate);
    return CommonOpExecutorRun(workspace, workspaceSize, executor, stream);
}

即所有计算流程都在第一段接口构建的 executor 中固化,第二段接口只负责在指定 stream 上运行 executor(见 aclnn_scatter_nd_update.cpp)。

约束说明

shape 限制

  • varRef 最多支持 8 维,其 rank 取值范围为 [1, 8]。
  • indices 至少是 2 维,其最后一维的大小表示索引的维度数 rank,rank 取值范围为 [1, 7],且必须满足 rank <= varRef.rank,即索引维度数不能超过 varRef 的维度数。
  • updates 的 shape 与 indices、varRef 之间存在强约束:假设 indices 最后一维的大小是 a,则 updates 的 shape 等于 indices 除最后一维外的 shape 拼接上 varRef 除前 a 维外的 shape。
  • 示例:varRef 的 shape 是 (4, 5, 6),indices 的 shape 是 (3, 2)(最后一维 a=2),则 updates 的 shape 必须是 (3, 6)。

这一 shape 规则在 ST 测试用例中得到了充分覆盖,例如 atk_aclnnScatterNdUpdate.json 中 id=0 的用例:varRef [1, 9]、indices [1, 2]、updates [1],即索引最后一维 a=2,updates 取 indices 除最后一维外的 shape [1] 拼接 varRef 除前 2 维外的 shape(空),得到 [1]。测试矩阵覆盖了从 1 维标量切片更新到 8 维高 rank 更新的各种组合(如 id=183 中 varRef [257, 7, 1, 1, 19]、indices [198, 3, 1, 1, 2]、updates [198, 3, 1, 1, 1, 1, 19]),并覆盖 int8/fp16/fp32/int64 多种 dtype 与 INT32/INT64 两种索引类型。

非连续 Tensor 支持

三个输入 Tensor 均可传入非连续视图,但不同芯片架构的优化力度不同:

  • Atlas A3 训练/推理系列产品、Atlas A2 训练/推理系列产品:varRef 支持首轴非连续(即第 0 维的 stride 大于其按连续布局计算的期望值,其余各维均连续)的场景,算子可直接基于该非连续视图完成更新,无需先将 varRef 转换为连续 Tensor。

源码层面,aclnn_scatter_nd_update.cpp 中实现了两套非连续判定与处理逻辑:

  • IsSupportNonContiguousArch22():针对 arch22(Atlas A2/A3 对应架构),仅放行“dim≥1 全部连续、dim 0 stride 大于连续期望值”的窄子集;
  • IsSupportNonContiguous():针对 arch35(Ascend 950 对应架构),支持更通用的“索引轴部分非连续、非索引轴部分连续”场景。

第一段接口会根据 GetCurrentPlatformInfo().GetCurNpuArch() 分流:

  1. arch35 且满足 IsSupportNonContiguous 条件 → 走 ProcessNonContiguousCase 通用 view 优化路径:indices/updates 先转连续,varRef 通过 uniqueExecutor->CreateView(...) 保持原始 stride 创建视图后直接交给 l0op::ScatterNdUpdate,无需做全量 contiguous 拷贝;
  2. arch22 且满足 IsSupportNonContiguousArch22 → 同样走 ProcessNonContiguousCase,将非连续 stride 信息透传给 arch22 的 tiling/kernel(kernel 内通过 isViewStride0 标记使用 ResolveOutOffset<isViewStride0> 计算带 stride 的输出偏移);
  3. 其余情况 → 走 ProcessContiguousCase 常规路径:先将 varRef 也转成连续 Tensor,若 varRef 原本非连续,则计算结束后再通过 l0op::ViewCopy 将结果拷回原始视图。

确定性计算

  • Ascend 950PR / Ascend 950DT:默认非确定性,支持通过 aclrtSetSysParamOpt 开启确定性计算;
  • Atlas A3 训练/推理系列产品、Atlas A2 训练/推理系列产品:默认确定性。

这一差异的内核根源可以从 scatter_nd_update.cpp 的 kernel 入口注释中看到:arch22 上按 tilingKey 区分排序(sorted)/非排序(unsorted)路径与 int32/int64 线性索引路径;当开启 HIGH_PERFORMANCE 宏时走 HP 路径——该路径按 indices 切分到各 core,融合 LinearIndex 与 Scatter 且不调用 SyncAll(),注释明确指出其代价是“对重复索引的写入在 core 间非确定性”,因此 tilingKey 30(int64 大索引)仍回退到确定性的 LargeIndexKernel。arch35 侧则分别提供了 scatter_nd_update_deterministic_simd/simt 与普通 simd/simt 内核文件(见 op_kernel/arch35),用于确定性/非确定性路径的选择。当 indices 中存在重复索引时,最终写入值由“最后一次更新”决定,因此确保确定性需要配合排序等预处理。

源码级实现剖析

op_api 层:接口路由与 L0 算子编排

第一段接口 aclnnScatterNdUpdateGetWorkspaceSize 的完整流程(见 aclnn_scatter_nd_update.cpp):

  1. CREATE_EXECUTOR() 创建 OpExecutor;
  2. CheckParams 完成空指针与 dtype 校验;
  3. 检查维度数上限与空 Tensor;
  4. 依据芯片架构与非连续条件选择 ProcessNonContiguousCase 或 ProcessContiguousCase;
  5. 两路径内部均调用 l0op::Contiguous 规整 indices/updates,再调用 l0op::ScatterNdUpdate 完成核心更新,最终通过 uniqueExecutor->GetWorkspaceSize() 汇总 workspace 大小并 ReleaseTo(executor) 释放执行器所有权。

op_host 层:算子注册与 InferShape

算子定义见 scatter_nd_update_def.cpp:

  • 输入为 var、indices、updates 三个 REQUIRED 输入,输出为 var(就地更新,输出即输入),格式全部限定为 ND;
  • 可选属性 use_locking,BOOL 类型,默认 false,置 true 时操作用 lock 保护;
  • AICore 配置开启了 DynamicCompileStaticFlag(true)、DynamicRankSupportFlag(true)、DynamicShapeSupportFlag(true),即支持动态 shape 与动态 rank;
  • arch22 配置额外开启了 DynamicFormatFlag(true)。

InferShape 实现见 scatter_nd_update_infershape.cpp:输出 shape 直接继承输入 var 的 shape(*output_shape = *var_shape),输出 dtype 继承输入 var 的 dtype;遇到 UnknownRank 时输出设置为 (-2,)。

Tiling 侧(见 arch35/scatter_nd_update_tiling_arch35.cpp)通过 TilingPrepareScatterNdUpdateForAscendC 从平台信息中获取 AIV core 数量与 UB 内存大小作为编译期信息,再在 Tiling4ScatterNdUpdate 中依据具体 shape 完成 block/row 切分。

op_kernel 层:多路径内核调度

arch22 的 kernel 入口(scatter_nd_update.cpp)按 tilingKey = indexType * 10 + sortFlag 分发:

  • tilingKey 11/21:排序后的线性索引路径(int32/int64),先 LinearIndexKernel 将多维索引扁平化为线性索引并排序,再 ScatterNdUpdateKernel 按行块拷贝 updates 写入 varRef,写前通过二分查找(findFirstLt/findLastGe)限定本 core 负责的索引区间,并对重复索引做 lastProcessedIdx_ 去重,保证“同一位置只写最后一次”;
  • tilingKey 10/20:非排序(NoSort)路径;
  • tilingKey 30:int64 大索引场景,走 LargeIndexKernel,避免线性化溢出(对应测试 JSON 中 varRef 首维超过 13 万的大规模用例,如 id=199 的 [131073, 7]);
  • 可选 HIGH_PERFORMANCE 编译宏下的 HP 融合路径。

内核实现细节可进一步参考 arch22/scatter_nd_update.h(排序路径的 double buffer 流水、UB tile 切分与降序二分边界查找)与 arch22/scatter_nd_update_linear_index.h、arch22/scatter_nd_update_large_index.h。

测试与验证

ST 测试定义在 atk_aclnnScatterNdUpdate.json(200 条用例),配合 executor_aclnnScatterNdUpdate.py 执行;UT 侧在 tests/ut/op_api/test_aclnn_scatter_nd_update.cpp,此外还包含 op_graph 的 fusion pass 单测。测试覆盖了 1~8 维、多种 dtype(fp16/fp32/int8/int64)、INT32/INT64 索引、单元素与切片级更新、超大索引规模等典型场景,可作为该算子行为的事实参照。

完整调用示例

以下示例摘自 examples/test_aclnn_scatter_nd_update.cpp,展示了从资源初始化、Tensor 构造到两段式接口调用、结果回拷与资源释放的完整流程。示例中 varRef shape 为 (2, 3, 7),indices shape 为 (2, 2),updates shape 为 (2, 7):indices 的每一行 (i, j) 定位 varRef 中第 (i, j) 个长度为 7 的行,updates 的对应行整体覆盖该位置。具体编译和执行过程请参考 编译与运行样例说明。

#include <iostream>
#include <vector>
#include "acl/acl.h"
#include "aclnnop/aclnn_scatter_nd_update.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 = {2, 3, 7};
  std::vector<int64_t> indicesShape = {2, 2};
  std::vector<int64_t> updatesShape = {2, 7};
  void* varRefDeviceAddr = nullptr;
  void* indicesDeviceAddr = nullptr;
  void* updatesDeviceAddr = nullptr;
  aclTensor* varRef = nullptr;
  aclTensor* indices = nullptr;
  aclTensor* updates = nullptr;
  std::vector<float> varRefHostData = {0.3816, 0.3939, 0.8474, 0.1652, 0.6049, 0.3315, 0.4954,
                                    0.3284, 0.7060, 0.4359, 0.6514, 0.9476, 0.4708, 0.0656,
                                    0.9652, 0.9512, 0.6452, 0.1981, 0.4159, 0.9575, 0.1516,
                                    0.4987, 0.9107, 0.6635, 0.4119, 0.4845, 0.5558, 0.2749,
                                    0.6230, 0.1180, 0.2400, 0.9971, 0.4093, 0.5561, 0.4023,
                                    0.6612, 0.4109, 0.8470, 0.9733, 0.6947, 0.7980, 0.7957};
  std::vector<int64_t> indicesHostData = {5, 0, 1, 5};
  std::vector<float> updatesHostData = {0.7804, 0.3411, 0.6674, 0.8468, 0.6679, 0.5549, 0.9893,
                                   0.2086, 0.2473, 0.5110, 0.4549, 0.3113, 0.8490, 0.9217};
  // 创建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_INT64, &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;
  // 调用aclnnScatterNdUpdate第一段接口
  ret = aclnnScatterNdUpdateGetWorkspaceSize(varRef, indices, updates, &workspaceSize, &executor);
  CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclnnScatterNdUpdateGetWorkspaceSize 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);
  }
  // 调用aclnnScatterNdUpdate第二段接口
  ret = aclnnScatterNdUpdate(workspaceAddr, workspaceSize, executor, stream);
  CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclnnScatterNdUpdate 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和aclScalar,需要根据具体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;
}

示例中几个容易踩坑的要点:

  • indicesHostData 的取值必须落在 varRef 的合法索引范围内(接口约束“索引数据不支持越界”),示例中 (5,0) 与 (1,5) 均对应 varRef 2×3 网格内的有效位置;
  • updates 的 dtype 必须与 varRef 完全一致,否则第一段接口返回 ACLNN_ERR_PARAM_INVALID;
  • workspaceSize 可能为 0,此时不需要申请 workspace 内存,直接以空指针调用第二段接口即可;
  • 结果回拷后应打印检查被更新位置的值是否与 updates 对应行一致,以验证更新语义。

总结

ScatterNdUpdate 是 ops-nn 中实现“按多维索引覆盖更新张量”的典型 scatter 族算子,其 aclnn 接口采用“GetWorkspaceSize + 执行”两段式设计,约束集中在 shape 推导规则(updates.shape = indices<a href="https://link.gitcode.com/i/9e5b7d018ac797acbe232e295727ad94" target="_blank">:-1].shape + varRef[a:])、dtype 一致性与平台差异上。从实现上看,op_api 层负责按芯片架构选择非连续优化路径或连续常规路径,op_host 层完成注册、InferShape 与 tiling 准备,op_kernel 层则依据索引类型与是否排序分派多条内核路径,并针对重复索引、大索引规模等场景提供确定性保障。开发者可结合 [算子 README、接口文档、示例代码 与 ST 测试用例 快速完成验证与二次开发。

登录后查看全文
ops-nn