CANN ops-math 算子开发实战:aclnnTanh 与 aclnnInplaceTanh 两段式接口详解

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

CANN ops-math 算子开发实战:aclnnTanh 与 aclnnInplaceTanh 两段式接口详解

本文以 CANN ops-math 仓库中 Tanh 算子的官方接口文档为核心,系统讲解 aclnnTanh 与 aclnnInplaceTanh 两个 NPU 侧激活函数算子的功能定义、两段式调用流程、参数约束、错误码语义与完整示例代码,并结合仓库源码(aclnn_tanh.cpp、tanh.cpp、tanh_def.cpp)剖析底层实现路径,帮助开发者快速掌握在 CANN 环境中正确调用 Tanh 算子完成 elementwise 双曲正切计算,并理解原地(inplace)与非原地接口的取舍。

产品支持情况

Tanh 算子在 CANN ops-math 中针对不同昇腾产品线的支持情况如下表所示,开发者在跨产品部署时需要先确认目标硬件是否在支持列表内:

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

其中,Atlas 训练系列产品(对应 tanh_def.cpp 中的 ascend950、ascend350 AI Core 配置,以及 tanh_binary.json 中的算子二进制编排)不支持 BFLOAT16 数据类型,实际使用中应使用 FLOAT/FLOAT16 替代。

功能说明

Tanh(双曲正切)是深度学习网络中最常用的激活函数之一,其输出范围收敛于 (-1, 1),具有零中心对称特性,常用于隐藏层激活与归一化场景。

  • 算子功能:激活函数。返回与输入 tensor shape 相同的 tensor,对输入 tensor 进行 elementwise(逐元素)的计算。
  • 计算公式:

tanh(self)=eself−e−selfeself+e−selftanh(self)=\frac{e^{self}-e^{-self}}{e^{self} + e^{-self}}

即对输入张量中的每一个元素 self_i 独立计算上述公式,输出张量 out 与输入 self 拥有完全一致的 shape。仓库在 golden.py 中给出了等价的标准实现(以 numpy 为准),可作为验证 NPU 计算结果的基准:

def tanh_golden(x, **kwargs):
    ori_dtype = x.dtype
    if ori_dtype.name in ("float16", "bfloat16"):
        x_cast = x.astype(np.float32)
        res = np.tanh(x_cast)
        return res.astype(ori_dtype, copy=False)
    return np.tanh(x)

注意其中对 float16/bfloat16 的处理:先在 float32 精度下计算再回落到原精度,这与算子底层"低精度输入先提升精度计算"的实现思路一致(详见下文源码剖析)。

函数原型:aclnnTanh 与 aclnnInplaceTanh 的差异

aclnnTanh 和 aclnnInplaceTanh 实现相同的计算功能,二者的使用区别如下,请根据自身实际场景选择合适的算子:

  • aclnnTanh:需新建一个输出张量对象存储计算结果,输入 self 在计算后保持不变;
  • aclnnInplaceTanh:无需新建输出张量对象,直接在输入张量的内存中存储计算结果,可节省一份设备侧内存,适合不需要保留原始输入的推理或激活后立即消费结果的场景。

两个算子的完整原型定义位于 aclnn_tanh.h,均为标准的两段式接口(详见 两段式接口):必须先调用 aclnnTanhGetWorkspaceSize / aclnnInplaceTanhGetWorkspaceSize 第一段接口,获取计算所需 workspace 大小以及包含了算子计算流程的执行器;再调用 aclnnTanh / aclnnInplaceTanh 第二段接口执行计算。

aclnnStatus aclnnTanhGetWorkspaceSize(
  const aclTensor* self,
  aclTensor*       out,
  uint64_t*        workspaceSize,
  aclOpExecutor**  executor)
aclnnStatus aclnnTanh(
  void*             workspace,
  uint64_t          workspaceSize,
  aclOpExecutor*    executor,
  const aclrtStream stream)
aclnnStatus aclnnInplaceTanhGetWorkspaceSize(
  aclTensor*       selfRef,
  uint64_t*        workspaceSize,
  aclOpExecutor**  executor)
aclnnStatus aclnnInplaceTanh(
  void*             workspace,
  uint64_t          workspaceSize,
  aclOpExecutor*    executor,
  const aclrtStream stream)

需要特别强调的是,第二段接口(aclnnTanh / aclnnInplaceTanh)不能重复调用:同一个 executor 仅对应一次计算流程,重复调用会导致异常。如需多次计算,必须重新走一遍"第一段获取 workspace 与 executor → 第二段执行"的完整流程。

aclnnTanhGetWorkspaceSize:第一段接口参数说明

  • 参数说明:
