第一次在昇腾设备上接触 aclnn，我对着头文件里的两个同名函数愣了很久：一个叫aclnnAddGetWorkspaceSize，一个叫aclnnAdd。你说一个算子，为什么偏偏拆成两个接口来调？当时翻文档只看到一句“两阶段调用”，看完还是一头雾水，代码也不知道该往哪个函数里填。真正跑通第一个算子、又翻完 ops-nn 仓库里那套标准封装之后，我才把背后的设计逻辑摸透。这篇文章就是把这段过程完整捋一遍：从为什么拆两步，到标准调用姿势，再到仓库里那套封装为什么能直接抄作业，最后附上我路上踩过的坑。想把 aclnn 两阶段调用一次性搞明白的同学，按这条线往下走就行。

1. 先别急着写代码：aclnn 是哪一层，两阶段在说什么

1.1 aclnn 的两层身份

aclnn 全称是 AscendCL Neural Network，从名字就能看出来，它不是最底层的运行时接口，而是专门面向神经网络算子的那一层高级 API。你通过它调用算子时，不需要关心算子内部在芯片上到底走了哪个核、用了什么 tiling 策略、数据怎么搬运，只需要把输入输出描述清楚，剩下的交给运行时和算子实现。

但这里有个容易混淆的点：aclnn 并不是和底层完全割裂的一层。它下面依然站着设备内存管理、流同步、指令下发这些基础能力，你该准备的设备指针、该同步的流，一个都不能省。我一开始把它理解成“高级接口所以什么都帮我处理”，结果吃了不少亏。

在实际工程里，aclnn 接口往往出现在两条路径上：一条是上层图编译框架把计算图拆成单算子后，逐个下发到 aclnn；另一条就是你手动写算子调用，常见于算子功能测试、自定义算子验证、模型推理里某些特殊头的实现。不管哪条路，落到单个算子上的调用模型都是一样的，就是标题里说的“两阶段调用”。

1.2 “先量尺寸，再干活”到底指什么

两阶段调用的套路，你可以完全用装修来类比。

你请师傅来给厨房装定制柜子，师傅不会拎着电钻直接开干，而是先上门量尺寸：量完墙距、水管位置、插座高度，然后告诉你“需要这些板子和五金，你先把料备齐”，等材料都齐了，师傅才正式进场施工。量尺寸这一步不产生装修结果，但它决定了后续所有工作能不能做对。

aclnn 也是这个逻辑。第一阶段是aclnnXxxGetWorkspaceSize，给它传算子所需的全部张量描述，它帮你算清楚：当前这组输入到底需要额外多少设备内存（叫 workspace），同时生成一个执行句柄 executor。第二阶段是aclnnXxx，把你从第一阶段拿到的 workspace 地址和执行句柄交给它，它才开始真正做计算。

换句话说，第一个函数的结尾，才是第二个函数的开始。很多第一次接触的人会下意识觉得第一阶段可调可不调，或者干脆猜一个 workspace 大小传进去，这是后面的坑。

1.3 为什么非拆两步不可

你可能想问：为什么不在一个函数内部把 workspace 分配好、直接执行完？这背后有三个实际原因。

第一，workspace 大小只有在运行期才知道。算子的输入 shape、dtype、format 一旦组合变化，算子内部选中的算法分支、tiling 策略、中间缓冲布局都会跟着变。算子实现没法在编译期给你一个固定值，只能拿到真实张量描述现场推导。既然推导需要用户输入，那就天然分成“先推导”和“再执行”两个动作。

第二，显存管理权必须留给上层。如果算子在内部偷偷调用内存分配，上层就完全失控了：没法做内存池复用，没法统一规划大块显存，高频小算子还会被反复分配释放拖垮性能。昇腾的应用往往对显存规划和流并发要求很高，所以 workspace 由调用方分配、由调用方管理，是最合理的设计。

第三，执行句柄可以复用。第一阶段不只是算出 workspace 大小，它还会构建一个 executor，里面装好了算子执行需要的各种内部状态。同一份输入描述组合下，executor 是可以复用的。两阶段模型给了上层一个缓存执行上下文的机会，而不是每次从头推导一遍。

