CANN ops-math aclnnAcosh 算子深度解析:两段式接口、参数约束与 NPU 内核实现

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

CANN ops-math aclnnAcosh 算子深度解析:两段式接口、参数约束与 NPU 内核实现

本指南以 CANN ops-math 仓库中 acosh 算子 API 文档 为主体,结合 aclnn_acosh.cpp、acosh_tiling.cpp 与 KernelAcosh 内核 等源码实现,系统讲解 aclnnAcosh 的数学语义、两段式调用流程、参数与约束、错误码语义以及从 L2 接口到 AI Core 内核的完整执行链路。读完本文,你将能够独立编写、编译并运行调用 aclnnAcosh 的 NPU 程序,并理解该算子在宿主侧校验、Tiling 切分与 Kernel 计算各阶段的行为。

产品支持情况

aclnnAcosh 接口在 CANN ops-math 中的产品支持情况如下表(以 aclnnAcosh.md 为准):

产品 是否支持
Ascend 950PR/Ascend 950DT ×
Atlas A3 训练系列产品/Atlas A3 推理系列产品 ×
Atlas A2 训练系列产品/Atlas A2 推理系列产品 ×
Atlas 200I/500 A2 推理产品 ×
Atlas 推理系列产品 ×
Atlas 训练系列产品 ×

需要注意的是,文档表格与仓库源码存在一处细节差异:acosh_def.cpp 中明确注册了 ascend950 的 AICore 配置,aclnn_acosh.cpp 的 IsDtypeSupported 也仅在 NpuArch::DAV_3510(即 Ascend 950 系列)上放行 FLOAT16/FLOAT/BF16 三种类型,且 README 将 Ascend 950PR/Ascend 950DT 标为支持。从源码结构看,该算子的 AI Core 实现面向 Ascend 950 系列(arch35)开发,其余产品形态走的是"不支持"路径;实际部署时请以运行环境对应版本的官方支持矩阵为准。

功能说明与数学语义

aclnnAcosh 的接口功能是:对输入张量 self 逐元素计算反双曲余弦值(inverse hyperbolic cosine),结果写入输出张量 out。计算公式为:

outi=cosh⁡−1(selfi)=ln⁡(selfi+selfi2−1)out_i = \cosh^{-1}(self_i) = \ln\left(self_i + \sqrt{self_i^2 - 1}\right)

其中 self_i 表示输入张量第 i 个元素,out_i 表示对应的输出元素。

两个与精度/值域相关的关键语义:

  • NaN 语义:当 self_i < 1 时,数学上无实数解,计算结果为 NaN。接口层不做拦截,与 PyTorch torch.acosh 语义保持一致,由调用方保证输入值域合法。
  • 逐元素、无广播:aclnnAcosh 是逐元素(elementwise)算子,不涉及广播机制,输入输出 shape 必须完全一致。

Kernel 侧对 fp16/bf16 大值还有一个额外的精度保护细节:acosh.h 注释指出,AscendC 的 Acosh 原语对 fp16 大值(如 65504)会因中间步骤 x^2 溢出而返回 0,bf16 原语不支持,因此 fp16/bf16 走 Cast 回退路径(详见后文内核实现)。

两段式接口与函数原型

aclnnAcosh 采用 CANN aclnn 标准的两段式接口设计(两段式接口的通用约定可参考 two_phase_api.md):

  1. 必须先调用 aclnnAcoshGetWorkspaceSize 获取计算所需 workspace 大小以及包含了算子计算流程的执行器(executor);
  2. 再调用 aclnnAcosh 执行实际计算。

第一段接口原型:

aclnnStatus aclnnAcoshGetWorkspaceSize(
  const aclTensor  *self,
  aclTensor        *out,
  uint64_t         *workspaceSize,
  aclOpExecutor    **executor)

第二段接口原型:

aclnnStatus aclnnAcosh(
  void           *workspace,
  uint64_t        workspaceSize,
  aclOpExecutor  *executor,
  aclrtStream     stream)

从 aclnn_acosh.h 的声明可见,两段接口均以 ACLNN_API 导出(默认可见性),头文件仅依赖 aclnn/aclnn_base.h。

aclnnAcoshGetWorkspaceSize 参数说明

第一段接口的参数说明如下:

