企业官网建设流程全解析

CANN ops-nn aclnnGeGlu 算子接口详解：GeGLU 高斯误差线性门控单元的两段式调用与 NPU 实现

【免费下载链接】ops-nn本项目是CANN提供的神经网络类计算算子库，实现网络在NPU上加速计算。项目地址: https://gitcode.com/cann/ops-nn

导读

aclnnGeGlu是 CANN ops-nn 神经网络算子库中GeGluV2算子对外暴露的 aclnn 标准接口，用于在昇腾 NPU 上计算高斯误差线性单元门控激活（GeGLU，Gated Gaussian Error Linear Unit）。本文以仓库文档 activation/ge_glu_v2/docs/aclnnGeGlu.md 为核心骨架，完整讲解其产品支持矩阵、数学原理、两段式接口原型与参数约束、错误码语义、完整可运行示例，并结合仓库内 op_host、op_kernel、op_graph 与测试代码，深入到 aclnn 执行器构图、infershape、tiling 分核与 kernel 实现的源码细节。读完本文，你将掌握如何在 NPU 上正确构造 aclTensor、调用aclnnGeGluGetWorkspaceSize/aclnnGeGlu完成 GeGLU 计算，并能对照源码理解其内部实现路径。

一、产品支持情况

aclnnGeGlu在不同昇腾产品线上的支持情况如下（来自 aclnnGeGlu.md 与 README.md 的对照）：

其中，Atlas 推理系列产品 / Atlas 训练系列产品仅支持 FLOAT、FLOAT16 两种数据类型；而 Atlas Kirin X90、Atlas Kirin 9030 系列不支持 BFLOAT16。这一产品差异在源码中也得到了印证：在 ge_glu_v2_def.cpp 中，ascend310p、kirinx90、kirin9030三个配置的输入输出只声明了DT_FLOAT16、DT_FLOAT，而ascend910_93、ascend910b、ascend950、ascend350配置则完整声明了DT_FLOAT16、DT_BF16、DT_FLOAT三种类型；aclnn_geglu.cpp 中GetDtypeSupportList()也只有在 DAV_2201 架构（对应 950 系列）或 Regbase 模式下才把DT_BF16加入支持列表。

二、功能说明与数学原理

aclnnGeGlu的接口功能是高斯误差线性单元激活函数（GeGLU，Gated GELU），其计算公式为：

$$ out_{i}=GeGlu(self_{i}) = A \cdot Gelu(B) $$

其中 $A$ 表示self的前半部分（split 轴左侧的数据块），$B$ 表示self的后半部分（split 轴右侧的数据块）。也就是说，self首先沿dim指定的轴被对半切分，对后半部分应用 GELU 激活，再与前半部分逐元素相乘得到out；同时，Gelu(B)的结果被单独输出到outGelu。

值得注意的版本差异：仓库中还存在增强版本aclnnGeGluV3（接口声明见 aclnn_geglu.h），它额外提供activateLeft布尔属性，用于控制激活函数作用于左半部分还是右半部分。当activateLeft=true时公式变为 $out_{i}=Gelu(A)\cdot B$；aclnnGeGlu内部等价于activateLeft=false的场景，即固定对后半部分做激活。图模式算子 IR 定义（ge_glu_v2_proto.h）中也包含activate_left属性，默认值为false。

三、两段式接口与函数原型

aclnnGeGlu属于 CANN 的两段式接口（Two-Phase API）：必须先调用第一段接口aclnnGeGluGetWorkspaceSize获取计算所需的 workspace 大小以及包含算子计算流程的执行器（aclOpExecutor），再调用第二段接口aclnnGeGlu真正执行计算。

第一段接口原型：

aclnnStatus aclnnGeGluGetWorkspaceSize( const aclTensor *self, int64_t dim, int64_t approximate, aclTensor *out, aclTensor *outGelu, uint64_t *workspaceSize, aclOpExecutor **executor)

第二段接口原型：

aclnnStatus aclnnGeGlu( void *workspace, uint64_t workspaceSize, aclOpExecutor *executor, aclrtStream stream)

