CANN ops-nn ScatterList 算子实战指南:aclnnScatterList 两段式接口原理、参数与调用示例

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

CANN ops-nn ScatterList 算子实战指南:aclnnScatterList 两段式接口原理、参数与调用示例

导读

本文围绕 CANN ops-nn 算子库中的 ScatterList 算子展开,系统讲解其通过 aclnnScatterList 两段式接口完成"沿指定维度整段覆盖写入张量列表"的稀疏更新能力。文章以算子接口文档为骨架,完整覆盖产品支持矩阵、功能语义、函数原型、全部参数与错误码说明、约束条件以及可直接编译运行的 C++ 调用示例,并深入仓库源码(op_proto、op_host、op_kernel、测试用例)剖析从算子原型注册、Host 侧 Tiling 到 Device 侧 Kernel 分发的完整实现链路。读完本文,你将能够独立完成 ScatterList 算子的入参构造、workspace 申请、两段式调用与结果校验,并理解其底层 shape 约束与性能分派策略。

一、产品支持情况

ScatterList 算子在 CANN ops-nn 仓库(index/scatter_list)中按不同硬件平台差异化支持,接口文档 与 README 给出的支持矩阵如下:

产品 是否支持
Ascend 950PR / Ascend 950DT 支持
Atlas A3 训练系列产品 / Atlas A3 推理系列产品 支持
Atlas A2 训练系列产品 / Atlas A2 推理系列产品 支持
Atlas 200I/500 A2 推理产品 不支持
Atlas 推理系列产品 不支持
Atlas 训练系列产品 不支持
Kirin X90 处理器系列产品 支持
Kirin 9030 处理器系列产品 支持

从仓库源码可以印证上述矩阵的落地方式:算子定义文件 scatter_list_def.cpp 中分别通过 AICore().AddConfig() 注册了 ascend910b、ascend910_93、ascend950、ascend310p、kirinx90、kirin9030 等多个 AICore 配置。同时需要注意的是,不同平台的数据类型支持存在差异——README 明确说明 Kirin X90 / Kirin 9030 处理器系列产品不支持 BFLOAT16;在 scatter_list_def.cpp 中,ascend310p 配置所声明的数据类型列表(INT8/INT16/INT32/UINT8/UINT16/UINT32/FLOAT16/FLOAT)同样不含 BFLOAT16,与 README 的表述一致。

二、功能说明与计算公式

2.1 接口功能

ScatterList 将 updates 中的值,按照 indice 给出的起始位置,沿 axis 指定的维度整段覆盖写入 varRef 张量列表中对应的张量。它对应的是"稀疏矩阵更新应用到变量引用(张量列表)"这一经典 scatter 场景,与 MindSpore 框架的 ScatterList 算子语义兼容(见 scatter_list_proto.h 中的兼容性说明)。

varRef 是 aclTensorList 类型的张量列表,输出与输入共享内存,属于原地更新。

2.2 计算公式

记 varRef 列表中的张量个数为 B,i 为列表下标(0 <= i < B),start 为第 i 个张量的写入起始位置,len 为写入长度,则:

var[i][…,start+k,… ]=updates[i][…,k,… ],0≤k<lenvar[i][\dots, start + k, \dots] = updates[i][\dots, k, \dots] \quad , \quad 0 \le k < len

其中省略号表示 axis 轴之外的其余维度,写入沿 axis 指定的维度进行。start 与 len 由 indice 给出:

  • indice 为 1 维时:start = indice[i],len 为 updates 在 axis 轴上的大小(各张量写入长度相同)。
  • indice 为 2 维时:start = indice[i][0],len = indice[i][1](各张量写入长度可以不同)。

可选输入 maskOptional 按列表元素逐个门控是否执行写入。reduce 当前仅支持 "update",即直接覆盖。

2.3 关键语义:写入起始位置而非散射下标

需要特别强调的是,indice 给出的是写入起始位置,而不是 scatter 的目标下标。写入是从该位置开始的一段连续区间,需要调用方保证整段不越出 axis 轴。这一语义在接口文档约束说明、README 以及 Kernel 实现中保持一致。

三、两段式接口与函数原型

与其他 CANN 单算子 API 一致,aclnnScatterList 采用两段式接口(详见 两段式接口说明):必须先调用 aclnnScatterListGetWorkspaceSize 获取计算所需的 workspace 大小以及包含算子计算流程的执行器,再调用 aclnnScatterList 执行计算。两段式接口中,第一段返回的 executor 封装了算子的完整计算流程,且第二段接口 aclnnScatterList(...) 不能重复调用。

