CANN Runtime 模型运行实例中的 Stream 跳转与激活实战:基于 aclmdlRI 的图捕获与条件执行样例解析

原创2026-09-18 11:40:261,685 阅读
文章标签:人工智能Ascend任务调度性能剖析

CANN Runtime 模型运行实例中的 Stream 跳转与激活实战:基于 aclmdlRI 的图捕获与条件执行样例解析

导读

本文围绕 CANN Runtime 开源仓库中的 2_model_switch 样例,深入讲解如何基于模型运行实例(Model Runtime Instance,简称 modelRI)接口族构建可复用的"算子任务图",并在任务图中实现 Stream 跳转(SwitchStream) 与 Stream 激活(ActiveStream) 两种异步控制流能力。读完本文,你将掌握 aclmdlRIBuildBegin / aclmdlRIBindStream / aclmdlRIEndTask / aclmdlRIBuildEnd 的完整建模流程,理解 aclrtSwitchStream 与 aclrtActiveStream 的语义差异与配合方式,并能照样例工程独立编译、运行与验证多分支条件执行的结果。

样例概览:一个任务图、三种条件路径

该样例位于 example/2_advanced_features/model_ri/2_model_switch 目录,属于 model_ri 系列(example/2_advanced_features/model_ri/README.md)中专门演示"模型运行实例中的 Stream 绑定、跳转与切换"的工程。该系列还包括简单模型捕获(0_simple_model)、任务更新(1_model_update)、条件模型(3_cond_model)等样例,本样例是其进阶一环。

样例的核心思路是:

  1. 用 aclmdlRI* 接口把分布在多个 Stream 上的算子任务"录制"成一个可重复执行的模型运行实例;
  2. 通过设备侧一个 uint32_t 变量(numDevice)作为条件值,在 Stream1 上插入两条 aclrtSwitchStream 跳转指令;
  3. 通过 aclrtActiveStream 让某个 Stream 上的算子完成后自动"激活"另一条汇聚 Stream(endStream);
  4. 同一个模型运行实例被执行两次,两次仅修改条件变量的值,验证不同分支路径下输出结果符合预期。

从源码结构看(main.cpp),任务图包含 3 组独立的 Add 算子(out = self + other * alpha,alpha 固定为 1.2),以及两条分支路径,可归纳为:

路径1(numDevice == 1): stream1 → stream3 → ActiveStream(endStream) → EndTask
路径2(numDevice == 2): stream1 → stream4 → ActiveStream(stream2) → ActiveStream(endStream) → EndTask

产品支持情况

原文档明确给出了关键接口在不同产品上的支持矩阵(详见 README.md)。其中 Stream 跳转与激活能力是产品差异化的关键点,在 Atlas A3 系列产品上暂不支持,使用时需按目标硬件核对:

接口 Ascend 950PR/Ascend 950DT Atlas A3 训练系列产品/Atlas A3 推理系列产品 Atlas A2 训练系列产品/Atlas A2 推理系列产品
aclmdlRIBuildBegin √ √ √
aclmdlRIBindStream √ √ √
aclmdlRIEndTask √ √ √
aclmdlRIBuildEnd √ √ √
aclmdlRIUnbindStream √ √ √
aclmdlRIExecuteAsync √ √ √
aclrtSwitchStream √ × √
aclrtActiveStream √ × √

即:模型运行实例的捕获与执行能力全系列支持,而 Stream 条件跳转(SwitchStream)与激活(ActiveStream)仅 Ascend 950 系列与 Atlas A2 系列支持。若在 Atlas A3 产品上运行本样例,请以实际报错为准并参考产品文档确认替代方案。

编译与运行

环境安装详情以及运行详情见 example 目录下的 README(即 example/README.md)。运行步骤如下:

# ${install_root} 替换为 CANN 安装根目录,默认安装在 /usr/local/Ascend 目录
source ${install_root}/cann/set_env.sh

# 自动识别 SOC_VERSION 和 ASCENDC_CMAKE_DIR
source ${git_clone_path}/example/set_sample_env.sh

# 编译运行
bash run.sh

构建脚本要点

run.sh(example/2_advanced_features/model_ri/2_model_switch/run.sh)内部依次完成:

  1. source $ASCEND_INSTALL_PATH/bin/setenv.bash:加载 CANN 环境变量(前提是已通过外层 set_env.sh 设置了 ASCEND_INSTALL_PATH);
  2. cmake -B build -DASCEND_CANN_PACKAGE_PATH=...:配置构建;
  3. cmake --build build -j 与 cmake --install build:编译并安装到 out 目录;
  4. ./build/main | tee output_msg.txt:运行可执行文件并把输出同时写到终端和 output_msg.txt,方便回看运行日志。