从实现看，第一段接口的职责在 aclnn_geglu.cpp 的ExecGeGluGetWorkspaceSize中完成：先做参数校验，然后创建 OpExecutor，将self通过l0op::Contiguous转成连续张量，调用l0op::GeGluV2构建计算图，再通过l0op::ViewCopy处理输出为非连续张量时的回写，最后通过GetWorkspaceSize()返回 workspace 大小并释放执行器。第二段接口则直接调用CommonOpExecutorRun完成异步计算。

四、aclnnGeGluGetWorkspaceSize 参数说明

4.1 参数表

注：Atlas 推理系列产品、Atlas 训练系列产品仅支持 FLOAT、FLOAT16。

参数语义在源码中有更细的印证：dim支持负数索引（dim < 0时实际作用轴为dimNum + dim，见 aclnn_geglu.cpp）；approximate取值必须为 0 或 1，超出范围会直接报ACLNN_ERR_PARAM_INVALID（checkApproximate，aclnn_geglu.cpp）；out与outGelu在 dim 维的大小必须是self在该维大小的一半（SLICE_NUM=2，aclnn_geglu.cpp），且除 dim 轴外其余维度三个张量必须完全一致（CheckOtherDimsMatch）。

4.2 返回值与错误码

第一段接口返回aclnnStatus状态码，出现以下场景时报错：

返回码的完整含义可参见 docs/zh/context/aclnn_return_code.md。需要注意的是，虽然文档中接口原型允许self为 0 维（标量）Tensor，但源码CheckShape中对dimNum == 0会直接报错“Not support the input self is scalar”（aclnn_geglu.cpp），即标量输入在实际实现中不受支持；同时空 Tensor（self->IsEmpty()）会被单独处理，直接返回 workspace 大小而不触发计算。

五、aclnnGeGlu 参数说明

第二段接口的参数如下：

返回值同样为aclnnStatus状态码。该接口内部不做任何参数校验，仅通过CommonOpExecutorRun(workspace, workspaceSize, executor, stream)驱动第一段接口构建好的执行器在指定 Stream 上异步执行（aclnn_geglu.cpp）。

六、约束说明

• 确定性计算：aclnnGeGlu默认确定性实现，即相同输入在相同环境下多次执行结果一致，适合对结果可复现性有要求的训练或推理场景。

七、调用示例（完整可运行）

以下代码来自文档原文，与仓库样例 examples/test_aclnn_ge_glu.cpp 一致，完整演示了「初始化 → 构造 aclTensor → 两段式调用 → 同步等待 → 结果回拷 → 资源释放」的完整流程。编译与运行的整体流程请参考 docs/zh/context/compile_and_run_sample.md。

#include <iostream> #include <vector> #include "acl/acl.h" #include "aclnnop/aclnn_geglu.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, 1}; void* selfDeviceAddr = nullptr; void* outDeviceAddr = nullptr; void* outGeluDeviceAddr = nullptr; aclTensor* self = nullptr; aclTensor* out = nullptr; aclTensor* outGelu = nullptr; std::vector<float> selfHostData = {0, 1, 2, 3}; std::vector<float> outHostData = {0, 0}; std::vector<float> outGeluHostData = {0, 0}; int dim = -1; int approximate = 1; // 创建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); // 创建outGelu aclTensor ret = CreateAclTensor(outGeluHostData, outShape, &outGeluDeviceAddr, aclDataType::ACL_FLOAT, &outGelu); CHECK_RET(ret == ACL_SUCCESS, return ret); // 3. 调用CANN算子库API，需要修改为具体的API名称 uint64_t workspaceSize = 0; aclOpExecutor* executor; // 调用aclnnGeGlu第一段接口 ret = aclnnGeGluGetWorkspaceSize(self, dim, approximate, out, outGelu, &workspaceSize, &executor); CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclnnGeGluGetWorkspaceSize 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); } // 调用aclnnGeGlu第二段接口 ret = aclnnGeGlu(workspaceAddr, workspaceSize, executor, stream); CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclnnGeGlu 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("result[%ld] is: %f\n", i, resultData[i]); } std::vector<float> resultGeluData(size, 0); ret = aclrtMemcpy( resultGeluData.data(), resultGeluData.size() * sizeof(resultGeluData[0]), outGeluDeviceAddr, size * sizeof(resultGeluData[0]), ACL_MEMCPY_DEVICE_TO_HOST); CHECK_RET( ret == ACL_SUCCESS, LOG_PRINT("copy resultGelu from device to host failed. ERROR: %d\n", ret); return ret); for (int64_t i = 0; i < size; i++) { LOG_PRINT("result[%ld] is: %f\n", i, resultGeluData[i]); } // 6. 释放aclTensor和aclScalar，需要根据具体API的接口定义修改 aclDestroyTensor(self); aclDestroyTensor(out); aclDestroyTensor(outGelu); // 7. 释放device资源，需要根据具体API的接口定义修改 aclrtFree(selfDeviceAddr); aclrtFree(outDeviceAddr); aclrtFree(outGeluDeviceAddr); if (workspaceSize > 0) { aclrtFree(workspaceAddr); } aclrtDestroyStream(stream); aclrtResetDevice(deviceId); aclFinalize(); return 0; }