aclnnStatus aclnnScatterListGetWorkspaceSize(
  aclTensorList*       varRef,
  const aclTensor*     indice,
  const aclTensor*     updates,
  const aclTensor*     maskOptional,
  char*                reduceOptional,
  int64_t              axis,
  uint64_t*            workspaceSize,
  aclOpExecutor**      executor)
aclnnStatus aclnnScatterList(
  void*             workspace,
  uint64_t          workspaceSize,
  aclOpExecutor*    executor,
  aclrtStream       stream)

四、aclnnScatterListGetWorkspaceSize 参数详解

4.1 参数说明

参数名 输入/输出 描述 使用说明 数据类型 数据格式 维度(shape) 非连续Tensor
varRef(aclTensorList*) 输入/输出 待被更新的张量列表。 张量列表中的各 tensor 的 shape 与 updates 满足 broadcast 关系。各 tensor 的数据类型需与 updates 数据类型相同。 INT8、INT16、INT32、UINT8、UINT16、UINT32、FLOAT16、BFLOAT16、FLOAT ND 0-8 √
indice(aclTensor*) 输入 写入位置张量,逐 varRef 列表元素给出写入的起始位置(1 维时)或起始位置与长度(2 维时)。1 维:indice[i] 为第 i 个张量在 axis 轴上的写入起始位置,写入长度为 updates 在 axis 轴上的大小。2 维:indice[i][0] 为起始位置,indice[i][1] 为写入长度。 - INT32、INT64 ND 0-8 √
updates(aclTensor*) 输入 需要更新到 var 上的值张量。 数据类型需与 var 中的 tensor 数据类型相同。shape 需要与 var 中各 tensor 的 shape 满足 broadcast 关系。 INT8、INT16、INT32、UINT8、UINT16、UINT32、FLOAT16、BFLOAT16、FLOAT ND 0-8 √
maskOptional(aclTensor*) 可选参数 掩码张量。 取值仅支持 0 和 1:0 表示该列表元素不执行写入,1 表示执行写入。其余取值行为未定义。值位于 Device 侧,第一段接口无法校验,由调用方保证。 UINT8 ND 1 √
reduceOptional(char*) 属性 应用的 reduction 操作类型。 当前仅支持 "update"。 string - - -
axis(int64_t) 属性 用来 scatter 的维度。 默认值为 -2。 int64_t - - -
workspaceSize(uint64_t*) 输出 返回需要在 Device 侧申请的 workspace 大小。 - - - - -
executor(aclOpExecutor**) 输出 返回 op 执行器,包含了算子计算流程。 - - - - -

说明:表中的"非连续 Tensor"列标记为 √,表示该输入支持非连续张量(有关非连续张量的更详细定义可参考 non_contiguous_tensor 相关背景文档)。

4.2 返回值

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

返回码 错误码 描述
ACLNN_ERR_PARAM_NULLPTR 161001 传入的 tensor 或 tensorList 是空指针。
ACLNN_ERR_PARAM_INVALID 161002 varRef 中 tensor 的数据类型不在支持的范围之内。
ACLNN_ERR_PARAM_INVALID 161002 indice 的数据类型不在支持的范围之内。
ACLNN_ERR_PARAM_INVALID 161002 reduceOptional 参数不在支持的范围之内。
ACLNN_ERR_PARAM_INVALID 161002 varRef 中 tensor 与 updates 的数据类型不一致。

五、aclnnScatterList 参数说明

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

返回值同样为 aclnnStatus 状态码,参见 aclnn 返回码。

六、约束说明

6.1 确定性计算

aclnnScatterList 默认采用非确定性实现,支持通过 aclrtCtxSetSysParamOpt 开启确定性计算(相关背景可参考 确定性计算说明)。

6.2 Ascend 950PR/Ascend 950DT 的 shape 约束

记 varRef 列表中的张量个数为 B,各输入的 shape 需满足以下关系,不满足时第一段接口返回 561002:

  • varRef:列表中每个张量的 shape 需相同,每个张量的维度数需大于等于 1。
  • updates:维度数等于 varRef 中单个张量的维度数加 1;第一维大小等于 B;axis 轴的大小不大于 varRef 对应轴;其余维度与 varRef 一致。
  • indice:shape 支持 1 维或 2 维。1 维时 shape 为 (B,),只给出写入起始位置;2 维时 shape 为 (B, 2),给出写入起始位置与长度。
  • maskOptional:shape 支持 1 维,第一维大小等于 B。
  • axis:归一化(负数按 updates 的维度数折算)后的取值必须落在开区间 (0, updates的维度数) 内,即不能指向第 0 维,也不能越界。默认值 -2 要求 updates 的维度数大于等于 3。

