CANN ops-math 算子 aclnnAminmaxDim 接口详解:沿指定维度求最小/最大值的两段式调用实践
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 中按序实现:
CheckNotNull:检查self、minOut、maxOut是否为空指针,不通过则返回ACLNN_ERR_PARAM_NULLPTR(错误码 161001);CheckDtypeValid:检查self的数据类型是否在支持列表内,并要求minOut、maxOut与self类型一致,否则返回ACLNN_ERR_PARAM_INVALID(161002);CheckShape:通过MAX_DIM_LEN = 8(源码第 33 行)约束三个 tensor 的维度均不超过 8 维;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 低阶算子编排了如下计算图:
- 空 tensor 处理:若
self->IsEmpty()为真,直接返回workspaceSize = 0,不执行任何计算; - 标量处理:若
self是 0 维(标量),通过l0op::ViewCopy将输入直接拷贝到minOut和maxOut(标量的最小/最大值即其本身); - 连续性转换:调用
l0op::Contiguous将非连续输入转换为连续 tensor(这也是参数表"非连续 Tensor"一列标记 √ 的原因,接口对非连续输入透明支持); - 类型适配:若输入是
DT_BOOL,先l0op::Cast到DT_UINT8再参与规约; - 核心规约:对同一
dimArray分别执行l0op::ReduceMin与l0op::ReduceMax,并通过CheckShapeAndScalarSame校验规约结果的 shape 与minOut、maxOut一致; - 输出回写:将规约结果
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 计算流程中。