CANN Runtime 模型运行实例中的 Stream 跳转与激活实战:基于 aclmdlRI 的图捕获与条件执行样例解析
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)等样例,本样例是其进阶一环。
样例的核心思路是:
- 用
aclmdlRI*接口把分布在多个 Stream 上的算子任务"录制"成一个可重复执行的模型运行实例; - 通过设备侧一个
uint32_t变量(numDevice)作为条件值,在 Stream1 上插入两条aclrtSwitchStream跳转指令; - 通过
aclrtActiveStream让某个 Stream 上的算子完成后自动"激活"另一条汇聚 Stream(endStream); - 同一个模型运行实例被执行两次,两次仅修改条件变量的值,验证不同分支路径下输出结果符合预期。
从源码结构看(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)内部依次完成:
source $ASCEND_INSTALL_PATH/bin/setenv.bash:加载 CANN 环境变量(前提是已通过外层set_env.sh设置了ASCEND_INSTALL_PATH);cmake -B build -DASCEND_CANN_PACKAGE_PATH=...:配置构建;cmake --build build -j与cmake --install build:编译并安装到out目录;./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(©Stream); // 独立拷贝流,不参与模型绑定
// 开始构建模型运行实例,绑定 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(通过aclrtMemcpyH2D 拷入);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 上的任务继续执行。样例中出现了两种用法:
aclrtActiveStream(endStream, stream2)与aclrtActiveStream(endStream, stream3):stream2/stream3 的算子跑完即激活汇聚流 endStream,实现两条路径在 endStream 汇合;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):
aclmdlRIUnbindStream依次解绑 5 条流,再aclmdlRIDestroy(modelRI)销毁模型运行实例;- 销毁各 Stream(含独立 copyStream、executeStream);
- 销毁 3 组 aclTensor 与 alpha 标量;
aclrtFree释放所有设备内存(含条件变量、右值、工作区);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)理解捕获、更新、条件模型等不同能力维度。