CANN ops-nn FatreluMul 算子开发指南:aclnnFatreluMul 两段式接口原理、约束与完整调用示例
CANN ops-nn FatreluMul 算子开发指南:aclnnFatreluMul 两段式接口原理、约束与完整调用示例
FatreluMul 是 CANN 神经网络算子库 ops-nn 中一个面向 NPU 加速的融合激活算子:它将输入张量沿最后一维对半切分为左右两部分,对左半部分执行 Threshold 截断后再与右半部分逐元素相乘,常用于门控类激活结构的快速实现。本文以 aclnnFatreluMul 接口文档 为核心,完整讲解该算子的数学定义、产品支持矩阵、两段式 aclnn 接口的函数原型与参数约束、错误码场景,并给出可直接编译运行的 C++ 调用示例,同时结合仓库内 op_host 与 op_kernel 的源码实现,剖析其 shape 推导、tiling 切分与 kernel 分发原理。读完本文,你将掌握在 Atlas 系列与 Ascend 950 等产品上正确调用 FatreluMul 算子的完整方法。
产品支持情况
FatreluMul 算子面向不同昇腾硬件产品线有着明确的差异化支持策略,以下表格与接口文档保持完全一致:
| 产品 | 是否支持 |
|---|---|
| Ascend 950PR / Ascend 950DT | 支持 |
| Atlas A3 训练系列产品 / Atlas A3 推理系列产品 | 支持 |
| Atlas A2 训练系列产品 / Atlas A2 推理系列产品 | 支持 |
| Atlas 200I/500 A2 推理产品 | 不支持 |
| Atlas 推理系列产品 | 不支持 |
| Atlas 训练系列产品 | 不支持 |
从算子注册源码 fatrelu_mul_def.cpp 可以看到,AICore 配置显式声明了 ascend910b、ascend910_93、ascend950、kirinx90、kirin9030 等 SOC 场景,其中 ascend950 配置覆盖 Ascend950PR / Ascend950DT,Kirin 系列(Atlas Kirin X90 / Kirin 9030 处理器系列)则通过 GetKirinCoreConfig() 单独注册。需要注意一个与接口文档互为补充的数据类型差异:Atlas Kirin X90 与 Atlas Kirin 9030 处理器系列不支持 BFLOAT16(其数据类型仅限定为 FLOAT16、FLOAT),而其他支持的产品上 BFLOAT16、FLOAT16、FLOAT 均可用,这一点在接口文档、README 与 def.cpp 的 Kirin 配置中保持一致。
功能说明与数学定义
FatreluMul 的名字由 "FatReLU"(Faster Than ReLU 一类门控激活的工程化实现)与 "Mul" 组合而来,其接口功能与数学定义如下:
-
接口功能:将输入 Tensor 按照最后一个维度分为左右两个 Tensor:x1 和 x2,对左边的 x1 进行 Threshold 计算,将计算结果与 x2 相乘。
-
计算公式:给定输入张量
input,最后一维的长度为 2d,计算过程分三步:- 将 input 分割为两部分:
- 对 x1 应用 Threshold 激活函数,定义如下:
因此,计算:
- 最终输出是 x1 和 x2 的逐元素乘积:
该计算逻辑在仓库的 ST 测试参考实现 executor_aclnnFatreluMul.py 中可以得到直接印证:测试代码先将末维对半切分为 x1 = input_tensor[..., :d] 与 x2 = input_tensor[..., d:],再调用 torch.threshold(x1, threshold.item(), 0.0) 完成截断,最后返回 x1 * x2。由此也可见算子的典型应用场景:当门控激活的原始实现包含 Threshold(x1, t) * x2 时,FatreluMul 将其融合为单个算子,省去一次显式的切分与中间张量落盘。
两段式接口与函数原型
每个 aclnn 算子均采用两段式接口调用,必须先调用 aclnnFatreluMulGetWorkspaceSize 接口获取入参并根据计算流程计算所需 workspace 大小,再调用 aclnnFatreluMul 接口执行计算。两段式接口的设计背景可参考 两段式接口说明。
第一段接口(计算 workspace 大小并生成执行器):
aclnnStatus aclnnFatreluMulGetWorkspaceSize(
const aclTensor *input,
const aclTensor *threshold,
const aclTensor *out,
uint64_t *workspaceSize,
aclOpExecutor **executor)
第二段接口(执行算子计算):
aclnnStatus aclnnFatreluMul(
void *workspace,
uint64_t workspaceSize,
aclOpExecutor *executor,
aclrtStream stream)
aclnnFatreluMulGetWorkspaceSize 参数详解
第一段接口共 5 个参数,其中前 3 个为算子数据参数,后 2 个为输出型参数,具体说明如下:
| 参数名 | 输入/输出 | 描述 | 使用说明 | 数据类型 | 数据格式 | 维度(shape) | 非连续Tensor |
|---|---|---|---|---|---|---|---|
| input(aclTensor*) | 输入 | 输入的张量,公式中的 input。 | 支持空 Tensor;最后一维值为偶数且小于等于 1024;其他维度的乘积小于等于 200000。 | BFLOAT16、FLOAT16、FLOAT | ND | 2-8 | √ |
| threshold(aclTensor*) | 输入 | Threshold 计算的边界值,公式中的 threshold。 | 数据类型和数据格式与 input 保持一致;要求 tensor 中元素只有一个;不支持 NaN 和 Inf。 | BFLOAT16、FLOAT16、FLOAT | ND | 0-8 | √ |
| out(aclTensor*) | 输出 | 输出的张量,公式中的 out。 | 输出的数据类型与输入 input 的数据类型保持一致;输出 shape 最后一维的值为输入 shape 最后一维值的二分之一;其他维度的值和输入 input 的 shape 其他维度的值保持一致。 | BFLOAT16、FLOAT16、FLOAT | ND | 2-8 | √ |
| workspaceSize(uint64_t*) | 输出 | 返回需要在 Device 侧申请的 workspace 大小。 | - | - | - | - | - |
| executor(aclOpExecutor**) | 输出 | 返回 op 执行器,包含了算子计算流程。 | - | - | - | - | - |
关于参数约束,需要特别强调以下要点:
- input 末维必须是偶数,因为它要被均分为 2d 的两半;末维上限 1024 与非末维乘积上限 200000 直接来自老代际 tiling 实现的校验逻辑(fatrelu_mul_tiling.cpp 中
lastDimSize > 1024与batchSize > 200000即报错返回),同时也是 Host 侧 tiling 保证计算规模可被 UB 承接的工程约束。 - threshold 是单元素标量张量,可以是 0 维(shape 0-8 的范围覆盖了 0-d 情形),其元素数量必须严格等于 1;且 threshold 不支持 NaN 与 Inf,因为 NaN/Inf 会使 Threshold 比较分支产生不确定结果。
- out 的 shape 完全由 input 决定:末维减半、其余维不变、dtype 一致。这一规则在 fatrelu_mul_infershape.cpp 的
InferShape4FatreluMul中落地实现:输出维度数等于输入维度数,末维通过lastDim / 2计算,未知维度(-1)与未知 rank(-2)则原样透传;InferDataType4FatreluMul则将输出 dtype 直接置为输入 dtype。同时该文件对非连续输入不敏感,配合def.cpp中三路 IO 的.AutoContiguous()声明,非连续 Tensor 在进入 kernel 前会自动整理为 ND 连续排布,这正是接口参数表中"非连续 Tensor √"的底层支撑。
返回值与错误场景
两段接口的返回值均为 aclnnStatus 状态码,具体可参见 aclnn 返回码说明。第一段接口会完成入参校验,出现以下场景时报错:
| 返回码 | 错误码 | 描述 |
|---|---|---|
| ACLNN_ERR_PARAM_NULLPTR | 161001 | 传入的 input、threshold 或 out 是空指针。 |
| ACLNN_ERR_PARAM_INVALID | 161002 | input 的数据类型不在支持的范围之内。 |
需要说明的是,上表来自接口文档中给出的错误码映射(其中 161002 行原文即仅列明 "input 的数据类型不在支持的范围之内" 一条场景),而 Host 侧 tiling 的 fatrelu_mul_tiling_arch35.cpp 在接口层之下还做了一层纵深防御校验,其校验顺序为 dtype → format → 维度 → shape:dtype 必须属于 {FLOAT, FLOAT16, BF16} 且 threshold/y 与 x 同 dtype;三路 IO 均须为 ND 格式;x 的 rank 必须在 [2, 8] 且 y 与 x 等秩;threshold 元素数必须为 1;x 末维必须为偶数且 y 末维等于其一半。这些校验保证即使绕开接口层直达 tiling,也不会把非法 shape/dtype 带进切分计算。
aclnnFatreluMul 执行接口参数
第二段接口的 4 个参数均为输入型参数,其中 workspace 相关两项由第一段接口配合产生:
| 参数名 | 输入/输出 | 描述 |
|---|---|---|
| workspace | 输入 | 在 Device 侧申请的 workspace 内存地址。 |
| workspaceSize | 输入 | 在 Device 侧申请的 workspace 大小,由第一段接口 aclnnFatreluMulGetWorkspaceSize 获取。 |
| executor | 输入 | op 执行器,包含了算子计算流程。 |
| stream | 输入 | 指定执行任务的 Stream。 |
调用范式为:先用第一段接口拿到 workspaceSize 与 executor,再按 workspaceSize 通过 aclrtMalloc 在 Device 侧申请内存(当 workspaceSize > 0 时才需要申请),随后将其与 executor、stream 一并传入第二段接口执行。值得注意的是,arch35 的 tiling 实现会将 workspace 显式置 0(fatrelu_mul_tiling_arch35.cpp 中 workspaces[0] = 0),即该实现路径下算子本身不需要 Device workspace;而 arch22 老代际实现则固定申请 16MB workspace(SIZE_16 * LENGTH_1024 * LENGTH_1024)。因此调用侧仍必须严格遵循"先取 workspaceSize、再按需申请"的通用流程,以同时兼容两种实现。
约束说明
- 确定性计算:aclnnFatreluMul 默认确定性实现,同一输入多次执行结果一致。
- 尾轴对齐建议:典型场景尾轴为 16 的倍数,当尾轴为非 32Byte 对齐时,建议走小算子拼接逻辑。这一约束源于 Vector 指令对 32B(一个 block)对齐的访存偏好:当末维长度不是 32 字节的整数倍时,单行末尾会出现跨 block 的零头数据,采用小算子拼接(或等价的对齐策略)可避免额外的边界处理开销。
完整调用示例
示例代码如下(与仓库 examples/arch35/test_aclnn_fatrelu_mul.cpp 内容一致),仅供参考,具体编译和执行过程请参考 编译与运行样例。
#include <iostream>
#include <vector>
#include "acl/acl.h"
#include "aclnnop/aclnn_fatrelu_mul.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;
}
void PrintOutResult(std::vector<int64_t> &shape, void** deviceAddr) {
auto size = GetShapeSize(shape);
std::vector<float> resultData(size, 0);
auto ret = aclrtMemcpy(resultData.data(), resultData.size() * sizeof(resultData[0]),
*deviceAddr, 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);
for (int64_t i = 0; i < size; i++) {
LOG_PRINT("mean result[%ld] is: %f\n", i, resultData[i]);
}
}
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> inputShape = {2, 4};
std::vector<float> inputHostData = {0, 1, 2, 3, 4, 5, 6, 7};
void* inputDeviceAddr = nullptr;
aclTensor* input = nullptr;
// 创建threshold aclTensor
ret = CreateAclTensor(inputHostData, inputShape, &inputDeviceAddr, aclDataType::ACL_FLOAT, &input);
CHECK_RET(ret == ACL_SUCCESS, return ret);
// 创建threshold aclTensor
std::vector<int64_t> threShape = {1};
std::vector<float> threData = {0.01};
void* threDeviceAddr = nullptr;
aclTensor* threshold = nullptr;
// 创建threshold aclTensor
ret = CreateAclTensor(threData, threShape, &threDeviceAddr, aclDataType::ACL_FLOAT, &threshold);
CHECK_RET(ret == ACL_SUCCESS, return ret);
std::vector<int64_t> outShape = {2, 2};
std::vector<float> outHostData(2 * 2, 1);
aclTensor* out = nullptr;
void* outDeviceAddr = nullptr;
// 创建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 = 16 * 1024 * 1024;
aclOpExecutor* executor;
// 调用aclnnFatreluMul第一段接口
ret = aclnnFatreluMulGetWorkspaceSize(input, threshold, out, &workspaceSize, &executor);
CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclnnFatreluMulGetWorkspaceSize 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);
}
// 调用aclnnFatreluMul第二段接口
ret = aclnnFatreluMul(workspaceAddr, workspaceSize, executor, stream);
CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclnnFatreluMul 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的接口定义修改
PrintOutResult(outShape, &outDeviceAddr);
// 6. 释放aclTensor,需要根据具体API的接口定义修改
aclDestroyTensor(input);
aclDestroyTensor(threshold);
aclDestroyTensor(out);
// 7.释放device资源,需要根据具体API的接口定义修改
aclrtFree(inputDeviceAddr);
aclrtFree(threDeviceAddr);
aclrtFree(outDeviceAddr);
if (workspaceSize > 0) {
aclrtFree(workspaceAddr);
}
aclrtDestroyStream(stream);
aclrtResetDevice(deviceId);
aclFinalize();
return 0;
}
示例代码解析
以示例数据 inputShape = {2, 4}、input = {0,1,2,3,4,5,6,7}、threshold = 0.01 为例,可以手工推演整个计算过程:末维 4 对半切分得到 x1 = {0,1,2,3,4,5,6,7} 的每行前两列 {0,1} 与 {4,5},x2 为每行后两列 {2,3} 与 {6,7};对 x1 做 Threshold(0.01) 截断后,0 和 4(均 ≥ 0.01,4 直接保留)原样保留,因此输出 shape 为 {2,2}。示例代码虽沿用通用模板(如 workspaceSize 初值 16MB 仅为占位,实际值以第一段接口回填为准),但其整体流程完整展示了 aclnn 调用的标准七步法:
- 资源初始化:
aclInit→aclrtSetDevice→aclrtCreateStream; - 构造输入输出:
CreateAclTensor模板函数完成 device 内存申请(aclrtMalloc)、数据拷贝(aclrtMemcpyH2D)、连续 strides 计算,以及aclCreateTensor创建 aclTensor(格式固定为ACL_FORMAT_ND); - 第一段接口:
aclnnFatreluMulGetWorkspaceSize获取workspaceSize与executor; - 按需申请 workspace:仅当
workspaceSize > 0时aclrtMalloc; - 第二段接口:
aclnnFatreluMul在指定stream上提交计算任务; - 同步与取数:
aclrtSynchronizeStream等待任务完成,PrintOutResult用aclrtMemcpy(D2H)拷回结果; - 资源释放:
aclDestroyTensor销毁张量、aclrtFree释放 device 内存、aclrtDestroyStream/aclrtResetDevice/aclFinalize收尾。
源码级实现剖析
了解调用方式后,进一步理解底层实现有助于排查问题与性能调优。FatreluMul 在仓库内的完整实现链路为:OpDef 注册 → InferShape/InferDataType → Host 侧 Tiling → Ascend C Kernel 分发执行。
算子定义层(OpDef)
fatrelu_mul_def.cpp 中通过 OP_ADD(FatreluMul) 注册算子,核心信息包括:
- 三个 IO 槽位:
x(输入)、threshold(输入)、y(输出),数据类型均为{DT_BF16, DT_FLOAT16, DT_FLOAT},格式均为FORMAT_ND,且均带.AutoContiguous(),支持非连续输入自动整理; - 多 SOC 的 AICore 配置:
ascend910b、ascend910_93使用默认配置;ascend950(覆盖 950PR/950DT)启用动态编译(DynamicCompileStaticFlag(true))、动态 rank(2D~8D)、动态 shape,并设置opFile.value = "fatrelu_mul_apt"指向 kernel 源文件;kirinx90/kirin9030复用GetKirinCoreConfig(),其数据类型收窄为{DT_FLOAT16, DT_FLOAT}(不含 BF16)。
Host 侧 Tiling
不同代际硬件对应两套 tiling 实现:
- arch22 老代际(fatrelu_mul_tiling.cpp):按 dtype 选择 tiling key(HALF=1 / FLOAT=2 / BFLOAT16=3),校验末维为偶数、末维 ≤ 1024、batch ≤ 200000、threshold 单元素,再依据"每核最多 10K 元素"的预算计算参与核数,workspace 固定 16MB,TilingData 仅含
lastDimSize/batchSize/needCoreNum三字段。 - arch35(fatrelu_mul_tiling_arch35.cpp):实现更精细的"行模型"切分。核心流程为:平台量获取(优先使用编译期缓存的 CompileInfo,并对异常垃圾值做可信度防御,回退到运行期
PlatformAscendC查询)→ 异常值校验 → 将输入展开为(batchSize, 2*halfDim)行模型 → 空 Tensor 短路 → 按 UB 容量与每元素 buffer 深度反推tileElems(256B 对齐,fp32 深度 12B/元素、fp16/bf16 深度 18B/元素)→ 按"每核 ≥ 4KB 数据、行不可跨核拆分"原则做多核切分(大小核均衡)→ 依据halfDim与tileElems的对比判界选择路径(FATRELUMUL_PATH_SMALL_TAIL行打包 /FATRELUMUL_PATH_BIG_TAIL行分段)→ 填充 7 字段 TilingData 并SetBlockDim/SetTilingKey。
Kernel 分发执行
kernel 入口在 fatrelu_mul_apt.cpp:FatreluMul<D_T_X, kPath> 模板函数接收 GM_ADDR 形式的 input / threshold / output / workspace / tiling,通过 REGISTER_NONE_TILING 注册、声明为 KERNEL_TYPE_AIV_ONLY(纯 Vector 算子,仅跑 AIV 核),用 GET_TILING_DATA_WITH_STRUCT 反序列化 TilingData,再做核守卫(blockIdx >= need_core_num 直接返回),最后实例化 FatreluMulKernel<D_T_X, kPath> 执行 Init / Process。模板参数 D_T_X(dtype)与 kPath(路径)由 FatreluMul_struct.h 中的 ASCENDC_TPL_SEL 声明实例化,3 种 dtype × 2 条路径共 6 个 sub-kernel,host 侧通过 tilingKey 的位编码(dtype 占低 8 bit、PATH 下标占 bit 8)选择具体实例;snake_case 入口 fatrelu_mul 则作为构建系统的适配层转发到 FatreluMul。老代际 kernel 入口见 fatrelu_mul.cpp,同样按 tiling key 分发到 half / float / bfloat16_t 三种 FatreluMulND<T> 实例。
测试与验证
仓库为 FatreluMul 提供了完整的测试支撑,可作为理解算子行为与自行验证的参考:
- ST 测试:executor_aclnnFatreluMul.py 以 PyTorch 实现
torch.threshold+ 切分相乘的参考语义,配套 atk_aclnnFatreluMul.json 定义用例数据,用于算子结果的精度比对; - UT 测试:test_fatrelu_mul_infershape.cpp 覆盖 shape 推导(含未知维度透传),test_fatrelu_mul_tiling.cpp 覆盖 tiling 计算,gen_data.py 与 compare_data.py 则负责 kernel 级数据生成与结果比对。
总结
FatreluMul 是 ops-nn 中一个结构紧凑、约束清晰的融合激活算子:数学上等价于 Threshold(x1, t) * x2,接口上遵循 aclnn 两段式调用范式,约束上以"末维偶数且 ≤ 1024、其余维乘积 ≤ 200000、threshold 单元素、三路 IO 同 dtype 同 ND 格式"为核心。理解其参数语义、错误码场景与完整调用流程后,你可以直接在支持的产品上(Ascend 950PR/950DT、Atlas A2/A3 训练与推理系列)快速集成该算子;若需深入调优,可进一步研读 op_host 与 op_kernel 下的 tiling 与 kernel 实现,掌握其行模型切分与双路径分发机制。