从 0 到 1 调用 aclnnAdd：CANN 内置算子 API 实战

面向刚接触 CANN 的应用开发者：本文不从复杂模型入手，而是用一个可独立编译、可在昇腾 NPU 上真实运行的二维张量加法示例，串起 ACL 初始化、Device 内存管理、Tensor 构造、两段式算子调用、流同步和 CPU 结果校验等关键步骤。

在 AI 应用开发中，框架通常已经封装了算子调用。但当我们需要更精细地控制执行流程、减少框架依赖，或把计算嵌入自己的 C/C++ 服务时，就需要直接使用 CANN 提供的 AscendCL 与 ACLNN 接口。

本文选择 aclnnAdd 作为第一个实操算子。实验完成下面的计算：

output = self + alpha × other
self = [[1, 2], [3, 4]]
other = [[10, 20], [30, 40]]
alpha = 0.5
output = [[6, 12], [18, 24]]

这项实操是CANN应用开发方向：开发者直接调用 ACL 运行时完成设备、内存和任务流管理，再调用 ACLNN 算子 API 执行加速计算。与只在上层框架中调用一个加法接口相比，这条路径把数据怎样进入 NPU、算子怎样下发、结果何时可读以及资源怎样释放都完整展示出来。对于需要把昇腾计算能力嵌入现有 C/C++ 应用、构建自定义推理流水线，或者希望理解框架底层执行机制的开发者，它是一个足够小、又没有省略关键步骤的起点。

一、实验环境与目标

本次实测使用 ModelArts Notebook 的昇腾预置镜像，环境信息如下。 项目 实测配置 处理器架构 aarch64 CANN 8.5.2 NPU Ascend 910B4 单卡 编译器 镜像内置 GNU C++ 编译器 构建工具 CMake 编程接口 AscendCL + ACLNN

从图可以看到，ASCEND_HOME_PATH 指向 CANN 安装目录，npu-smi 能识别 910B4，设备健康状态为 OK。这一步很重要：如果系统只能找到头文件，却识别不到 NPU，程序可能成功编译，但会在 aclrtSetDevice 或算子执行阶段失败。

开始编码前，建议把“工具链可用”和“设备可用”分开检查。前者关注 CANN 头文件、动态库以及环境变量，决定项目能否完成编译和链接；后者关注驱动、设备枚举和健康状态，决定程序能否真正下发任务。两项检查同时通过，才能说明这是一次真实的 NPU 实操，而不是只在普通 CPU 环境中完成了代码编译。

本例的成功标准也不只是一条“运行完成”日志，而是同时满足四个条件：CMake 生成可执行文件；程序成功初始化 0 号设备；aclnnAdd 返回成功且 Stream 同步完成；NPU 结果与 CPU 期望值在误差阈值内一致。这四层证据分别覆盖构建、运行时、算子执行和数值正确性。

二、为什么 ACLNN 要分两段调用

ACLNN 单算子 API 通常采用“两段式”调用：

在本例中，对应接口是：

aclnnAddGetWorkspaceSize(self, other, alpha, output,
&workspaceSize, &executor);

aclnnAdd(workspace, workspaceSize, executor, stream);

这种设计把“准备执行”和“真正执行”分开。应用可以准确申请临时内存，也便于运行时根据输入 Tensor 的形状、数据类型和格式选择合适的算子实现。需要注意，算子下发通常是异步的；读取结果前必须同步 Stream。

这里的 executor 可以理解为本次算子执行所需信息的载体。它由第一段接口生成，应用不应自行构造，也不应跨越不兼容的输入配置随意复用。workspaceSize 则是本次执行额外需要的临时 Device 内存大小。不同形状、数据类型或算子实现可能得到不同结果，因此不能写死一个“经验值”。即使返回 0，也不是异常，只表示本次执行不需要额外工作空间。

把两段式接口放入完整调用链后，顺序如下：

