CANN ops-nn aclnnRepeatInterleaveTensor 算子接口详解:两段式调用、参数约束与 NPU 调用示例
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;
}
代码要点:
- 头文件:需要包含
acl/acl.h与算子接口头文件aclnnop/aclnn_repeat_interleave.h。 - Tensor 构造:
aclCreateTensor需要显式传入 shape、strides、format(本算子为 ACL_FORMAT_ND)等元信息;连续 tensor 的 strides 可按示例逐维计算。 - 两段式调用:务必先调用
...GetWorkspaceSize,再按返回的 workspaceSize 用aclrtMalloc(ACL_MEM_MALLOC_HUGE_FIRST策略)申请 workspace,最后才调用第二段接口;workspaceSize 为 0 时无需申请内存。 - 结果回拷与释放:执行完成后需
aclrtSynchronizeStream同步,再通过aclrtMemcpy把 Device 结果拷回 Host 打印,最后对称释放 aclTensor、Device 内存与 stream。
完整可编译源码可直接参考 examples/test_aclnn_repeat_interleave_tensor.cpp;编译与运行的环境搭建、构建流程请参考 编译与运行样例。
七、源码级实现原理
7.1 API 层:组合式算子实现
aclnn_repeat_interleave.cpp 中 aclnnRepeatInterleaveTensorGetWorkspaceSize 的实现逻辑如下(L704-L757):
- 空 tensor 早退:当
repeats->IsEmpty()或out->IsEmpty()时,workspaceSize 直接置 0 并返回成功; - 构造下标序列:以 repeats 的元素个数为长度,通过
l0op::Arange(0, repeatsSize, 1)生成 self; - 输入预处理:
InitializeTensor保证 repeats 为连续 tensor;INT32 输入自动 Cast 为 INT64; - 核心计算:
l0op::RepeatInterleave(selfContiguous, repeatsContiguous, 0, outputSize, ...),axis 固定为 0; - 结果校验与回写:
CheckRepeatresOutShape校验 shape 一致,再按需 Cast 回 INT32,最后ViewCopy写回 out; - 计算 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 等接口。