CANN ops-nn 算子开发指南:aclnnIndexFillTensor 与 aclnnInplaceIndexFillTensor 两段式接口使用与实现解析

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

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);),可见两者底层共享同一套计算流程。

两段式接口调用机制

每个算子分为两段式接口:

  1. 第一段(GetWorkspaceSize 接口):必须先调用 aclnnIndexFillTensorGetWorkspaceSize 或 aclnnInplaceIndexFillTensorGetWorkspaceSize,完成入参校验、算子流程编排,并获取计算所需 workspace 大小以及包含了算子计算流程的执行器 executor;
  2. 第二段(执行接口):再调用 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 的执行流程如下:

  1. 入参校验:依次执行空指针检查、dtype 检查、shape/dim/index 检查、value 类型检查,任一失败立即返回对应错误码;
  2. 格式检查:CheckFormat 会对 FORMAT_FRACTAL_NZ 格式输出告警日志(不阻断执行);
  3. 边界场景短路:当 index->Size() == 0 时,直接执行 ViewCopy(self, out),等效于整体拷贝,无需进入 kernel;当 self 为空 tensor 时,workspaceSize 置 0 直接返回;
  4. 负索引归一化:将负 dim 与负 index 元素统一转换为非负值;
  5. 构造辅助张量:调用 GenerateAssistMatrix 生成 assist1(掩码矩阵,命中位置为 0、其余为 1,用于保留原值)与 assist2(填充矩阵,命中位置为 fillVal、其余为 0)两个与 self 同 shape 的辅助张量,通过 Cast、Reshape 等 l0 算子适配到目标 dtype 与形状;
  6. 下发 l0 算子:调用 l0op::IndexFillD(selfContiguous, assist1, assist2, dim) 完成核心计算,再用 ViewCopy 将结果写入(可能非连续的)out;
  7. 返回资源规划结果: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 训练/推理系列产品上的确定性执行。

登录后查看全文
ops-nn