CANN ops-math AsinhGrad 算子指南:反双曲正弦梯度计算原理与图模式调用实战
CANN ops-math AsinhGrad 算子指南:反双曲正弦梯度计算原理与图模式调用实战
AsinhGrad 是 CANN ops-math 数学算子库中为反双曲正弦函数(asinh)反向传播设计的梯度算子,其核心职责是根据前向输出 y 与上游梯度 dy 计算出对输入的梯度 dx。本文以 math/asinh_grad/README.md 为骨架,结合仓库中算子定义、Tiling、Kernel 与单测源码,完整讲解该算子的功能、参数、支持平台、图模式调用方式及其底层实现原理,帮助开发者快速上手并在昇腾 NPU 上验证使用。
功能说明:算子做什么、公式是什么
AsinhGrad 用于计算反双曲正弦函数 asinh(x) 的梯度,即反向传播中损失对前向输入 x 的偏导。其输入输出关系可表达为:
其中:
y:asinh 前向计算得到的输出(即asinh(x)的结果),作为本算子的第一个输入;dy:上游(后一层)传入的梯度张量;dx:本算子输出的输入梯度,即∂L/∂x。
从数学推导看,asinh(x) = ln(x + sqrt(x² + 1)),其导数为 1/sqrt(x² + 1) = 1/cosh(asinh(x)),因此用前向输出 y 表示梯度时恰好得到上式,这也是 AsinhGrad 只需要 y 和 dy 两个输入、不需要原始输入 x 的原因。
在仓库的算子原型注释中,给出了一个等价的数值稳定计算形式(见 math/asinh_grad/op_graph/asinh_grad_proto.h):
z = dy / cosh(y) = 2 * dy * exp(y) / (exp(2y) + 1)
该等价式只使用 exp、mul、add、div 等向量指令即可完成计算,避免了直接求 cosh 可能引入的中间精度问题,这也是 Kernel 实现采用的核心计算路径(详见下文“Kernel 实现”一节)。
该算子与 TensorFlow 框架的 AsinhGrad 算子保持兼容(math/asinh_grad/op_graph/asinh_grad_proto.h 注明 "Compatible with the TensorFlow operator AsinhGrad"),并由 math/asinh_grad/framework/asinh_grad_tf_plugin.cpp 完成 TF 侧的算子注册与参数映射。
产品支持情况
根据 math/asinh_grad/README.md,AsinhGrad 算子当前支持以下昇腾产品:
| 产品 | 是否支持 |
|---|---|
| Ascend 950PR/Ascend 950DT | √ |
| Atlas A3 训练系列产品/Atlas A3 推理系列产品 | √ |
| Atlas A2 训练系列产品/Atlas A2 推理系列产品 | √ |
| Atlas 200I/500 A2 推理产品 | √ |
| Atlas 推理系列产品 | √ |
| Atlas 训练系列产品 | √ |
从源码结构看,算子为 arch35(Ascend 950)体系单独提供了 Kernel 与 Tiling 实现(math/asinh_grad/op_kernel/arch35 与 math/asinh_grad/op_host/arch35),并在算子定义中显式配置了 ascend950 的 AICore 配置项(math/asinh_grad/op_host/asinh_grad_def.cpp),与上表所列产品支持范围一致。
参数说明
AsinhGrad 共 3 个张量参数,全部为必选参数,统一使用 ND 数据格式。参数明细如下(源自 math/asinh_grad/README.md):
| 参数名 | 输入/输出 | 描述 | 数据类型 | 数据格式 |
|---|---|---|---|---|
| y | 输入 | 前向计算输入张量,对应公式中 y,为 asinh 函数自变量 | FLOAT16、FLOAT、BFLOAT16 | ND |
| dy | 输入 | 上游传入的梯度张量,对应公式中 dy,数据类型须与 y 完全一致 | FLOAT16、FLOAT、BFLOAT16 | ND |
| dx | 输出 | 输出的输入梯度张量,对应公式中 dx,数据类型须与 y 完全一致 | FLOAT16、FLOAT、BFLOAT16 | ND |
上述接口定义在代码层面有严格的对应实现:
- 算子定义(math/asinh_grad/op_host/asinh_grad_def.cpp)中,输入
y、dy与输出z均声明为REQUIRED,数据类型集合为{ge::DT_FLOAT, ge::DT_FLOAT16, ge::DT_BF16},格式限定为FORMAT_ND,并开启AutoContiguous; - GE 算子原型(math/asinh_grad/op_graph/asinh_grad_proto.h)通过
REG_OP(AsinhGrad)注册.INPUT(y, ...)、.INPUT(dy, ...)、.OUTPUT(z, ...),数据类型同样限定为{DT_FLOAT16, DT_FLOAT, DT_BF16}。
此外,算子定义中开启了多项动态特性(math/asinh_grad/op_host/asinh_grad_def.cpp):
DynamicRankSupportFlag(true):支持动态 Rank;DynamicShapeSupportFlag(true):支持动态 Shape;DynamicCompileStaticFlag(true)与DynamicFormatFlag(false):支持动态编译、固定 ND 格式;PrecisionReduceFlag(true):允许精度降级优化。
约束说明
原文档对 AsinhGrad 的约束描述为“无”。结合源码可以进一步确认,算子层面的隐式约束均由实现代码校验并兜底,主要包括:
- 输入输出 Shape 必须一致:Tiling 阶段会校验
y、dy、z三者的元素总数完全相等,否则报错(math/asinh_grad/op_host/arch35/asinh_grad_tiling_arch35.cpp); y与dy数据类型必须一致:Tiling 校验二者 dtype 相同(math/asinh_grad/op_host/arch35/asinh_grad_tiling_arch35.cpp);- 不支持广播:原型注释明确说明 "Broadcasting is not supported"(math/asinh_grad/op_graph/asinh_grad_proto.h),
dy需与y保持同 Shape、同 dtype。
源码实现深度解析
1. Shape 与数据类型推导
- Shape 推导:
InferShape4AsinhGrad直接将输出 Shape 赋值为输入y的 Shape(math/asinh_grad/op_host/asinh_grad_infershape.cpp),即输出与输入逐元素一一对应; - 数据类型推导:
InferDataTypeForAsinhGrad将输出数据类型设置为输入y的类型(math/asinh_grad/op_graph/asinh_grad_graph_infer.cpp),保证dx与y类型一致。
2. Kernel 实现:FP16/BF16 升 FP32 计算的数值策略
Kernel 入口在 math/asinh_grad/op_kernel/asinh_grad.cpp,以模板类 NsAsinhGrad::AsinhGrad<D_T_Y, BUFFER_MODE> 承载计算逻辑(math/asinh_grad/op_kernel/arch35/asinh_grad.h)。其中:
- 模板参数
D_T_Y取C_DT_FLOAT / C_DT_FLOAT16 / C_DT_BF16,BUFFER_MODE取 0(单缓冲)或 1(双缓冲),二者组合由 TilingKey 声明(math/asinh_grad/op_kernel/arch35/asinh_grad_tiling_key.h); - FP16/BF16 路径:先
Cast升为 FP32,在 FP32 域内完成全部计算,最后用CAST_RINT(银行家舍入)降回原类型,避免低精度中间结果累积误差(math/asinh_grad/op_kernel/arch35/asinh_grad.h); - FP32 主路径:直接按
z = 2 * dy * exp(y) / (exp(2y) + 1)序列执行Exp → Mul → Adds → Mul → Div → Muls六步向量运算(math/asinh_grad/op_kernel/arch35/asinh_grad.h); - 流水结构:
CopyIn → Compute → CopyOut三段式流水(math/asinh_grad/op_kernel/arch35/asinh_grad.h),配合 VECIN/VECOUT 队列与可选的 VECCALC 中间缓冲,实现数据搬运与计算的并行。
3. Tiling 策略:多核切分与 UB 分配
Tiling 实现在 math/asinh_grad/op_host/arch35/asinh_grad_tiling_arch35.cpp,关键策略如下:
- 多核切分:
blockFactor = CeilAlign(CeilDiv(totalNum, coreNum), 32B),按 AIV 核数均匀切分,并 32 字节对齐; - UB 切分:
ubFactor = FloorAlign(FloorDiv(ubSize / bytesPerElem), 32B),根据 FP32/FP16 两条路径的缓冲占用保守估算每核单次处理的元素数; - 双缓冲开关:
totalNum > 1024时启用双缓冲(MIN_SPLIT_THRESHOLD = 1024),以 UB 空间换流水并行度(math/asinh_grad/op_host/arch35/asinh_grad_tiling_arch35.cpp 与 #L168); - Workspace:本算子不需要额外 Workspace,
GetWorkspaceSize返回 0(math/asinh_grad/op_host/arch35/asinh_grad_tiling_arch35.cpp)。
调用说明:GE 图模式完整示例
原文档提供的调用方式为图模式(GE IR)。完整可编译示例位于 math/asinh_grad/examples/test_geir_asinh_grad.cpp,此外在 math/asinh_grad/examples/arch35 下还提供了 arch35 平台版本。该示例通过 GE Session 构建计算图、编译并执行 AsinhGrad 算子,其关键流程如下:
1. 构造算子节点
auto asinhGradOp = op::AsinhGrad("asinh_grad_1");
std::vector<int64_t> xShape = {4, 4, 4};
其中 xShape = {4, 4, 4} 是示例中 y、dy、z 三者共用的张量形状,总共 64 个元素。
2. 添加输入占位符并生成输入数据
示例通过宏 ADD_INPUT 为每个输入创建 op::Data 占位节点,并用 TensorDesc(ge::Shape, FORMAT_ND, dtype) 声明 ND 格式与数据类型:
ADD_INPUT(1, y, inDtype, xShape);
ADD_INPUT(2, dy, inDtype, xShape);
输入数据的生成规则(math/asinh_grad/examples/test_geir_asinh_grad.cpp):
y:取线性分布pData[i] = i * 0.1f - 3.0f,即取值落在[-3.0, 3.3]区间,便于覆盖正负两侧的梯度形态;dy:全部填充1.0f,即假设上游梯度恒为 1,此时输出应等于1/cosh(y)。
3. 声明输出描述
ADD_OUTPUT(1, z, inDtype, xShape);
4. 初始化 GE 并运行图
std::map<AscendString, AscendString> global_options = {
{"ge.exec.deviceId", "0"}, {"ge.graphRunMode", "1"}};
Status ret = ge::GEInitialize(global_options);
...
ge::Session* session = new Session(build_options);
ret = session->AddGraph(graph_id, graph, graph_options);
ret = session->RunGraph(graph_id, input, output);
...
ge::GEFinalize();
5. 结果校验
运行后示例会打印输出数据,并与理论值比对:
float expected = 1.0f / std::cosh(y);
printf(" output[%ld] = %.6f (expected = %.6f)\n", j, outData[j], expected);
该示例还支持通过命令行参数切换输入精度:不传参默认 DT_FLOAT,传 fp16 使用 DT_FLOAT16,传 bf16 使用 DT_BF16(math/asinh_grad/examples/test_geir_asinh_grad.cpp),方便在同一用例下验证三种数据类型。
测试验证:UT 与 Kernel 单测
仓库为 AsinhGrad 提供了两级测试:
- Shape 推导 UT:math/asinh_grad/tests/ut/op_host/test_asinh_grad_infershape.cpp 验证
InferShape输出与输入y一致; - Kernel 单测(APT):math/asinh_grad/tests/ut/op_kernel/test_asinh_grad_apt.cpp 通过
ICPU_RUN_KF在 CPU 侧仿真执行 Kernel:test_fp32_basic:256 个元素的 FP32 小规模用例,blockFactor = ubFactor = 256,单核单次搬入计算;test_fp32_large:2048 个元素的 FP32 大规模用例,blockFactor = 2048、ubFactor = 1024,覆盖多轮 UB 循环切分的执行路径。
测试中通过 AscendC::GmAlloc/GmFree 管理 GM 内存,以 KernelMode::AIV_MODE 运行向量核路径,可直接作为修改 Kernel 后的回归验证入口。
小结
AsinhGrad 是一个结构清晰、实现完整的数学梯度算子:功能上通过 dx = dy / cosh(y) 完成反双曲正弦梯度的逐元素计算;实现上由 math/asinh_grad/op_host 的算子定义与推导、math/asinh_grad/op_kernel 的 Kernel 计算、math/asinh_grad/op_host/arch35 的 Tiling 调度三层构成,并针对 FP16/BF16 采用“升 FP32 计算、再降回”的精度策略。开发者可直接参考 math/asinh_grad/examples/test_geir_asinh_grad.cpp 完成图模式调用,并结合 math/asinh_grad/tests/ut/op_kernel/test_asinh_grad_apt.cpp 在本地验证算子行为。