示例要点解读

• 示例中selfShape={2,2}、dim=-1：self沿最后一维（size=2）对半切分，得到左右各 2 个元素，因此outShape={2,1}；若dim指定为0，则self沿第 0 维切分，此时out的 shape 应为{1,2}。
• approximate=1表示使用 tanh 近似 GELU；若置0则使用精确的 erf 公式（F.gelu(approximate="none")语义）。
• workspace 仅在workspaceSize > 0时申请，避免无谓的内存开销；示例中申请使用ACL_MEM_MALLOC_HUGE_FIRST策略。
• 第 5 步必须放在aclrtSynchronizeStream之后，确保 Device 侧计算完成后再把结果回拷 Host。

八、仓库源码级原理纵深

8.1 aclnn 接口执行链路

aclnnGeGluGetWorkspaceSize的完整执行链路（aclnn_geglu.cpp）：

1. 参数校验：CheckParams依次执行空指针检查（CheckNotNull）、数据类型检查（CheckDtypeValid，校验 self/out/outGelu 均在支持列表内且类型一致）、shape 检查（CheckShape：最大维数、dim 范围、切分维大小与其余维一致性）以及 approximate 取值范围检查；
2. 空 Tensor 快速路径：self->IsEmpty()或 0 维时直接返回GetWorkspaceSize()，不构图；
3. 构图：l0op::Contiguous将非连续输入转连续 →l0op::GeGluV2(selfContiguous, dim, approximate, activateLeft, executor)生成主计算图（返回两个输出）→l0op::ViewCopy将连续结果回写到用户可能不连续的out/outGelu；
4. 返回 workspace 大小：uniqueExecutor->GetWorkspaceSize()汇总整条链路所需的 Device 侧临时内存（包括Contiguous与ViewCopy可能产生的拷贝缓冲）。

头文件 aclnn_geglu.h 中给出了等价的计算图示意：self → Contiguous → GeGlu → ViewCopy → out / outGelu，dim与approximate作为属性输入到GeGlu节点。

8.2 算子定义与 shape 推导

图模式算子GeGluV2的 IR 定义位于 ge_glu_v2_proto.h：输入x、输出y与gelu，支持DT_BF16 / DT_FLOAT16 / DT_FLOAT；三个属性dim（默认 -1）、approximate（默认 1）、activate_left（默认 false）。IR 注释明确说明：split 维度长度必须是偶数；Atlas 推理系列产品仅支持tanh近似（approximate=1）。

Host 侧的算子注册与格式/精度配置见 ge_glu_v2_def.cpp，其中对ascend950、ascend350启用了动态编译、动态格式、动态 rank/shape 支持与精度保持标志（PrecisionReduceFlag）。infershape 实现（ge_glu_v2_infershape.cpp）的核心逻辑是：out与outGelu的 shape 在除dim轴外与x完全一致，dim轴长度被置为x在该维长度除以 2（SPLIT_NUM=2）。

8.3 tiling 分核策略

tiling 实现（ge_glu_v2_tiling.cpp）展示了 NPU kernel 侧如何把大张量切分为多核并行任务：