其对应的 CMakeLists.txt 展示了编译期关键依赖:

  • 通过 ASCENDC_CMAKE_DIR/ascendc.cmake 的 ascendc_library 把公共内核源文件 example/kernel_func/easy_OP.cpp 编成静态库 kernels;
  • 头文件搜索路径包含 ${ASCEND_CANN_PACKAGE_PATH}/include(AscendCL 头文件)与 ${ASCEND_CANN_PACKAGE_PATH}/aclnn(算子接口头文件);
  • 链接 libascendcl.so、libnnopbase.so、libopapi.so,分别对应 AscendCL 运行时、算子基础库与 aclnn 算子 API。

CANN Runtime 关键 API 全景

在该样例中,涉及的关键功能点及其关键接口(与 README.md 保持一致并补充接口声明出处)如下:

  • 初始化
    • 调用 aclInit 接口初始化 AscendCL 配置;
    • 调用 aclFinalize 接口实现 AscendCL 去初始化。
  • Device 管理
    • 调用 aclrtSetDevice 接口指定用于运算的 Device;
    • 调用 aclrtResetDeviceForce 接口强制复位当前运算的 Device,回收 Device 上的资源。
  • Context 管理
    • 调用 aclrtCreateContext 接口创建 Context;
    • 调用 aclrtDestroyContext 接口销毁 Context。
  • Stream 管理
    • 调用 aclrtCreateStream 接口创建 Stream;
    • 调用 aclrtSynchronizeStream 阻塞等待 Stream 上任务的完成;
    • 调用 aclrtDestroyStreamForce 接口强制销毁 Stream,丢弃所有任务;
    • 调用 aclrtCreateStreamWithConfig 接口创建特殊 config 的 Stream;
    • 调用 aclrtSwitchStream 接口根据条件在 Stream 之间跳转;
    • 调用 aclrtActiveStream 接口激活 Stream。
  • model 管理
    • 调用 aclmdlRIBuildBegin 接口开始构建一个模型运行实例;
    • 调用 aclmdlRIBindStream 接口将模型运行实例与 Stream 绑定;
    • 调用 aclmdlRIEndTask 接口标记下发任务结束;
    • 调用 aclmdlRIBuildEnd 接口结束构建模型运行实例;
    • 调用 aclmdlRIUnbindStream 接口解除模型运行实例与 Stream 的绑定;
    • 调用 aclmdlRIExecuteAsync 接口异步执行模型推理;
    • 调用 aclmdlRIDestroy 接口销毁模型运行实例。
  • 内存管理
    • 调用 aclrtMalloc 接口申请 Device 上的内存;
    • 调用 aclrtFree 接口释放 Device 上的内存。
  • 数据传输
    • 调用 aclrtMemcpy 接口通过内存复制的方式实现数据传输;
    • 调用 aclrtMemcpyAsync 接口进行异步的内存复制。

其中模型运行实例接口的声明集中在 include/external/acl/acl_rt.h 的 modelRI 区段,例如:

  • aclmdlRIExecuteAsync(aclmdlRI modelRI, aclrtStream stream):异步执行模型推理直至结果返回(acl_rt.h);
  • aclmdlRIDestroy(aclmdlRI modelRI):销毁模型运行实例(acl_rt.h);
  • aclmdlRIBuildBegin(aclmdlRI* modelRI, uint32_t flag)、aclmdlRIBindStream(aclmdlRI modelRI, aclrtStream stream, uint32_t flag)、aclmdlRIEndTask(aclmdlRI modelRI, aclrtStream stream)、aclmdlRIBuildEnd(aclmdlRI modelRI, void* reserve)、aclmdlRIUnbindStream(aclmdlRI modelRI, aclrtStream stream) 构成任务图"开始捕获 → 绑定流 → 标记结束 → 结束捕获 → 解绑流"的完整生命周期。

源码级拆解:建模、跳转、激活与二次执行

1. 初始化、Device 与 Context

main.cpp 的启动序列为:

CHECK_ERROR(aclInit(NULL));
CHECK_ERROR(aclrtSetDevice(deviceId));          // deviceId = 0
CHECK_ERROR(aclrtCreateContext(&context, deviceId));

随后通过公共工具 ModelUtils::CreateAclTensor(见 model_utils.h 与 model_utils.cpp)为 3 组 Add 算子分配设备内存并创建 aclTensor。每组数据均为 {4, 2} 形状、float 类型,即 8 个元素;alpha 为标量 1.2,因此算子语义为 out[i] = self[i] + other[i] * 1.2。

2. 构建模型运行实例并绑定 Stream

模型运行实例的构建使用如下序列(main.cpp):

aclmdlRI modelRI;
aclrtStream stream1, stream2, stream3, stream4, endStream, copyStream;