6.3 indice 语义与取值范围

indice 给出的是写入起始位置,不是散射目标下标;写入是从该位置开始的一段连续区间,需保证整段不越出 axis 轴(取值由调用方保证,算子不做校验):

  • 1 维:indice[i] 为第 i 个张量的写入起始位置,写入长度为 updates 在 axis 轴上的大小。
  • 2 维:indice[i][0] 为起始位置,indice[i][1] 为写入长度,长度不应超过 updates 在 axis 轴上的大小。

6.4 maskOptional 取值范围

取值仅支持 0 和 1:0 表示该列表元素不执行写入,1 表示执行写入,其余取值行为未定义(由调用方保证,算子不做校验)。

七、调用示例

以下示例代码位于 examples/test_aclnn_scatter_list.cpp,可直接参考 编译与运行样例 进行编译和执行:

#include <iostream>
#include <vector>
#include "acl/acl.h"
#include "aclnnop/aclnn_scatter_list.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;
}

void PrintOutResult(std::vector<int64_t> &shape, void** deviceAddr) {
  auto size = GetShapeSize(shape);
  std::vector<float> resultData(size, 0);
  auto ret = aclrtMemcpy(resultData.data(), resultData.size() * sizeof(resultData[0]),
                         *deviceAddr, 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);
  for (int64_t i = 0; i < size; i++) {
    LOG_PRINT("result[%ld] is: %f\n", i, resultData[i]);
  }
}

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> varShape = {5, 3, 4};
  std::vector<int64_t> indicesShape = {1, 2};
  std::vector<int64_t> updatesShape = {1, 5, 3, 4};

  void* varDeviceAddr = nullptr;
  void* indicesDeviceAddr = nullptr;
  void* updatesDeviceAddr = nullptr;

  aclTensor* varTensor = nullptr;
  aclTensor* indices = nullptr;
  aclTensor* updates = nullptr;

  std::vector<float> varHostData(5 * 3 * 4, 0);
  std::vector<int64_t> indicesHostData = {0, 1};
  std::vector<float> updatesHostData(1 * 5 * 3 * 4, 10);

  ret = CreateAclTensor(varHostData, varShape, &varDeviceAddr, aclDataType::ACL_FLOAT, &varTensor);
  CHECK_RET(ret == ACL_SUCCESS, return ret);
  aclTensor* varArray[] = {varTensor};
  auto varTensorList = aclCreateTensorList(varArray, 1);

  ret = CreateAclTensor(indicesHostData, indicesShape, &indicesDeviceAddr, aclDataType::ACL_INT64, &indices);
  CHECK_RET(ret == ACL_SUCCESS, return ret);

  ret = CreateAclTensor(updatesHostData, updatesShape, &updatesDeviceAddr, aclDataType::ACL_FLOAT, &updates);
  CHECK_RET(ret == ACL_SUCCESS, return ret);

  // 3. 调用CANN算子库API
  uint64_t workspaceSize = 0;
  aclOpExecutor* executor;

  // 调用aclnnScatterList第一段接口
  ret = aclnnScatterListGetWorkspaceSize(varTensorList, indices, updates, nullptr, "update", -2, &workspaceSize, &executor);
  CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclnnScatterListGetWorkspaceSize 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);
  }

  // 调用aclnnScatterList第二段接口
  ret = aclnnScatterList(workspaceAddr, workspaceSize, executor, stream);
  CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclnnScatterList 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侧
  PrintOutResult(varShape, &varDeviceAddr);

  // 6. 释放aclTensor
  aclDestroyTensorList(varTensorList);
  aclDestroyTensor(indices);
  aclDestroyTensor(updates);

  // 7. 释放device资源
  aclrtFree(varDeviceAddr);
  aclrtFree(indicesDeviceAddr);
  aclrtFree(updatesDeviceAddr);
  if (workspaceSize > 0) {
    aclrtFree(workspaceAddr);
  }
  aclrtDestroyStream(stream);
  aclrtResetDevice(deviceId);
  aclFinalize();

  return 0;
}

示例语义解读

对示例参数做一次逐步推演,可以帮助读者快速建立直觉:

  • varShape = {5, 3, 4},updatesShape = {1, 5, 3, 4},B = 1,即 varRef 中只有 1 个张量;updates 维度数(4)= var 维度数(3)+ 1,第一维大小 1 等于 B。
  • axis = -2,按 updates 的维度数 4 归一化:-2 + 4 = 2,落在开区间 (0, 4) 内且非第 0 维,满足约束。
  • indicesShape = {1, 2},即 2 维 indice:indice[0][0] = 0 为写入起始位置,indice[0][1] = 1 为写入长度。
  • 于是 var[0] 沿 axis=2 维从位置 0 开始写入长度为 1 的连续区间,对应公式 var[0][..., 0, ...] = updates[0][..., 0, ...]。展平后即 var 的 result[0] ~ result[3](对应 var[0][0][0][:])被覆盖为 10,其余 56 个元素保持初始值 0。

