CANN ops-math 中 aclnnTopk 算子详解:两段式接口调用、参数约束与调度实现
CANN ops-math 中 aclnnTopk 算子详解:两段式接口调用、参数约束与调度实现
本指南以 CANN ops-math 开源仓库中 math/topk/docs/aclnnTopk.md 为核心,系统讲解 TopK 算子(返回输入 Tensor 在指定维度上的 k 个极值及对应索引)的 aclnn 两段式编程接口。读者将掌握 aclnnTopkGetWorkspaceSize / aclnnTopk 的完整参数语义、支持的数据类型与产品范围、错误码排查方法,以及该算子在仓库中 AiCore / AiCpu 双路径的调度与实现原理,可直接照抄示例代码完成一次可运行的 NPU 计算任务。
算子概述与产品支持情况
aclnnTopk 是 CANN ops-math 数学算子库中 TopK 算子的 Level0(aclnn)调用接口。算子功能为:返回输入 Tensor 在指定维度上的 k 个极值(最大值或最小值)及其索引,是排序、抽样、注意力 Top-k 掩码等场景的高频基础算子。仓库中除该接口外,还在 math/topk/docs/aclnnTopkV2.md 提供支持 sortPolicy 参数的进阶版本。
按照 math/topk/docs/aclnnTopk.md 的产品支持清单:
| 产品 | 支持情况 |
|---|---|
| Ascend 950PR / Ascend 950DT | 支持 |
| Atlas A3 训练系列产品 / Atlas A3 推理系列产品 | 支持 |
| Atlas A2 训练系列产品 / Atlas A2 推理系列产品 | 支持 |
| Atlas 200I/500 A2 推理产品 | 不支持 |
| Atlas 推理系列产品 | 支持 |
| Atlas 训练系列产品 | 支持 |
与 math/topk/README.md 中记录的算子级支持矩阵(上述全产品均支持)相比,aclnnTopk 这一 aclnn 接口在 Atlas 200I/500 A2 推理产品上暂不支持,使用前请先确认目标硬件型号。
功能与计算语义
aclnnTopk 沿用户指定的 dim 维度,从 self 中取出最大的或最小的 k 个元素:输出 valuesOut 保存极值本身,indicesOut 保存这些极值在原输入中的索引。以 self 形状为 {2, 4}、dim=1、k=2、largest=true 为例,每一行 4 个元素中取最大的 2 个,输出形状为 {2, 2}。
其形状推导逻辑在 math/topk/op_host/topk_infershape.cpp 中实现:输出形状等于输入形状,仅将 dim 对应维替换为 k;负 dim 会先按 dim + rank 归一化;k 必须满足 0 <= k <= dim 维的 size。该 InferShape 同时作用于 values 与 indices 两个输出(math/topk/op_host/topk_infershape.cpp)。
两段式接口与函数原型
每个 aclnn 算子都采用两段式接口(详见 docs/zh/context/two_phase_api.md):
- 第一段:调用
aclnnTopkGetWorkspaceSize完成入参校验,并返回计算所需的 workspace 大小及一个封装了算子计算流程的执行器executor; - 第二段:调用
aclnnTopk传入 workspace 与 executor 真正下发执行。
aclnnStatus aclnnTopkGetWorkspaceSize(
const aclTensor* self,
int64_t k,
int64_t dim,
bool largest,
bool sorted,
aclTensor* valuesOut,
aclTensor* indicesOut,
uint64_t* workspaceSize,
aclOpExecutor** executor)
aclnnStatus aclnnTopk(
void* workspace,
uint64_t workspaceSize,
aclOpExecutor* executor,
const aclrtStream stream)
两个接口均返回 aclnnStatus 状态码,取值含义参见 docs/zh/context/aclnn_return_code.md。
aclnnTopkGetWorkspaceSize 参数详解
第一段接口共 9 个参数,其中 self、k、dim、largest、sorted 为输入,valuesOut、indicesOut 为输出 Tensor,workspaceSize、executor 为返回结果:
| 参数名 | 输入/输出 | 描述 | 使用说明 | 数据类型 | 数据格式 | 维度(shape) | 非连续Tensor |
|---|---|---|---|---|---|---|---|
| self(aclTensor*) | 输入 | 输入Tensor | 支持空Tensor | INT8、UINT8、INT16、INT32、INT64、FLOAT16、FLOAT32、DOUBLE、BFLOAT16、UINT16、UINT32、UINT64 | ND | 1-8 | √ |
| k(int64_t) | 输入 | 计算维度上输出的极值个数 | 取值范围 [0, self.size(dim)] | - | - | - | - |
| dim(int64_t) | 输入 | 计算维度 | 取值范围 [-self.dim(), self.dim()) | - | - | - | - |
| largest(bool) | 输入 | 结果排序方式 | True 表示结果由大到小输出,False 表示由小到大输出 | - | - | - | - |
| sorted(bool) | 输入 | 输出结果是否排序 | True 表示排序,False 表示不排序。注意:当前该参数仅支持取 True | - | - | - | - |
| valuesOut(aclTensor*) | 输出 | 输出Tensor,包含极值 | 数据类型与 self 保持一致 | INT8、UINT8、INT16、INT32、INT64、FLOAT16、FLOAT32、DOUBLE、BFLOAT16、UINT16、UINT32、UINT64 | ND | 1-8 | √ |
| indicesOut(aclTensor*) | 输出 | 输出Tensor,包含索引 | 数据类型支持 INT64 | INT64 | ND | 1-8 | √ |
| workspaceSize(uint64_t*) | 输出 | 返回需要在 Device 侧申请的 workspace 大小 | - | - | - | - | - |
| executor(aclOpExecutor**) | 输出 | 返回 op 执行器,包含算子计算流程 | - | - | - | - | - |
产品数据类型限制:Atlas A2 训练系列产品/Atlas A2 推理系列产品、Atlas A3 训练系列产品/Atlas A3 推理系列产品上,self、valuesOut 的数据类型不支持 UINT16、UINT32、UINT64。
参数使用要点
dim支持负索引(-1表示最后一维),这是aclnnTopk在接口层对负维度的容错;在 math/topk/op_kernel_aicpu/topk_aicpu.cpp 的 AICPU 内核中同样会执行dim_ = dim_ < 0 ? (input_rank + dim_) : dim_的归一化,并校验结果落在[0, input_rank)。indicesOut在 aclnn 接口层固定为 INT64;而底层 AICPU 内核的indices输出原生为 INT32(见 math/topk/op_kernel_aicpu/topk_aicpu_def.cpp),上层会按需通过Cast转成目标类型(见 math/topk/op_api/topk.cpp)。
aclnnTopk 参数详解
第二段接口是实际的执行入口,4 个参数全部为输入:
| 参数名 | 输入/输出 | 描述 |
|---|---|---|
| workspace | 输入 | 在 Device 侧申请的 workspace 内存地址 |
| workspaceSize | 输入 | 在 Device 侧申请的 workspace 大小,由第一段接口 aclnnTopkGetWorkspaceSize 获取 |
| executor | 输入 | op 执行器,包含算子计算流程 |
| stream | 输入 | 指定执行任务的 Stream |
调用时,若 workspaceSize 大于 0,需先通过 aclrtMalloc 在 Device 侧申请对应大小的内存;若为 0 则可跳过申请。
返回值与错误码
第一段接口 aclnnTopkGetWorkspaceSize 完成入参校验,以下场景会直接报错返回:
| 返回值 | 错误码 | 描述 |
|---|---|---|
| ACLNN_ERR_PARAM_NULLPTR | 161001 | 传入的 self、valuesOut 或 indicesOut 是空指针 |
| ACLNN_ERR_PARAM_INVALID | 161002 | self、valuesOut 或 indicesOut 的数据类型和数据格式不在支持的范围之内 |
| ACLNN_ERR_PARAM_INVALID | 161002 | dim 不在输入 self 的合理维度范围内 |
| ACLNN_ERR_PARAM_INVALID | 161002 | k 小于 0 或者 k 大于输入 self 在 dim 维度上的 size 大小 |
这些约束与内核侧校验一一对应:AICPU 内核在 GetInputAndCheck 中检查 k >= 0 与 n >= k(math/topk/op_kernel_aicpu/topk_aicpu.cpp),并拒绝 rank 为 0 的输入(math/topk/op_kernel_aicpu/topk_aicpu.cpp)。
约束说明
- 确定性计算:
aclnnTopk默认采用确定性实现,相同输入在多次运行中输出一致,相关背景可参考 docs/zh/context/determinism_compute.md。 - sorted 仅支持 True:当前版本
sorted参数只支持True,即输出必然按排序结果给出。 - 形状约束:
self的维度(shape 维数)支持 1-8,k不超过self.size(dim),dim取值范围为[-self.dim(), self.dim())。 - 非连续 Tensor:
self、valuesOut、indicesOut均支持非连续 Tensor,相关概念可参考 docs/zh/context/non_contiguous_tensor.md。
完整调用示例
以下示例代码取自 math/topk/docs/aclnnTopk.md 并保留了全部注释,完整演示从环境初始化、Tensor 构造、两段式调用到结果回收的整个流程。具体编译与执行方法参见 docs/zh/context/compile_and_run_sample.md。
#include <iostream>
#include <vector>
#include "acl/acl.h"
#include "aclnnop/aclnn_topk.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 = {2, 4};
std::vector<int64_t> outShape = {2, 2};
void* selfDeviceAddr = nullptr;
void* outDeviceAddr = nullptr;
void* indicesDeviceAddr = nullptr;
aclTensor* self = nullptr;
aclTensor* out = nullptr;
aclTensor* indices = nullptr;
std::vector<float> selfHostData = {0, 1, 2.5, 3, 4, 5.5, 6, 7};
std::vector<float> outHostData = {0, 1, 2, 3.1};
std::vector<int64_t> indicesHostData = {0, 1, 2, 3};
// 创建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);
// 创建indices aclTensor
ret = CreateAclTensor(indicesHostData, outShape, &indicesDeviceAddr, aclDataType::ACL_INT64, &indices);
CHECK_RET(ret == ACL_SUCCESS, return ret);
// 3.调用CANN算子库API,需要修改为具体的API名称
int64_t k = 2;
int64_t dim = 1;
bool largest = true;
bool sorted = true;
uint64_t workspaceSize = 0;
aclOpExecutor* executor;
// 调用aclnnTopk第一段接口
ret = aclnnTopkGetWorkspaceSize(self, k, dim, largest, sorted, out, indices, &workspaceSize, &executor);
CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclnnTopkGetWorkspaceSize 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);
}
// 调用aclnnTopk第二段接口
ret = aclnnTopk(workspaceAddr, workspaceSize, executor, stream);
CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclnnTopk 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 outSize = GetShapeSize(outShape);
std::vector<float> outData(outSize, 0);
ret = aclrtMemcpy(outData.data(), outData.size() * sizeof(outData[0]), outDeviceAddr,
outSize * sizeof(outData[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 < outSize; i++) {
LOG_PRINT("out[%ld] is: %f\n", i, outData[i]);
}
auto indicesSize = GetShapeSize(outShape);
std::vector<int64_t> indicesData(indicesSize, 0);
ret = aclrtMemcpy(indicesData.data(), indicesData.size() * sizeof(indicesData[0]), indicesDeviceAddr,
indicesSize * sizeof(indicesData[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 < indicesSize; i++) {
LOG_PRINT("indices[%ld] is: %ld\n", i, indicesData[i]);
}
// 6.释放aclTensor和aclScalar,需要根据具体API的接口定义修改
aclDestroyTensor(self);
aclDestroyTensor(out);
aclDestroyTensor(indices);
// 7.释放device资源,需要根据具体API的接口定义修改
aclrtFree(selfDeviceAddr);
aclrtFree(outDeviceAddr);
aclrtFree(indicesDeviceAddr);
if (workspaceSize > 0) {
aclrtFree(workspaceAddr);
}
aclrtDestroyStream(stream);
aclrtResetDevice(deviceId);
aclFinalize();
return 0;
}
示例中 self 数据为 {0, 1, 2.5, 3, 4, 5.5, 6, 7}(形状 {2, 4}),在 dim=1、k=2、largest=true、sorted=true 下,预期输出为每行的两个最大值:第一行 {3, 2.5}(索引 {3, 2}),第二行 {7, 6}(索引 {3, 2})。对照 math/topk/tests/ut/op_kernel_aicpu/test_topk.cpp 中的单测可以发现,仓库对相等值的处理规则是“值相等时,原始索引较小的排在前面”(比较器见 math/topk/op_kernel_aicpu/topk_aicpu.cpp)。
源码级原理:AiCore / AiCpu 双路径调度
aclnnTopk 的执行入口实现在 math/topk/op_api/topk.cpp 的 l0op::TopkCommon 中(math/topk/op_api/topk.cpp)。该函数先根据输入形状推导输出(outShape.SetDim(dim, k)),随后依据芯片型号、数据类型、输入规模与 k 的大小动态选择执行路径:
- AiCore 路径:当
IsAiCoreSupport判定支持时走 AiCore 加速,并进一步细分:- 小
k的 Atlas 推理系列产品场景走TopkV3; - A2/A3 上大排序轴、大
k的场景走RadixTopK(阈值逻辑见 math/topk/op_api/topk.cpp,如排序轴 ≥ 1200 万且sortLen > 100 * k); - 常规场景走
TopkV2AiCore,k > 2000且排序轴 ≤ 1000 万时切换为 SortWithIndex 模板以换取更好的索引转换性能(math/topk/op_api/topk.cpp)。
- 小
- AiCpu 路径:不满足 AiCore 条件时,通过
ADD_TO_LAUNCHER_LIST_AICPU下发到 math/topk/op_kernel_aicpu/topk_aicpu.cpp 中的TopkCpuKernel。
IsAiCoreSupport 的判定(math/topk/op_api/topk.cpp)体现了平台差异:例如 Atlas 训练系列产品(910)仅支持 FLOAT16 走 AiCore;A2/A3 支持 FLOAT16、FLOAT、BF16;Ascend 950(RegBase)支持完整数据类型清单,并对 INT64 输入做了额外的规模判断(输入元素数在 6.5 万到 2500 万之间、且排序轴小于 22 时,实测 AICPU 反而更快,因此强制走 CPU)。这说明同一份 aclnnTopk 调用在不同硬件上可能映射到不同的内核实现。
AICPU 内核的多算法分派
TopkCpuKernel(math/topk/op_kernel_aicpu/topk_aicpu.cpp)按行(head * tail 个独立排序单元)并行处理,并根据 n(排序轴长度)与 k 的关系选择不同算法(math/topk/op_kernel_aicpu/topk_aicpu.cpp):
- 小规模路径(
n <= 64且k < n且k <= 8):先通过DetectMonotone探测行数据是否已(反)有序或全相等,命中则 O(k) 直接输出;否则走选择排序式SelectionTopK; - 全排序路径(
n <= 64且k == n):直接std::sort全量排序; - 常规路径:Floyd O(k) 建堆 + 线性扫掠的
HeapTopK,若sorted=true再做原堆内排序InPlaceHeapSort。
数据量较小时(总输入字节 < 8KB 或仅 1 行)走串行,否则按 32KB 分片目标用 ParallelFor 多核并行(math/topk/op_kernel_aicpu/topk_aicpu.cpp)。内核支持 FLOAT16、FLOAT、DOUBLE 及全部整数类型,分派表见 math/topk/op_kernel_aicpu/topk_aicpu.cpp。
算子注册与图模式调用
TopK 的算子定义在 math/topk/op_kernel_aicpu/topk_aicpu_def.cpp 中注册:输入 x(11 种数据类型)与 k(INT32),输出 values 与 indices,属性 dim(默认 -1)、largest(默认 true)、sorted(默认 true)均为可选。除 aclnn 两段式接口外,仓库还提供基于算子 IR 的图模式调用示例 math/topk/examples/test_geir_topk.cpp(通过 math/topk/op_graph/topk_proto.h 构造 GE 图并强制走 AICPU 引擎),适合需要在构图阶段集成 TopK 的场景。
小结
aclnnTopk 以两段式接口封装了 TopK 的完整调用链路:第一段负责校验与 workspace 计算,第二段负责实际执行。使用时需重点把握三点:sorted 当前仅支持 True;indicesOut 固定为 INT64;A2/A3 产品不支持 UINT16/UINT32/UINT64。底层实现上,该算子在 AiCore 与 AiCpu 之间按平台、数据类型与规模动态路由,AICPU 内核内部还针对不同 n/k 组合选择单调探测、选择排序、堆排序等多种算法,兼顾了正确性与性能。更多算子接口与数学库细节可继续阅读 math/topk/docs/aclnnTopkV2.md 以及 math/topk/README.md。