• 依据approximate选择 tanh（tiling key 101/102/103）或 erf（tiling key 111/112/113）计算路径，以及按 FP16/BF16/FP32 选择不同的 block 对齐粒度（FP16/BF16 为 16 元素一个 block，FP32 为 8 元素一个 block，32 字节对齐）；
• 数据量小时使用GetTilingDataSmall单组处理，数据量大时使用GetTilingDataBig按 buffer 上限分多组循环处理；numPerCore、group、loopNum、尾核处理（tailLoopNum/lastTailGroup）等字段共同刻画每个 AI Core 的搬运与计算节奏；
• workspace 大小固定预留 16MB（WORK_SPACE_SIZE = 16U * 1024U * 1024U），用于 310P 等场景下数据跨 block 边界的转存。

8.4 kernel 实现要点

kernel 侧（op_kernel/ge_glu_v2_base.h 及 arch35 下的 tanh/erf 分支实现）基于 AscendC 编写，关键点包括：

• GELU 的两种计算公式被编译为不同的 kernel 变体：tanh 近似使用常数beta=0.044715、alpha=1.5957691；erf 精确计算使用分段多项式逼近系数（ERF_PARAM21~ERF_PARAM27）与阈值ERF_THRESHOLD=5.75，对应 arch35 目录下的ge_glu_v2_*_erf.h系列文件；
• 输入按奇偶通道拆分（EVEN/ODD掩码，vreduce_srcPattern_x1/x2），分别对应公式中的 A 与 B 数据块；
• 不同 dtype 与切片形态（对齐/不对齐、末轴大数据、vreduce）组合出多套特化 kernel，如ge_glu_v2_fp16_align.h、ge_glu_v2_fp32_align_last_axis_big.h、ge_glu_v2_bf16_vreduce.h等，分布在 op_kernel 目录。

8.5 测试与 golden 验证

仓库为aclnnGeGlu提供了完整的验证体系：

• ST 测试：tests/st/aclnnGeGlu/executor_aclnnGeGlu.py 中定义了aclnnGeGluV3Discontinues的 golden 参考实现：先对输入在dim维做chunk(2, dim)切分，对后半块调用F.gelu(approximate=...)（0→none，1→tanh），再与前半块逐元素相乘；同时校验切分维长度必须为偶数（input_x.size(dim) % 2 != 0时报错），与接口参数约束严格对应；用例参数由 atk_aclnnGeGlu.json 驱动；
• UT 测试：Host 侧覆盖了 infershape 与 tiling 的单元测试（tests/ut/op_host/test_ge_glu_v2_infershape.cpp、test_ge_glu_v2_tiling.cpp），kernel 侧通过 ge_glu_v2_data/gen_data.py 生成测试数据并在 test_ge_glu_v2.cpp 中验证计算结果。

九、与其他调用方式的关系

GeGluV2算子在本仓库中共有三种调用方式（见 README.md）：

其中aclnnGeGlu与aclnnGeGluV3共享同一套底层实现（ExecGeGluGetWorkspaceSize），区别仅在于 V3 多传入一个activateLeft布尔参数（aclnnGeGlu 固定传false，见 aclnn_geglu.cpp），开发者可以按需选择。

十、使用建议与注意事项

1. 两段式接口顺序不可颠倒：aclnnGeGlu必须在aclnnGeGluGetWorkspaceSize返回成功之后调用，且workspaceSize、executor必须原样回传；
2. shape 规划：out与outGelu在dim维的大小必须是self的一半，且self该维长度必须为偶数，否则第一段接口直接返回ACLNN_ERR_PARAM_INVALID（161002）；
3. dtype 一致性：out、outGelu的数据类型必须与self完全一致；在 Atlas 推理系列 / Atlas 训练系列产品上仅支持 FLOAT、FLOAT16，在 Kirin X90/9030 上不支持 BFLOAT16，跨平台移植时需注意；
4. 非连续 Tensor 支持：self、out、outGelu均支持非连续 Tensor，框架内部会通过Contiguous/ViewCopy自动处理，用户无需手动转连续，但会带来额外的 workspace 开销；
5. 资源管理：workspace 内存、device 内存与 aclTensor 需要按示例第 6、7 步显式释放，避免 NPU 显存泄漏；stream同步等待后再读取结果。

【免费下载链接】ops-nn本项目是CANN提供的神经网络类计算算子库，实现网络在NPU上加速计算。项目地址: https://gitcode.com/cann/ops-nn