CANN ops-nn aclnnRepeatInterleaveTensor 算子接口详解:两段式调用、参数约束与 NPU 调用示例

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

CANN ops-nn aclnnRepeatInterleaveTensor 算子接口详解:两段式调用、参数约束与 NPU 调用示例

aclnnRepeatInterleaveTensor 是 CANN ops-nn 仓库中 RepeatInterleave 系列算子库(index/repeat_interleave)提供的单算子 API,用于在 NPU 上按照 repeats Tensor 中每个元素的值,将对应的下标 i 重复 repeatsi] 次,实现 torch.repeat_interleave(repeats) 的语义。本文以 [aclnnRepeatInterleaveTensor.md 为骨架,结合 op_api、op_host、op_kernel 与测试用例,系统讲解该接口的功能语义、两段式调用流程、参数与返回码约束,并给出可直接编译运行的完整 C++ 调用示例。

一、算子功能与语义

1.1 接口功能

针对 repeats 的第 i 个元素,将下标 i 重复 repeats[i] 次,最终生成一个 1D 输出 tensor。该接口没有输入 x,其“被重复的数据”隐式定义为下标序列 0, 1, ..., len(repeats)-1,因此它等价于 PyTorch 中的 torch.repeat_interleave(repeats) 不带输入张量的用法。

1.2 语义示例

假设 repeats = [1, 3],则:

  • repeats[0] = 1,表示将下标 0 重复 1 次;
  • repeats[1] = 3,表示将下标 1 重复 3 次;

最终输出为 tensor([0, 1, 1, 1])。输出元素个数(即 outputSize)恰好等于 repeats 中所有元素之和。

从源码实现看,aclnn_repeat_interleave.cpp 中 aclnnRepeatInterleaveTensorGetWorkspaceSize 的核心流程正是先通过 l0op::Arange 构造出下标序列 self = [0, 1, ..., repeatsSize-1](AllocScalar(0) 为 start、AllocScalar(repeatsSize) 为 end、AllocScalar(1) 为 step),再调用 l0op::RepeatInterleave(self, repeatsContiguous, 0, outputSize, ...) 完成重复拼接,最后经 ViewCopy 写入 out。

二、两段式接口调用模型

每个 aclnn 算子均采用两段式接口设计,aclnnRepeatInterleaveTensor 也不例外(详见 两段式接口说明):

  • 第一段 aclnnRepeatInterleaveTensorGetWorkspaceSize:完成入参校验,计算本次计算所需的 workspace 大小,并返回包含算子计算流程的 aclOpExecutor 执行器;
  • 第二段 aclnnRepeatInterleaveTensor:真正在 Device 上执行计算,需要传入第一段申请到的 workspace、workspaceSize、executor 以及任务执行的 stream。

注意:第二段接口不能重复调用。即 GetWorkspaceSize → 执行 → 再执行 的调用方式属于非法使用。

调用流程可概括为:初始化 acl 环境与 stream → 构造输入/输出 aclTensor → 调第一段接口获取 workspaceSize 与 executor → 按 workspaceSize 申请 Device 内存 → 调第二段接口执行 → 同步 stream → 拷贝结果回 Host → 释放资源。

2.1 第一段接口原型

aclnnStatus aclnnRepeatInterleaveTensorGetWorkspaceSize(
  const aclTensor* repeats,
  int64_t          outputSize,
  aclTensor*       out,
  uint64_t*        workspaceSize,
  aclOpExecutor**  executor)

2.2 第二段接口原型

aclnnStatus aclnnRepeatInterleaveTensor(
  void*          workspace,
  uint64_t       workspaceSize,
  aclOpExecutor* executor,
  aclrtStream    stream)

三、参数说明

3.1 第一段接口参数表

参数名 输入/输出 描述 使用说明 数据类型 数据格式 维度(shape) 非连续Tensor
repeats(aclTensor*) 输入 重复的次数 支持空Tensor(包括shape=[0,]的场景) INT32、INT64 ND 1 √
outputSize(int64_t) 输入 进行重复后的tensor最终大小 outputSize必须等于repeats的值之和 - - - -
out(aclTensor*) 输出 功能说明中数据复制完成的输出tensor 数据类型需要与repeats一致;shape维度与repeats一致,元素个数等于repeats的值之和 INT32、INT64 ND 1 √
workspaceSize(uint64_t*) 输出 返回需要在Device侧申请的workspace大小 - - - - -
executor(aclOpExecutor**) 输出 返回op执行器,包含了算子计算流程 - - - - -

参数细节解读(与源码对应):

  • repeats:作为整个算子的唯一“输入”,其元素即各下标对应的重复次数。类型仅支持 INT32、INT64 两种,对应源码中 aclnn_repeat_interleave.cpp 的 DTYPE_SUPPORT_LIST_REPEATS_TENSOR = {DT_INT64, DT_INT32};源码中还实现了 INT32 → INT64 的自动 Cast(CastIfNeeded(repeatsContiguous, needCastInt32, DT_INT64, ...)),因此 INT32 输入在内部会先转为 INT64 统一计算,最终再转回 INT32 输出。
  • outputSize:必须是 repeats 中所有元素之和。源码在构造下标序列后直接以 outputSize 作为 l0op::RepeatInterleave 的输出长度参数,并在结束后通过 CheckRepeatresOutShape(repeatInterleaveOut, out) 校验计算结果的 shape 与 out 一致,不一致时报 ACLNN_ERR_PARAM_INVALID。
  • out:输出 tensor,dtype 必须与 repeats 一致,1D,元素个数等于 repeats 之和。源码通过 OP_CHECK_DTYPE_NOT_MATCH(out, repeats->GetDataType(), ...) 强制 dtype 一致。
  • workspaceSize / executor:由框架内部 CREATE_EXECUTOR() 创建执行器并返回,workspace 由第一段接口在构图过程中累加得出(uniqueExecutor->GetWorkspaceSize()),第二段执行时由用户负责申请并传入。

3.2 第二段接口参数表

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

四、返回值与错误码

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

返回值 错误码 描述
ACLNN_ERR_PARAM_NULLPTR 161001 repeats或out是空指针
ACLNN_ERR_PARAM_INVALID 161002 repeats的数据类型不在支持范围内
ACLNN_ERR_PARAM_INVALID 161002 repeats、out的数据类型不一样
ACLNN_ERR_PARAM_INVALID 161002 repeats不为1D tensor或空tensor
ACLNN_ERR_PARAM_INVALID 161002 repeatInterleave计算的结果与out的shape不一致

与源码的对应关系(aclnn_repeat_interleave.cpp 的 CheckParamsTensor):

  • OP_CHECK_NULL(repeats/out) 对应 161001 空指针错误;
  • OP_CHECK_DTYPE_NOT_SUPPORT(repeats, DTYPE_SUPPORT_LIST_REPEATS_TENSOR) 与 OP_CHECK_DTYPE_NOT_MATCH(out, repeats->GetDataType()) 对应数据类型类 161002;
  • 显式判断 repeats->IsEmpty() || 1D,不满足时报 "repeats must be an empty tensor / 1D tensor.",对应 shape 类 161002;
  • CheckRepeatresOutShape 的 OP_CHECK_SHAPE_NOT_EQUAL 对应结果 shape 与 out 不一致的 161002。

五、约束说明

  • 确定性计算:aclnnRepeatInterleaveTensor 默认确定性实现,即相同输入在多次运行下结果可复现(确定性语义参见 determinism_compute)。
  • 输入 shape 限制:repeats 只能为 1D tensor(包括 shape=[0,] 的空 tensor 场景)。
  • 输入值域限制:repeats tensor 中的值必须为自然数(0、1、2、…)。
  • 其他限制:
    • outputSize 的值必须等于 repeats 的值之和;
    • outputSize 的值不能超过 2^22(4,194,304)。

六、完整调用示例

以下示例来自文档并已与仓库 examples 目录中的 test_aclnn_repeat_interleave_tensor.cpp 核对一致,可直接作为编写 NPU 推理代码的模板。示例构造 repeats = [1, 2, 3],outputSize = 6,期望输出为 [0, 1, 1, 2, 2, 2]。

#include <iostream>
#include <vector>
#include "acl/acl.h"
#include "aclnnop/aclnn_repeat_interleave.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> repeatsShape = {3};
  std::vector<int64_t> outShape = {6};
  void* repeatsDeviceAddr = nullptr;
  void* outDeviceAddr = nullptr;
  aclTensor* repeats = nullptr;
  int64_t output_size = 6;
  aclTensor* out = nullptr;
  std::vector<int64_t> repeatsHostData = {1, 2, 3};
  std::vector<int64_t> outHostData = {0, 0, 0, 0, 0, 0};

  // 创建repeats aclTensor
  ret = CreateAclTensor(repeatsHostData, repeatsShape, &repeatsDeviceAddr, aclDataType::ACL_INT64, &repeats);
  CHECK_RET(ret == ACL_SUCCESS, return ret);
  // 创建out aclTensor
  ret = CreateAclTensor(outHostData, outShape, &outDeviceAddr, aclDataType::ACL_INT64, &out);
  CHECK_RET(ret == ACL_SUCCESS, return ret);

  // 3. 调用CANN算子库API
  uint64_t workspaceSize = 0;
  aclOpExecutor* executor;
  // 调用aclnnRepeatInterleaveTensor第一段接口
  ret = aclnnRepeatInterleaveTensorGetWorkspaceSize(repeats, output_size, out, &workspaceSize, &executor);
  CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclnnRepeatInterleaveTensorGetWorkspaceSize 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);
  }
  // 调用aclnnRepeatInterleaveTensor第二段接口
  ret = aclnnRepeatInterleaveTensor(workspaceAddr, workspaceSize, executor, stream);
  CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclnnRepeatInterleaveTensor 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侧
  auto size = GetShapeSize(outShape);
  std::vector<int64_t> 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: %ld\n", i, resultData[i]);
  }

  // 6. 释放aclTensor
  aclDestroyTensor(repeats);
  aclDestroyTensor(out);

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