aclInit
→ aclrtSetDevice
→ aclrtCreateStream
→ 申请 Device 内存并创建 Tensor/Scalar
→ aclnnAddGetWorkspaceSize
→ 按需申请 workspace
→ aclnnAdd 下发任务
→ aclrtSynchronizeStream
→ 结果复制回 Host 并校验
→ 逆序释放资源、aclFinalize

这条顺序不仅适用于 aclnnAdd。以后换成矩阵乘、激活函数或其他 ACLNN 内置算子时，运行时初始化、内存管理、Stream 同步和清理框架通常仍可复用，主要变化集中在算子头文件、输入输出 Tensor 以及属性参数。

三、准备输入并创建 aclTensor

项目目录如下：

aclnn-add-demo/
├── CMakeLists.txt
└── src/
└── main.cpp

示例在 Host 侧准备两个 float 类型的 2×2 矩阵，并给出 CPU 期望值：

const std::vector<int64_t> shape{2, 2};
const std::vector<float> selfHost{1.0F, 2.0F, 3.0F, 4.0F};
const std::vector<float> otherHost{10.0F, 20.0F, 30.0F, 40.0F};
const std::vector<float> expected{6.0F, 12.0F, 18.0F, 24.0F};
float alphaValue = 0.5F;

随后依次执行三件事：使用 aclrtMalloc 申请 Device 内存；用 aclrtMemcpy 把输入从 Host 复制到 Device；最后通过 aclCreateTensor 描述形状、步长、类型、格式和数据地址。

aclrtMalloc(deviceAddress, byteSize, ACL_MEM_MALLOC_HUGE_FIRST);
aclrtMemcpy(*deviceAddress, byteSize, hostData.data(), byteSize,
ACL_MEMCPY_HOST_TO_DEVICE);

*tensor = aclCreateTensor(
shape.data(), shape.size(), ACL_FLOAT, strides.data(), 0,
ACL_FORMAT_ND, shape.data(), shape.size(), *deviceAddress);

aclTensor 本身是元数据描述，真正的数据仍位于传入的 Device 地址。输出 Tensor 也要提前创建，并绑定一块足够大的 Device 内存。

创建 Tensor 时最容易被忽略的是 shape、strides 和数据区大小必须彼此一致。本例使用连续存储的二维数组，因此形状是 {2, 2}，步长是 {2, 1}：跨过第一维的一个元素需要移动两个 float，跨过第二维的一个元素只需移动一个 float。如果步长与真实布局不一致，程序未必立即报错，却可能按照错误的位置解释数据。

ACL_FORMAT_ND 表示按照通用 N 维格式描述数据，适合这个不带特殊图像布局的矩阵示例。数据类型选择 ACL_FLOAT，因此每个元素占 4 字节，四个元素需要 16 字节。申请、Host-to-Device 复制和创建 Tensor 时都使用同一字节数，能够避免越界或只复制部分数据。

alpha 与两个输入 Tensor 的角色不同。self 和 other 是位于 Device 上的张量，alpha 是通过 aclCreateScalar 创建的标量描述。算子最终计算的不是简单的 self + other，而是 self + alpha × other。本例把 alpha 设为 0.5，既能验证标量参数确实生效，也比全 1 参数更容易发现调用或数据传递是否出错。

四、下发 aclnnAdd 并取回结果

完成 ACL 初始化、Device 设置和 Stream 创建后，先创建 alpha 标量，再执行两段式调用：

aclOpExecutor* executor = nullptr;
uint64_t workspaceSize = 0;

aclError error = aclnnAddGetWorkspaceSize(
self, other, alpha, output, &workspaceSize, &executor);
if (error != ACL_SUCCESS) {
// 实际工程中应记录 API 名称与错误码
return 1;
}

void* workspace = nullptr;
if (workspaceSize > 0) {
aclrtMalloc(&workspace, workspaceSize, ACL_MEM_MALLOC_HUGE_FIRST);
}