理解到这里，你对两阶段调用就有了一个总体的印象：第一阶段是“查需求”，第二阶段是“干活”，中间的 workspace 是干活时要用的临时料场。

2. 两阶段调用的标准姿势：从 API 签名到内存分配

2.1 第一阶段aclnnXxxGetWorkspaceSize里到底发生了什么

先看一个标准的调用签名（以 Add 算子为例，我写成原型风格，具体参数名以你本机头文件为准）：

aclnnStatus aclnnAddGetWorkspaceSize( const aclTensor* src0, const aclTensor* src1, const aclTensor* dst, uint64_t* workspaceSize, aclOpExecutor** executor);

注意它的入参里有输入张量，也有输出张量。这一点容易忽略：你以为第一阶段只是“算算大小”，其实它已经把算子的完整执行计划都准备好了，包括输出张量的推导和内部 kernel 的选择。

在这个函数的黑盒里，大致做了下面几件事：

• 参数校验：检查 dtype、shape、format 当前组合是否支持，比如输入和输出的形状是否满足广播规则；
• 算法选择：同一类算子往往有多个 kernel 实现，比如不同 shape 段位、不同 dtype 走不同的核函数，这里会选择最合适的一个；
• workspace 计算：选中 kernel 后，内核实现会返回它需要的临时缓冲大小，这个大小就是workspaceSize；
• executor 构建：把所有推导结果、kernel 信息、张量引用打包进一个执行句柄，供第二阶段直接使用。

你在编码时只要记住一件事：第一阶段必须保证入参张量已经正确创建，输出张量的对象也要存在（哪怕里面的内容还没被计算）。它不是一个“可跑可不跑”的可选步骤，而是第二阶段的必要前置。

2.2 第二阶段aclnnXxx的调用细节

拿到 workspaceSize 和 executor 之后，调用方要负责分配一块不小于 workspaceSize 的设备内存，然后把指针交给执行函数：

aclnnStatus aclnnAdd( void* workspaceAddr, uint64_t workspaceSize, aclOpExecutor* executor, aclrtStream stream);

这里有个容易踩坑的语义：如果第一阶段返回的workspaceSize是 0，说明这个算子在当前输入下不需要额外 workspace，你可以传nullptr进去。但如果 workspaceSize 大于 0 而你传了nullptr，或者分配的长度不够，轻则算子内部越界访问，重则直接 crash。

还需要注意，aclnn 的第二次调用是异步的。它只是把指令下发到指定的 stream 上，返回时计算可能还没发生。如果你紧接着就去读输出数据或者释放内存，拿到的基本是随机结果。标准流程里，执行完要根据业务需求做一次aclrtSynchronizeStream(stream)或者依赖这个 stream 上的事件同步。

整个过程连起来是这个样子：