参数名 输入/输出 描述 使用说明 数据类型 数据格式 维度(shape) 非连续Tensor
self(aclTensor*) 输入 输入张量,对应公式中 self,表示待计算反双曲余弦值的数据。 支持空 Tensor(元素数为 0);数据类型需与 out 保持一致;shape 需与 out 完全一致;输入值域建议为 [1, +∞),小于 1 的值会产生 NaN,框架层不做拦截。 FLOAT16、FLOAT、BFLOAT16 ND 0-8 √
out(aclTensor*) 输出 输出张量,对应公式中 out,用于存放反双曲余弦计算结果。 不支持空 Tensor(self 为空 Tensor 时除外);数据类型需与 self 一致;shape 需与 self 完全一致。 FLOAT16、FLOAT、BFLOAT16 ND 0-8 √
workspaceSize(uint64_t*) 输出 返回需要在 Device 侧申请的 workspace 大小。 - - - - -
executor(aclOpExecutor**) 输出 返回 op 执行器,包含了算子计算流程。 - - - - -

参数要点补充(结合源码确认):

  • 空 Tensor 支持:aclnn_acosh.cpp 中在 CheckParams 之后会先判断 self->IsEmpty(),若为空则直接令 workspaceSize = 0 并快速返回,不再构建执行链。
  • 非连续 Tensor 支持:L2 接口内部通过 l0op::Contiguous 将非连续输入转为连续存储(见下方源码链路),非连续 Tensor 的通用约定可参考 non_contiguous_tensor.md。
  • 数据格式:仅支持 ND,私有格式会被 CheckFormat 直接拒绝,ND 格式的定义参见 data_format.md。

返回值与错误码

两段接口的返回值类型均为 aclnnStatus,返回码的完整说明参见 aclnn_return_code.md。

第一段接口会完成入参校验,出现以下场景时报错:

返回值 错误码 描述
ACLNN_ERR_PARAM_NULLPTR 161001 self 或 out 存在空指针。
ACLNN_ERR_PARAM_INVALID 161002 self 或 out 的数据类型不在支持的范围之内(仅支持 FLOAT16、FLOAT、BFLOAT16)。
ACLNN_ERR_PARAM_INVALID 161002 self 与 out 的数据类型不一致。
ACLNN_ERR_PARAM_INVALID 161002 self 或 out 的 shape 维度不在支持的范围之内(仅支持 0-8 维),或 self 与 out 的 shape 不一致。

对照 aclnn_acosh.cpp 的 CheckParams 实现,校验顺序为:空指针检查(CheckNotNull)→ 数据类型一致性及平台支持检查(CheckDtypeValid,其中 ACLNN_MAX_SHAPE_RANK = 8 同时约束维度上限)→ 格式检查(CheckFormat)→ 维度上限检查(CheckShape)。这与上表错误码的优先级完全对应。

aclnnAcosh 参数说明

第二段接口的参数说明如下:

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

第二段接口不再做入参校验,直接通过 CommonOpExecutorRun 提交执行(见 aclnn_acosh.cpp)。

约束说明

使用 aclnnAcosh 时需注意以下约束:

  • 确定性:aclnnAcosh 默认确定性实现,多次运行结果一致。
  • 数据类型:Atlas A2 训练/推理系列产品仅支持 FLOAT16、FLOAT、BFLOAT16 数据类型,不支持其他数据类型;从源码看,AI Core 路径(Ascend 950)同样仅放行这三种类型。
  • 输入值域:acosh 数学定义域为 [1, +∞),输入元素小于 1 时结果为 NaN,接口层不做拦截,由调用方保证输入合法性。
  • 无广播:逐元素算子,不涉及广播,输入输出 shape 须完全一致。

调用示例