error = aclnnAdd(workspace, workspaceSize, executor, stream);
if (error != ACL_SUCCESS) {
return 1;
}

aclrtSynchronizeStream(stream);

同步完成后，再使用 ACL_MEMCPY_DEVICE_TO_HOST 把输出复制回 Host。程序对所有 ACL/ACLNN 返回值进行检查，并在退出前逆序释放 Scalar、Tensor、workspace、Device 内存和 Stream，最后重置 Device、调用 aclFinalize。

示例没有把错误处理简化为一句“如果失败就退出”。每个可能失败的 API 都保留接口名称和错误码，便于判断问题发生在初始化、内存申请、参数准备还是算子下发阶段。如果中途出现错误，程序仍会进入统一清理流程，释放已经成功创建的资源。初学示例也应覆盖失败路径，因为 NPU Device 内存、Stream 和 Tensor 描述对象都有独立生命周期；只处理成功路径，连续调试时很容易积累资源泄漏。

真实业务项目可以进一步用 RAII 把这些句柄封装为 C++ 对象，让析构函数自动调用对应的释放接口。本文保留显式的 Resources 结构与 Cleanup 函数，是为了让第一次接触 ACL 的读者能清楚看到每项资源从哪里创建、又在哪里销毁。

五、使用 CMake 编译

示例从 ASCEND_HOME_PATH 查找头文件和动态库，链接 ascendcl、nnopbase 与 opapi：

find_path(ASCEND_INCLUDE_DIR acl/acl.h
PATHS "${ASCEND_HOME_PATH}/include" NO_DEFAULT_PATH)
find_library(ASCENDCL_LIBRARY ascendcl
PATHS "${ASCEND_HOME_PATH}/lib64" NO_DEFAULT_PATH)
find_library(NNOPBASE_LIBRARY nnopbase
PATHS "${ASCEND_HOME_PATH}/lib64" NO_DEFAULT_PATH)
find_library(OPAPI_LIBRARY opapi
PATHS "${ASCEND_HOME_PATH}/lib64" NO_DEFAULT_PATH)

target_link_libraries(aclnn_add_demo PRIVATE
"${ASCENDCL_LIBRARY}"
"${NNOPBASE_LIBRARY}"
"${OPAPI_LIBRARY}")

编译命令如下：

source "$ASCEND_HOME_PATH/bin/setenv.bash"
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake –build build -j2

图中来自 CANN 头文件的零长度数组提示是 -Wpedantic 触发的兼容性警告，不影响本次目标文件链接；最终出现 Built target aclnn_add_demo 与 [Build check] PASS，说明可执行文件已生成。

CMake 中没有写死 /usr/local/Ascend/… 之类的具体版本目录，而是从 ASCEND_HOME_PATH 查找依赖。这样在切换 CANN 安装版本时，只需加载对应版本的环境脚本，不必改动工程源码。find_path 和 find_library 均使用 NO_DEFAULT_PATH，可以避免系统中存在多套 CANN 时误链接到另一个版本的库。配置阶段若缺少任一依赖会直接给出错误，比把问题拖到链接或运行阶段更容易定位。

BUILD_RPATH 指向同一套 CANN 的 lib64，让示例可执行文件在当前实验环境中找到运行库。正式部署时，还应结合产品的安装结构、容器镜像或发布规范管理动态库搜索路径，不能把开发机的绝对目录当作通用发布方案。

六、在昇腾 NPU 上运行

执行命令：

./build/aclnn_add_demo

实测输出为：

[NPU result] = [[6.000000, 12.000000], [18.000000, 24.000000]]
[CPU expected] = [[6.000000, 12.000000], [18.000000, 24.000000]]
[Max abs error] = 0.000000
[Check] PASS

这里不仅打印 NPU 结果，还在 Host 侧用同一公式计算期望值，并计算最大绝对误差。对于更复杂的浮点算子，不应简单使用 ==，而要根据数据类型和业务精度选择绝对误差或相对误差阈值。