代码要点:

  1. 头文件:需要包含 acl/acl.h 与算子接口头文件 aclnnop/aclnn_repeat_interleave.h。
  2. Tensor 构造:aclCreateTensor 需要显式传入 shape、strides、format(本算子为 ACL_FORMAT_ND)等元信息;连续 tensor 的 strides 可按示例逐维计算。
  3. 两段式调用:务必先调用 ...GetWorkspaceSize,再按返回的 workspaceSize 用 aclrtMalloc(ACL_MEM_MALLOC_HUGE_FIRST 策略)申请 workspace,最后才调用第二段接口;workspaceSize 为 0 时无需申请内存。
  4. 结果回拷与释放:执行完成后需 aclrtSynchronizeStream 同步,再通过 aclrtMemcpy 把 Device 结果拷回 Host 打印,最后对称释放 aclTensor、Device 内存与 stream。

完整可编译源码可直接参考 examples/test_aclnn_repeat_interleave_tensor.cpp;编译与运行的环境搭建、构建流程请参考 编译与运行样例。

七、源码级实现原理

7.1 API 层:组合式算子实现

aclnn_repeat_interleave.cpp 中 aclnnRepeatInterleaveTensorGetWorkspaceSize 的实现逻辑如下(L704-L757):

  1. 空 tensor 早退:当 repeats->IsEmpty() 或 out->IsEmpty() 时,workspaceSize 直接置 0 并返回成功;
  2. 构造下标序列:以 repeats 的元素个数为长度,通过 l0op::Arange(0, repeatsSize, 1) 生成 self;
  3. 输入预处理:InitializeTensor 保证 repeats 为连续 tensor;INT32 输入自动 Cast 为 INT64;
  4. 核心计算:l0op::RepeatInterleave(selfContiguous, repeatsContiguous, 0, outputSize, ...),axis 固定为 0;
  5. 结果校验与回写:CheckRepeatresOutShape 校验 shape 一致,再按需 Cast 回 INT32,最后 ViewCopy 写回 out;
  6. 计算 workspaceSize 并释放执行器句柄。

