企业官网建设流程全解析

CANN ops-math Sign 算子 aclnnSign 接口使用指南与源码解析

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

本文以 CANN ops-math 开源仓库中 Sign 算子的官方接口文档 aclnnSign.md 为主体，结合仓库内算子定义、Tiling、Kernel 与 API 层源码，系统讲解在 NPU 上通过两段式接口aclnnSignGetWorkspaceSize+aclnnSign逐元素计算符号（Sign）的完整方法，包括产品支持范围、参数与返回码语义、可运行的调用示例，以及从 Host 侧算子注册到 Device 侧 Kernel 执行的底层实现脉络。读完本文，你将能够独立编写并编译运行一个基于 aclnn 接口的 Sign 算子调用程序，并理解其内部工作机理。

一、功能与产品支持

1.1 算子功能

Sign（符号函数）算子对输入 Tensor 逐元素进行取符号运算，并将结果写入输出 Tensor。其行为完全由输入元素的正负零决定：

$$ result_i= \begin{cases} 1 & \text{if } self_i>0 \[4pt] 0 & \text{if } self_i=0 \[4pt] -1 & \text{if } self_i<0 \end{cases} $$

即：正数输出 1，零输出 0，负数输出 -1。该算子在归一化、梯度符号裁剪、量化符号提取等数值处理场景中应用广泛，是 CANN ops-math 数学类基础算子库中的典型 element-wise 算子。

1.2 产品支持情况

从算子注册源码 sign_def.cpp 可见，Sign 算子的 AICore 配置同时添加了ascend910b与ascend910_93两种硬件配置，分别对应上述 A2/A3 系列产品，与文档声明一致。

二、两段式接口设计

每个 aclnn 算子都采用两段式接口的调用约定。Sign 算子同样如此：

1. 第一段：调用aclnnSignGetWorkspaceSize，完成入参校验，并获取计算所需的 workspace 大小以及一个封装了算子计算流程的执行器（aclOpExecutor）；
2. 第二段：调用aclnnSign，将第一段获取的 workspace 与 executor 传入，在指定的 stream 上真正执行计算。

函数原型如下：

aclnnStatus aclnnSignGetWorkspaceSize( const aclTensor *self, const aclTensor *result, uint64_t *workspaceSize, aclOpExecutor **executor)

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

接口声明定义在 aclnn_sign.h，标注@domain aclnn_math，属于数学域 aclnn 接口。

三、aclnnSignGetWorkspaceSize 参数说明

第一段接口的参数如下：

几点说明：

• self与result支持的数据类型完全一致（FLOAT、FLOAT16、INT32、INT16、BFLOAT16），且两者 shape 必须一致（下文约束说明会详述）；
• 支持非连续 Tensor（标记 √），API 内部会自动完成连续化处理；
• workspaceSize与executor均为输出参数，由框架在内部计算并返回，调用方无需预知具体数值。

3.1 返回值与入参校验

两段接口的返回值均为aclnnStatus状态码，具体含义参见 aclnn返回码。

第一段接口会完成入参校验，出现以下场景时报错：

从 API 实现 aclnn_sign.cpp 可以确认实际的校验流程（CheckParams）依次为：

1. CheckNotNull2Tensor(self, result)：检查参数是否为空指针，失败返回ACLNN_ERR_PARAM_NULLPTR；
2. CheckDtypeValid(self, result)：检查输入/输出数据类型是否在 API 支持的数据类型范围之内，失败返回ACLNN_ERR_PARAM_INVALID；
3. CheckShape(self, result)：检查 self 与 result 的 shape 是否一致（OP_CHECK_SHAPE_NOT_EQUAL），失败返回ACLNN_ERR_PARAM_INVALID。

四、aclnnSign 参数说明

第二段接口的参数如下：

workspace由调用方依据第一段接口返回的workspaceSize通过aclrtMalloc在 Device 侧申请；当workspaceSize为 0 时无需申请（例如空 Tensor 场景，API 内部会直接返回workspaceSize = 0，见 aclnn_sign.cpp）。

五、约束说明