// 工作流与汇聚流都使用持久化配置创建
aclrtCreateStreamWithConfig(&stream1, 0x00U, ACL_STREAM_PERSISTENT);
// ... stream2/stream3/stream4/endStream 同理
aclrtCreateStream(&copyStream);  // 独立拷贝流,不参与模型绑定

// 开始构建模型运行实例,绑定 5 条流
aclmdlRIBuildBegin(&modelRI, 0x00U);
aclmdlRIBindStream(modelRI, stream1, ACL_MODEL_STREAM_FLAG_HEAD);
aclmdlRIBindStream(modelRI, stream2, ACL_MODEL_STREAM_FLAG_DEFAULT);
aclmdlRIBindStream(modelRI, stream3, ACL_MODEL_STREAM_FLAG_DEFAULT);
aclmdlRIBindStream(modelRI, stream4, ACL_MODEL_STREAM_FLAG_DEFAULT);
aclmdlRIBindStream(modelRI, endStream, ACL_MODEL_STREAM_FLAG_DEFAULT);

几个值得注意的设计点:

  • ACL_STREAM_PERSISTENT(定义值为 0x00000004U,见 acl_rt.h)使 Stream 具有持久化语义;ACL_MODEL_STREAM_FLAG_HEAD 用于标记入口流,其余流使用 ACL_MODEL_STREAM_FLAG_DEFAULT;
  • 独立的 copyStream:样例刻意不把拷贝流绑定进模型实例,其注释说明了原因——"防止流状态异常",且后续所有与图无关的初始化拷贝、结果回拷都复用这条流,保持模型内部流拓扑纯净。

绑定完成后,先通过 aclrtMemcpyAsync 把输入数据拷入各 Stream,再依次下发算子:

  • stream1:下发 aclnnAdd,并用一次 ACL_MEMCPY_DEVICE_TO_DEVICE 异步拷贝把 targetValDev_1(值为 1 或 2)写入条件变量 numDevice;
  • stream2:下发 aclnnAdd,随后 aclrtActiveStream(endStream, stream2)——stream2 算子完成后激活 endStream;
  • stream3:下发 aclnnAdd,随后 aclrtActiveStream(endStream, stream3)。

3. Stream 条件跳转:aclrtSwitchStream

跳转指令下在 stream1 上,条件变量是设备侧地址 numDevice(main.cpp):

aclrtSwitchStream(numDevice, condition, rightDevice1, dataType, stream3, nullptr, stream1);
aclrtSwitchStream(numDevice, condition, rightDevice2, dataType, stream4, nullptr, stream1);

接口原型(acl_rt.h):

aclError aclrtSwitchStream(void* leftValue, aclrtCondition cond, void* rightValue,
                           aclrtCompareDataType dataType, aclrtStream trueStream,
                           aclrtStream falseStream, aclrtStream stream);
  • leftValue:设备侧比较值指针(此处为 numDevice);
  • cond:比较条件,样例使用 ACL_RT_EQUAL(枚举值 0,见 acl_rt.h),即相等则跳转;
  • rightValue:目标值指针,rightDevice1 中存放 1、rightDevice2 中存放 2(通过 aclrtMemcpy H2D 拷入);
  • dataType:比较数据类型,ACL_RT_SWITCH_INT32(枚举值 0,见 acl_rt.h),即按 int32 比较;
  • trueStream:条件满足时跳转到的流;
  • falseStream:预留参数,此处传 nullptr;
  • stream:下发该跳转任务的流(stream1)。

因此两条跳转的语义是:若 numDevice == 1 则跳转 stream3,若 numDevice == 2 则跳转 stream4。源码注释也明确提到"必须确保第一个分支哪怕未命中时,设备侧仍兼容执行第二个分支",即两条 Switch 指令按顺序依次判定。

4. Stream 激活:aclrtActiveStream

aclrtActiveStream 的原型(acl_rt.h):

aclError aclrtActiveStream(aclrtStream activeStream, aclrtStream stream);

其语义是:stream 上的任务执行完成后,自动激活 activeStream 上的任务继续执行。样例中出现了两种用法:

  1. aclrtActiveStream(endStream, stream2) 与 aclrtActiveStream(endStream, stream3):stream2/stream3 的算子跑完即激活汇聚流 endStream,实现两条路径在 endStream 汇合;
  2. aclrtActiveStream(stream2, stream4)(main.cpp):路径 2 中 stream4 被 Switch 命中后,其任务会激活 stream2,两者并行执行——源码注释特别提醒:使用该接口的两个流都应已绑定模型实例。

5. 结束任务并执行

任务图收尾与执行(main.cpp):

aclmdlRIEndTask(modelRI, endStream);   // 仅在汇聚流上调用,一个模型只能有一个 EndGraph
aclmdlRIBuildEnd(modelRI, NULL);

