CANN Runtime aclGraph 条件操作实战:基于 modelRI 捕获 IF/WHILE/SWITCH 分支图

原创2026-09-18 18:52:241,954 阅读
文章标签:人工智能Ascend任务调度性能剖析

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 条件操作的固定五步法:

  1. 捕获父模型:aclmdlRICaptureBegin(stream, mode) → aclmdlRICaptureGetInfo 拿到 parentModelRI;
  2. 创建条件句柄:aclmdlRICondHandleCreate(parentModelRI, defaultLaunchValue, flag, &condHandle),并通过 aclmdlRICondHandleGetCondPtr 获取设备端条件指针;
  3. 注册条件任务:填充 aclmdlRICondTaskParams(handle / type / size / modelRIArray),调用 aclmdlRIAddCondTask(params, stream, 0);
  4. 捕获分支子模型:对每个分支调用 aclmdlRICaptureToModelRIBegin(subStream, subModel, mode) 开始、下发算子、aclmdlRICaptureEnd(subStream, &subModel) 结束,最后 aclmdlRICaptureEnd(stream, &parentModelRI) 收尾父模型;
  5. 写条件值并执行:向条件指针写入对应值(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

暂无。

延伸阅读

登录后查看全文
runtime