CANN ops-math 算子 aclnnAminmaxDim 接口详解:沿指定维度求最小/最大值的两段式调用实践

原创2026-09-20 18:33:161,821 阅读
文章标签:算子库人工智能深度学习高性能计算CANNAscend

CANN ops-math 算子 aclnnAminmaxDim 接口详解:沿指定维度求最小/最大值的两段式调用实践

本指南以 CANN ops-math 仓库中 aclnnAminmaxDim 文档 为主体,结合 aclnn_aminmax_dim.cpp 等源码与测试用例,系统讲解 aclnnAminmaxDim 算子的功能语义、参数约束、两段式调用流程与完整可运行的 C++ 示例。读完本文,你将掌握如何在 NPU 上沿指定维度一次性同时求出输入张量的最小值与最大值,并能够独立完成从环境初始化、workspace 申请到结果回收的完整单算子 API 编程。

一、算子功能与定位

aclnnAminmaxDim 是 CANN ops-math 数学类基础算子库中 reduce_min 目录下提供的规约(reduce)类算子接口,其功能为:返回输入张量在指定维度上的最小值和最大值。与一次只计算一个极值的 aclnnAmin / aclnnMin 等接口不同,它通过一次 API 调用同时产出 minOut 与 maxOut 两个输出张量,对应 PyTorch 的 torch.aminmax(input, dim, keepdim) 语义。

从仓库的 golden 校验脚本 golden.py 可以确认其数学语义:

def aclnn_aminmax_dim_golden(self, dim=0, keepDim=0, minOut=None, maxOut=None, **kwargs):
    result = torch.aminmax(self, dim=dim, keepdim=bool(keepDim))
    return [result.min, result.max]

即 minOut 与 maxOut 分别等于 torch.aminmax 结果的 min 与 max。该接口常用于网络中的归一化、裁剪、统计量计算等同时需要上下界信息的场景。

需要说明的是,根据 reduce_min 目录 README,本目录主要承载 ReduceMin 相关算子的 aclnn 接口实现;该接口内部实际会同时调度底层 ReduceMin 与 ReduceMax 计算(详见下文源码解析)。

产品支持情况

原文档给出了各硬件平台的支持矩阵,整理如下:

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

二、两段式接口与函数原型

aclnnAminmaxDim 遵循 CANN 单算子 API 的两段式接口约定:必须先调用第一段接口 aclnnAminmaxDimGetWorkspaceSize 获取入参校验结果、完成计算流程编排并得到所需 workspace 大小,再按照该大小在 Device 侧申请内存,最后调用第二段接口 aclnnAminmaxDim 执行计算。

两段接口的声明可在头文件 aclnn_aminmax_dim.h 中查看,原型如下:

aclnnStatus aclnnAminmaxDimGetWorkspaceSize(
  const aclTensor *self,
  const int64_t    dim,
  bool             keepDim,
  aclTensor       *minOut,
  aclTensor       *maxOut,
  uint64_t        *workspaceSize,
  aclOpExecutor  **executor)
aclnnStatus aclnnAminmaxDim(
  void          *workspace,
  uint64_t       workspaceSize,
  aclOpExecutor *executor,
  aclrtStream    stream)

注意:第二段接口 aclnnAminmaxDim 不可重复调用,一次 GetWorkspaceSize 获取的 executor 只能配合执行一次计算,重复调用会出现异常。

三、aclnnAminmaxDimGetWorkspaceSize 参数详解

第一段接口完成入参校验与计算图编排。各参数说明如下表:

参数名 输入/输出 描述 使用说明 数据类型 数据格式 维度(shape) 非连续Tensor
self 输入 输入 tensor - FLOAT、BFLOAT16、FLOAT16、DOUBLE、INT8、INT16、INT32、INT64、UINT8、BOOL ND - √
dim 输入 指定要缩减的维度 取值范围为 [-self.dim(), self.dim()-1] INT64 - - -
keepDim 输入 reduce 轴的维度是否保留 - BOOL - - -
minOut 输出 输出的最小值 tensor 数据类型与 self 一致 FLOAT、BFLOAT16、FLOAT16、DOUBLE、INT8、INT16、INT32、INT64、UINT8、BOOL ND - √
maxOut 输出 输出的最大值 tensor 数据类型与 self 一致 FLOAT、BFLOAT16、FLOAT16、DOUBLE、INT8、INT16、INT32、INT64、UINT8、BOOL ND - √
workspaceSize 输出 返回需要在 Device 侧申请的 workspace 大小 - - - - -
executor 输出 返回 op 执行器,包含了算子计算流程 - - - - -

平台差异说明:在 Atlas 训练系列产品上,不支持 BFLOAT16 数据类型(即 self、minOut、maxOut 均不能使用 BFLOAT16)。

返回值与参数校验

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

返回码 错误码 描述
ACLNN_ERR_PARAM_NULLPTR 161001 传入的 self、minOut 或 maxOut 是空指针
ACLNN_ERR_PARAM_INVALID 161002 self 的数据类型不在支持的范围内时
ACLNN_ERR_PARAM_INVALID 161002 minOut 或 maxOut 与 self 的数据类型不一致
ACLNN_ERR_PARAM_INVALID 161002 self、minOut 或 maxOut 的 shape 超过 8 维
ACLNN_ERR_PARAM_INVALID 161002 dim 超出 self 维度范围
ACLNN_ERR_PARAM_INVALID 161002 dim 指定的轴为空轴

这些校验规则在源码 aclnn_aminmax_dim.cpp 的 CheckParams 中按序实现:

  1. CheckNotNull:检查 self、minOut、maxOut 是否为空指针,不通过则返回 ACLNN_ERR_PARAM_NULLPTR(错误码 161001);
  2. CheckDtypeValid:检查 self 的数据类型是否在支持列表内,并要求 minOut、maxOut 与 self 类型一致,否则返回 ACLNN_ERR_PARAM_INVALID(161002);
  3. CheckShape:通过 MAX_DIM_LEN = 8(源码第 33 行)约束三个 tensor 的维度均不超过 8 维;
  4. CheckDimValid:要求 dim 落在 [-dimNum, dimNum-1] 区间(self 为标量时按 1 维处理),并要求该轴尺寸非 0,即不能是空轴。

支持的数据类型与平台相关性

源码中根据当前 SoC 版本动态选择数据类型支持列表(aclnn_aminmax_dim.cpp):

  • ASCEND910_DTYPE_DTYPE_SUPPORT_LIST(Atlas 训练系列产品等):FLOAT、FLOAT16、UINT8、INT32、INT64、INT16、INT8、DOUBLE、BOOL;
  • ASCEND910B_DTYPE_DTYPE_SUPPORT_LIST(Atlas A2/A3、Ascend 950 等):在上述基础上增加 BF16。

这与原文档"Atlas 训练系列产品不支持 BFLOAT16"的约束一一对应。其中 FLOAT、FLOAT16、UINT8、INT32 走 AiCore 路径,INT64、INT16、INT8、DOUBLE 走 AiCpu 路径,BOOL 则在接口层先被 Cast 为 UINT8 参与计算(详见下文实现流程)。

四、aclnnAminmaxDim 参数详解

第二段接口执行实际计算,参数如下:

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

其实现非常简洁,直接调用框架能力完成异步计算(aclnn_aminmax_dim.cpp):

aclnnStatus aclnnAminmaxDim(void *workspace, uint64_t workspaceSize, aclOpExecutor *executor, aclrtStream stream) {
  L2_DFX_PHASE_2(aclnnAminmaxDim);
  return CommonOpExecutorRun(workspace, workspaceSize, executor, stream);
}

五、第一段接口的内部实现流程