第二段接口 aclnnRepeatInterleaveTensor 则直接调用 CommonOpExecutorRun(workspace, workspaceSize, executor, stream) 完成执行。

7.2 算子定义与 shape 推导

  • 算子定义见 repeat_interleave_def.cpp:输入 x 支持 BF16/FP16/FP32/UINT8/INT8/UINT16/INT16/UINT32/INT32/UINT64/INT64/BOOL 等全量整型与浮点类型,repeats 限定 INT32/INT64,输出 y 与 x 同类型,格式均为 ND;该定义在 ascend950 与 ascend350 两个 AICore 配置上注册,并开启动态 shape/动态 rank/动态 format 支持。
  • shape 推导见 repeat_interleave_infershape.cpp:当 repeats 是常量 tensor 时,若 repeats 长度为 1,则输出轴长度 = x 轴长度 × repeats 值;否则输出轴长度 = repeats 各元素之和(GetOutputAxisLen 中的 repeatsSum 逻辑,与本文接口的 outputSize 约束完全一致);当 repeats 非编译期常量时,输出 shape 置为未知(-2),由运行时动态推导。

7.3 多核切分与 kernel 计算

在 ascend950/ascend350 上,NPU kernel 侧(op_kernel/arch35/repeat_interleave.h)以 RepeatInterleaveImpl 为核心,通过 tiling 阶段(repeat_interleave_tiling_base.cpp)把输入按“repeat 轴 × cp 轴”做维度合并与多核切分:

  • tiling 将输入 shape 合并为 [n, repeatsLen, cp] 三个逻辑维(MergDimForTensor),其中 n 为 axis 前的维度乘积、cp 为 axis 后的维度乘积;
  • 每个核根据 GetBlockIdx() 计算起始偏移(ComputeStartOffset),分别按整 cp 切分(ProcessWholeCp)或按 cp 分片切分(ProcessSplitCp)两种策略执行;
  • 数据搬入使用双缓冲队列(DOUBLE_BUFFER)隐藏访存延迟;当单条 cp 数据超过 128 字节阈值时再对 cp 轴二次分 loop(MIN_CP_THRESHOLD = 128);
  • 每个元素按 repeats 值进行多次拷贝写入(CopyOneCpToRepeatOutVf 的循环 repeatTimes 次 StoreUnAlign),正是“下标 i 重复 repeats[i] 次”这一语义在硬件侧的落地实现;
  • workspace 大小由 tiling 统一申请,GetWorkspaceSize 返回 16MB 系统 workspace 加上每个核 128 字节缓存行对齐的额外空间。

