CANN ops-math Erf 算子开发指南aclnnErf 与 aclnnInplaceErf 双接口调用详解【免费下载链接】ops-math本项目是CANN提供的数学类基础计算算子库实现网络在NPU上加速计算。项目地址: https://gitcode.com/cann/ops-math本指南以 CANN 开源数学算子库 ops-math 中的 Erf 算子为对象系统讲解其 aclnn 两级接口aclnnErf / aclnnInplaceErf的函数原型、参数约束、错误码语义与完整调用示例并结合仓库内算子定义、Shape 推导、Tiling 与 Kernel 源码深入剖析误差函数erf在 NPU 上的实现原理与性能优化策略。读者学完后将能够在 Atlas A2 训练/推理系列产品上独立完成 Erf 算子的工程集成与非连续 Tensor、Inplace 场景的正确调用。一、算子概述什么是 erf为什么要单独提供 Inplace 版本误差函数Gaussian Error Function是概率论、统计学与信号处理中的基础特殊函数其定义为$$ erf(x)\frac{2}{\sqrt{\pi } } \int_{0}^{x} e^{-t^{2} } \mathrm{d}t $$在深度学习中erf 常用于 GELU 激活函数、正态分布相关统计量计算等场景。CANN ops-math 仓库在 experimental/math/erf 目录下提供了完整的 Erf 算子实现支持通过 aclnnAscend CANN 算子接口两段式 API 完成 NPU 侧的计算。ops-math 为 Erf 算子同时提供了一对功能相同的接口区别仅在于结果写入方式接口功能适用场景aclnnErf新建一个输出 Tensor 对象存储计算结果需要保留原始输入的场景aclnnInplaceErf在原输入 Tensor 上直接覆写计算结果in-place输入不再复用、希望节省显存与拷贝开销的场景产品支持情况Atlas A2 训练系列产品/Atlas A2 推理系列产品√ 支持。对应算子定义位于 op_host/erf_def.cpp其中通过AICore().AddConfig(ascend910b)声明了该算子的硬件适配平台。二、两段式接口机制与函数原型每个 aclnn 算子都采用两段式接口详细机制参见 docs/zh/context/two_phase_api.md必须先调用*GetWorkspaceSize接口完成入参校验、构建算子执行图并计算所需 workspace 大小再调用执行接口完成实际计算。两段接口必须配套使用不可混用。Erf 算子的四个接口原型如下声明见 op_api/aclnn_erf.h// 第一段获取 workspace 大小与执行器 aclnnStatus aclnnErfGetWorkspaceSize(const aclTensor *self, aclTensor *out, uint64_t *workspaceSize, aclOpExecutor **executor); // 第二段执行计算 aclnnStatus aclnnErf(void *workspace, uint64_t workspaceSize, aclOpExecutor *executor, aclrtStream stream); // Inplace 版本selfRef 既是输入也是输出 aclnnStatus aclnnInplaceErfGetWorkspaceSize(aclTensor *selfRef, uint64_t *workspaceSize, aclOpExecutor **executor); aclnnStatus aclnnInplaceErf(void *workspace, uint64_t workspaceSize, aclOpExecutor *executor, aclrtStream stream);从源码实现看op_api/aclnn_erf.cppaclnnInplaceErfGetWorkspaceSize在完成 Inplace 参数校验后直接复用GetWorkspaceSizeCommon(selfRef, selfRef, ...)这条公共计算链路即输入输出共用同一份内存因此Inplace 版本要求 selfRef 的数据类型必须同时满足输入与输出的约束。2.1 第一段接口参数说明aclnnErfGetWorkspaceSize参数方向说明self入参Device 侧 aclTensor计算输入。数据格式支持 NDshape 维度不超过 8 维支持非连续的 Tensor。Atlas A2 产品上数据类型支持 FLOAT32、FLOAT16、BFLOAT16out入参Device 侧 aclTensor计算输出。数据格式支持 NDshape 必须与 self 完全一致维度不超过 8 维支持非连续 Tensor。Atlas A2 产品上数据类型支持 FLOAT32、FLOAT16、BFLOAT16workspaceSize出参返回需要在 Device 侧申请的 workspace 大小字节数executor出参返回 op 执行器包含了算子计算流程值得注意虽然本产品Atlas A2上仅开放 FLOAT32 / FLOAT16 / BFLOAT16 三种类型但 aclnn 层源码aclnn_erf.cpp维护了更宽的平台相关类型支持列表——910 系列支持 DT_DOUBLE/DT_FLOAT/DT_FLOAT16/DT_BOOL/DT_INT64910B 系列在此基础上追加 DT_BF16。这些类型经过 Cast 后被统一送入核心 Erf 计算因此接口头文件注释中声明支持 FLOAT64、INT64、BOOL 等扩展类型使用前请以实际产品与版本的支持矩阵为准。2.2 第一段接口的错误码语义两段式接口的第一段会完成全部入参校验完整错误码定义见 docs/zh/context/aclnn_return_code.md161001(ACLNN_ERR_PARAM_NULLPTR)1. 传入的 self 或 out 是空指针。 161002(ACLNN_ERR_PARAM_INVALID)1. self 和 out 的数据类型和数据格式不在支持的范围之内。 2. self 和 out 的 shape 不一致。 3. 计算结果不能 cast 成 out 的类型。 4. self、out 的维度超过 8。Inplace 版本校验逻辑对应 CheckInplaceParamsErf稍有不同161001(ACLNN_ERR_PARAM_NULLPTR)1. 传入的 selfRef 是空指针。 161002(ACLNN_ERR_PARAM_INVALID)1. selfRef 的数据类型和数据格式不在支持的范围之内。 2. selfRef 的维度超过 8。上述校验在源码中都有对应实现CheckParamsErf依次执行空指针检查CheckNotNull2Tensor、类型合法性检查CheckDtypeValid与同 shape 检查CheckSameShape1In1Out参见 aclnn_erf.cpp。其中CheckDtypeValid还针对 BOOL/INT64 输入做了「输出类型必须可由 FLOAT cast 得到」的二次校验对应错误码 161002 的第 3 条场景。2.3 第二段接口参数说明aclnnErf / aclnnInplaceErf参数方向说明workspace入参在 Device 侧申请的 workspace 内存地址workspaceSize入参workspace 大小必须由第一段接口获取executor入参op 执行器包含了算子计算流程stream入参指定执行任务的 aclrtStream第二段接口内部仅做固定流程调用CommonOpExecutorRun实际计算由执行器驱动完成。三、执行图构建从 self 到 out 的完整链路第一段接口的核心工作之一是构建算子执行图。从 GetWorkspaceSizeCommon 的实现可以看到Erf 的执行图按输入类型分为两种场景与 aclnn_erf.h 头文件注释中的 mermaid 计算图一致场景一输入类型在算子原生支持范围内FLOAT32 / FLOAT16 / BFLOAT16Self ──► l0op::Contiguous ──► l0op::Erf ──► l0op::ViewCopy ──► out场景二self 为 BOOL / INT64 类型需先 Cast 到 FLOAT32 再计算Self ──► l0op::Contiguous ──► l0op::Cast(FLOAT32) ──► l0op::Erf ──► l0op::Cast(out类型) ──► l0op::ViewCopy ──► out各环节职责l0op::Contiguous若 self 为非连续 Tensor先转换为连续存储保证后续向量化计算的高效访问l0op::Cast可选BOOL/INT64 类型统一提升为 FLOAT32 参与计算计算结束后再 Cast 回 out 声明的目标类型l0op::Erf核心计算对应 l0 层接口l0op::Erf声明见 op_api/erf.hl0op::ViewCopy若 out 是非连续 Tensor将连续的计算结果按 out 的视图strides写回。此外第一段接口还有一处易被忽略的细节空 Tensor 处理。当self-IsEmpty()时直接返回workspaceSize 0并成功退出aclnn_erf.cpp无需走完整计算图这是保证 shape 含 0 维场景下接口仍能正确运行的关键。四、算子定义与 Shape 推导ND 格式与逐元素同形输出4.1 算子信息注册Erf 算子的输入输出在算子信息库中注册为op_host/erf_def.cpp输入self必需参数数据类型 DT_FLOAT16 / DT_FLOAT / DT_BF16数据格式 FORMAT_ND输出out必需参数数据类型与格式同输入硬件配置AICore 适配ascend910b。由于 erf 是逐元素elementwise算子输出与输入在数值类型和存储格式上天然对齐这也是「约束说明无」这一结论的底层依据。4.2 Shape 推导erf_infershape.cpp 中的InferShapeErf实现非常直观读取输入self的 shapexShape将维数DimNum与每一维大小Dim逐一拷贝到输出yShape即输出 shape 与输入完全一致。这一行为与接口文档中「out 的 shape 必须和 self 一样」的约束一一对应也解释了为何维度上限统一为 8 维仓库上下文文档 data_format.md 对 ND 格式维度有统一约束。五、Tiling 策略与 Kernel 实现源码级的性能优化细节深入到算子内核层Erf 的 Tiling 与 Kernel 实现体现了针对 AICore 的典型优化思路。5.1 双 Kernel 调度策略Tiling 逻辑位于 op_host/erf_tiling.cpp。它以DB_TILING_MIN_NUM 262144即 2^18 个元素为阈值将计算拆分为两种调度模式ELEMENTWISE_TPL_SCH_MODE_0/1见 erf_tiling_key.h小输入元素数 ≤ 262144不开启 Double Buffer尽量减少 scale 开销UBUnified Buffer单次容纳数据量按阈值表在 512 ~ 6656 个元素之间分档选取大输入元素数 262144开启 Double BufferBUFFER_NUM 2单次 UB 承载 6144 个元素UB_DATA_NUM_DB并引入大核/小核bigCore/smallCore与尾块tail拆分尽可能用满 AICore 计算能力。其它关键常量还包括GM 数据按 512 字节对齐GM_ALIGN_NUM以提升搬运效率、REPEAT_NUM 256与元素类型共同决定单次 repeat 的粒度。最终生成的ErfTilingData见 erf_tiling_data.h包含 smallCoreDataNum、bigCoreDataNum、tileDataNum、tailDataNum、finalTileNum 等字段供 Kernel 端循环切块使用。5.2 Kernel 内计算有理逼近而非数值积分值得特别说明的是NPU Kernel 并不会真的去计算文档公式中的定积分而是采用经典的有理函数逼近类似 Abramowitz-Stegun 7.1.25 近似相关常量定义在 op_kernel/erf.hP 0.47047 A 0.3480242 B -0.0958798 C 0.7478556计算流程为先按符号位统一绝对值SCALER_NEGATIVE_ONE、SIGN_FACTOR -2、SIGN_OFFSET 1用于恢复符号再通过上述多项式系数完成 erf(|x|) 的有理逼近同时 Kernel 模板按输入/输出类型TYPE_X/TYPE_Y实例化并针对 FP16 做了SCALER_FP16_MAX/MIN的数值范围保护。Kernel 主体使用 AscendC 编程框架的TQue双缓冲队列VECIN/VECOUT实现流水线对应代码见 op_kernel/erf.h。仓库同时提供了 Kernel 级测试与数据生成脚本tests/ut/op_kernel/erf_data/gen_data.py、compare_data.py可用于校验逼近精度。六、完整调用示例非 Inplace 与 Inplace 双路径实战接口文档给出了可直接编译运行的完整示例docs/aclnnErfaclnnInplaceErf.md仓库亦提供同款样例 examples/test_aclnn_erf.cpp 与 UT 用例 tests/ut/op_api/test_aclnn_erf.cpp。整体编译与运行流程请参考 编译与运行样例。下面给出按步骤拆解的核心流程对文档示例做了注释精简保留完整调用骨架#include iostream #include vector #include acl/acl.h #include aclnnop/aclnn_erf.h #define CHECK_RET(cond, return_erfr) \ do { if (!(cond)) { return_erfr; } } while (0) #define LOG_PRINT(message, ...) printf(message, ##__VA_ARGS__) int64_t GetShapeSize(const std::vectorint64_t shape) { int64_t shape_size 1; for (auto i : shape) shape_size * i; return shape_size; } 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::vectorT hostData, const std::vectorint64_t shape, void** deviceAddr, aclDataType dataType, aclTensor** tensor) { auto size GetShapeSize(shape) * sizeof(T); // 申请 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); // 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::vectorint64_t strides(shape.size(), 1); for (int64_t i shape.size() - 2; i 0; i--) { strides[i] shape[i 1] * strides[i 1]; } // 创建 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 初始化固定写法deviceId 按实际填写 int32_t deviceId 0; aclrtStream stream; auto ret Init(deviceId, stream); CHECK_RET(ret 0, LOG_PRINT(Init acl failed. ERROR: %d\n, ret); return ret); // 2. 构造输入与输出 aclTensor std::vectorint64_t selfShape {2, 2}; std::vectorint64_t outShape {2, 2}; void* selfDeviceAddr nullptr; void* outDeviceAddr nullptr; aclTensor* self nullptr; aclTensor* out nullptr; std::vectorfloat selfHostData {0, 1, 2, 3}; std::vectorfloat outHostData {0, 0, 0, 0}; ret CreateAclTensor(selfHostData, selfShape, selfDeviceAddr, aclDataType::ACL_FLOAT, self); CHECK_RET(ret ACL_SUCCESS, return ret); ret CreateAclTensor(outHostData, outShape, outDeviceAddr, aclDataType::ACL_FLOAT, out); CHECK_RET(ret ACL_SUCCESS, return ret); // 3. 调用 aclnnErf第一段获取 workspace第二段执行 uint64_t workspaceSize 0; aclOpExecutor* executor; ret aclnnErfGetWorkspaceSize(self, out, workspaceSize, executor); CHECK_RET(ret ACL_SUCCESS, LOG_PRINT(aclnnErfGetWorkspaceSize failed. ERROR: %d\n, ret); return ret); void* workspaceAddr nullptr; if (workspaceSize 0) { // 注意workspaceSize 可能为 0如空 Tensor 场景 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); } ret aclnnErf(workspaceAddr, workspaceSize, executor, stream); CHECK_RET(ret ACL_SUCCESS, LOG_PRINT(aclnnErf 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 并打印 auto size GetShapeSize(outShape); std::vectorfloat resultData(size, 0); ret aclrtMemcpy(resultData.data(), resultData.size() * sizeof(resultData[0]), outDeviceAddr, size * sizeof(float), 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]); } // 6. Inplace 路径直接对 self 覆写无需额外 out uint64_t inplaceWorkspaceSize 0; aclOpExecutor* inplaceExecutor; ret aclnnInplaceErfGetWorkspaceSize(self, inplaceWorkspaceSize, inplaceExecutor); CHECK_RET(ret ACL_SUCCESS, LOG_PRINT(aclnnInplaceErfGetWorkspaceSize failed. ERROR: %d\n, ret); return ret); 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); } ret aclnnInplaceErf(inplaceWorkspaceAddr, inplaceWorkspaceSize, inplaceExecutor, stream); CHECK_RET(ret ACL_SUCCESS, LOG_PRINT(aclnnInplaceErf failed. ERROR: %d\n, ret); return ret); ret aclrtSynchronizeStream(stream); CHECK_RET(ret ACL_SUCCESS, LOG_PRINT(aclrtSynchronizeStream failed. ERROR: %d\n, ret); return ret); // 从 selfDeviceAddr即被覆写的输入内存读取 Inplace 结果 auto inplaceSize GetShapeSize(selfShape); std::vectorfloat inplaceResultData(inplaceSize, 0); ret aclrtMemcpy(inplaceResultData.data(), inplaceResultData.size() * sizeof(inplaceResultData[0]), selfDeviceAddr, inplaceSize * sizeof(float), 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(inplaceResult[%ld] is: %f\n, i, inplaceResultData[i]); } // 7. 释放 aclTensor 与 device 资源固定写法 aclDestroyTensor(self); aclDestroyTensor(out); aclrtFree(selfDeviceAddr); aclrtFree(outDeviceAddr); if (workspaceSize 0) { aclrtFree(workspaceAddr); } if (inplaceWorkspaceSize 0) { aclrtFree(inplaceWorkspaceAddr); } aclrtDestroyStream(stream); aclrtResetDevice(deviceId); aclFinalize(); return 0; }示例要点解读两段式接口的严格配对aclnnErfGetWorkspaceSize返回的workspaceSize/executor只能交给配对的aclnnErf使用Inplace 系列同理交叉混用属于未定义行为。workspace 条件申请workspaceSize 0时才需要aclrtMalloc。从源码可知空 Tensor 输入时第一段接口直接返回workspaceSize 0示例中的条件判断正好覆盖此场景。Inplace 的内存语义aclnnInplaceErf复用selfRef的内存示例中 Inplace 结果直接从selfDeviceAddr拷回因此在构造 Inplace 调用前self中若还需保留原始数据应提前备份。结果校验对{0, 1, 2, 3}逐元素求 erf预期结果约等于{0, 0.8427008, 0.9953223, 0.9999779}可用于快速验证调用正确性。七、约束与最佳实践小结约束说明无。Erf 算子本身无额外的数学定义域限制——erf 在全实数域收敛且有界值域 (-1, 1)因此不存在除接口参数校验外的其它使用约束。数据格式与维度输入输出均为 ND 格式shape 一致维度不超过 8 维非连续 Tensor 由执行图内的 Contiguous/ViewCopy 自动处理开发者无需手动搬移。类型选择Atlas A2 产品上推荐直接使用 FLOAT32 / FLOAT16 / BFLOAT16BOOL/INT64 输入会经 Cast 链路自动提升为 FLOAT32 计算注意此时输出类型须能由 FLOAT 安全转换否则第一段接口将返回 161002。性能相关从 Tiling 实现可知元素数 ≤ 262144 的小输入走无 Double Buffer 的轻量模式大输入自动切换 Double Buffer 模式以提升 AICore 利用率开发者一般无需干预如需验证性能与精度可参考 tests/ut/op_kernel 目录下的数据生成与对比脚本。【免费下载链接】ops-math本项目是CANN提供的数学类基础计算算子库实现网络在NPU上加速计算。项目地址: https://gitcode.com/cann/ops-math创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
CANN ops-math Erf 算子开发指南aclnnErf 与 aclnnInplaceErf 双接口调用详解【免费下载链接】ops-math本项目是CANN提供的数学类基础计算算子库实现网络在NPU上加速计算。项目地址: https://gitcode.com/cann/ops-math本指南以 CANN 开源数学算子库 ops-math 中的 Erf 算子为对象系统讲解其 aclnn 两级接口aclnnErf / aclnnInplaceErf的函数原型、参数约束、错误码语义与完整调用示例并结合仓库内算子定义、Shape 推导、Tiling 与 Kernel 源码深入剖析误差函数erf在 NPU 上的实现原理与性能优化策略。读者学完后将能够在 Atlas A2 训练/推理系列产品上独立完成 Erf 算子的工程集成与非连续 Tensor、Inplace 场景的正确调用。一、算子概述什么是 erf为什么要单独提供 Inplace 版本误差函数Gaussian Error Function是概率论、统计学与信号处理中的基础特殊函数其定义为$$ erf(x)\frac{2}{\sqrt{\pi } } \int_{0}^{x} e^{-t^{2} } \mathrm{d}t $$在深度学习中erf 常用于 GELU 激活函数、正态分布相关统计量计算等场景。CANN ops-math 仓库在 experimental/math/erf 目录下提供了完整的 Erf 算子实现支持通过 aclnnAscend CANN 算子接口两段式 API 完成 NPU 侧的计算。ops-math 为 Erf 算子同时提供了一对功能相同的接口区别仅在于结果写入方式接口功能适用场景aclnnErf新建一个输出 Tensor 对象存储计算结果需要保留原始输入的场景aclnnInplaceErf在原输入 Tensor 上直接覆写计算结果in-place输入不再复用、希望节省显存与拷贝开销的场景产品支持情况Atlas A2 训练系列产品/Atlas A2 推理系列产品√ 支持。对应算子定义位于 op_host/erf_def.cpp其中通过AICore().AddConfig(ascend910b)声明了该算子的硬件适配平台。二、两段式接口机制与函数原型每个 aclnn 算子都采用两段式接口详细机制参见 docs/zh/context/two_phase_api.md必须先调用*GetWorkspaceSize接口完成入参校验、构建算子执行图并计算所需 workspace 大小再调用执行接口完成实际计算。两段接口必须配套使用不可混用。Erf 算子的四个接口原型如下声明见 op_api/aclnn_erf.h// 第一段获取 workspace 大小与执行器 aclnnStatus aclnnErfGetWorkspaceSize(const aclTensor *self, aclTensor *out, uint64_t *workspaceSize, aclOpExecutor **executor); // 第二段执行计算 aclnnStatus aclnnErf(void *workspace, uint64_t workspaceSize, aclOpExecutor *executor, aclrtStream stream); // Inplace 版本selfRef 既是输入也是输出 aclnnStatus aclnnInplaceErfGetWorkspaceSize(aclTensor *selfRef, uint64_t *workspaceSize, aclOpExecutor **executor); aclnnStatus aclnnInplaceErf(void *workspace, uint64_t workspaceSize, aclOpExecutor *executor, aclrtStream stream);从源码实现看op_api/aclnn_erf.cppaclnnInplaceErfGetWorkspaceSize在完成 Inplace 参数校验后直接复用GetWorkspaceSizeCommon(selfRef, selfRef, ...)这条公共计算链路即输入输出共用同一份内存因此Inplace 版本要求 selfRef 的数据类型必须同时满足输入与输出的约束。2.1 第一段接口参数说明aclnnErfGetWorkspaceSize参数方向说明self入参Device 侧 aclTensor计算输入。数据格式支持 NDshape 维度不超过 8 维支持非连续的 Tensor。Atlas A2 产品上数据类型支持 FLOAT32、FLOAT16、BFLOAT16out入参Device 侧 aclTensor计算输出。数据格式支持 NDshape 必须与 self 完全一致维度不超过 8 维支持非连续 Tensor。Atlas A2 产品上数据类型支持 FLOAT32、FLOAT16、BFLOAT16workspaceSize出参返回需要在 Device 侧申请的 workspace 大小字节数executor出参返回 op 执行器包含了算子计算流程值得注意虽然本产品Atlas A2上仅开放 FLOAT32 / FLOAT16 / BFLOAT16 三种类型但 aclnn 层源码aclnn_erf.cpp维护了更宽的平台相关类型支持列表——910 系列支持 DT_DOUBLE/DT_FLOAT/DT_FLOAT16/DT_BOOL/DT_INT64910B 系列在此基础上追加 DT_BF16。这些类型经过 Cast 后被统一送入核心 Erf 计算因此接口头文件注释中声明支持 FLOAT64、INT64、BOOL 等扩展类型使用前请以实际产品与版本的支持矩阵为准。2.2 第一段接口的错误码语义两段式接口的第一段会完成全部入参校验完整错误码定义见 docs/zh/context/aclnn_return_code.md161001(ACLNN_ERR_PARAM_NULLPTR)1. 传入的 self 或 out 是空指针。 161002(ACLNN_ERR_PARAM_INVALID)1. self 和 out 的数据类型和数据格式不在支持的范围之内。 2. self 和 out 的 shape 不一致。 3. 计算结果不能 cast 成 out 的类型。 4. self、out 的维度超过 8。Inplace 版本校验逻辑对应 CheckInplaceParamsErf稍有不同161001(ACLNN_ERR_PARAM_NULLPTR)1. 传入的 selfRef 是空指针。 161002(ACLNN_ERR_PARAM_INVALID)1. selfRef 的数据类型和数据格式不在支持的范围之内。 2. selfRef 的维度超过 8。上述校验在源码中都有对应实现CheckParamsErf依次执行空指针检查CheckNotNull2Tensor、类型合法性检查CheckDtypeValid与同 shape 检查CheckSameShape1In1Out参见 aclnn_erf.cpp。其中CheckDtypeValid还针对 BOOL/INT64 输入做了「输出类型必须可由 FLOAT cast 得到」的二次校验对应错误码 161002 的第 3 条场景。2.3 第二段接口参数说明aclnnErf / aclnnInplaceErf参数方向说明workspace入参在 Device 侧申请的 workspace 内存地址workspaceSize入参workspace 大小必须由第一段接口获取executor入参op 执行器包含了算子计算流程stream入参指定执行任务的 aclrtStream第二段接口内部仅做固定流程调用CommonOpExecutorRun实际计算由执行器驱动完成。三、执行图构建从 self 到 out 的完整链路第一段接口的核心工作之一是构建算子执行图。从 GetWorkspaceSizeCommon 的实现可以看到Erf 的执行图按输入类型分为两种场景与 aclnn_erf.h 头文件注释中的 mermaid 计算图一致场景一输入类型在算子原生支持范围内FLOAT32 / FLOAT16 / BFLOAT16Self ──► l0op::Contiguous ──► l0op::Erf ──► l0op::ViewCopy ──► out场景二self 为 BOOL / INT64 类型需先 Cast 到 FLOAT32 再计算Self ──► l0op::Contiguous ──► l0op::Cast(FLOAT32) ──► l0op::Erf ──► l0op::Cast(out类型) ──► l0op::ViewCopy ──► out各环节职责l0op::Contiguous若 self 为非连续 Tensor先转换为连续存储保证后续向量化计算的高效访问l0op::Cast可选BOOL/INT64 类型统一提升为 FLOAT32 参与计算计算结束后再 Cast 回 out 声明的目标类型l0op::Erf核心计算对应 l0 层接口l0op::Erf声明见 op_api/erf.hl0op::ViewCopy若 out 是非连续 Tensor将连续的计算结果按 out 的视图strides写回。此外第一段接口还有一处易被忽略的细节空 Tensor 处理。当self-IsEmpty()时直接返回workspaceSize 0并成功退出aclnn_erf.cpp无需走完整计算图这是保证 shape 含 0 维场景下接口仍能正确运行的关键。四、算子定义与 Shape 推导ND 格式与逐元素同形输出4.1 算子信息注册Erf 算子的输入输出在算子信息库中注册为op_host/erf_def.cpp输入self必需参数数据类型 DT_FLOAT16 / DT_FLOAT / DT_BF16数据格式 FORMAT_ND输出out必需参数数据类型与格式同输入硬件配置AICore 适配ascend910b。由于 erf 是逐元素elementwise算子输出与输入在数值类型和存储格式上天然对齐这也是「约束说明无」这一结论的底层依据。4.2 Shape 推导erf_infershape.cpp 中的InferShapeErf实现非常直观读取输入self的 shapexShape将维数DimNum与每一维大小Dim逐一拷贝到输出yShape即输出 shape 与输入完全一致。这一行为与接口文档中「out 的 shape 必须和 self 一样」的约束一一对应也解释了为何维度上限统一为 8 维仓库上下文文档 data_format.md 对 ND 格式维度有统一约束。五、Tiling 策略与 Kernel 实现源码级的性能优化细节深入到算子内核层Erf 的 Tiling 与 Kernel 实现体现了针对 AICore 的典型优化思路。5.1 双 Kernel 调度策略Tiling 逻辑位于 op_host/erf_tiling.cpp。它以DB_TILING_MIN_NUM 262144即 2^18 个元素为阈值将计算拆分为两种调度模式ELEMENTWISE_TPL_SCH_MODE_0/1见 erf_tiling_key.h小输入元素数 ≤ 262144不开启 Double Buffer尽量减少 scale 开销UBUnified Buffer单次容纳数据量按阈值表在 512 ~ 6656 个元素之间分档选取大输入元素数 262144开启 Double BufferBUFFER_NUM 2单次 UB 承载 6144 个元素UB_DATA_NUM_DB并引入大核/小核bigCore/smallCore与尾块tail拆分尽可能用满 AICore 计算能力。其它关键常量还包括GM 数据按 512 字节对齐GM_ALIGN_NUM以提升搬运效率、REPEAT_NUM 256与元素类型共同决定单次 repeat 的粒度。最终生成的ErfTilingData见 erf_tiling_data.h包含 smallCoreDataNum、bigCoreDataNum、tileDataNum、tailDataNum、finalTileNum 等字段供 Kernel 端循环切块使用。5.2 Kernel 内计算有理逼近而非数值积分值得特别说明的是NPU Kernel 并不会真的去计算文档公式中的定积分而是采用经典的有理函数逼近类似 Abramowitz-Stegun 7.1.25 近似相关常量定义在 op_kernel/erf.hP 0.47047 A 0.3480242 B -0.0958798 C 0.7478556计算流程为先按符号位统一绝对值SCALER_NEGATIVE_ONE、SIGN_FACTOR -2、SIGN_OFFSET 1用于恢复符号再通过上述多项式系数完成 erf(|x|) 的有理逼近同时 Kernel 模板按输入/输出类型TYPE_X/TYPE_Y实例化并针对 FP16 做了SCALER_FP16_MAX/MIN的数值范围保护。Kernel 主体使用 AscendC 编程框架的TQue双缓冲队列VECIN/VECOUT实现流水线对应代码见 op_kernel/erf.h。仓库同时提供了 Kernel 级测试与数据生成脚本tests/ut/op_kernel/erf_data/gen_data.py、compare_data.py可用于校验逼近精度。六、完整调用示例非 Inplace 与 Inplace 双路径实战接口文档给出了可直接编译运行的完整示例docs/aclnnErfaclnnInplaceErf.md仓库亦提供同款样例 examples/test_aclnn_erf.cpp 与 UT 用例 tests/ut/op_api/test_aclnn_erf.cpp。整体编译与运行流程请参考 编译与运行样例。下面给出按步骤拆解的核心流程对文档示例做了注释精简保留完整调用骨架#include iostream #include vector #include acl/acl.h #include aclnnop/aclnn_erf.h #define CHECK_RET(cond, return_erfr) \ do { if (!(cond)) { return_erfr; } } while (0) #define LOG_PRINT(message, ...) printf(message, ##__VA_ARGS__) int64_t GetShapeSize(const std::vectorint64_t shape) { int64_t shape_size 1; for (auto i : shape) shape_size * i; return shape_size; } 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::vectorT hostData, const std::vectorint64_t shape, void** deviceAddr, aclDataType dataType, aclTensor** tensor) { auto size GetShapeSize(shape) * sizeof(T); // 申请 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); // 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::vectorint64_t strides(shape.size(), 1); for (int64_t i shape.size() - 2; i 0; i--) { strides[i] shape[i 1] * strides[i 1]; } // 创建 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 初始化固定写法deviceId 按实际填写 int32_t deviceId 0; aclrtStream stream; auto ret Init(deviceId, stream); CHECK_RET(ret 0, LOG_PRINT(Init acl failed. ERROR: %d\n, ret); return ret); // 2. 构造输入与输出 aclTensor std::vectorint64_t selfShape {2, 2}; std::vectorint64_t outShape {2, 2}; void* selfDeviceAddr nullptr; void* outDeviceAddr nullptr; aclTensor* self nullptr; aclTensor* out nullptr; std::vectorfloat selfHostData {0, 1, 2, 3}; std::vectorfloat outHostData {0, 0, 0, 0}; ret CreateAclTensor(selfHostData, selfShape, selfDeviceAddr, aclDataType::ACL_FLOAT, self); CHECK_RET(ret ACL_SUCCESS, return ret); ret CreateAclTensor(outHostData, outShape, outDeviceAddr, aclDataType::ACL_FLOAT, out); CHECK_RET(ret ACL_SUCCESS, return ret); // 3. 调用 aclnnErf第一段获取 workspace第二段执行 uint64_t workspaceSize 0; aclOpExecutor* executor; ret aclnnErfGetWorkspaceSize(self, out, workspaceSize, executor); CHECK_RET(ret ACL_SUCCESS, LOG_PRINT(aclnnErfGetWorkspaceSize failed. ERROR: %d\n, ret); return ret); void* workspaceAddr nullptr; if (workspaceSize 0) { // 注意workspaceSize 可能为 0如空 Tensor 场景 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); } ret aclnnErf(workspaceAddr, workspaceSize, executor, stream); CHECK_RET(ret ACL_SUCCESS, LOG_PRINT(aclnnErf 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 并打印 auto size GetShapeSize(outShape); std::vectorfloat resultData(size, 0); ret aclrtMemcpy(resultData.data(), resultData.size() * sizeof(resultData[0]), outDeviceAddr, size * sizeof(float), 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]); } // 6. Inplace 路径直接对 self 覆写无需额外 out uint64_t inplaceWorkspaceSize 0; aclOpExecutor* inplaceExecutor; ret aclnnInplaceErfGetWorkspaceSize(self, inplaceWorkspaceSize, inplaceExecutor); CHECK_RET(ret ACL_SUCCESS, LOG_PRINT(aclnnInplaceErfGetWorkspaceSize failed. ERROR: %d\n, ret); return ret); 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); } ret aclnnInplaceErf(inplaceWorkspaceAddr, inplaceWorkspaceSize, inplaceExecutor, stream); CHECK_RET(ret ACL_SUCCESS, LOG_PRINT(aclnnInplaceErf failed. ERROR: %d\n, ret); return ret); ret aclrtSynchronizeStream(stream); CHECK_RET(ret ACL_SUCCESS, LOG_PRINT(aclrtSynchronizeStream failed. ERROR: %d\n, ret); return ret); // 从 selfDeviceAddr即被覆写的输入内存读取 Inplace 结果 auto inplaceSize GetShapeSize(selfShape); std::vectorfloat inplaceResultData(inplaceSize, 0); ret aclrtMemcpy(inplaceResultData.data(), inplaceResultData.size() * sizeof(inplaceResultData[0]), selfDeviceAddr, inplaceSize * sizeof(float), 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(inplaceResult[%ld] is: %f\n, i, inplaceResultData[i]); } // 7. 释放 aclTensor 与 device 资源固定写法 aclDestroyTensor(self); aclDestroyTensor(out); aclrtFree(selfDeviceAddr); aclrtFree(outDeviceAddr); if (workspaceSize 0) { aclrtFree(workspaceAddr); } if (inplaceWorkspaceSize 0) { aclrtFree(inplaceWorkspaceAddr); } aclrtDestroyStream(stream); aclrtResetDevice(deviceId); aclFinalize(); return 0; }示例要点解读两段式接口的严格配对aclnnErfGetWorkspaceSize返回的workspaceSize/executor只能交给配对的aclnnErf使用Inplace 系列同理交叉混用属于未定义行为。workspace 条件申请workspaceSize 0时才需要aclrtMalloc。从源码可知空 Tensor 输入时第一段接口直接返回workspaceSize 0示例中的条件判断正好覆盖此场景。Inplace 的内存语义aclnnInplaceErf复用selfRef的内存示例中 Inplace 结果直接从selfDeviceAddr拷回因此在构造 Inplace 调用前self中若还需保留原始数据应提前备份。结果校验对{0, 1, 2, 3}逐元素求 erf预期结果约等于{0, 0.8427008, 0.9953223, 0.9999779}可用于快速验证调用正确性。七、约束与最佳实践小结约束说明无。Erf 算子本身无额外的数学定义域限制——erf 在全实数域收敛且有界值域 (-1, 1)因此不存在除接口参数校验外的其它使用约束。数据格式与维度输入输出均为 ND 格式shape 一致维度不超过 8 维非连续 Tensor 由执行图内的 Contiguous/ViewCopy 自动处理开发者无需手动搬移。类型选择Atlas A2 产品上推荐直接使用 FLOAT32 / FLOAT16 / BFLOAT16BOOL/INT64 输入会经 Cast 链路自动提升为 FLOAT32 计算注意此时输出类型须能由 FLOAT 安全转换否则第一段接口将返回 161002。性能相关从 Tiling 实现可知元素数 ≤ 262144 的小输入走无 Double Buffer 的轻量模式大输入自动切换 Double Buffer 模式以提升 AICore 利用率开发者一般无需干预如需验证性能与精度可参考 tests/ut/op_kernel 目录下的数据生成与对比脚本。【免费下载链接】ops-math本项目是CANN提供的数学类基础计算算子库实现网络在NPU上加速计算。项目地址: https://gitcode.com/cann/ops-math创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
