CANN ops-nn FatreluMul 算子开发指南:aclnnFatreluMul 两段式接口原理、约束与完整调用示例

原创2026-09-18 11:40:241,325 阅读
文章标签:人工智能深度学习算子库高性能计算模型量化AscendCANN

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,计算过程分三步:

    1. 将 input 分割为两部分:

    x1=input[...,:d],x2=input[...,d:]x_1 = \text{input}[..., :d], \quad x_2 = \text{input}[..., d:]

    1. 对 x1 应用 Threshold 激活函数,定义如下:

    Threshold(x,threshold)={0if x<thresholdxif x≥threshold\text{Threshold}(x, \text{threshold}) = \begin{cases} 0 & \text{if } x < \text{threshold} \\ x & \text{if } x \geq \text{threshold} \end{cases}

    因此,计算:

    x1=Threshold(x1,threshold)x_1 = \text{Threshold}(x_1, \text{threshold})

    1. 最终输出是 x1 和 x2 的逐元素乘积:

    out=x1×x2\text{out} = x_1 \times x_2

该计算逻辑在仓库的 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 调用的标准七步法:

  1. 资源初始化:aclInit → aclrtSetDevice → aclrtCreateStream;
  2. 构造输入输出:CreateAclTensor 模板函数完成 device 内存申请(aclrtMalloc)、数据拷贝(aclrtMemcpy H2D)、连续 strides 计算,以及 aclCreateTensor 创建 aclTensor(格式固定为 ACL_FORMAT_ND);
  3. 第一段接口:aclnnFatreluMulGetWorkspaceSize 获取 workspaceSize 与 executor;
  4. 按需申请 workspace:仅当 workspaceSize > 0 时 aclrtMalloc;
  5. 第二段接口:aclnnFatreluMul 在指定 stream 上提交计算任务;
  6. 同步与取数:aclrtSynchronizeStream 等待任务完成,PrintOutResult 用 aclrtMemcpy(D2H)拷回结果;
  7. 资源释放: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 提供了完整的测试支撑,可作为理解算子行为与自行验证的参考:

总结

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 实现,掌握其行模型切分与双路径分发机制。

登录后查看全文
ops-nn