阅读 aclnnAminmaxDimGetWorkspaceSize 的实现,可以看到它在完成参数校验后,通过 l0op 低阶算子编排了如下计算图:

  1. 空 tensor 处理:若 self->IsEmpty() 为真,直接返回 workspaceSize = 0,不执行任何计算;
  2. 标量处理:若 self 是 0 维(标量),通过 l0op::ViewCopy 将输入直接拷贝到 minOut 和 maxOut(标量的最小/最大值即其本身);
  3. 连续性转换:调用 l0op::Contiguous 将非连续输入转换为连续 tensor(这也是参数表"非连续 Tensor"一列标记 √ 的原因,接口对非连续输入透明支持);
  4. 类型适配:若输入是 DT_BOOL,先 l0op::Cast 到 DT_UINT8 再参与规约;
  5. 核心规约:对同一 dimArray 分别执行 l0op::ReduceMin 与 l0op::ReduceMax,并通过 CheckShapeAndScalarSame 校验规约结果的 shape 与 minOut、maxOut 一致;
  6. 输出回写:将规约结果 Cast 回 minOut/maxOut 声明的数据类型,再通过 l0op::ViewCopy 写入输出 tensor(兼容非连续输出)。

由此可以推断:该接口在算子库层面把"求最小值"与"求最大值"两次规约合并为一次 API 调用,同时复用了仓库中 reduce_min 与 reduce_max 的底层规约能力(后者头文件来自 math/reduce_max/op_api/reduce_max.h 的引用)。底层 ReduceMin 算子本身支持动态 shape、动态 rank(见 reduce_min_def.cpp 的 DynamicShapeSupportFlag(true) 等配置),其 keep_dims 属性默认值为 false、noop_with_empty_axes 默认值为 true(见 reduce_min_proto.h)。

六、约束说明

  • 确定性计算:aclnnAminmaxDim 默认采用确定性实现,即在相同输入与硬件环境下多次运行结果一致,便于调试与结果复现。

七、完整调用示例

以下为原文档提供的完整可编译示例(test_aclnn_aminmax_dim.cpp 与之对应),演示了两段式接口的标准调用流程。示例输入 shape 为 {2, 3, 2},dim = 0、keepDim = true,期望输出 shape 为 {1, 3, 2}。具体编译与运行方法请参考编译与运行样例。