7.4 测试与 golden 对齐

仓库测试用例(tests/st/aclnnRepeatInterleaveTensor)将本接口与 PyTorch 原生 torch.repeat_interleave 对齐验证:

  • executor_aclnnRepeatInterleaveTensor.py 中 __call__ 直接执行 torch.repeat_interleave(input_data.kwargs["repeats"]) 作为参考输出,init_by_input_data 用参考输出的 shape[0] 自动计算并回填 outputSize,这与接口“outputSize 必须等于 repeats 之和”的约束天然一致;
  • atk_aclnnRepeatInterleaveTensor.json 覆盖 INT32/INT64 两种 dtype、shape 从 [1] 到 [11298] 的多种规模,并包含 outputSize = 0、repeats 单元素、超大 repeats 长度等边界场景(is_boundary: true),精度对比采用 md5 一致性校验。

八、产品支持情况

产品形态 支持情况
Ascend 950PR / Ascend 950DT 支持
Atlas A3 训练系列产品 / Atlas A3 推理系列产品 支持
Atlas A2 训练系列产品 / Atlas A2 推理系列产品 支持
Atlas 200I/500 A2 推理产品 不支持
Atlas 推理系列产品 不支持
Atlas 训练系列产品 不支持

从算子注册配置(repeat_interleave_def.cpp)与 op_host 配置目录(op_host/config)可以看出,当前 AscendC 实现主要面向 ascend950 与 ascend350(Atlas A2/A3 系列)架构,因此老款 Atlas 训练/推理产品不支持该算子,实际可用性请以所部署的 NPU 型号为准。

九、与同系列接口的区分

本接口属于 RepeatInterleave 算子族中的一个变体,同一目录下还提供以下接口(均见 index/repeat_interleave/docs):

  • aclnnRepeatInterleave:无 dim,tensor repeats,输入 x 为任意受支持 dtype 的 tensor,输出与 x 同类型;
  • aclnnRepeatInterleaveInt:无 dim,repeats 为 int64 标量;
  • aclnnRepeatInterleaveWithDim:有 dim,tensor repeats;
  • aclnnRepeatInterleaveIntWithDim:有 dim,repeats 为 int64 标量。

而 aclnnRepeatInterleaveTensor 是唯一一个没有输入 x、输出即下标序列重复展开结果的变体,其输出 dtype 固定为 INT32/INT64 且必须与 repeats 一致,对应 PyTorch 中 torch.repeat_interleave(repeats)(单参数)的用法。若需要沿指定轴重复任意输入张量,应使用 aclnnRepeatInterleaveWithDim / aclnnRepeatInterleaveIntWithDim 等接口。

登录后查看全文
ops-nn