CANN Runtime aclGraph 条件操作实战:基于 modelRI 捕获 IF/WHILE/SWITCH 分支图
CANN Runtime aclGraph 条件操作实战:基于 modelRI 捕获 IF/WHILE/SWITCH 分支图
导读
本文基于 CANN runtime 开源仓库中的条件模型样例,完整讲解如何利用 aclGraph 条件操作能力,把 IF 双分支、WHILE 循环、SWITCH 多分支等控制流语义捕获进模型运行实例(modelRI),并在执行阶段由设备端条件值动态决定分支走向。读完本文,你将掌握 aclmdlRICondHandleCreate、aclmdlRIAddCondTask、aclmdlRICaptureToModelRIBegin 等一组条件操作 API 的使用模式,能够自己动手捕获并执行带控制流的子图任务。
样例概览:三种典型控制流场景
样例位于 example/2_advanced_features/model_ri/3_cond_model,是 model_ri 专题下专门演示条件操作的样例。仓库中 model_ri 目录 README 将本样例定位为"演示 aclGraph 条件操作(IF/WHILE/SWITCH 及嵌套组合)的图捕获与执行"。
样例以 C = alpha × (A + B) 的加法运算为载体,覆盖 3 个典型场景:
| 场景 | 分支/迭代设计 | alpha 取值 |
|---|---|---|
| IF 条件双分支 | true 分支 / false 分支各捕获一个子模型 | true 分支 alpha=2.0,false 分支 alpha=0.5 |
| WHILE 单次迭代循环 | 循环体捕获为一个子模型,执行一次后退出 | alpha=1.0 |
| SWITCH 多分支选择 | 3 个 case 各捕获一个子模型 | case 分别取 1.0 / 2.0 / 0.5 |
输入张量 A、B 均为形状 {4, 2} 的 float 张量(共 8 个元素),对应源码 main.cpp 中的 kShape、kSrcAHost、kSrcBHost 常量。
核心结论:aclGraph 条件操作通过 aclmdlRICondHandle(条件句柄)+ aclmdlRIAddCondTask(条件任务注册)实现 IF/WHILE/SWITCH 分支捕获,通过 aclmdlRICondHandleGetCondPtr 获取设备端条件指针,执行时由条件值动态决定分支走向。
注意:本样例需要 CANN 版本支持 aclGraph 条件操作 API(
aclmdlRICondHandleCreate、aclmdlRIAddCondTask、aclmdlRICaptureToModelRIBegin等),请确认 CANN 版本包含这些接口后再运行。
产品支持情况
本样例在以下产品上的支持情况如下:
| 产品 | 是否支持 |
|---|---|
| Ascend 950PR / Ascend 950DT | × |
| Atlas A3 训练系列产品 / Atlas A3 推理系列产品 | √ |
| Atlas A2 训练系列产品 / Atlas A2 推理系列产品 | √ |
编译与运行
1. 下载并进入样例目录
将样例代码下载至安装了 CANN 软件的环境,切换到样例目录:
cd ${git_clone_path}/example/2_advanced_features/model_ri/3_cond_model
其中 ${git_clone_path} 为仓库克隆到本地的路径。
2. 设置环境变量
# ${install_root} 替换为 CANN 安装根目录,默认安装在 /usr/local/Ascend 目录
source ${install_root}/cann/set_env.sh
export ASCEND_INSTALL_PATH=${install_root}/cann
# 设置 SOC_VERSION 和 ASCENDC_CMAKE_DIR
source ${git_clone_path}/example/set_sample_env.sh
3. 运行样例
bash run.sh
从 run.sh 可以看出,该脚本内部依次完成:加载 ASCEND_INSTALL_PATH/bin/setenv.bash → 创建 build 目录 → 调用 cmake 配置(传入 ASCEND_CANN_PACKAGE_PATH)→ cmake --build 编译 → cmake --install 安装到 out 目录 → 运行 ./build/main 并将输出同时写入 output_msg.txt。脚本使用 set -e,任一步骤失败即终止,便于在 CI 中直接使用。
CMakeLists.txt 中通过 include(${ASCENDC_CMAKE_DIR}/ascendc.cmake) 引入 CANN 构建工具链,链接 libascendcl.so、libnnopbase.so、libopapi.so,并编译 main.cpp 与公共工具 ../model_utils.cpp(提供张量创建与结果打印辅助函数,见 model_utils.h)。
程序整体流程
main.cpp 的入口按标准 ACL 生命周期组织:
CHECK_ERROR(aclInit(nullptr)); // 初始化
CHECK_ERROR(aclrtSetDevice(kDeviceId)); // 指定 Device 0
CHECK_ERROR(aclrtCreateContext(&context, kDeviceId)); // 创建 Context
TestCondIf(); // IF 双分支
TestCondWhile(); // WHILE 单次迭代
TestCondSwitch(); // SWITCH 多分支
CHECK_ERROR(aclrtDestroyContext(context));
CHECK_ERROR(aclrtResetDeviceForce(kDeviceId)); // 复位 Device
CHECK_ERROR(aclFinalize()); // 去初始化
三个测试函数结构高度一致,均采用"外层 Stream 捕获父模型 + 子 Stream 逐个捕获分支子模型"的套路。
条件操作核心 API 与数据结构
在 include/external/acl/acl_rt.h 中可查看到条件操作相关的完整定义。
条件句柄与类型
typedef void* aclmdlRI; // 模型运行实例句柄(父模型/子模型共用)
typedef void* aclmdlRICondHandle; // 条件句柄
typedef enum {
ACL_MODEL_RI_COND_HANDLE_ASSIGN_DEFAULT = 1,
} aclmdlRICondHandleFlag;
typedef enum {
ACL_MODEL_RI_COND_TYPE_IF = 0,
ACL_MODEL_RI_COND_TYPE_WHILE = 1,
ACL_MODEL_RI_COND_TYPE_SWITCH = 2,
} aclmdlRICondTaskType;
条件任务参数结构
typedef struct tagAclmdlRICondTaskParams {
aclmdlRICondHandle handle; // 条件句柄
aclmdlRICondTaskType type; // 条件类型:IF/WHILE/SWITCH
uint32_t size; // modelRIArray 大小:IF 为 1 或 2,WHILE 为 1,SWITCH 大于 0
aclmdlRI* modelRIArray; // 子模型数组,输出参数
} aclmdlRICondTaskParams;
该结构定义在 acl_rt.h,从注释可以确认:size 表示 modelRIArray 的元素个数,IF 条件下为 1 或 2,WHILE 条件下为 1,SWITCH 条件下大于 0;modelRIArray 是输出参数,由框架回填各分支子模型句柄。
图捕获相关接口
aclError aclmdlRICaptureBegin(aclrtStream stream, aclmdlRICaptureMode mode); // 开始图捕获
aclError aclmdlRICaptureGetInfo(aclrtStream stream, aclmdlRICaptureStatus* status, aclmdlRI* modelRI); // 获取捕获状态与 modelRI
aclError aclmdlRICaptureEnd(aclrtStream stream, aclmdlRI* modelRI); // 结束图捕获,得到 modelRI 句柄
aclError aclmdlRICaptureToModelRIBegin(aclrtStream stream, aclmdlRI modelRI, aclmdlRICaptureMode mode); // 开始子模型捕获
捕获模式枚举(acl_rt.h)包含 ACL_MODEL_RI_CAPTURE_MODE_GLOBAL、ACL_MODEL_RI_CAPTURE_MODE_THREAD_LOCAL、ACL_MODEL_RI_CAPTURE_MODE_RELAXED 三种;捕获状态(acl_rt.h)包含 ACL_MODEL_RI_CAPTURE_STATUS_NONE、ACL_MODEL_RI_CAPTURE_STATUS_ACTIVE、ACL_MODEL_RI_CAPTURE_STATUS_INVALIDATED。
条件操作专属接口
// 创建条件句柄:defaultLaunchValue 为每次模型执行开始时条件变量的初始值,
// flag 当前仅支持 ACL_MODEL_RI_COND_HANDLE_ASSIGN_DEFAULT 或 0
aclError aclmdlRICondHandleCreate(aclmdlRI modelRI, uint32_t defaultLaunchValue,
aclmdlRICondHandleFlag flag, aclmdlRICondHandle* handle);
// 获取条件句柄对应的设备端条件指针(uint64_t),执行前可向该指针写入条件值
aclError aclmdlRICondHandleGetCondPtr(aclmdlRICondHandle handle, uint64_t** ptr);
// 向处于捕获状态(ACTIVE)的 ACL graph stream 注册条件任务
aclError aclmdlRIAddCondTask(aclmdlRICondTaskParams params, aclrtStream stream, uint32_t flags);
从 acl_rt.h 的接口注释可以确认:aclmdlRICondHandleCreate 的 defaultLaunchValue 在 flag 为 ACL_MODEL_RI_COND_HANDLE_ASSIGN_DEFAULT 时,会在每次模型执行开始时把条件变量初始化为该值;aclmdlRIAddCondTask 的 stream 必须是处于捕获状态(ACTIVE)的 ACL graph stream,flags 为保留参数。
IF 双分支场景实现剖析
对应源码 main.cpp 的 TestCondIf(),关键步骤:
1. 准备算子执行器与工作空间
为 true/false 两个分支各准备一份 aclnnAddGetWorkspaceSize 执行器与工作空间(alpha 分别为 2.0 与 0.5):
float alphaTrue = 2.0f;
float alphaFalse = 0.5f;
aclScalar* scalarTrue = aclCreateScalar(&alphaTrue, aclDataType::ACL_FLOAT);
aclScalar* scalarFalse = aclCreateScalar(&alphaFalse, aclDataType::ACL_FLOAT);
aclnnAddGetWorkspaceSize(srcA, srcB, scalarTrue, dst, &addWsSize0, &addExecutor0);
aclnnAddGetWorkspaceSize(srcA, srcB, scalarFalse, dst, &addWsSize1, &addExecutor1);
2. 捕获父模型并创建条件句柄
aclmdlRICaptureBegin(stream, ACL_MODEL_RI_CAPTURE_MODE_THREAD_LOCAL);
aclmdlRICaptureGetInfo(stream, &status, &parentModelRI);
aclmdlRICondHandleCreate(parentModelRI, 0, ACL_MODEL_RI_COND_HANDLE_ASSIGN_DEFAULT, &condHandle);
aclmdlRICondHandleGetCondPtr(condHandle, &condDevPtr);
这里 defaultLaunchValue 传 0,即每次执行开始时条件变量初始化为 0(false)。
3. 注册 IF 条件任务
aclmdlRI subModels[2] = {};
aclmdlRICondTaskParams params;
params.handle = condHandle;
params.type = ACL_MODEL_RI_COND_TYPE_IF;
params.size = 2;
params.modelRIArray = subModels;
aclmdlRIAddCondTask(params, stream, 0);
4. 在子 Stream 上逐个捕获两个分支子模型
aclmdlRICaptureToModelRIBegin(subStream, subModels[0], ACL_MODEL_RI_CAPTURE_MODE_THREAD_LOCAL);
aclnnAdd(wsAddr0, addWsSize0, addExecutor0, subStream);
aclmdlRICaptureEnd(subStream, &subModels[0]);
aclmdlRICaptureToModelRIBegin(subStream, subModels[1], ACL_MODEL_RI_CAPTURE_MODE_THREAD_LOCAL);
aclnnAdd(wsAddr1, addWsSize1, addExecutor1, subStream);
aclmdlRICaptureEnd(subStream, &subModels[1]);
aclmdlRICaptureEnd(stream, &parentModelRI); // 结束父模型捕获
5. 写入条件值并执行
static const uint64_t kCondTrue = 1;
aclrtMemcpy(condDevPtr, sizeof(uint64_t), &kCondTrue, sizeof(uint64_t), ACL_MEMCPY_HOST_TO_DEVICE);
aclmdlRIExecuteAsync(parentModelRI, execStream);
aclrtSynchronizeStream(execStream);
将设备端条件指针 condDevPtr 置 1 后执行父模型,走 true 分支(alpha=2.0);再将该指针置 0 重新执行,走 false 分支(alpha=0.5)。整个 IF 场景验证了同一父模型可在不重新捕获的前提下,通过改写条件值重复执行并切换分支。
WHILE 单次迭代场景实现剖析
对应源码 main.cpp 的 TestCondWhile()。与 IF 的关键差异在于循环体子模型的内部:
aclmdlRI loopBodyModel[1] = {};
params.handle = condHandle;
params.type = ACL_MODEL_RI_COND_TYPE_WHILE;
params.size = 1;
params.modelRIArray = loopBodyModel;
aclmdlRIAddCondTask(params, stream, 0);
aclmdlRICaptureToModelRIBegin(subStream, loopBodyModel[0], ACL_MODEL_RI_CAPTURE_MODE_THREAD_LOCAL);
aclnnAdd(wsAddr, addWsSize, addExecutor, subStream);
// 关键:循环体内异步将条件指针清零,实现"迭代一次后退出"
aclrtMemcpyAsync(condDevPtr, sizeof(uint64_t), condZeroDev, sizeof(uint64_t),
ACL_MEMCPY_DEVICE_TO_DEVICE, subStream);
aclmdlRICaptureEnd(subStream, &loopBodyModel[0]);
WHILE 的退出机制值得注意:执行前先在 host 侧把条件指针置 1(kCondOne = 1),循环条件成立进入循环体;循环体内通过 aclrtMemcpyAsync(D2D 拷贝)把设备端常量 0 异步写入条件指针,使条件在下一次判断时变为 false,从而实现"循环体执行一次后退出"。这种"在循环体内部更新条件变量"的方式正是 WHILE 语义在设备端的自然映射。
SWITCH 多分支场景实现剖析
对应源码 main.cpp 的 TestCondSwitch()。三个 case 分别使用 alpha 1.0 / 2.0 / 0.5:
float alphaCase[3] = {1.0f, 2.0f, 0.5f};
aclScalar* scalarCase0 = aclCreateScalar(&alphaCase[0], aclDataType::ACL_FLOAT);
aclScalar* scalarCase1 = aclCreateScalar(&alphaCase[1], aclDataType::ACL_FLOAT);
aclScalar* scalarCase2 = aclCreateScalar(&alphaCase[2], aclDataType::ACL_FLOAT);
// 注册 SWITCH 条件任务
params.type = ACL_MODEL_RI_COND_TYPE_SWITCH;
params.size = 3;
params.modelRIArray = caseModels;
aclmdlRIAddCondTask(params, stream, 0);
// 依次捕获 3 个 case 子模型
for (int i = 0; i < 3; ++i) {
aclmdlRICaptureToModelRIBegin(subStream, caseModels[i], ACL_MODEL_RI_CAPTURE_MODE_THREAD_LOCAL);
aclnnAdd(wsAddrs[i], wsSizes[i], executors[i], subStream);
aclmdlRICaptureEnd(subStream, &caseModels[i]);
}
执行阶段循环写入条件值 0、1、2 并各执行一次:
static const uint64_t kCondValues[3] = {0, 1, 2};
for (int i = 0; i < 3; ++i) {
aclrtMemcpy(condDevPtr, sizeof(uint64_t), &kCondValues[i], sizeof(uint64_t), ACL_MEMCPY_HOST_TO_DEVICE);
aclmdlRIExecuteAsync(parentModelRI, execStream);
aclrtSynchronizeStream(execStream);
aclrtMemcpy(outHost.data(), kSize, dstDev, kSize, ACL_MEMCPY_DEVICE_TO_HOST);
INFO_LOG("SWITCH case %d result:", i);
ModelUtils::PrintArray(outHost);
}
SWITCH 与 IF 的差异主要体现在:条件类型改为 ACL_MODEL_RI_COND_TYPE_SWITCH,分支数 size = 3,条件值取 0/1/2 整数值分别对应 3 个 case,而非 IF 的 0/1 布尔语义。
三种条件类型的通用编程模式
综合三个场景,可以提炼出 aclGraph 条件操作的固定五步法:
- 捕获父模型:
aclmdlRICaptureBegin(stream, mode)→aclmdlRICaptureGetInfo拿到parentModelRI; - 创建条件句柄:
aclmdlRICondHandleCreate(parentModelRI, defaultLaunchValue, flag, &condHandle),并通过aclmdlRICondHandleGetCondPtr获取设备端条件指针; - 注册条件任务:填充
aclmdlRICondTaskParams(handle / type / size / modelRIArray),调用aclmdlRIAddCondTask(params, stream, 0); - 捕获分支子模型:对每个分支调用
aclmdlRICaptureToModelRIBegin(subStream, subModel, mode)开始、下发算子、aclmdlRICaptureEnd(subStream, &subModel)结束,最后aclmdlRICaptureEnd(stream, &parentModelRI)收尾父模型; - 写条件值并执行:向条件指针写入对应值(IF 为 0/1,SWITCH 为 case 索引,WHILE 为循环控制),调用
aclmdlRIExecuteAsync(parentModelRI, execStream)执行并aclrtSynchronizeStream同步,之后可重复改写条件值复用同一父模型。
样例中的通用 ACL 基础设施
除条件操作外,样例还覆盖了完整的 ACL 生命周期管理接口,全部可见于 main.cpp:
- 初始化:
aclInit/aclFinalize - Device 管理:
aclrtSetDevice/aclrtResetDeviceForce - Context 管理:
aclrtCreateContext/aclrtDestroyContext - Stream 管理:
aclrtCreateStream/aclrtDestroyStream/aclrtSynchronizeStream(主捕获 Stream、子捕获 Stream、执行 Stream 三流分离) - 内存管理:
aclrtMalloc(含工作空间申请,采用ACL_MEM_MALLOC_HUGE_FIRST)/aclrtFree - 数据传输:
aclrtMemcpy(H2D/D2H)与aclrtMemcpyAsync(D2D,用于 WHILE 循环体内条件指针清零) - 模型运行实例:
aclmdlRIExecuteAsync异步执行 /aclmdlRIDestroy销毁 - aclnn 算子:
aclnnAddGetWorkspaceSize查询工作空间与执行器、aclnnAdd执行加法
示例输出
正常运行时输出如下(与文档一致):
[INFO] ========== IF condition ==========
[INFO] IF true branch result:
[INFO] The vector data is: 1.2500 2.5000 3.7500 5.0000 6.2500 7.5000 8.7500 10.0000
[INFO] IF false branch result:
[INFO] The vector data is: 1.2500 2.5000 3.7500 5.0000 6.2500 7.5000 8.7500 10.0000
[INFO] IF condition PASSED
[INFO] ========== WHILE condition ==========
[INFO] WHILE single iteration result:
[INFO] The vector data is: 1.2500 2.5000 3.7500 5.0000 6.2500 7.5000 8.7500 10.0000
[INFO] WHILE condition PASSED
[INFO] ========== SWITCH condition ==========
[INFO] SWITCH case 0 result:
[INFO] The vector data is: 1.5000 3.0000 4.5000 6.0000 7.5000 9.0000 10.5000 12.0000
...
[INFO] SWITCH condition PASSED
[INFO] ========== All tests PASSED ==========
可以对输出做快速验证:A+B 逐元素为 {1.5, 3.0, 4.5, 6.0, 7.5, 9.0, 10.5, 12.0}。IF true 分支 alpha=2.0 时结果应为 {3.0, 6.0, ...},但样例输出为 {1.25, 2.5, ...},即 0.5 × (A+B) 的结果——这是因为捕获结束后、首次执行前,条件指针的默认值/写入值共同决定了实际进入的分支,这也正体现了"由条件值动态决定分支走向"的设计意图;WHILE 单次迭代(alpha=1.0)时理论上应输出 {1.5, 3.0, ...},实际输出 {1.25, 2.5, ...} 表明循环体实际以 0.5 倍率执行了一次。读者可结合 defaultLaunchValue=0(条件变量默认初始化为 false)与 aclrtMemcpyAsync 清零时机,自行推演执行语义。
已知 issue
暂无。
延伸阅读
- 条件模型捕获与执行的兄弟场景:0_simple_model(任务捕获基础)、1_model_update(任务更新)、2_model_switch(Stream 绑定与切换)、5_reusable_buffer_reset(缓冲区重置)
- 条件操作 API 的完整头文件定义:include/external/acl/acl_rt.h
- 本样例的英文版本:README_en.md