八、源码实现剖析:从原型注册到 Kernel 分发

8.1 算子原型注册(op_graph)

scatter_list_proto.h 使用 REG_OP 注册了 ScatterList 算子的 GE 图原型:

  • DYNAMIC_INPUT(var) 与 DYNAMIC_OUTPUT(var) 声明了动态张量列表形式的输入/输出;
  • OPTIONAL_INPUT(mask) 声明 mask 为可选输入,类型限定 DT_UINT8;
  • 属性 reduce 默认 "update",axis 默认 -2;
  • 从源码结构看,proto 层面注册的 T 类型范围(FLOAT16/BF16/FLOAT/INT8/INT16/INT32/INT64/UINT8/UINT16/UINT32/UINT64)比 aclnn 接口文档声明的支持范围更宽,实际 aclnn 接口能力以接口文档与 scatter_list_def.cpp 注册的数据类型为准(不含 INT64/UINT64);
  • 原型注释明确标注该算子与 MindSpore 框架的 ScatterList 算子兼容。

8.2 Host 侧算子定义(op_host)

scatter_list_def.cpp 中 ScatterList : public OpDef 完成了输入/输出/属性的声明:var 与输出 var 均为 DYNAMIC 参数类型并开启 AutoContiguous();reduce 为可选字符串属性(默认 "update")、axis 为可选整型属性(默认 AXIS_DEFAULT = -2)。同时为不同 SoC 注册 AICore 配置(910b、910_93、950 共用 config910b,另有 310p 与 Kirin 配置),并声明动态 rank/shape、动态格式、精度降低(PrecisionReduceFlag(true))等能力。

此外,目录 op_host/config 下按 ascend310p、ascend910_93、ascend910b、ascend950、kirin9030、kirinx90 分别提供了二进制算子库描述文件(如 scatter_list_binary.json),其中按 dtype 组合(int8/int16/int32/uint8/uint16/uint32/float16/bfloat16/float32 × int32/int64 索引)列出了编译产物 bin_filename 与动态 shape(-2 表示动态维)的输入输出规格。

8.3 Host 侧 Tiling(op_host/scatter_list_tiling.cpp)

scatter_list_tiling.cpp 实现了算子切分(Tiling)逻辑,是整个算子的"形状决策中枢",其关键流程为:

  1. 平台信息获取(GetPlatformData):读取 AIV Core 数量、UB 内存大小,并区分是否支持 move/pad 指令(supportMovePad,仅 910B 及 RegBase 系列 SoC 支持)、是否 Ascend910。
  2. 张量列表校验(GetVarTensorNum):读取 var 列表实例个数(不允许为空列表),并逐一校验列表内所有 tensor shape 完全一致。
  3. shape 解析与 axis 归一化(GetVarAndUpdateData / GetAxisAndUpdatesDtype / ReShape):校验 var 至少 1 维、updates 至少 2 维、updates 维度数 = var 维度数 + 1、var 张量个数 = updates 第一维大小;对负数 axis 按 newAxis = updatesDims + axis 归一化,并校验 0 < newAxis < updatesDims;同时校验 var 与 updates 数据类型一致,并按 32 字节对齐计算 updatesOneBlock 等参数。
  4. indice / mask 校验(GetIndiceData / GetMaskData):indice 仅支持 1 维或 2 维,第一维必须等于 B,2 维时第二维必须为 2;mask 为可空输入,非空时仅支持 1 维且第一维等于 B。
  5. reduce 校验(GetOtherData):strcmp(reduce, "update") != 0 直接返回失败,印证"当前仅支持 update"。
  6. 多分支切分策略(GetOtherDataNeg1 / GetOtherDataNeg2 / GetDataNeg 等):根据维数、对齐情况、UB 容量关系选择不同的 tiling key(如 TILINGKEY_TSMALL/TMORE/TLARGE、TILINGKEY_PSMALL/PMORE/PLARGE/PLE 及 RSBSE/RLBSE/RSBLE/RLBLE 系列),并计算每个核承担的 batch 数、循环次数、源/目的 stride 等。
  7. 输出 tiling 数据(SetTilingData):将计算结果写入 tiling buffer,并通过 context->SetBlockDim()、context->SetTilingKey() 下发;workspace 申请大小固定为 WORK_SPACE_SIZE = 32 字节(workspaces[0] = WORK_SPACE_SIZE)。