原文档对 Sign 算子的约束说明为：无。

需要说明的是，虽然算子本身无额外约束，但根据 sign_def.cpp 中的算子定义，输入x与输出y的参数类型均为REQUIRED，支持的数据类型（ge::DT_BF16, DT_FLOAT16, DT_FLOAT, DT_INT32, DT_INT16）与数据格式（均为FORMAT_ND）必须匹配；同时由 sign_infershape.cpp 可知，输出 shape 直接由输入 shape 拷贝而来（*yShape = *xShape），因此输入与输出的 Shape 必须严格保持一致，这也是 API 层CheckShape校验的根源。

六、调用示例

以下示例代码完整展示了一个 Sign 算子 aclnn 调用的全流程，仅供参考。具体编译和执行过程请参考编译与运行样例。

#include <iostream> #include <vector> #include "acl/acl.h" #include "aclnnop/aclnn_sign.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 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::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根据自己的需要处理 CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("Init acl failed. ERROR: %d\n", ret); return ret); // 2. 构造输入与输出，需要根据API的接口自定义构造 std::vector<int64_t> selfShape = {4, 2}; std::vector<int64_t> outShape = {4, 2}; void* selfDeviceAddr = nullptr; void* outDeviceAddr = nullptr; aclTensor* self = nullptr; aclTensor* out = nullptr; std::vector<float> selfHostData = {1, 2, 3, 4, 5, 6, 7,8}; std::vector<float> outHostData = {0, 0, 0, 0, 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名称 uint64_t workspaceSize = 0; aclOpExecutor* executor; // 调用aclnnSign第一段接口 ret = aclnnSignGetWorkspaceSize(self, out, &workspaceSize, &executor); CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclnnSignGetWorkspaceSize 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); } // 调用aclnnSign第二段接口 ret = aclnnSign(workspaceAddr, workspaceSize, executor, stream); CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclnnSign 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]); } // 6. 释放aclTensor，需要根据具体API的接口定义修改 aclDestroyTensor(self); aclDestroyTensor(out); // 7. 释放device资源，需要根据具体API的接口定义修改 aclrtFree(selfDeviceAddr); aclrtFree(outDeviceAddr); if (workspaceSize > 0) { aclrtFree(workspaceAddr); } aclrtDestroyStream(stream); aclrtResetDevice(deviceId); aclFinalize(); return 0; }

上述示例针对ACL_FLOAT类型编写。仓库自带的完整可运行样例位于 examples/test_aclnn_sign.cpp，其输入为 INT16 数据{-3, -1, 0, 1, 2, -5, 0, 6}，shape 为{4, 2}，期望输出为{-1, -1, 0, 1, 1, -1, 0, 1}，可用作验证结果正确性的参考基准。

七、源码级实现原理

下面沿着"算子注册 → shape 推导 → Tiling 切分 → Kernel 计算 → aclnn 封装"的链路，解读 Sign 算子在仓库中的完整实现。

7.1 算子定义与注册（Host 侧）

sign_def.cpp 通过OP_ADD(Sign)注册Sign算子：

• 输入x、输出y均为REQUIRED；
• 数据类型支持DT_BF16 / DT_FLOAT16 / DT_FLOAT / DT_INT32 / DT_INT16五种，格式全部为ND；
• AICore 配置为ascend910b与ascend910_93。

7.2 Shape 推导

sign_infershape.cpp 中InferShapeSign从输入x取出 shape 后直接赋给输出y（*yShape = *xShape）。由于 Sign 是逐元素算子，输出与输入天然同构，这是整个算子在形状层面"零变化"的直接体现，也是 API 层要求 self 与 result shape 一致的底层原因。

7.3 Tiling 切分策略

sign_tiling.cpp 负责在编译/构图阶段生成 Tiling 数据，关键逻辑：