aclrtCreateStream(&executeStream);      // 独立的执行流
aclmdlRIExecuteAsync(modelRI, executeStream);
aclrtSynchronizeStream(executeStream);

要点:

  • aclmdlRIEndTask 只在 endStream 上调用一次,因为"一个模型只能有一个 EndGraph",这也是两条 Switch 分支都必须通过 ActiveStream 汇聚到 endStream 的原因;
  • 执行模型时使用一条全新的 executeStream,与建模期的工作流解耦;
  • 执行完成后用未绑定模型的 copyStream 把三组输出异步拷回主机,并 aclrtSynchronizeStream(copyStream) 保证拷回完成。

6. 二次执行:切换条件分支

为了验证条件跳转的可控性,样例对同一模型运行实例执行两次(main.cpp):

  • 第一次:targetValDev_1 中为 1,图内录制的 DeviceToDevice 拷贝把 1 写入 numDevice,命中"stream1 → stream3"分支;
  • 第二次:先用 copyStream 把 2 异步拷入 targetValDev_1 并同步,再把主机侧三组输出清零,重新执行同一 modelRI,命中"stream1 → stream4"分支。

这正体现了模型运行实例"录制一次、多次执行、按条件分派"的价值:改变分支只改设备侧数据,无需重新捕获任务图。

7. 资源释放顺序

样例的清理顺序严格与创建顺序相反(main.cpp):

  1. aclmdlRIUnbindStream 依次解绑 5 条流,再 aclmdlRIDestroy(modelRI) 销毁模型运行实例;
  2. 销毁各 Stream(含独立 copyStream、executeStream);
  3. 销毁 3 组 aclTensor 与 alpha 标量;
  4. aclrtFree 释放所有设备内存(含条件变量、右值、工作区);
  5. aclrtDestroyContext(context)、aclrtResetDeviceForce(deviceId)、aclFinalize() 完成复位与去初始化。

示例输出解读

样例运行后会打印两次执行的三组向量结果,预期输出如下(完整输出见 README.md):

[INFO]  After executing, print data1.
[INFO]  The vector data is: 3.4000  3.4000  3.4000  3.4000  3.4000  3.4000  3.4000  3.4000
[INFO]  After executing, print data2.
[INFO]  The vector data is: 0.0000  0.0000  0.0000  0.0000  0.0000  0.0000  0.0000  0.0000
[INFO]  After executing, print data3.
[INFO]  The vector data is: 5.4000  5.4000  5.4000  5.4000  5.4000  5.4000  5.4000  5.4000
...
[INFO]  After second execution, print data2.
[INFO]  The vector data is: 4.4000  4.4000  4.4000  4.4000  4.4000  4.4000  4.4000  4.4000

对照算子公式 out = self + other * 1.2 可以验证各分支的执行情况:

分支 输入 (self, other) 计算结果 输出
路径1 命中 stream3 (3, 2) 3 + 2×1.2 = 5.4 data3 = 5.4
路径2 命中 stream4 并激活 stream2 stream2 输入 (2, 2) 2 + 2×1.2 = 4.4 data2 = 4.4
未命中分支的 stream1 数据 (1, 2) 1 + 2×1.2 = 3.4 data1 = 3.4(两次都执行)
未命中的另一路径 — 该分支算子未进入执行路径 输出保持初始值 0.0

即:第一次执行(numDevice=1)时 data3 得到 5.4,而 data2 因 stream2 未被激活保持 0.0;第二次执行(numDevice=2)时分支切到 stream4,stream2 被激活后 data2 得到 4.4。输出结果与 Switch 分支语义完全自洽,可据此判断条件跳转是否生效。

常见问题与注意事项

原文档"已知 issue"一栏当前为空,但结合样例实现与接口语义,使用时有以下几点建议:

  • Atlas A3 产品不支持 SwitchStream/ActiveStream:开发前先对照上文支持矩阵确认硬件型号;
  • EndTask 只能有一个:多分支汇聚时必须保证所有路径最终到达同一个 EndGraph 所在流,否则构建或执行阶段可能报错;
  • 激活接口涉及的流都应绑定模型实例:对未绑定的流调用 ActiveStream 属于未定义用法,样例刻意用独立 copyStream 规避了拷贝操作的绑定问题;
  • 分支条件依赖设备侧数据:SwitchStream 的比较值必须位于设备侧,条件变量的更新应通过受控的异步拷贝完成,并配合 aclrtSynchronizeStream 保证执行顺序;
  • 资源释放必须逆序:先解绑再销毁 modelRI,最后销毁 Stream 与内存,避免悬挂引用。

如需进一步学习,可对照同目录下的 README_en.md 英文版,以及 model_ri 系列其他样例(0_simple_model、1_model_update、3_cond_model)理解捕获、更新、条件模型等不同能力维度。

登录后查看全文
runtime