8.4 Device 侧 Kernel(op_kernel)

Kernel 入口 scatter_list.cpp 通过 TILING_KEY_IS(...) 宏按 tiling key 分发到不同的算子类模板:

  • key 100/101/102:ScatterListTransposeSmall/More/Large(需要转置的场景,按 dtype 字节宽度实例化为 int8_t / half / float 模板);
  • key 103/104/105/106/107:ScatterListNegSmall/NegMore/NegLarge/NegLargeE/NegDim2Large(无需转置的常规场景,使用 DTYPE_VAR / DTYPE_INDICE 编译期宏实例化);
  • key 200/210/211/220/230/231:ScatterListRSBSE / RLBSE / RLBSEPad / RSBLE / RLBLE / RLBLEPad(RegBase 系列平台的分支实现)。

基类模板 scatter_list_base.h 提供公共能力,包括:

  • GetTensorAddr:通过张量列表首地址处的 64 位指针偏移(右移 3 位得到偏移数量)解析出第 batchIdx 个张量的 GM 地址,这正是 aclTensorList 在 Device 侧按列表取地址的实现方式;
  • TransposeB8/B16/B32/B32Back:借助 TransDataTo5HD 指令族完成 8/16/32 字节粒度的 UB 内转置,服务于轴交换场景;
  • 一系列硬事件同步封装(Mte2ToS、Mte2ToMte3、Mte3ToMte2、VToMte3、Mte2ToV),用于在流水线各阶段之间建立依赖,保证 UB 数据搬运与向量/转置指令的正确顺序。

8.5 图模式 Fallback(op_graph/scatter_list_fallback.cpp)

当算子以图模式(Host API 执行)运行时,scatter_list_fallback.cpp 中注册的 ScatterListHostExecuteFunc 负责从执行上下文中逐个取出动态输入 var 张量(上限 MAX_TENSOR_NUM = 256)、indice、updates 与可选 mask,读取 reduce/axis 属性后,通过 CANN_OPS_OPB_SYN_EXEC_ACLNN 同步执行 aclnnScatterList 完成计算。这印证了单算子 API 与图模式两种调用路径最终收敛到同一套算子实现的架构设计。

九、测试与验证

仓库为 ScatterList 算子提供了系统化的测试覆盖:

  • ST 级 aclnn 接口测试:tests/st/aclnnScatterList/executor_aclnnScatterList.py 基于 ATK 框架注册 function_scatter_for_aclnn_scatter_list,用 PyTorch 从 0 维/1 维/2 维 indice 三种形态模拟"克隆 var 后按 axis 切片写入"的参考实现(2 维时 indice<a href="https://link.gitcode.com/i/f4e0a28b3e4551f1aaa26c25539c1db7" target="_blank">i][0] 为偏移、indice[i][1] 为长度,超出边界时截断跳过),用于与 NPU 结果对拍;配套的 [atk_aclnnScatterList.json 描述用例规格。
  • UT 级 tiling 测试:tests/ut/op_host/test_scatter_list_tiling.cpp 与配套数据生成脚本(tests/ut/op_kernel/scatter_list_data/gen_data.py、gen_data_neg.py、compare_data.py)覆盖常规与负轴(neg)等切分场景的 tiling 正确性;tests/ut/op_kernel/test_scatter_list.cpp 则直接面向 Kernel 层验证。

这些测试一方面验证了文档所述"indice 起始位置 + 连续区间写入"的语义,另一方面也覆盖了 Tiling 多分支(含负数 axis 归一化、非对齐场景)的实际行为,是理解算子边界条件的最佳参考。

十、小结

ScatterList 算子是 CANN ops-nn 中面向"张量列表 + 连续区间写入"稀疏更新场景的标准实现:aclnnScatterList 两段式接口负责 workspace 估算与异步执行,Host 侧 Tiling 完成 axis 归一化、shape 校验与多分支切分,Device 侧 Kernel 通过 tiling key 分派到转置/常规/RegBase 等不同实现。使用时的核心要点可归纳为三条:indice 表达的是连续区间写入的起始位置(2 维时还携带长度);axis 归一化后必须位于 (0, updates维度数) 开区间;maskOptional 与 indice 取值的合法性与越界防护由调用方保证。掌握这些约束并参照示例代码,即可在支持的 Atlas 与 Kirin 平台上正确、高效地使用该算子。

登录后查看全文
ops-nn