参数名 输入/输出 描述 使用说明 数据类型 数据格式 维度(shape) 非连续Tensor
self(aclTensor*) 输入 公式中的输入self。 shape需要与out一致,和out的数据类型满足互推导关系。 FLOAT、FLOAT16、BOOL、UINT8、INT8、INT16、INT32、INT64、BFLOAT16 ND 不大于8 √
out(aclTensor*) 输出 公式中的out。 shape需要与self一致,和self的数据类型满足互推导关系。 FLOAT、FLOAT16、BFLOAT16 ND - √
workspaceSize(uint64_t*) 输出 返回需要在Device侧申请的workspace大小。 - - - - -
executor(aclOpExecutor**) 输出 返回op执行器,包含了算子计算流程。 - - - - -
  • Atlas 训练系列产品:不支持 BFLOAT16。

  • 返回值:

    aclnnStatus:返回状态码,具体参见 aclnn返回码。

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

返回值 错误码 描述
ACLNN_ERR_PARAM_NULLPTR 161001 传入的self或out是空指针。
ACLNN_ERR_PARAM_INVALID 161002 self和out的数据类型和数据格式不在支持的范围之内。
self和out的数据类型不满足互推导关系。
self和out的维度大于8。
self和out的shape不一致。

参数细节与底层校验逻辑

从源码 aclnn_tanh.cpp 可以看到,aclnnTanhGetWorkspaceSize 内部按固定顺序完成四步参数校验(CheckParams),与上表错误码一一对应:

  1. 空指针检查(CheckNotNull):self 或 out 为 null 时返回 ACLNN_ERR_PARAM_NULLPTR(161001);

  2. 数据类型检查(CheckDtypeValid):self 与 out 的类型必须落在当前架构支持列表内,且二者满足互推导关系。源码中针对不同架构维护了两套支持列表:

    • ASCEND910_DTYPE_SUPPORT_LIST(对应 Atlas 训练系列产品):FLOAT、FLOAT16、BOOL、UINT8、INT8、INT16、INT32、INT64,输出仅 FLOAT、FLOAT16;
    • ASCEND910B_DTYPE_SUPPORT_LIST(对应 Atlas A2/A3 系列等):额外支持 BFLOAT16。

    值得关注的是 DTYPE_CAST_LIST(BOOL、UINT8、INT8、INT16、INT32、INT64):当输入为整型/布尔类型时,底层会先将其转换为 FLOAT32 再参与 tanh 计算,这也是为什么 self 允许整型输入而 out 只支持浮点类型——整型输入经过 cast 后输出为浮点结果,符合公式定义;

  3. 数据格式检查(CheckFormat):输入输出 ViewFormat 必须一致,私有格式直接报错;存储格式非 ND 时仅打印 warning 日志(资料约定只支持 ND);

  4. shape 检查(CheckShape):self 的维度不大于 8(MAX_SUPPORT_DIMS_NUMS),且 self 与 out shape 一致。

校验通过后还有一项重要分支:若 self 或 out 为空 tensor(IsEmpty),则直接返回 workspaceSize = 0,无需真正申请 workspace。

aclnnTanh:第二段接口参数说明

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

    aclnnStatus:返回状态码,具体参见 aclnn返回码。

第二段接口本身不进行参数语义校验,而是通过 CommonOpExecutorRun 将第一段接口构建好的计算流程按 executor 提交到指定 stream 上异步执行(见 aclnn_tanh.cpp)。

底层计算流程剖析

在 aclnn_tanh.cpp 的 ExecTanhGetWorkspaceSize 中,可以清晰看到 tanh 算子在 L0 层的完整执行流水线,与 aclnn_tanh.h 头文件中的 mermaid 注释图一致:

graph LR
    A[(self)] -->B([L0::Contiguous])
    B --> C([L0::Tanh])
    C --> D([L0::ViewCopy])
    D --> E[(out)]

各步骤职责如下:

  1. L0::Contiguous:将非连续的输入 self 转换为连续 tensor。这正是上表"非连续 Tensor √"能力的实现基础——非连续输入(如切片、转置视图)无需用户手动 contiguous(),框架层自动处理;
  2. L0::Cast(条件触发):若输入为 DTYPE_CAST_LIST 中的整型/布尔类型,先转换为 FLOAT32 进行计算,保证数值精度;
  3. L0::Tanh:真正的核心计算。对应 tanh.cpp 中的 l0op::Tanh,它通过 AllocTensor 按输入的存储 shape 与数据类型分配中间结果,并通过 ADD_TO_LAUNCHER_LIST_AICORE 将 AICore 算子任务(tanh_apt,见 tanh_apt.cpp)加入执行队列。算子定义侧(tanh_def.cpp)注册了 ascend950 与 ascend350 两个 AI Core 配置,支持动态 rank、动态 shape 与精度规约(PrecisionReduceFlag(true));
  4. L0::Cast(输出):将 tanh 计算结果转换为 out 声明时的数据类型,保证输出类型与用户预期一致;
  5. L0::ViewCopy:将结果拷贝到 out tensor 上,即使 out 是非连续 tensor 也能正确落位。

