CANN ops-math 算子指南:aclnnAmax 两段式接口详解与 NPU 调用实战
CANN ops-math 算子指南:aclnnAmax 两段式接口详解与 NPU 调用实战
aclnnAmax 是 CANN ops-math 数学算子库中用于"返回张量在指定维度(dim)上每个切片最大值"的 NPU 加速算子接口,其实现位于 math/reduce_max 目录。本文以 math/reduce_max/docs/aclnnAmax.md 为骨架,结合仓库源码与测试用例,完整讲解 aclnnAmax 的产品支持情况、两段式接口的每个参数、错误返回码、约束说明,并给出可直接编译运行的完整 C++ 调用示例,帮助你快速在自己的 CANN 应用中完成 Amax 归约计算。
一、功能与产品支持情况
功能说明
aclnnAmax 返回输入张量 self 在指定维度(dim)上每个切片的最大值。例如对 shape 为 (2, 3, 2) 的张量在 dim {0, 2} 上做归约,输出 shape 为 (1, 3, 1)(keepDim=true 时),对应 调用示例 中的具体数据。
从源码实现看,aclnnAmax 内部并非独立 kernel,而是复用了 ReduceMax 归约算子完成核心计算:op_api/aclnn_amax.cpp 中调用 l0op::ReduceMax(selfCasted, dim, keepDim, true, ...),而 op_api/reduce_max.cpp 中的 ReduceMax 会根据芯片类型与数据类型自动选择 AiCore kernel(ReduceMaxAiCore)或 AiCpu kernel(ReduceMaxAiCpu)执行。
产品支持情况
根据文档的 <term> 标注,各产品的支持情况如下:
| 产品 | 支持情况 |
|---|---|
| Ascend 950PR / Ascend 950DT | 支持 |
| Atlas A3 训练系列产品 / Atlas A3 推理系列产品 | 支持 |
| Atlas A2 训练系列产品 / Atlas A2 推理系列产品 | 支持 |
| Atlas 200I/500 A2 推理产品 | 不支持 |
| Atlas 推理系列产品 | 支持 |
| Atlas 训练系列产品 | 支持 |
结合 op_host/reduce_max_def.cpp 可看到,ReduceMax 算子的 AiCore 配置目前注册了 ascend950 与 ascend350 两个平台,并通过 DynamicCompileStaticFlag(true)、DynamicRankSupportFlag(true)、DynamicShapeSupportFlag(true) 支持动态编译、动态 rank 与动态 shape,这为 aclnnAmax 在多产品上的一致性行为提供了底层支撑。
二、两段式接口与函数原型
与 CANN 所有 aclnn 算子一样,aclnnAmax 采用两段式接口设计:必须先调用第一段接口 aclnnAmaxGetWorkspaceSize 完成入参校验、算子流程构建并计算所需 workspace 大小,再调用第二段接口 aclnnAmax 真正下发计算任务。
第一段接口原型:
aclnnStatus aclnnAmaxGetWorkspaceSize(
const aclTensor *self,
const aclIntArray *dim,
bool keepDim,
aclTensor *out,
uint64_t *workspaceSize,
aclOpExecutor **executor);
第二段接口原型:
aclnnStatus aclnnAmax(
void *workspace,
uint64_t workspaceSize,
aclOpExecutor *executor,
aclrtStream stream);
从 op_api/aclnn_amax.cpp 的实现可以看到两段接口的分工非常清晰:第一段通过 CheckParams 完成四步参数检查(空指针、数据类型、dim 范围与重复、输出 shape 推导),随后构建 l0op::Contiguous → l0op::Cast → l0op::ReduceMax → l0op::Cast → l0op::ViewCopy 的完整计算图并统计 uniqueExecutor->GetWorkspaceSize();第二段接口则只是固定写法,调用 CommonOpExecutorRun(workspace, workspaceSize, executor, stream) 完成实际计算。
三、aclnnAmaxGetWorkspaceSize 参数说明
| 参数名 | 输入/输出 | 描述 | 使用说明 | 数据类型 | 数据格式 | 维度(shape) | 非连续Tensor |
|---|---|---|---|---|---|---|---|
| self(aclTensor*) | 输入 | 待归约的输入张量 | - | FLOAT、FLOAT16、DOUBLE、INT8、INT16、INT32、INT64、UINT8、BOOL、BFLOAT16 | ND | - | √ |
| dim(aclIntArray*) | 输入 | 指定进行最大值计算的维度 | 范围[-self.dim(), self.dim() - 1],且 dim 中的元素不能重复 | INT64 | - | - | - |
| keepDim(bool) | 输入 | reduce 轴的维度是否保留 | - | BOOL | - | - | - |
| out(aclTensor*) | 输出 | 归约结果 | 要与 self 数据类型相同 | FLOAT、FLOAT16、DOUBLE、INT8、INT16、INT32、INT64、UINT8、BOOL、BFLOAT16 | ND | - | √ |
| workspaceSize(uint64_t*) | 输出 | 返回需要在 Device 侧申请的 workspace 大小 | - | - | - | - | - |
| executor(aclOpExecutor**) | 输出 | 返回 op 执行器,包含了算子计算流程 | - | - | - | - | - |
针对上表补充几点仓库源码给出的细节:
- dim 支持负索引:源码
GetPosDim会将负数 dim 归一化为dim + dimNum(见 op_api/aclnn_amax.cpp),因此-1等价于最后一个维度。 - dim 为空数组:当
dim->Size() == 0时,源码GetAllDims会补齐全部维度(等价于对所有维度归约);CheckDimValid中的dimMask.flip()也印证了空 dim 视为归约全部维度。 - 标量输入:当 self 为 0 维标量时,第一段接口会直接通过
l0op::ViewCopy将输入拷贝到输出,不再走 ReduceMax 流程(op_api/aclnn_amax.cpp)。 - 空 Tensor:当
self->IsEmpty()时直接返回ACLNN_SUCCESS,workspaceSize 置 0。 - BOOL 类型内部处理:BOOL 输入会在内部
Cast为 FLOAT 参与归约,输出再Cast回 BOOL(op_api/aclnn_amax.cpp)。 - 非连续 Tensor:
self与out均支持非连续 Tensor,第一段接口会先用Contiguous转换输入,再用ViewCopy将结果写回可能非连续的out。 - 平台差异:
Atlas 推理系列产品、Atlas 训练系列产品不支持 BFLOAT16 数据类型。源码中ASCEND910_DTYPE_SUPPORT_LIST与ASCEND910B_DTYPE_SUPPORT_LIST的差异(BF16、INT8 仅存在于 910B 及之后平台)也与此一致(op_api/aclnn_amax.cpp)。 - FRACTAL_NZ 格式告警:
CheckFormat对FORMAT_FRACTAL_NZ输入会打印告警日志,提示可能导致精度问题,建议使用 ND 格式。
返回值与错误码
第一段接口返回 aclnnStatus 状态码,具体参见 aclnn返回码。第一段接口完成入参校验,出现如下场景时报错:
| 返回值 | 错误码 | 描述 |
|---|---|---|
| ACLNN_ERR_PARAM_NULLPTR | 161001 | 传入的 self、out 和 dim 是空指针时。 |
| ACLNN_ERR_PARAM_INVALID | 161002 | self、out 和 dim 的数据类型不在支持的范围内时。 |
| ACLNN_ERR_PARAM_INVALID | 161002 | self、out 的数据格式不在支持的范围内时。 |
| ACLNN_ERR_PARAM_INVALID | 161002 | self 和 out 的维度超过 8 维。 |
| ACLNN_ERR_PARAM_INVALID | 161002 | dim 数组中的维度超出输入 Tensor 的维度范围。 |
| ACLNN_ERR_PARAM_INVALID | 161002 | dim 数组中元素重复。 |
| ACLNN_ERR_PARAM_INVALID | 161002 | self 中需要 reduce 的维度 size 为 0。 |
这些错误路径与 tests/ut/op_api/test_aclnn_amax.cpp 中的单元测试一一对应:nullptr_self / nullptr_dim / nullptr_out 用例断言返回 ACLNN_ERR_PARAM_NULLPTR;dimension(10 维输入)、dim_invalid(dim=2 超出 2 维范围)、duplicate_dim(dim={0,0} 重复)用例断言返回 ACLNN_ERR_PARAM_INVALID;而 empty_self、scalar_input、empty_dim 则属于被支持的边界场景,返回 ACLNN_SUCCESS。
四、aclnnAmax 参数说明
第二段接口在拿到第一段接口产出的 workspace 与 executor 后执行计算:
| 参数名 | 输入/输出 | 描述 |
|---|---|---|
| workspace | 输入 | 在 Device 侧申请的 workspace 内存地址。 |
| workspaceSize | 输入 | 在 Device 侧申请的 workspace 大小,由第一段接口 aclnnAmaxGetWorkspaceSize 获取。 |
| executor | 输入 | op 执行器,包含了算子计算流程。 |
| stream | 输入 | 指定执行任务的 Stream。 |
五、约束说明
- 确定性计算:aclnnAmax 默认确定性实现,即相同输入在多次运行中结果保持一致。
六、调用示例
示例代码与仓库中的 examples/test_aclnn_amax.cpp 完全一致,可直接参考。具体编译和执行过程请参考 编译与运行样例。
示例场景:输入 self 的 shape 为 (2, 3, 2),host 数据为 {0..11},dim 为 {0, 2},keepDim 为 true,则输出 shape 为 (1, 3, 1)。归约逻辑:对第 0 维和第 2 维求最大值,即对 (i, j, k) 中固定 j、遍历 i 和 k 求最大值——j=0 时 max(0,1,4,5)=5,j=1 时 max(2,3,6,7)=7,j=2 时 max(8,9,10,11)=11,最终输出 {5, 7, 11}。
#include <iostream>
#include <vector>
#include "acl/acl.h"
#include "aclnnop/aclnn_amax.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, 1};
void* selfDeviceAddr = nullptr;
void* outDeviceAddr = nullptr;
aclTensor* self = nullptr;
aclTensor* out = nullptr;
std::vector<float> selfHostData = {0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11};
std::vector<int64_t> dimData = {0, 2};
std::vector<float> outHostData = {0, 0, 0};
// 创建self aclTensor
ret = CreateAclTensor(selfHostData, selfShape, &selfDeviceAddr, aclDataType::ACL_FLOAT, &self);
CHECK_RET(ret == ACL_SUCCESS, return ret);
// 创建dim aclIntArray
aclIntArray *dim = aclCreateIntArray(dimData.data(), dimData.size());
bool keepDim = true;
// 创建out aclTensor
ret = CreateAclTensor(outHostData, outShape, &outDeviceAddr, aclDataType::ACL_FLOAT, &out);
CHECK_RET(ret == ACL_SUCCESS, return ret);
// 3.调用CANN算子库API,需要修改为具体的API名称
uint64_t workspaceSize = 0;
aclOpExecutor* executor;
// 调用aclnnAmax第一段接口
ret = aclnnAmaxGetWorkspaceSize(self, dim, keepDim, out, &workspaceSize, &executor);
CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclnnAmaxGetWorkspaceSize 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);
}
// 调用aclnnAmax第二段接口
ret = aclnnAmax(workspaceAddr, workspaceSize, executor, stream);
CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclnnAmax 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> 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: %f\n", i, resultData[i]);
}
// 6.释放aclTensor,需要根据具体API的接口定义修改
aclDestroyTensor(self);
aclDestroyTensor(out);
// 7.释放device资源
aclrtFree(selfDeviceAddr);
aclrtFree(outDeviceAddr);
if (workspaceSize > 0) {
aclrtFree(workspaceAddr);
}
aclrtDestroyStream(stream);
aclrtResetDevice(deviceId);
aclFinalize();
return 0;
}
示例运行流程拆解
- 资源初始化(固定写法):
aclInit→aclrtSetDevice→aclrtCreateStream,失败时通过CHECK_RET宏打印错误并返回。 - 构造输入输出:用
aclrtMalloc申请 Device 侧内存、aclrtMemcpy灌入数据、按连续布局计算 strides,最后通过aclCreateTensor创建aclTensor;dim 通过aclCreateIntArray创建。 - 两段式调用:先
aclnnAmaxGetWorkspaceSize拿到workspaceSize与executor,按需aclrtMalloc申请 workspace 后再调aclnnAmax下发计算。 - 同步等待:
aclrtSynchronizeStream确保任务执行结束。 - 取回结果:
aclrtMemcpy将 Device 侧输出拷回 Host 并逐元素打印。 - 资源释放:依次释放
aclTensor、Device 内存(含 workspace)、Stream,最后aclrtResetDevice与aclFinalize。
与 torch.amax 的一致性验证
仓库在 tests/st/aclnnAmax/atk_aclnnAmax.json 中提供了基于 torch.amax 的 ST 用例定义("name": "torch.amax", "aclnn_name": "Amax"),覆盖 fp64、int8、int64、int32、int16、bf16、fp16、fp32 等数据类型,dim 取正负值、keepdim 取 true/false,shape 覆盖 1~8 维等边界情况,精度标准为 high_precision,可直接用于验证 aclnnAmax 与 PyTorch 语义的一致性。
七、总结
- 语义:aclnnAmax 对
self在dim指定的一个或多个维度上求最大值,keepDim控制归约轴是否保留为 1。 - 接口形态:两段式接口,第一段
aclnnAmaxGetWorkspaceSize完成校验与 workspace 计算,第二段aclnnAmax执行计算;必须按顺序调用。 - 入参要点:dim 支持负索引、不可重复、范围需在
[-dim, dim-1]内;self 与 out 数据类型必须一致;张量最高 8 维;支持非连续 Tensor;空 dim、标量、空 Tensor 均有专门处理。 - 错误处理:空指针返回
ACLNN_ERR_PARAM_NULLPTR(161001),类型/格式/维度/dim 越界或重复/归约轴 size 为 0 均返回ACLNN_ERR_PARAM_INVALID(161002)。 - 底层实现:内部复用 ReduceMax 算子,按平台与数据类型自动调度 AiCore/AiCpu kernel,BOOL 输入内部先转 FLOAT 计算再转回。
- 验证手段:可参考 tests/ut/op_api/test_aclnn_amax.cpp 的单元测试与 tests/st/aclnnAmax/atk_aclnnAmax.json 的 ST 用例,覆盖正常与异常路径。