CANN ops-nn 算子开发指南:aclnnIndexFillTensor 与 aclnnInplaceIndexFillTensor 两段式接口使用与实现解析
CANN ops-nn 算子开发指南:aclnnIndexFillTensor 与 aclnnInplaceIndexFillTensor 两段式接口使用与实现解析
本指南围绕 CANN ops-nn 开源仓库中 IndexFillD 算子对应的两个上层接口——aclnnIndexFillTensor(非原地)与 aclnnInplaceIndexFillTensor(原地)展开,系统讲解其功能语义、参数约束、错误码、两段式调用流程与完整可运行示例,并结合仓库源码(host 侧 API、算子定义、inferShape、tiling、kernel 与 UT 测试)剖析其底层实现机制,帮助开发者快速上手在 Atlas A2 训练/推理系列产品上完成「沿指定轴按索引填充张量」的计算任务。
产品支持情况
| 产品 | 是否支持 |
|---|---|
| Atlas A2 训练系列产品 / Atlas A2 推理系列产品 | √ |
从算子定义文件 index_fill_d_def.cpp 的 AICore().AddConfig("ascend910b") 也可以印证:该算子的 AI Core 配置面向 910B 系列昇腾芯片(即 Atlas A2 训练/推理系列产品),其他 SoC 版本暂未在仓库中补充配置项。
功能说明
接口功能:沿输入 self 的给定轴 dim,将 index 指定位置的值使用 value 进行替换。该功能等价于 PyTorch 的 Tensor.index_fill 语义,是 NLP/推荐场景中掩码填充、索引定点改写等操作的常用基础算子。
计算示例
输入 self 为:
[[1, 2, 3],
[4, 5, 6],
[7, 8, 9]]
- 若
dim = 0,index = [0, 2],value = 0,计算结果为:
[[0, 0, 0],
[4, 5, 6],
[0, 0, 0]]
即在第 0 维(行方向)上,将第 0 行与第 2 行的所有元素替换为 0。
- 若
dim = 1,index = [0, 2],value = 0,计算结果为:
[[0, 2, 0],
[0, 5, 0],
[0, 8, 0]]
即在第 1 维(列方向)上,将每行的第 0 列与第 2 列元素替换为 0。
两个接口的差异
aclnnIndexFillTensor 与 aclnnInplaceIndexFillTensor 实现相同的计算功能,区别仅在于结果的存放方式,请根据自身实际场景选择:
- aclnnIndexFillTensor:需新建一个输出张量对象
out存储计算结果,输入self在计算后保持不变; - aclnnInplaceIndexFillTensor:无需新建输出张量对象,直接在输入张量的内存中存储计算结果,适合需要就地改写、节省显存的场景。
从实现上看,仓库 aclnn_index_fill_tensor.cpp 中的原地版本接口 aclnnInplaceIndexFillTensorGetWorkspaceSize 直接复用了非原地版本的实现逻辑,仅将 out 替换为 selfRef 本身(return aclnnIndexFillTensorGetWorkspaceSize(selfRef, dim, index, value, selfRef, workspaceSize, executor);),可见两者底层共享同一套计算流程。
两段式接口调用机制
每个算子分为两段式接口:
- 第一段(GetWorkspaceSize 接口):必须先调用
aclnnIndexFillTensorGetWorkspaceSize或aclnnInplaceIndexFillTensorGetWorkspaceSize,完成入参校验、算子流程编排,并获取计算所需 workspace 大小以及包含了算子计算流程的执行器executor; - 第二段(执行接口):再调用
aclnnIndexFillTensor或aclnnInplaceIndexFillTensor,传入第一段返回的 workspace 与 executor,在指定 stream 上真正执行计算。
这种设计将「参数校验与资源规划」和「异步执行」解耦:第一段在 Host 侧完成所有合法性检查与内存规划(返回错误码),第二段将任务下发到 Device 侧流式执行,避免把昂贵的校验逻辑放在执行路径上。
函数原型
aclnnStatus aclnnIndexFillTensorGetWorkspaceSize(
const aclTensor* self,
int64_t dim,
const aclIntArray* index,
const aclScalar* value,
aclTensor* out,
uint64_t* workspaceSize,
aclOpExecutor** executor)
aclnnStatus aclnnIndexFillTensor(
void* workspace,
uint64_t workspaceSize,
aclOpExecutor* executor,
aclrtStream stream)
aclnnStatus aclnnInplaceIndexFillTensorGetWorkspaceSize(
aclTensor* selfRef,
int64_t dim,
const aclIntArray* index,
const aclScalar* value,
uint64_t* workspaceSize,
aclOpExecutor** executor)
aclnnStatus aclnnInplaceIndexFillTensor(
void* workspace,
uint64_t workspaceSize,
aclOpExecutor* executor,
aclrtStream stream)
其中 aclTensor、aclIntArray、aclScalar、aclOpExecutor、aclrtStream 等数据结构的定义与构造方式可参见 数据结构说明。接口声明位于仓库头文件 aclnn_index_fill_tensor.h,对应的头文件 aclnnop/aclnn_index_fill_tensor.h 由 CANN 工具链生成后随算子库发布。
参数说明
aclnnIndexFillTensorGetWorkspaceSize 参数
| 参数名 | 输入/输出 | 描述 | 使用说明 | 数据类型 | 数据格式 | 维度(shape) | 非连续 Tensor |
|---|---|---|---|---|---|---|---|
| self | 输入 | 功能示例中的 self,即待被在指定位置的值用 value 替换的张量 | - | FLOAT16、FLOAT、INT32、INT64、BOOL、BFLOAT16 | ND | 0-8 | √ |
| dim | 输入 | 指定了 self 将要填充的维度 | 当 self 为 1-8 维时,dim 的取值范围在 [-self.dim(), self.dim()),当 self 为 0 维时,dim 的取值范围在 [-1, 1) | int64 | - | - | - |
| index | 输入 | 指定 self 在 dim 维度将要填充的下标 | 其中的元素值小于 self 对应 dim 的维度大小 | - | - | - | - |
| value | 输入 | 指定填充的数据值 | 需要可转化为 self 的数据类型 | 与 self 一致 | - | - | - |
| out | 输出 | 指定的输出张量 | - | 与 self 一致 | ND | 与 self 一致 | √ |
| workspaceSize | 输出 | 返回需要在 Device 侧申请的 workspace 大小 | - | - | - | - | - |
| executor | 输出 | 返回 op 执行器,包含了算子计算流程 | - | - | - | - | - |
关于非连续 Tensor 的语义与支持方式,可参考 非连续 Tensor 说明:接口层会通过 l0op::Contiguous 与 l0op::ViewCopy 在内部统一处理非连续输入输出。
aclnnInplaceIndexFillTensorGetWorkspaceSize 参数
| 参数名 | 输入/输出 | 描述 | 使用说明 | 数据类型 | 数据格式 | 维度(shape) | 非连续 Tensor |
|---|---|---|---|---|---|---|---|
| selfRef | 输入 | 待被在指定位置的值用 value 替换的张量 | - | FLOAT16、FLOAT、INT32、INT64、BOOL、BFLOAT16 | ND | 0-8 | √ |
| dim | 输入 | 指定了 selfRef 将要填充的维度 | 当 self 为 1-8 维时,dim 的取值范围在 [-self.dim(), self.dim()),当 self 为 0 维时,dim 的取值范围在 [-1, 1) | int64 | - | - | - |
| index | 输入 | 指定 self 在 dim 维度将要填充的下标 | 其中的元素值小于 selfRef 对应的 dim 的维度大小 | - | - | - | - |
| value | 输入 | 指定填充的数据值 | - | 与 selfRef 一致 | - | - | - |
| workspaceSize | 输出 | 返回需要在 Device 侧申请的 workspace 大小 | - | - | - | - | - |
| executor | 输出 | 返回 op 执行器,包含了算子计算流程 | - | - | - | - | - |
执行接口参数(两个算子一致)
| 参数名 | 输入/输出 | 描述 |
|---|---|---|
| workspace | 输入 | 在 Device 侧申请的 workspace 内存地址 |
| workspaceSize | 输入 | 在 Device 侧申请的 workspace 大小,由第一段接口(aclnnIndexFillTensorGetWorkspaceSize / aclnnInplaceIndexFillTensorGetWorkspaceSize)获取 |
| executor | 输入 | op 执行器,包含了算子计算流程 |
| stream | 输入 | 指定执行任务的 Stream |
参数细节补充说明
- dim 的负值语义:
dim支持负索引。从 aclnn_index_fill_tensor.cpp 源码可见,第一段接口会对dim < 0做dim = dim + selfDim的正向转换;index中的负值也会被转换为index[i] + selfShape[dim]后参与计算,与 PyTorch 的负索引行为保持一致。 - index 的元素范围:
index中的每个元素值必须小于self在dim维的维度大小,且不小于该维度大小的相反数(即支持[-dimSize, dimSize)),越界会在第一段接口直接报ACLNN_ERR_PARAM_INVALID。 - value 的类型:
value需要可以转化为self的数据类型;接口内部会拒绝复数类型的value(源码中的CheckPromoteType检查),并在进入 kernel 前通过l0op::Cast完成类型转换。
返回值与错误码
两个接口均返回 aclnnStatus 状态码,具体参见 aclnn 返回码说明。
第一段接口(GetWorkspaceSize)完成入参校验,出现以下场景时报错:
aclnnIndexFillTensorGetWorkspaceSize:
| 返回值 | 错误码 | 描述 |
|---|---|---|
| ACLNN_ERR_PARAM_NULLPTR | 161001 | 传入的 self、index、value 或 out 是空指针 |
| ACLNN_ERR_PARAM_INVALID | 161002 | self、index、value 的数据类型不在支持的范围之内 |
| ACLNN_ERR_PARAM_INVALID | 161002 | dim 的绝对值超出 self 的 dim 最大值或超出 8 维 |
| ACLNN_ERR_PARAM_INVALID | 161002 | index 中的值超过 self 指定 dim 的最大值 |
| ACLNN_ERR_PARAM_INVALID | 161002 | self 与 out 的 shape 不相等 |
| ACLNN_ERR_PARAM_INVALID | 161002 | self 与 out 的数据类型不相等 |
aclnnInplaceIndexFillTensorGetWorkspaceSize:
| 返回值 | 错误码 | 描述 |
|---|---|---|
| ACLNN_ERR_PARAM_NULLPTR | 161001 | 传入的 selfRef、index、value 是空指针 |
| ACLNN_ERR_PARAM_INVALID | 161002 | selfRef、index、value 的数据类型不在支持的范围之内 |
| ACLNN_ERR_PARAM_INVALID | 161002 | dim 的绝对值超出 selfRef 的 dim 最大值或超出 8 维 |
| ACLNN_ERR_PARAM_INVALID | 161002 | index 中的值超过 selfRef 指定 dim 的最大值 |
源码中 CheckParams 依次完成四类校验:① 空指针检查(CheckNotNull,返回 ACLNN_ERR_PARAM_NULLPTR);② 数据类型检查(CheckDtypeValid,校验 dtype 在支持列表内且 self/out 一致);③ shape 检查(CheckShape,含最大 8 维限制、dim 范围、index 元素范围、self 与 out shape 一致性);④ value 类型检查(CheckPromoteType)。UT 用例 test_aclnn_index_fill_tensor.cpp 中 test_index_fill_exceed_negative_index(index 越界)与 test_index_fill_max_dim_overflow_out(超过 8 维)均验证返回 ACLNN_ERR_PARAM_INVALID。
约束说明
- 确定性计算:
aclnnIndexFillTensor与aclnnInplaceIndexFillTensor默认采用确定性实现,即相同输入、相同环境下多次执行结果一致,不受多核调度顺序影响。确定性计算的机制说明可参考 确定性计算说明。
调用示例
示例代码如下,仅供参考,具体编译和执行过程请参考编译与运行样例。
aclnnIndexFillTensor 调用示例
#include <iostream>
#include <vector>
#include "acl/acl.h"
#include "aclnnop/aclnn_index_fill_tensor.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对外接口列表
// 根据自己的实际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> selfShape = {3, 3};
std::vector<int64_t> outShape = selfShape;
void* selfDeviceAddr = nullptr;
void* outDeviceAddr = nullptr;
aclTensor* self = nullptr;
aclScalar* value = nullptr;
aclIntArray* index = nullptr;
aclTensor* out = nullptr;
std::vector<float> selfHostData = {0, 1, 2, 3, 4, 5, 6, 7, 8};
std::vector<float> outHostData = {0, 0, 0, 0, 0, 0, 0, 0, 0};
int64_t dim = 1;
float fillVal = 10;
int64_t indexVal = 0;
// 创建self aclTensor
ret = CreateAclTensor(selfHostData, selfShape, &selfDeviceAddr, aclDataType::ACL_FLOAT, &self);
CHECK_RET(ret == ACL_SUCCESS, return ret);
// 创建out aclTensor
ret = CreateAclTensor(outHostData, outShape, &outDeviceAddr, aclDataType::ACL_FLOAT, &out);
CHECK_RET(ret == ACL_SUCCESS, return ret);
// 创建value aclScalar
value = aclCreateScalar(&fillVal, aclDataType::ACL_FLOAT);
CHECK_RET(value != nullptr, return ret);
// 创建index aclIntArray
index = aclCreateIntArray(&indexVal, 1);
CHECK_RET(index != nullptr, return ret);
// 3. 调用CANN算子库API,需要修改为具体的API名称
uint64_t workspaceSize = 0;
aclOpExecutor* executor;
// 调用aclnnIndexFillTensor第一段接口
ret = aclnnIndexFillTensorGetWorkspaceSize(self, dim, index, value, out, &workspaceSize, &executor);
CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclnnIndexFillTensorGetWorkspaceSize 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);
}
// 调用aclnnIndexFillTensor第二段接口
ret = aclnnIndexFillTensor(workspaceAddr, workspaceSize, executor, stream);
CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclnnIndexFillTensor 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(outShape);
std::vector<float> resultData(size, 0);
ret = aclrtMemcpy(resultData.data(), resultData.size() * sizeof(resultData[0]), outDeviceAddr,
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. 释放申请的变量,需要根据具体API的接口定义修改
aclDestroyTensor(self);
aclDestroyTensor(out);
aclDestroyScalar(value);
aclDestroyIntArray(index);
// 7. 释放device资源,需要根据具体API的接口定义修改
aclrtFree(selfDeviceAddr);
aclrtFree(outDeviceAddr);
if (workspaceSize > 0) {
aclrtFree(workspaceAddr);
}
aclrtDestroyStream(stream);
aclrtResetDevice(deviceId);
aclFinalize();
return 0;
}
aclnnInplaceIndexFillTensor 调用示例
#include <iostream>
#include <vector>
#include "acl/acl.h"
#include "aclnnop/aclnn_index_fill_tensor.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> selfShape = {3, 3};
void* selfDeviceAddr = nullptr;
aclTensor* self = nullptr;
aclScalar* value = nullptr;
aclIntArray* index = nullptr;
std::vector<float> selfHostData = {0, 1, 2, 3, 4, 5, 6, 7, 8};
int64_t dim = 1;
float fillVal = 10;
int64_t indexVal = 0;
// 创建self aclTensor
ret = CreateAclTensor(selfHostData, selfShape, &selfDeviceAddr, aclDataType::ACL_FLOAT, &self);
CHECK_RET(ret == ACL_SUCCESS, return ret);
// 创建value aclScalar
value = aclCreateScalar(&fillVal, aclDataType::ACL_FLOAT);
CHECK_RET(value != nullptr, return ret);
// 创建index aclIntArray
index = aclCreateIntArray(&indexVal, 1);
CHECK_RET(index != nullptr, return ret);
// 3. 调用CANN算子库API,需要修改为具体的API名称
uint64_t workspaceSize = 0;
aclOpExecutor* executor;
// 调用aclnnInplaceIndexFillTensor第一段接口
ret = aclnnInplaceIndexFillTensorGetWorkspaceSize(self, dim, index, value, &workspaceSize, &executor);
CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclnnInplaceIndexFillTensorGetWorkspaceSize 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);
}
// 调用aclnnInplaceIndexFillTensor第二段接口
ret = aclnnInplaceIndexFillTensor(workspaceAddr, workspaceSize, executor, stream);
CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclnnInplaceIndexFillTensor 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(selfShape);
std::vector<float> resultData(size, 0);
ret = aclrtMemcpy(resultData.data(), resultData.size() * sizeof(resultData[0]), selfDeviceAddr,
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. 释放申请的变量,需要根据具体API的接口定义修改
aclDestroyTensor(self);
aclDestroyScalar(value);
aclDestroyIntArray(index);
// 7. 释放device资源,需要根据具体API的接口定义修改
aclrtFree(selfDeviceAddr);
if (workspaceSize > 0) {
aclrtFree(workspaceAddr);
}
aclrtDestroyStream(stream);
aclrtResetDevice(deviceId);
aclFinalize();
return 0;
}
两个示例的差异点值得注意:非原地版本额外创建了 out 张量(outHostData 初始化为全 0),结果从 outDeviceAddr 拷回 Host;原地版本不创建 out,结果直接从 selfDeviceAddr 拷回 Host。仓库 examples 目录提供了 test_aclnn_index_fill_tensor.cpp、test_aclnn_inplace_index_fill_tensor.cpp、test_aclnn_index_fill.cpp、test_aclnn_inplace_index_fill.cpp 四个可直接参考的完整样例。
源码级实现解析
Host 侧接口流程
以 aclnn_index_fill_tensor.cpp 为入口,第一段接口 aclnnIndexFillTensorGetWorkspaceSize 的执行流程如下:
- 入参校验:依次执行空指针检查、dtype 检查、shape/dim/index 检查、value 类型检查,任一失败立即返回对应错误码;
- 格式检查:
CheckFormat会对FORMAT_FRACTAL_NZ格式输出告警日志(不阻断执行); - 边界场景短路:当
index->Size() == 0时,直接执行ViewCopy(self, out),等效于整体拷贝,无需进入 kernel;当self为空 tensor 时,workspaceSize 置 0 直接返回; - 负索引归一化:将负
dim与负index元素统一转换为非负值; - 构造辅助张量:调用
GenerateAssistMatrix生成assist1(掩码矩阵,命中位置为 0、其余为 1,用于保留原值)与assist2(填充矩阵,命中位置为fillVal、其余为 0)两个与self同 shape 的辅助张量,通过Cast、Reshape等 l0 算子适配到目标 dtype 与形状; - 下发 l0 算子:调用
l0op::IndexFillD(selfContiguous, assist1, assist2, dim)完成核心计算,再用ViewCopy将结果写入(可能非连续的)out; - 返回资源规划结果:
workspaceSize = uniqueExecutor->GetWorkspaceSize(),并将 executor 通过ReleaseTo转移给调用方。
第二段接口 aclnnIndexFillTensor 则非常简洁,仅调用 CommonOpExecutorRun(workspace, workspaceSize, executor, stream) 由框架完成 Device 侧执行。
该算子还提供了一条基于 l0op::IndexFill 的 AICore 路径(IndexFillAiCore),将 index 转为 tensor、value 转为与 self 同类型的 tensor 后直接调用 l0 的 IndexFill,可作为不同形态下的替代实现。
底层算子定义与 shape 推导
- 算子定义:index_fill_d_def.cpp 中
IndexFillD算子接收三个输入x、assist1、assist2,输出y,并携带一个dim的 Int 属性;dtype 支持 FLOAT16、FLOAT、BF16、INT32、BOOL,格式为 ND; - shape 推导:index_fill_d_infershape.cpp 中
InferShapeIndexFillD将输出 shape 直接置为输入x的 shape(*zShape = *xShape),与文档中「out 与 self shape 一致」的参数约束吻合。
Tiling 与 Kernel 实现
- Tiling:index_fill_d_tiling.cpp 首先通过平台信息获取 UB 大小与 AI Core 核数;然后根据输入 dtype 选择不同的 UB 数据量倍数(FLOAT 为 13、INT32 为 12、BF16 为 11、FP16 为 7、INT8/BOOL 为 6,注释为「输入1 + 输入2 + 输出」及可能的中间缓冲区),动态决定使用单流水(
TILING_KEY_NDB)还是双流水(TILING_KEY_DB),并按TILE_SPLIT_NUM = 1024的元素粒度计算参与计算的核数与每个核的数据块划分(bigCore/smallCore、bigTail/smallTail); - Kernel:index_fill_d.cpp 与 index_fill_d.h 中
KernelIndexFillD基于 AscendC 向量流水实现。以 float/half 为例,计算核心是CompareScalar(assist1 > 0)生成掩码,再用Select(yLocal, mask, xLocal, assist2Local)完成「命中位置取 assist2(填充值)、未命中位置取 xLocal(原值)」的选择;对 BF16 与 INT8 则先Cast到中间类型(float / half)计算后再Cast回来;BOOL 输入在 kernel 层以int8_t类型实例化处理。数据搬运使用MTE2→V→MTE3事件同步,DOUBLE_BUFFER_NUM = 2时通过双缓冲隐藏搬运延迟。
测试用例验证
仓库 UT 覆盖了接口的各种合法与非法场景:
- 数据类型:INT32、FLOAT16、FLOAT、BOOL、BF16 均返回
ACL_SUCCESS(见 test_aclnn_index_fill_tensor.cpp); - 类型提升:self 为 INT32 时 value 传 float、self 为 FLOAT/FLOAT16 时 value 传 int32 等混合类型场景均通过(
test_index_fill_int32_float16_cast_out等),印证了「value 需要可转化为 self 数据类型」的说明; - 多种 format:HWCN、NCDHW、NDHWC、NHWC、NCHW 格式均通过校验;
- 负索引:
dim = -1、index = [0, -1]正常通过,而index = [0, -5](超出维度大小)返回ACLNN_ERR_PARAM_INVALID; - 维度上限:10 维输入返回
ACLNN_ERR_PARAM_INVALID,验证 8 维限制。
配套的原地接口 UT 见 test_aclnn_inplace_index_fill_tensor.cpp,算子级 UT(含数据生成脚本 gen_data.py 与结果比对脚本 compare_data.py)位于 tests/ut/op_kernel 目录,可用于端到端验证算子计算结果。
小结
aclnnIndexFillTensor 与 aclnnInplaceIndexFillTensor 是 CANN ops-nn 中实现张量沿轴索引填充的标准两段式接口。使用时注意三点:一是必须遵循「先 GetWorkspaceSize 后执行」的两段式流程;二是根据是否需要保留原张量选择非原地或原地版本;三是入参需满足 dtype(FLOAT16/FLOAT/INT32/INT64/BOOL/BFLOAT16)、维度(0-8 维)、index 范围与 shape 一致性等约束,否则第一段接口会以 ACLNN_ERR_PARAM_INVALID(161002)或 ACLNN_ERR_PARAM_NULLPTR(161001)返回。底层实现通过 assist 掩码矩阵与向量 Select 运算完成填充语义,Tiling 阶段按 dtype 与 UB 容量动态选择流水方式,保证了在 Atlas A2 训练/推理系列产品上的确定性执行。