uint64_t workspaceSize = 0; aclOpExecutor* executor = nullptr; aclnnStatus ret = aclnnAddGetWorkspaceSize(src0, src1, dst, &workspaceSize, &executor); if (ret != ACLNN_SUCCESS) { // 按错误码排查 } void* workspaceAddr = nullptr; if (workspaceSize > 0) { ret = aclrtMalloc(&workspaceAddr, workspaceSize, ACL_MEM_MALLOC_HUGE_FIRST); if (ret != ACL_SUCCESS) { // 分配失败处理 } } ret = aclnnAdd(workspaceAddr, workspaceSize, executor, stream); if (ret != ACLNN_SUCCESS) { // 按错误码排查 } aclrtSynchronizeStream(stream); // 用完统一释放 if (workspaceAddr != nullptr) { aclrtFree(workspaceAddr); }

2.3 workspace 分配的三种策略

既然 workspace 要自己分配，那每次调用都现分现释，显然是最简单的写法，却不是最优的。实际项目里通常有三种策略。

第一种是每次调用临时分配。代码最直观，适合算子测试脚本、验证 demo，或者低频调用的场景。缺点也明显：显存分配是有开销的，高频小算子场景下，分配和释放本身可能比计算还耗时。

第二种是进程级缓存。用一个缓存结构，以“算子名 + 输入输出的 shape/dtype/format + 设备号”为 key，把 workspace 指针缓存下来。下次遇到相同 key 直接复用。这套路看起来简单，但要注意 key 必须算全，漏一个字段就可能把不对尺寸的 workspace 复用给新 shape，最终踩出越界问题。还需要处理设备指针跨流使用的同步问题。

第三种是有界内存池。这种做法更接近框架内部的行为，把 workspace 和其他设备内存统一在一个池子里管理，按需从池中切块。实现成本高，普通应用没必要自己造，我也是在改造性能敏感模块时才认真对待。

我的建议很简单：起步阶段就老老实实用第一种，先把逻辑跑对，确认整体流程没问题；等你真遇到性能瓶颈了，再上缓存的策略。千万别在一开始就搞复杂内存池，否则出了问题你分不清是算子逻辑错了还是池子代码错了。

3. ops-nn 仓库给出的标准答案：封装类是这样把两阶段“藏”起来的

3.1 一个 runner 类是如何炼成的

看完上面的调用过程，你应该能感觉到：每个算子的两阶段调用模板都差不多，区别只是参数列表不同。ops-nn 仓库里那一套标准答案，核心思路就是把这段样板代码封装成一个通用的 runner，让业务代码从“操作两阶段”变成“描述一次算子调用”。

我看到过不少这类封装，典型形态是这样一个类：

class AclnnOpRunner { public: AclnnOpRunner(const std::string& opName, aclrtStream stream) : opName_(opName), stream_(stream) {} AclnnOpRunner& AddInput(const aclTensor* tensor) { inputs_.push_back(tensor); return *this; } AclnnOpRunner& AddOutput(aclTensor* tensor) { outputs_.push_back(tensor); return *this; } void Run() { Prepare(); // 内部调用 GetWorkspaceSize AllocWorkspace(); Execute(); // 内部调用真正的执行函数 Sync(); } private: std::string opName_; aclrtStream stream_; std::vector<const aclTensor*> inputs_; std::vector<aclTensor*> outputs_; aclOpExecutor* executor_ = nullptr; uint64_t workspaceSize_ = 0; void* workspace_ = nullptr; };

关键在Run()里。它把第一阶段、workspace 分配、第二阶段调用这些细节全部吞掉了。使用方看到的代码就变成：

AclnnOpRunner("Add", stream) .AddInput(src0) .AddInput(src1) .AddOutput(dst) .Run();

为什么仓库会选这种 builder 风格的封装，而不是写一个模板函数？因为算子与算子之间的输入输出个数差别太大了。有的算子一个输入一个输出，有的三输入两输出，有的还带属性参数。模板函数没法统一所有签名的组合，但 builder 模式天然支持“这条加一行，那条加一行”，调用方表达起来非常自然。

3.2 从标准答案里挖出的三个设计细节

翻这种封装代码，不能只看它怎么调 API，还要看它默认处理了哪些你容易忽略的问题。我至少挖出了三个。

第一个细节是 executor 的释放和重建。很多封装类在Prepare()里会先检查已有 executor 是否还匹配当前的输入形状，如果 shape 变了，必须先销毁旧 executor 再重建。否则你在 1x1024 的输入下构建的 executor，换个 2x512 的形状继续复用，内部 tiling 信息就是错的。这一点在仓库的标准实现里通常有清晰注释，但我见过不少人自己写简化版封装时把这个边界漏了。

第二个细节是 workspace 的内存对齐。虽然接口给的是字节数，但真实设备上 workspace 往往要求一定对齐粒度。封装类在分配时会额外对齐，然后再把对齐后的地址传给执行函数。自己写测试代码时如果发现某些算子在特定尺寸下偶发异常，可以考虑是不是 workspace 只分配了裸字节数、没有做对齐。当然这个行为依赖具体实现版本，准确判断要看核函数实现里的要求。

第三个细节是错误码包装。裸的 aclnn 调用返回aclnnStatus，但状态码很干，对定位问题帮助有限。好的封装会把状态码转成字符串、附带当前算子名和参数摘要一起打日志。我在排查线上算子问题时，靠这种日志省了很多力气。入门阶段可以自己造一个轻量的CheckStatus辅助函数，至少把状态码打出来，不要拿到非成功返回就直接return，否则等于把线索全扔了。

3.3 顺着仓库文档读代码的顺序

很多同学拿到 ops-nn 仓库不知道从哪里看起。我建议的顺序是：先看它提供的示例工程的目录结构，定位到一个算子的 demo 入口；然后从入口函数一路看到调用 runner 的地方；接着再打开 runner 类的实现文件，只看Run()和Prepare()这两个函数。这样十分钟就能把“业务代码如何使用”和“内部如何封装”两层都盘清楚。

陪跑一遍之后你会明白，所谓“标准答案”，本质上不是某个神奇的函数，而是一套成熟的工程约定：资源谁分配、谁释放、生命周期如何管理、异常如何暴露。照着这套约定去写自己的算子封装，比从 API 文档逐行学要高效得多。

4. 实操：把 Add 算子从零跑到通

4.1 准备输入输出张量

理论讲再多，不如动手跑一次。下面我用一个最简单的 Add 例子，把完整流程走一遍。场景固定：两个 float32 的一维向量相加，长度都是 1024，输出也是长度 1024 的向量。

在调用 aclnn 之前，先得把张量描述搭起来。aclnn 接口里用的是aclTensor这个高层句柄，但在不同版本里创建方式略有出入。为了方便说明，我用一组相对通用的伪代码来表达，实际开发时以你机器上的头文件为准：

const int64_t dims[1] = {1024}; // 创建张量描述 auto desc = aclCreateTensorDesc(ACL_FLOAT32, 1, dims, ACL_FORMAT_ND); // 创建数据缓冲区（data 是已经搬运到设备侧的内存指针） auto buffer = aclCreateDataBuffer(data, 1024 * sizeof(float)); // 组装成 aclTensor aclTensor* tensor = aclCreateTensor(desc, buffer);

这里有个重点：data 必须已经是设备侧内存。aclnn 不会帮你做 host 到 device 的搬运，也不会替你判断指针是主机指针还是设备指针。你在写测试代码时最容易犯的错误就是把 host 端malloc出来的指针直接塞进去，结果要么数据错乱，要么设备侧访问出错。

正确顺序是先用标准方式申请设备内存，把 host 数据拷贝到设备，再构建张量描述。至于数据怎么准备，常见做法是用随机数或固定值填充输入。我习惯用固定值，比如第一个输入全是 3.0，第二个输入全是 5.0，这样做完一加，结果应该全等于 8.0，验证非常直观。

4.2 完整的两阶段调用骨架

张量准备好之后，后面的调用代码就非常机械了。为了保证你直接能看懂、能照着写，我把整段流程放在一个函数里：

bool RunAddOnDevice( aclrtStream stream, void* deviceSrc0, void* deviceSrc1, void* deviceDst) { // 1. 构建张量对象 const int64_t dims[1] = {1024}; aclTensorDesc* desc = aclCreateTensorDesc(ACL_FLOAT32, 1, dims, ACL_FORMAT_ND); aclTensor* src0 = aclCreateTensor(desc, aclCreateDataBuffer(deviceSrc0, 1024 * sizeof(float))); aclTensor* src1 = aclCreateTensor(desc, aclCreateDataBuffer(deviceSrc1, 1024 * sizeof(float))); aclTensor* dst = aclCreateTensor(desc, aclCreateDataBuffer(deviceDst, 1024 * sizeof(float))); // 2. 第一阶段：获取 workspace 大小 和 executor uint64_t workspaceSize = 0; aclOpExecutor* executor = nullptr; aclnnStatus ret = aclnnAddGetWorkspaceSize(src0, src1, dst, &workspaceSize, &executor); if (ret != ACLNN_SUCCESS) { // 打印错误码，不要直接 here return false; } // 3. 分配 workspace void* workspaceAddr = nullptr; if (workspaceSize > 0) { if (aclrtMalloc(&workspaceAddr, workspaceSize, ACL_MEM_MALLOC_HUGE_FIRST) != ACL_SUCCESS) { return false; } } // 4. 第二阶段：真正执行 ret = aclnnAdd(workspaceAddr, workspaceSize, executor, stream); if (ret != ACLNN_SUCCESS) { return false; } // 5. 同步，确保执行完成 aclrtSynchronizeStream(stream); // 6. 清理 aclDestroyTensor(src0); aclDestroyTensor(src1); aclDestroyTensor(dst); if (workspaceAddr != nullptr) { aclrtFree(workspaceAddr); } return true; }

这个骨架基本可以直接套用到其他算子：把aclnnAddGetWorkspaceSize换成对应算子的 Get 接口，把aclnnAdd换成对应算子的执行接口，参数列表按头文件替换，就可以了。本质上所有算子在两阶段这个层面是同一套节奏。

4.3 验证结果与资源释放

执行完之后，输出数据还在设备侧。想确认算子真的执行了，有两个途径：一是把deviceDst拷回 host 端，用memcpy那套逻辑打印前几个数，确认是不是 8.0；二是直接看 profiling 数据，确认算子时间片确实下发过。入门阶段第一招就够用了，毕竟固定值一眼能看出对错。

资源释放的顺序也值得多说一句。释放的先后原则是：先同步流，再释放 workspace 和中间对象，最后才释放设备侧数据内存。如果顺序反了，比如先释放数据内存，然后才同步流，执行可能还没真正读完输入，就会拿到已经归还给系统的内存，结果变得不可预测。我见过不少初学的同事在这里栽跟头，跑一次没问题、跑第二次就崩。

还有一个小细节：如果同一个张量对象要在多次算子调用之间复用，那不要每调一次就销毁一次。销毁的语义是“这个对象不再使用了”，而不是“这次调用结束了”。把生命周期和调用次数严格对应，能省掉一批很难查的指针悬空问题。

5. 常见问题与排查技巧实录

5.1 问题速查表

把踩过的坑整理成一张表，方便你排查时对照参考：

5.2 生命周期问题：最容易翻车的边界

上面表格里，我特别想把“executor 复用”和“张量生命周期”单独拎出来讲。

先说说 executor。第一次跑通 Add 之后，很多人会想把 executor 缓存起来，省去每次都调用 GetWorkspaceSize 的开销。这个优化本身没错，但缓存条件必须严格。executor 内部携带了当前输入输出的 shape、dtype、format 以及选中的 kernel。只要这些条件任何一个变了，旧 executor 必须销毁重建。

我自己的做法是：在缓存结构里把“输入输出形状、dtype、format、算子名”作为 key，每次调用前算一遍 key，不一致就重建 executor。这样既保留了缓存收益，又不会因为形状切换导致崩溃。你要是更懒一点，也可以参考 ops-nn 封装实现里的判断逻辑，仓库里那套写法已经验证过。

再说张量生命周期。aclTensor对象有一个常见误解：它被传给算子之后，是不是算子会把它的数据复制一份？不是。aclnn 在执行时，本质上还会引用你传入的张量对象和底层数据指针。所以你不能在算子执行完成之前就把张量销毁，也不能把底层数据内存提前释放。一个安全的准则就是：同步完之后才允许释放所有传给算子的对象和缓冲区。

5.3 两个容易被忽略的认知盲区

最后补两个认知层面的坑。

第一个是“两阶段之间能改什么”。GetWorkspaceSize 返回之后，到真正执行之前，你可以搬运输入数据、准备数据内容，这些都没有问题。但你绝对不能修改张量的 shape、dtype、format，因为这些直接影响 workspaceSize 和 executor 的推导结果。改了就等于拿着错误的尺子去施工，后面崩了别奇怪。

第二个是“workspaceSize 为 0 不代表没执行”。我在前面提到过，有些算子对某些 shape 组合天然不需要 workspace。看到 0 不要慌，也不要觉得是接口没生效。区分“真的不需要”和“调用失败”，看函数返回的aclnnStatus就够了，只要返回成功，0 就是正常的。

我个人在实际操作里的体会是，两阶段调用本身不难，真正难的是把它背后的资源管理逻辑内化成习惯。先看清楚每个对象从哪来到哪去，再写代码，你会少走很多弯路。如果现在让我给正在入门昇腾算子调用的朋友一个建议，那就是别从零手写一堆分散的测试代码，直接去看 ops-nn 仓库里那套 runner 封装，把结构抄过来，在它的基础上做加减法。这样你既拿到了标准答案，又能把两阶段调用这个模型的每个环节都摸得明明白白。