最后 *workspaceSize = uniqueExecutor->GetWorkspaceSize() 汇总整条流水线所需的临时内存大小。此外,tanh_def.cpp 中通过 ExtendCfgInfo("opFile.value", "tanh_apt") 与 tanh_binary.json 完成算子二进制与输入类型(float16/float32/bfloat16,shape 用 -2 表示动态)的匹配映射,shape 推导则复用 elewise 通用规则 InferShape4Elewise(见 tanh_infershape.cpp)。

aclnnInplaceTanhGetWorkspaceSize:第一段接口参数说明

  • 参数说明:
参数名 输入/输出 描述 使用说明 数据类型 数据格式 维度(shape) 非连续Tensor
selfRef(aclTensor*) 输入/输出 公式中的self。 - FLOAT、FLOAT16、BFLOAT16 ND 不大于8 √
workspaceSize(uint64_t*) 输出 返回需要在Device侧申请的workspace大小。 - - - - -
executor(aclOpExecutor**) 输出 返回op执行器,包含了算子计算流程。 - - - - -
  • Atlas 训练系列产品:不支持 BFLOAT16。

  • 返回值:

    aclnnStatus:返回状态码,具体参见 aclnn返回码。

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

返回值 错误码 描述
ACLNN_ERR_PARAM_NULLPTR 161001 传入的selfRef是空指针。
ACLNN_ERR_PARAM_INVALID 161002 selfRef的数据类型不在支持的范围之内。

原地接口的实现要点

从源码 aclnn_tanh.cpp 可以看到,aclnnInplaceTanhGetWorkspaceSize 先通过 CheckInplaceParams 做轻量校验:仅检查 selfRef 非空及其数据类型是否在输出支持列表(FLOAT、FLOAT16、BFLOAT16,即 GetOutDtypeSupportList,随架构切换)之内。随后直接执行 auto out = const_cast<aclTensor*>(selfRef),将 selfRef 同时作为输入与输出传给 ExecTanhGetWorkspaceSize——"原地"语义由此实现:计算结果通过 ViewCopy 直接写回输入 tensor 的内存。

这也解释了为何 inplace 接口的 selfRef 数据类型仅限浮点类型:整型/布尔输入需要 cast 到 FLOAT32 计算,无法在原有内存中原地完成,因此不提供 inplace 支持。

aclnnInplaceTanh:第二段接口参数说明

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

    aclnnStatus:返回状态码,具体参见 aclnn返回码。

约束说明

  • 确定性计算:aclnnTanh 与 aclnnInplaceTanh 默认即确定性实现(deterministic),即相同输入在同一硬件与软件栈下多次运行得到逐位一致的结果,便于调试与结果复现(相关概念可参考 确定性计算 与 基础概念)。
  • 其他约束(数据格式仅 ND、维度不大于 8、shape 一致、类型互推导等)已在前文各接口的参数表格中列出,调用前请逐项核对。

调用示例

以下示例代码演示如何在 CANN 环境中完整调用 aclnnTanh 与 aclnnInplaceTanh,涵盖环境初始化、张量构造、两段式调用、结果回拷与资源释放全流程。该示例与仓库中的 examples/test_aclnn_tanh.cpp 及 测试用例 结构一致,仅供参考,具体编译和执行过程请参考 编译与运行样例。