以下代码来自 test_aclnn_acosh.cpp 的核心调用流程(该示例以 float32 为例,计算 acosh(<a href="https://link.gitcode.com/i/db531d298b2d85f4c70d790be26e4ba6" target="_blank">1.0, 2.0, 5.0, 10.0])),完整编译和执行过程参考 [compile_and_run_sample.md:

#include "acl/acl.h"
#include "aclnn_acosh.h"

// 1. ACL 初始化
aclInit(nullptr);
aclrtSetDevice(0);
aclrtStream stream = nullptr;
aclrtCreateStream(&stream);

// 2. 准备输入数据(以 float32 为例,计算 acosh([1.0, 2.0, 5.0, 10.0]))
std::vector<float> inputData = {1.0f, 2.0f, 5.0f, 10.0f};
std::vector<int64_t> shape = {4};
size_t dataSize = inputData.size() * sizeof(float);

// 3. 分配 NPU 内存并拷贝输入数据
void* inputDev = nullptr;
void* outputDev = nullptr;
aclrtMalloc(&inputDev, dataSize, ACL_MEM_MALLOC_HUGE_FIRST);
aclrtMalloc(&outputDev, dataSize, ACL_MEM_MALLOC_HUGE_FIRST);
aclrtMemcpy(inputDev, dataSize, inputData.data(), dataSize, ACL_MEMCPY_HOST_TO_DEVICE);

// 4. 创建 aclTensor(连续 ND 格式)
std::vector<int64_t> strides = {1};   // shape={4} 时 stride={1}
aclTensor* selfTensor = aclCreateTensor(shape.data(), shape.size(), ACL_FLOAT,
    strides.data(), 0, ACL_FORMAT_ND, shape.data(), shape.size(), inputDev);
aclTensor* outTensor = aclCreateTensor(shape.data(), shape.size(), ACL_FLOAT,
    strides.data(), 0, ACL_FORMAT_ND, shape.data(), shape.size(), outputDev);

// 5. 第一段接口:获取 workspace 大小和 executor
uint64_t workspaceSize = 0;
aclOpExecutor* executor = nullptr;
aclnnAcoshGetWorkspaceSize(selfTensor, outTensor, &workspaceSize, &executor);

// 6. 分配 workspace(大小为 0 时跳过)
void* workspace = nullptr;
if (workspaceSize > 0) {
    aclrtMalloc(&workspace, workspaceSize, ACL_MEM_MALLOC_HUGE_FIRST);
}

// 7. 第二段接口:执行算子
aclnnAcosh(workspace, workspaceSize, executor, stream);
aclrtSynchronizeStream(stream);

// 8. 拷回结果
std::vector<float> output(inputData.size());
aclrtMemcpy(output.data(), dataSize, outputDev, dataSize, ACL_MEMCPY_DEVICE_TO_HOST);
// output = [0.0, 1.3169578, 2.2924316, 2.9932227]

// 9. 清理资源
if (workspace) aclrtFree(workspace);
aclDestroyTensor(selfTensor);
aclDestroyTensor(outTensor);
aclrtFree(inputDev);
aclrtFree(outputDev);
aclrtDestroyStream(stream);
aclrtResetDevice(0);
aclFinalize();

该示例的预期输出可以通过数学关系验证:acosh(1)=0,acosh(2)=ln(2+√3)≈1.31696,acosh(5)≈2.29243,acosh(10)≈2.99322,与注释中的结果一致。仓库中的完整示例还提供了更贴近生产的写法,包括:

  • CHECK_RET 宏对每一步 ACL 调用返回值做检查;
  • CreateAclTensor 辅助函数根据 shape 自动计算连续 strides 并完成 aclrtMalloc + aclrtMemcpy;
  • fp16 数据的 FloatToFp16/Fp16ToFloat 转换工具;
  • 以 atol=1e-3, rtol=1e-3 为阈值的逐元素精度验证逻辑(std::acosh 为标准对照),并统计 NaN 个数后返回进程退出码。

仓库示例默认使用 fp16、shape 为 [8, 8](64 个元素,小于 1024),因此触发的是 TilingKey_A(fp16 单缓冲)路径,输入值域取 [1.0, 10.0) 保证 acosh 有效。

源码级实现原理

L2 接口的完整调用链

aclnn_acosh.cpp 中第一段接口的流程为:

CREATE_EXECUTOR -> CheckParams -> HasEmptyTensor -> Contiguous
-> l0op::Acosh -> ViewCopy -> GetWorkspaceSize

具体步骤:

  1. CREATE_EXECUTOR() 创建执行器;
  2. CheckParams 完成空指针、dtype、格式、维度校验;
  3. 空 Tensor 快速返回(workspaceSize 置 0);
  4. l0op::Contiguous(self) 将非连续输入规整为连续存储;
  5. l0op::Acosh(selfContiguous) 进入 L0 层,完成形状推导并分配输出;
  6. l0op::ViewCopy 将中间结果写回调用方传入的 out;
  7. GetWorkspaceSize 汇总返回所需 workspace 大小。

L0 层实现位于 op_api/acosh.cpp:AcoshInferShape 直接令输出 shape 等于输入 shape;IsAiCoreSupport 在 DAV_2201/DAV_3510 上校验 dtype;Acosh 入口通过 executor->AllocTensor 按输入 dtype 分配输出,再经 ADD_TO_LAUNCHER_LIST_AICORE 将算子挂入 AI Core 启动器列表。

第二段接口则简洁地调用 CommonOpExecutorRun(workspace, workspaceSize, executor, stream) 完成最终执行。

算子定义与形状推导

  • acosh_def.cpp:声明算子输入 x、输出 y(均 REQUIRED),数据类型为 DT_FLOAT16/DT_FLOAT/DT_BF16,格式为 FORMAT_ND,并开启 AutoContiguous;AICore 配置中 DynamicRankSupportFlag(true) 支持动态 rank、DynamicShapeSupportFlag(true) 支持动态 shape、PrecisionReduceFlag(true) 允许精度降低优化。
  • acosh_infershape.cpp:InferShape4Acosh 将输出 shape 直接拷贝为输入 shape,从宿主侧再次印证"逐元素、shape 完全一致"的约束。

Tiling 切分策略

acosh_tiling.cpp 实现了 arch35(Ascend 950)上的 Tiling:

  • 多核切分:按元素总数均分到各 AI Core,blockFactor = CeilDiv(totalNum, coreNum),实际使用的核数为 CeilDiv(totalNum, blockFactor)(L142-L145);
  • UB 切分:按可用 UB 大小与缓冲区数量均分,ubFactor 通过 FloorAlign(FloorDiv(ubSize/typeSize, bufferNum), GetUbBlockSize()) 计算;
  • 缓冲模式选择:总元素数大于 1024(MIN_SPLIT_THRESHOLD)时启用双缓冲(L149);
  • TilingData:结构体见 acosh_tiling_data.h,包含 totalNum、blockFactor、ubFactor 三个字段;
  • TilingKey:dtype × buffer_mode 共 6 个组合(A~F),定义见 acosh_tiling_key.h:A= fp16 单缓冲、B=fp16 双缓冲、C=fp32 单缓冲、D=fp32 双缓冲、E=bf16 单缓冲、F=bf16 双缓冲。

Kernel 计算与 fp16/bf16 精度回退

Kernel 入口 acosh_apt.cpp 按模板参数 D_T_X(half/float/bfloat16_t)与 BUFFER_MODE(0/1)实例化 NsAcosh::KernelAcosh,调用 Init 与 Process。核心实现位于 acosh.h:

  • fp32 路径:直接调用 AscendC::Acosh(yLocal, xLocal, currentNum),无溢出问题;
  • fp16/bf16 回退路径:由于 fp16 大值(65504)直接计算会因 x^2 中间步骤溢出返回 0、bf16 原语不支持,因此走 Cast(fp16/bf16->fp32, CAST_NONE) -> Acosh(fp32) -> Cast(fp32->fp16/bf16) 的三段链路;fp32→fp16 使用 CAST_ROUND,fp32→bf16 使用 CAST_RINT,中转缓冲 tmpBuf_ 位于 VECCALC 位置(L118-L132);
  • 流水结构:Process 按 ubFactor 分块循环,每轮执行 CopyIn(DataCopyPad 从 GM 搬运到 VECIN 队列)→ Compute(队列 DeQue/Alloc + 计算 + EnQue)→ CopyOut(写回 GM),缓冲数为 BUFFER_MODE ? 2 : 1;
  • 尾部核处理:Init 中通过 blockFactor * blockIdx 计算当前核的起始偏移,尾部核元素数可能少于 blockFactor,blockLength_ <= 0 时直接跳过(L78-L84)。

由此可以完整还原 aclnnAcosh 的执行链路:调用方两段式接口 → L2 层校验与执行器构建 → L0 层形状推导与输出分配 → Tiling 阶段的多核/UB 切分 → arch35 AI Core 上的逐元素 acosh 计算(含 fp16/bf16 的 fp32 中转精度回退)。

总结

aclnnAcosh 是 CANN ops-math 中面向 Ascend 950 系列(arch35)实现的逐元素反双曲余弦算子,遵循 aclnn 标准两段式接口(GetWorkspaceSize + 执行),仅支持 FLOAT16/FLOAT/BFLOAT16、ND 格式、0-8 维、输入输出 shape 与 dtype 严格一致,且默认确定性实现。其数值语义与 PyTorch torch.acosh 一致(输入小于 1 产生 NaN,框架不拦截),工程上通过 Cast 回退路径规避了 fp16/bf16 在 x² 中间步骤的溢出问题。开发者可直接复用 examples/test_aclnn_acosh.cpp 作为上手模板,并结合 two_phase_api.md 与 compile_and_run_sample.md 理解更通用的 aclnn 算子调用范式。

登录后查看全文
ops-math