CANN ops-math 中 aclnnTopk 算子详解:两段式接口调用、参数约束与调度实现

原创2026-09-21 23:39:182,177 阅读
文章标签:算子库人工智能深度学习高性能计算CANNAscend

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):

  1. 第一段:调用 aclnnTopkGetWorkspaceSize 完成入参校验,并返回计算所需的 workspace 大小及一个封装了算子计算流程的执行器 executor;
  2. 第二段:调用 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。

参数使用要点

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。

登录后查看全文
ops-math