#include <iostream>
#include <vector>
#include "acl/acl.h"
#include "aclnnop/aclnn_tanh.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_RET(ret == ACL_SUCCESS, LOG_PRINT("Init acl failed. ERROR: %d\n", ret); return ret);
  // 2.构造输入与输出,需要根据API的接口自定义构造
  std::vector<int64_t> selfShape = {2, 2};
  std::vector<int64_t> outShape = {2, 2};
  void* selfDeviceAddr = nullptr;
  void* outDeviceAddr = nullptr;
  aclTensor* self = nullptr;
  aclTensor* out = nullptr;
  std::vector<float> selfHostData = {0, 1, 2, 3};
  std::vector<float> outHostData = {0, 0, 0, 0};
  // 创建self aclTensor
  ret = CreateAclTensor(selfHostData, selfShape, &selfDeviceAddr, aclDataType::ACL_FLOAT, &self);
  CHECK_RET(ret == ACL_SUCCESS, return ret);
  // 创建out aclTensor
  ret = CreateAclTensor(outHostData, outShape, &outDeviceAddr, aclDataType::ACL_FLOAT, &out);
  CHECK_RET(ret == ACL_SUCCESS, return ret);
  // 3.调用CANN算子库API,需要修改为具体的API名称
  // aclnnTanh接口调用示例
  uint64_t workspaceSize = 0;
  aclOpExecutor* executor;
  // 调用aclnnTanh第一段接口
  ret = aclnnTanhGetWorkspaceSize(self, out, &workspaceSize, &executor);
  CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclnnTanhGetWorkspaceSize 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);
  }
  // 调用aclnnTanh第二段接口
  ret = aclnnTanh(workspaceAddr, workspaceSize, executor, stream);
  CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclnnTanh failed. ERROR: %d\n", ret); return ret);

  // aclnnInplaceTanh接口调用示例
  uint64_t inplaceWorkspaceSize = 0;
  aclOpExecutor* inplaceExecutor;
  // 调用aclnnInplaceTanh第一段接口
  ret = aclnnInplaceTanhGetWorkspaceSize(self, &inplaceWorkspaceSize, &inplaceExecutor);
  CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclnnInplaceTanhGetWorkspaceSize failed. ERROR: %d\n", ret); return ret);
  // 根据第一段接口计算出的workspaceSize申请device内存
  void* inplaceWorkspaceAddr = nullptr;
  if (inplaceWorkspaceSize > 0) {
    ret = aclrtMalloc(&inplaceWorkspaceAddr, inplaceWorkspaceSize, ACL_MEM_MALLOC_HUGE_FIRST);
    CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("allocate workspace failed. ERROR: %d\n", ret); return ret);
  }
  // 调用aclnnInplaceTanh第二段接口
  ret = aclnnInplaceTanh(inplaceWorkspaceAddr, inplaceWorkspaceSize, inplaceExecutor, stream);
  CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclnnInplaceTanh 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("aclnnTanh result[%ld] is: %f\n", i, resultData[i]);
  }

  auto inplaceSize = GetShapeSize(selfShape);
  std::vector<float> inplaceResultData(inplaceSize, 0);
  ret = aclrtMemcpy(inplaceResultData.data(), inplaceResultData.size() * sizeof(inplaceResultData[0]), selfDeviceAddr, inplaceSize * sizeof(inplaceResultData[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 < inplaceSize; i++) {
    LOG_PRINT("aclnnInplaceTanh result[%ld] is: %f\n", i, inplaceResultData[i]);
  }

  // 6.释放aclTensor和aclScalar,需要根据具体API的接口定义修改
  aclDestroyTensor(self);
  aclDestroyTensor(out);

  // 7.释放device资源,需要根据具体API的接口定义修改
  aclrtFree(selfDeviceAddr);
  aclrtFree(outDeviceAddr);
  if (workspaceSize > 0) {
    aclrtFree(workspaceAddr);
  }
  if (inplaceWorkspaceSize > 0) {
    aclrtFree(inplaceWorkspaceAddr);
  }
  aclrtDestroyStream(stream);
  aclrtResetDevice(deviceId);
  aclFinalize();
  return 0;
}

示例代码要点解读

  1. 流程骨架固定:Init(aclInit → aclrtSetDevice → aclrtCreateStream)与收尾(aclrtSynchronizeStream → 资源释放 → aclFinalize)是所有单算子 API 调用的固定写法,可直接复用;
  2. 张量构造的关键点:CreateAclTensor 中手动计算连续 tensor 的 strides 后调用 aclCreateTensor,format 固定为 ACL_FORMAT_ND。示例展示的是连续张量,若输入为切片/转置产生的非连续视图,仍可直接传入——底层 L0::Contiguous 会自动处理;
  3. workspace 按需申请:workspaceSize > 0 时才调用 aclrtMalloc 申请临时内存,避免空转申请;释放时也以 workspaceSize > 0 为判据,与第一段接口返回值严格对应;
  4. inplace 输出读取:inplace 计算后结果直接写入 selfDeviceAddr,因此结果回拷读取的是 selfDeviceAddr 指向的内存(示例第 5 步),而非单独的 out 地址;
  5. 类型映射:示例使用 ACL_FLOAT(FLOAT32)。如需验证 FLOAT16/BFLOAT16 或整型输入,只需调整 CreateAclTensor 的 dataType 与 host 数据向量类型,并注意整型输入输出应为浮点类型。

小结与推荐阅读

aclnnTanh 与 aclnnInplaceTanh 是 CANN 数学算子库中典型的 elementwise 激活算子接口:两者共享同一套底层 L0 计算流水线(Contiguous → Cast → Tanh → Cast → ViewCopy),区别仅在于输出内存的归属——前者写入独立的 out 张量,后者原地覆写 selfRef。实际工程中,若后续仍需使用原始输入,请选择 aclnnTanh;若内存敏感且原始数据不再需要,aclnnInplaceTanh 可减少一次设备侧内存分配。

围绕本文涉及的概念,可以进一步阅读仓库文档深入了解:

登录后查看全文
ops-math