CANN ops-math 算子开发实战:aclnnTanh 与 aclnnInplaceTanh 两段式接口详解
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(逐元素)的计算。
- 计算公式:
即对输入张量中的每一个元素 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),与上表错误码一一对应:
-
空指针检查(
CheckNotNull):self或out为 null 时返回ACLNN_ERR_PARAM_NULLPTR(161001); -
数据类型检查(
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 后输出为浮点结果,符合公式定义; -
数据格式检查(
CheckFormat):输入输出 ViewFormat 必须一致,私有格式直接报错;存储格式非 ND 时仅打印 warning 日志(资料约定只支持 ND); -
shape 检查(
CheckShape):self的维度不大于 8(MAX_SUPPORT_DIMS_NUMS),且self与outshape 一致。
校验通过后还有一项重要分支:若 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)]
各步骤职责如下:
L0::Contiguous:将非连续的输入self转换为连续 tensor。这正是上表"非连续 Tensor √"能力的实现基础——非连续输入(如切片、转置视图)无需用户手动contiguous(),框架层自动处理;L0::Cast(条件触发):若输入为DTYPE_CAST_LIST中的整型/布尔类型,先转换为 FLOAT32 进行计算,保证数值精度;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));L0::Cast(输出):将 tanh 计算结果转换为out声明时的数据类型,保证输出类型与用户预期一致;L0::ViewCopy:将结果拷贝到outtensor 上,即使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;
}
示例代码要点解读
- 流程骨架固定:
Init(aclInit → aclrtSetDevice → aclrtCreateStream)与收尾(aclrtSynchronizeStream → 资源释放 → aclFinalize)是所有单算子 API 调用的固定写法,可直接复用; - 张量构造的关键点:
CreateAclTensor中手动计算连续 tensor 的 strides 后调用aclCreateTensor,format 固定为ACL_FORMAT_ND。示例展示的是连续张量,若输入为切片/转置产生的非连续视图,仍可直接传入——底层L0::Contiguous会自动处理; - workspace 按需申请:
workspaceSize > 0时才调用aclrtMalloc申请临时内存,避免空转申请;释放时也以workspaceSize > 0为判据,与第一段接口返回值严格对应; - inplace 输出读取:inplace 计算后结果直接写入
selfDeviceAddr,因此结果回拷读取的是selfDeviceAddr指向的内存(示例第 5 步),而非单独的 out 地址; - 类型映射:示例使用
ACL_FLOAT(FLOAT32)。如需验证 FLOAT16/BFLOAT16 或整型输入,只需调整CreateAclTensor的dataType与 host 数据向量类型,并注意整型输入输出应为浮点类型。
小结与推荐阅读
aclnnTanh 与 aclnnInplaceTanh 是 CANN 数学算子库中典型的 elementwise 激活算子接口:两者共享同一套底层 L0 计算流水线(Contiguous → Cast → Tanh → Cast → ViewCopy),区别仅在于输出内存的归属——前者写入独立的 out 张量,后者原地覆写 selfRef。实际工程中,若后续仍需使用原始输入,请选择 aclnnTanh;若内存敏感且原始数据不再需要,aclnnInplaceTanh 可减少一次设备侧内存分配。
围绕本文涉及的概念,可以进一步阅读仓库文档深入了解:
- 两段式接口:workspace 与 executor 的完整语义;
- 编译与运行样例:示例代码的编译、链接与运行方式;
- aclnn返回码:161001/161002 等错误码的完整含义;
- 互推导关系:
self与out数据类型匹配规则; - 非连续Tensor:非连续输入的底层处理机制;
- 源码入口:aclnn_tanh.cpp、tanh.cpp、tanh_def.cpp、tanh_binary.json、golden.py。