• 通过platform_ascendc::PlatformAscendC获取 UB 内存大小与可用核数（GetPlatformInfo）；
• 以 32 字节（BLOCK_SIZE）为基本对齐单元计算单核可承载的 tile 数据量tileDataNum。其中 BF16 类型在 UB 中预留 9 份分块空间（UB_DATA_NUM_BF16），其他类型预留 5 份（UB_DATA_NUM_OTHER），因为 BF16 在 Kernel 计算时需要额外的 FP32 中转缓冲区；
• 数据量不足一个 tile 时只用 1 个核；否则按"每核至少 32B 数据"的原则将数据尽量均摊到所有可用核上，并区分大核/小核（bigCoreDataNum/smallCoreDataNum）、尾块（tailBlockNum）以及每核的 tile 数与尾数据量，最终写入SignTilingData结构；
• 通过GetWorkspaceSize计算 workspace（包含系统库 API 所需空间），最终SetBlockDim(coreNum)设置核数、SetTilingKey设置 tiling key。

7.4 Kernel 计算（Device 侧）

sign.cpp 是 Kernel 入口，核心实现在 sign.h 的KernelSign<TYPE_X>类中，采用标准的CopyIn → Compute → CopyOut流水（双缓冲BUFFER_NUM = 2）。Compute针对不同数据类型做了差异化处理：

• BFLOAT16：先用Cast将数据转到 FP32 执行AscendC::Sign，再Cast回 BF16 输出（因为向量单元不直接提供 BF16 的 Sign 指令）；
• INT32 / INT16：用Maxs与Mins将数值钳位到[-1, 1]区间，等价于符号函数（Maxs(x, -1)保证不小于 -1，Mins(·, 1)保证不大于 1）；
• 其他浮点类型（FLOAT / FLOAT16）：直接调用向量指令AscendC::Sign(yLocal, xLocal, processDataNum)。

7.5 aclnn API 层封装

aclnn_sign.cpp 实现了对外接口，除了前文所述的参数校验外，还有几个值得注意的细节：

• 空 Tensor 快速路径：若 self 或 result 为空 Tensor，直接返回workspaceSize = 0并结束，不进入计算构图；
• 非连续 Tensor 处理：self非连续时先调用l0op::Contiguous转连续；计算完成后若result是非连续 Tensor，则通过l0op::ViewCopy将连续结果写回目标内存视图；
• BOOL 类型支持：API 层类型支持列表（DTYPE_SUPPORT_LIST）除 FLOAT/FLOAT16/INT16/INT32 外，还包括 DOUBLE、INT64、COMPLEX64、COMPLEX128、BOOL。其中 BOOL 输入会被l0op::Cast转成 INT32 计算，输出前再Cast回 BOOL；BF16 则通过平台判断（DAV_2201/DAV_3510，即 Atlas A2/A3）单独放行；
• 维度上限：超过MAX_SUPPORT_DIMS_NUMS（8 维）的输入会先经l0op::Reshape压维处理，计算完成后再恢复原形状；
• 第一段接口统一通过CREATE_EXECUTOR()创建执行器、GetWorkspaceSize()汇总 workspace 大小；第二段接口最终由CommonOpExecutorRun完成在指定 stream 上的异步下发执行。

八、测试与验证

仓库为 Sign 算子提供了完整的单测与数据校验脚本，便于验证实现正确性：

• tests/ut/op_api/test_aclnn_sign.cpp：aclnn 接口层的单元测试；
• tests/ut/op_host/test_sign_tiling.cpp：Tiling 计算正确性测试；
• tests/ut/op_kernel/test_sign.cpp：Kernel 计算结果验证，配套 gen_data.py 生成输入数据、compare_data.py 对比期望输出。

此外，README.md 的贡献说明记录了该算子的演进历史：2025/12/12 由个人开发者 hth810 适配开源仓，2026/5/12 补充 INT16 数据类型支持——这也解释了上文中 Kernel 对 INT16 走Maxs/Mins钳位路径的由来。

九、延伸阅读

• 两段式接口说明：aclnn 接口统一调用约定
• aclnn 返回码：状态码含义与错误处理
• 编译与运行样例：示例程序编译运行指引
• 非连续 Tensor 说明：理解 API 层连续化与 ViewCopy 机制
• 算子接口文档 与 算子目录 README

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