#include <iostream>
#include <vector>
#include "acl/acl.h"
#include "aclnnop/aclnn_aminmax_dim.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根据自己的需要处理
  CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("Init acl failed. ERROR: %d\n", ret); return ret);

  // 2.构造输入与输出,需要根据API的接口自定义构造
  std::vector<int64_t> selfShape = {2, 3, 2};
  std::vector<int64_t> outShape = {1, 3, 2};
  void* selfDeviceAddr = nullptr;
  void* minOutDeviceAddr = nullptr;
  void* maxOutDeviceAddr = nullptr;
  aclTensor* self = nullptr;
  aclTensor* minOut = nullptr;
  aclTensor* maxOut = nullptr;
  std::vector<float> selfHostData = {0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11};
  std::vector<float> minOutHostData = {0, 0, 0, 0, 0, 0};
  std::vector<float> maxOutHostData = {0, 0, 0, 0, 0, 0};
  int64_t dim = 0;
  bool keepDim = true;
  // 创建self aclTensor
  ret = CreateAclTensor(selfHostData, selfShape, &selfDeviceAddr, aclDataType::ACL_FLOAT, &self);
  CHECK_RET(ret == ACL_SUCCESS, return ret);
  // 创建out aclTensor
  ret = CreateAclTensor(minOutHostData, outShape, &minOutDeviceAddr, aclDataType::ACL_FLOAT, &minOut);
  CHECK_RET(ret == ACL_SUCCESS, return ret);
  ret = CreateAclTensor(maxOutHostData, outShape, &maxOutDeviceAddr, aclDataType::ACL_FLOAT, &maxOut);
  CHECK_RET(ret == ACL_SUCCESS, return ret);
  // 3.调用CANN算子库API,需要修改为具体的API名称
  uint64_t workspaceSize = 0;
  aclOpExecutor* executor;
  // 调用aclnnAminmaxDim第一段接口
  ret = aclnnAminmaxDimGetWorkspaceSize(self, dim, keepDim, minOut, maxOut, &workspaceSize, &executor);
  CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclnnAminmaxDimGetWorkspaceSize 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);
  }
  // 调用aclnnAminmaxDim第二段接口
  ret = aclnnAminmaxDim(workspaceAddr, workspaceSize, executor, stream);
  CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclnnAminmaxDim 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> minResultData(size, 0);
  ret = aclrtMemcpy(minResultData.data(), minResultData.size() * sizeof(minResultData[0]), minOutDeviceAddr,
                    size * sizeof(minResultData[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, minResultData[i]);
  }
  std::vector<float> maxResultData(size, 0);
  ret = aclrtMemcpy(maxResultData.data(), maxResultData.size() * sizeof(maxResultData[0]), maxOutDeviceAddr,
                    size * sizeof(maxResultData[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, maxResultData[i]);
  }

  // 6.释放aclTensor,需要根据具体API的接口定义修改
  aclDestroyTensor(self);
  aclDestroyTensor(minOut);
  aclDestroyTensor(maxOut);

  // 7.释放device资源,需要根据具体API的接口定义修改
  aclrtFree(selfDeviceAddr);
  aclrtFree(minOutDeviceAddr);
  aclrtFree(maxOutDeviceAddr);
  if (workspaceSize > 0) {
    aclrtFree(workspaceAddr);
  }
  aclrtDestroyStream(stream);
  aclrtResetDevice(deviceId);
  aclFinalize();
  return 0;
}

对示例做几点补充说明,便于你改造成自己的用例:

  • dim 支持负数索引(如 -1 表示最后一维),源码与单测均覆盖了 dim = 1、dim = -1 的路径(见 test_aclnn_aminmax_dim.cpp);
  • keepDim = false 时输出会去掉被规约的维度,例如 {2, 4} 在 dim = 0 下输出 shape 为 {4}(见 test_aclnn_aminmax_dim.cpp);
  • 输出的实际 shape 由 keepDim 与 dim 共同决定,创建 minOut/maxOut 时必须与其匹配,否则第一段接口会因 shape 不一致(CheckShapeAndScalarSame 校验)返回 ACLNN_ERR_PARAM_INVALID;
  • workspace 只有在 workspaceSize > 0 时才需要申请,申请与释放必须成对出现。

八、测试与验证

仓库为该接口提供了完整的验证体系,可作为功能正确性的参考依据:

  • 单测(UT):tests/ut/op_api/test_aclnn_aminmax_dim.cpp 使用 gtest 框架覆盖了空指针异常(self/minOut/maxOut 分别为 nullptr)、FLOAT32/FLOAT16/INT64 正常路径、dim = 0/1/-1、keepDim = true/false、空 tensor、dim 越界等场景;
  • 黄金脚本(golden):tests/assets/golden.py 使用 torch.aminmax 作为数值基准,从语义上锁定最小/最大值的计算结果;
  • ST 用例:tests/st/arch35/ttk_aclnn_aminmax_dim_st.csv 覆盖了 5 维大 shape(如 (1,7831,1,1,107))、dim = 4、keepDim = True 的高维规约场景,并设置了精度容差。

九、小结

aclnnAminmaxDim 是 CANN ops-math 提供的沿指定维度同时求最小/最大值的单算子 API。使用时要牢记三点:一是遵循"先 GetWorkspaceSize 后执行"的两段式调用顺序;二是保证 minOut、maxOut 的数据类型与 self 一致、shape 与规约结果匹配;三是注意平台差异(如 Atlas 训练系列产品不支持 BFLOAT16)。结合本仓库的源码、单测与 golden 校验,你可以快速验证接口语义,并将其正确集成到自己的 NPU 计算流程中。

登录后查看全文
ops-math