CANN ops-math 算子指南:aclnnAmax 两段式接口详解与 NPU 调用实战

原创2026-09-21 11:37:371,904 阅读
文章标签:算子库人工智能深度学习高性能计算CANNAscend

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;
}

示例运行流程拆解

  1. 资源初始化(固定写法):aclInit → aclrtSetDevice → aclrtCreateStream,失败时通过 CHECK_RET 宏打印错误并返回。
  2. 构造输入输出:用 aclrtMalloc 申请 Device 侧内存、aclrtMemcpy 灌入数据、按连续布局计算 strides,最后通过 aclCreateTensor 创建 aclTensor;dim 通过 aclCreateIntArray 创建。
  3. 两段式调用:先 aclnnAmaxGetWorkspaceSize 拿到 workspaceSize 与 executor,按需 aclrtMalloc 申请 workspace 后再调 aclnnAmax 下发计算。
  4. 同步等待:aclrtSynchronizeStream 确保任务执行结束。
  5. 取回结果:aclrtMemcpy 将 Device 侧输出拷回 Host 并逐元素打印。
  6. 资源释放:依次释放 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 用例,覆盖正常与异常路径。
登录后查看全文
ops-math