为了排除偶然结果，本次又连续执行三轮；每一轮的 NPU 输出都与 CPU 期望值一致，最大绝对误差均为 0。

重复运行的意义不只是“多打印几次 PASS”。它能够初步检查资源是否在每次进程退出时完整释放、输入是否被意外复用，以及异步任务是否存在未同步就读取结果的问题。对于本例这样规模很小、理论结果确定的算子，三次一致足以作为教程级验证；进入生产项目后，还应增加不同形状、广播组合、边界值、不同数据类型和异常输入测试，并在目标硬件与目标 CANN 版本上建立自动化回归。

七、什么时候适合直接调用 ACLNN

直接调用 ACLNN 的优势是控制粒度清晰。应用可以决定数据何时进入 Device、多个算子共享哪条 Stream、在哪个位置同步，以及怎样复用输入输出内存。对于已有 C/C++ 系统、低延迟服务、需要减少上层框架依赖的组件，或者希望把少量热点计算迁移到昇腾 NPU 的场景，这种方式很实用。

它的代价是开发者需要自己承担更多工程职责，包括参数合法性、内存容量、异步执行、错误处理和资源释放。如果需求是快速训练完整网络或直接运行成熟模型，优先使用已适配的深度学习框架通常更高效；如果现有内置算子无法表达目标计算，再考虑算子组合或自定义算子开发。aclnnAdd 的价值正在于帮助开发者先掌握这条基础边界：哪些工作属于 ACL 运行时，哪些参数属于算子 API，哪些资源必须由应用管理。

八、初学者常见问题

编译时提示找不到 aclnnop/aclnn_add.h

先检查 ASCEND_HOME_PATH 是否指向实际 CANN 版本目录，并确认 ${ASCEND_HOME_PATH}/include/aclnnop/aclnn_add.h 存在。不要只依赖一个失效的 latest 软链接。

链接阶段出现 undefined reference

只链接 ascendcl 不够。ACLNN 单算子程序还需要按文档和安装版本链接 nnopbase、opapi，并确保运行时能找到 ${ASCEND_HOME_PATH}/lib64。

workspaceSize 为 0 是不是错误

不是。应把 0 当作合法返回值：只有 workspaceSize > 0 时才申请 workspace，随后仍把该大小和指针传给执行接口。

为什么复制回 Host 后结果不对

最常见原因是漏掉 aclrtSynchronizeStream。算子是异步下发的，必须确认 Stream 执行完成后再进行 Device-to-Host 复制和结果校验。

资源释放顺序为什么重要

Tensor、Scalar、workspace、数据内存和 Stream 都有独立生命周期。推荐使用统一清理路径或 RAII 封装，既覆盖成功流程，也覆盖任何 API 中途失败的流程，避免 NPU 内存泄漏。

6. npu-smi 正常，但 aclInit 仍失败怎么办

先确认运行程序的终端已经加载当前 CANN 版本的 setenv.bash，并检查程序实际加载的动态库是否来自同一版本。驱动能识别设备只说明硬件层面基本可用，并不能证明应用运行时环境完整。若系统安装了多套 Toolkit，环境变量与链接库版本不一致也是常见原因。

换一组输入后为什么要重新检查输出容量

输出 Tensor 的形状和数据区由应用预先准备。修改输入形状、启用广播或切换数据类型后，原来的输出字节数可能不再正确。调用前应依据算子约束重新推导输出形状，并确保绑定的 Device 内存足够，不能只替换 Host 输入数组。

九、总结

通过一个小型 aclnnAdd 示例，我们已经走通了 CANN 应用开发的最小闭环：

掌握这条路径后，再学习其他 ACLNN 内置算子时，变化主要集中在输入输出、属性参数和对应的算子接口，整体工程框架可以继续复用。

参考资料

• CANN 算子库 API 概述

• AscendCL 单算子调用示例：Add

• CANN 社区主页