CANN ops-nn ScatterList 算子实战指南:aclnnScatterList 两段式接口原理、参数与调用示例
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 为写入长度,则:
其中省略号表示 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)逻辑,是整个算子的"形状决策中枢",其关键流程为:
- 平台信息获取(
GetPlatformData):读取 AIV Core 数量、UB 内存大小,并区分是否支持 move/pad 指令(supportMovePad,仅 910B 及 RegBase 系列 SoC 支持)、是否 Ascend910。 - 张量列表校验(
GetVarTensorNum):读取 var 列表实例个数(不允许为空列表),并逐一校验列表内所有 tensor shape 完全一致。 - 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等参数。 - indice / mask 校验(
GetIndiceData/GetMaskData):indice 仅支持 1 维或 2 维,第一维必须等于 B,2 维时第二维必须为 2;mask 为可空输入,非空时仅支持 1 维且第一维等于 B。 - reduce 校验(
GetOtherData):strcmp(reduce, "update") != 0直接返回失败,印证"当前仅支持 update"。 - 多分支切分策略(
GetOtherDataNeg1/GetOtherDataNeg2/GetDataNeg等):根据维数、对齐情况、UB 容量关系选择不同的 tiling key(如 TILINGKEY_TSMALL/TMORE/TLARGE、TILINGKEY_PSMALL/PMORE/PLARGE/PLE 及 RSBSE/RLBSE/RSBLE/RLBLE 系列),并计算每个核承担的 batch 数、循环次数、源/目的 stride 等。 - 输出 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 平台上正确、高效地使用该算子。