CANN Runtime 配置化 Stream 创建与属性查询实战:基于 `aclrtCreateStreamWithConfig` 与 ID/Flag/Priority 查询接口

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

CANN Runtime 配置化 Stream 创建与属性查询实战:基于 aclrtCreateStreamWithConfig 与 ID/Flag/Priority 查询接口

本篇文章以 CANN Runtime 开源仓库中的 3_stream_config_query 样例 为主线,系统讲解如何在单 Device 场景下使用 aclrtCreateStreamWithConfig 接口按指定的 Priority(优先级)与 Flag(标志)创建 Stream,并通过 aclrtStreamGetId、aclrtStreamGetFlags、aclrtStreamGetPriority 三个查询接口回读 Stream 的属性。读者学完后,将掌握配置化 Stream 创建、属性查询、同步销毁的完整调用链,并能结合源码理解 Flag 各取值对 Stream 运行行为的影响。

一、样例定位:为什么需要"配置化"创建 Stream

在 CANN Runtime 的 Stream 管理体系中,Stream 是任务下发与执行的核心载体。常规的 aclrtCreateStream 接口只负责创建一个"默认属性"的 Stream;而 aclrtCreateStreamWithConfig 接口则允许开发者在创建时直接注入优先级(priority)与功能标志(flag),从而定制 Stream 的行为特性,例如:

  • 提升任务下发速度(ACL_STREAM_FAST_LAUNCH);
  • 缩短同步等待时间(ACL_STREAM_FAST_SYNC);
  • 用于模型绑定与模型构建场景(ACL_STREAM_PERSISTENT)等。

根据官方接口文档 06_stream_management.md 的说明,相比 aclrtCreateStream,使用 aclrtCreateStreamWithConfig 可以创建一个快速下发任务的 Stream,但会增加内存消耗或 CPU 的性能消耗——这是"创建一次、使用多次"场景下以资源换性能的经典取舍。

本样例(main.cpp)正是这一能力的最小可运行演示:它在单个 Device 上创建带指定 Priority 和 Flag 的 Stream,随后查询并校验 Stream 的 ID、Flag、Priority,最后同步并销毁。它同时被收录于 stream 目录样例列表 中,与 0_simple_stream(基础创建)、1_stream_with_failure_mode(失败模式)、2_multi_stream(多流协同)、4_stream_resource_budget(资源预算)互为补充,构成完整的 Stream 主题矩阵。

二、产品支持情况

根据样例 README 及接口文档中的产品支持标注,aclrtCreateStreamWithConfig 及本样例涉及的全部查询接口(aclrtStreamGetId、aclrtStreamGetFlags、aclrtStreamGetPriority)在以下产品上支持运行:

产品 是否支持
Ascend 950PR/Ascend 950DT √
Atlas A3 训练系列产品/Atlas A3 推理系列产品 √
Atlas A2 训练系列产品/Atlas A2 推理系列产品 √

需要说明的是,接口文档(06_stream_management.md)显示这些接口在更广的产品范围内受支持(如 Atlas 200I/500 A2 推理产品、Atlas 推理系列产品、Atlas 训练系列产品),而本样例 README 仅声明了上述三类产品,实际部署时请以你当前 CANN 版本对应产品的支持矩阵为准。另外,个别 Flag 也有产品型号限制,例如 ACL_STREAM_DEVICE_USE_ONLY 仅支持 Ascend 950PR/Ascend 950DT、Atlas A3 系列、Atlas A2 系列及 Atlas 推理系列产品。

三、编译与运行

3.1 环境准备

样例要求运行环境已安装 CANN 软件包,并已配置环境变量。推荐按以下步骤操作:

# 1. 切换到样例目录(git_clone_path 为仓库克隆根目录)
cd ${git_clone_path}/example/1_basic_features/stream/3_stream_config_query

# 2. 设置 CANN 环境变量
# ${install_root} 替换为 CANN 安装根目录,默认安装在 /usr/local/Ascend 目录
source ${install_root}/cann/set_env.sh

从 run.sh 源码可见,脚本会优先读取 ASCEND_HOME_PATH 环境变量,若未设置则直接报错退出:

_ASCEND_CANN_PATH="${ASCEND_HOME_PATH:-}"
if [[ -z "${_ASCEND_CANN_PATH}" ]]; then
    echo "[ERROR]: ASCEND_HOME_PATH is not set."
    echo "[ERROR]: Please source CANN set_env.sh before running this sample."
    exit 1
fi

因此,务必先执行 source ${install_root}/cann/set_env.sh,确保 ASCEND_HOME_PATH 已指向 CANN 安装目录(同时脚本还会校验 ${_ASCEND_CANN_PATH}/bin/setenv.bash 是否存在)。

3.2 编译与运行

bash run.sh

run.sh 内部完整执行了"清理 → CMake 配置 → 编译 → 运行 → 结果校验"全流程:

rm -rf build
cmake -B build \
    -DASCEND_CANN_PACKAGE_PATH="${_ASCEND_CANN_PATH}"
cmake --build build -j

file_path=output_msg.txt
if ! ./build/main | tee "${file_path}"; then
    echo "[FAILURE] Stream config query sample failed."
    exit 1
fi

if grep -q "\[SUCCESS\] Stream config query sample completed successfully" "${file_path}"; then
    echo "[SUCCESS] Stream config query sample executed successfully."
else
    echo "[FAILURE] Stream config query sample did not print the expected success marker."
    exit 1
fi

注意其中的两个细节:

  1. CMake 传参:通过 -DASCEND_CANN_PACKAGE_PATH 指定 CANN 包路径,供 CMakeLists.txt 使用——它将该路径下的 include 目录加入头文件搜索路径,将 lib64 目录加入链接搜索路径,并最终链接 ${ASCEND_CANN_PACKAGE_PATH}/lib64/libacl_rt.so 动态库。
  2. 自动化结果校验:程序运行输出同时写入 output_msg.txt(通过 tee),随后脚本用 grep 检查是否包含 [SUCCESS] Stream config query sample completed successfully 这一成功标志,据此决定脚本整体成败。这意味着样例自带"自验证"能力,非常适合集成进 CI 流水线。

如果不想使用脚本,也可以手动执行:

cmake -B build -DASCEND_CANN_PACKAGE_PATH=${install_root}/cann
cmake --build build -j
./build/main

四、核心 CANN Runtime API 全解析

本样例涉及的接口可按功能分为三类(详见 06_stream_management.md):

4.1 初始化与 Device 管理

接口 作用
aclInit 完成 ACL 初始化,样例中传入 nullptr 使用默认配置
aclrtSetDevice 指定用于运算的 Device(样例使用 Device 0)
aclrtResetDeviceForce 复位当前 Device,强制回收该 Device 上的资源
aclFinalize 完成 ACL 去初始化,释放全局资源

4.2 Stream 配置与创建:aclrtCreateStreamWithConfig

aclError aclrtCreateStreamWithConfig(aclrtStream *stream, uint32_t priority, uint32_t flag)

接口原型与参数说明(来自 acl_rt.h 及接口文档):

参数 输入/输出 说明
stream 输出 创建出的 Stream 的指针
priority 输入 优先级,取值范围 0~7(见 acl_rt.h 注释),数字越小优先级越高
flag 输入 Stream 的功能标志。既支持配置单个宏,也支持多个宏按位或(bitwise OR);对于不支持位或的宏,接口会返回报错。配置其他值创建出的 Stream 等同于通过 aclrtCreateStream 创建

flag 支持的全部宏定义位于 acl_rt.h,其取值与业务语义整理如下:

宏 值 语义 注意事项
ACL_STREAM_FAST_LAUNCH 0x00000001U 下发任务速度更快 创建时预申请系统内部资源,创建耗时增加、内存消耗增加,但下发任务耗时缩短;适合"创建一次、使用多次"场景
ACL_STREAM_FAST_SYNC 0x00000002U 调用 aclrtSynchronizeStream 时主动查询任务状态,任务完成立即返回 免去被动等待通知,总时长缩短,但主动查询增加 CPU 消耗
ACL_STREAM_PERSISTENT 0x00000004U 任务不立即执行、执行完也不立即销毁,销毁 Stream 时才释放任务资源 用于模型绑定场景,配合 aclmdlRIBindStream 使用
ACL_STREAM_HUGE 0x00000008U Stream 可容纳的最大 Task 数量更大 当前版本(对应接口文档标注的产品范围)设置该 flag 不生效
ACL_STREAM_CPU_SCHEDULE 0x00000010U 用于队列方式模型推理场景下承载 AI CPU 调度的相关任务 预留功能
ACL_STREAM_DEVICE_USE_ONLY 0x00000020U 表示该 Stream 仅在 Device 上调用 仅 Ascend 950PR/Ascend 950DT、Atlas A3 系列、Atlas A2 系列及 Atlas 推理系列产品支持

多个 Flag 可按位或组合,例如同时开启快速下发与快速同步可传入 ACL_STREAM_FAST_LAUNCH | ACL_STREAM_FAST_SYNC(0x03U)。查询时 aclrtStreamGetFlags 返回的也正是各 flag 按位或后的结果。

4.3 Stream 查询与同步

接口 原型 关键说明
aclrtStreamGetId aclError aclrtStreamGetId(aclrtStream stream, int32_t *streamId) 获取指定 Stream 的 ID;传入 NULL 时获取默认 Stream 的 ID
aclrtStreamGetFlags aclError aclrtStreamGetFlags(aclrtStream stream, uint32_t *flags) 查询创建 Stream 时设置的 flag;多 flag 返回按位或结果,未配置则返回 0;默认 Stream 的 flag 值因产品型号而异,应以本接口查询到的值为准
aclrtStreamGetPriority aclError aclrtStreamGetPriority(aclrtStream stream, uint32_t *priority) 查询 Stream 优先级,数字越小优先级越高
aclrtSynchronizeStream aclError aclrtSynchronizeStream(aclrtStream stream) 阻塞 Host 侧当前线程,直到指定 Stream 上的所有任务完成
aclrtDestroyStream aclError aclrtDestroyStream(aclrtStream stream) 销毁 Stream;若有未完成任务会等待完成后再销毁;销毁前应保证 Stream 在当前 Context 下

接口文档特别提示:aclrtDestroyStream 销毁前建议先调用 aclrtSynchronizeStream 确保任务全部完成(见 06_stream_management.md 约束说明),本样例正是遵循了这一顺序。

五、源码逐步拆解:从创建到查询的完整链路

main.cpp 全文件不足 150 行,却完整展示了"初始化 → 创建 → 查询 → 校验 → 同步 → 销毁 → 去初始化"的规范流程,可作为业务代码的模板。

5.1 常量与错误处理封装

constexpr int32_t kDeviceId = 0;       // 使用 Device 0
constexpr uint32_t kStreamFlags = 0;   // 创建时使用的 Flag
constexpr uint32_t kStreamPriority = 0; // 创建时使用的优先级

int CheckAcl(aclError ret, const char* expr)
{
    if (ret != ACL_SUCCESS) {
        fprintf(stderr, "[ERROR]  Operation failed: %s returned error code %d\n", expr, static_cast<int32_t>(ret));
        fflush(stderr);
        return -1;
    }
    return 0;
}

CheckAcl 对每个 ACL 接口的返回值做统一检查,失败时打印接口名与错误码并返回 -1。日志宏(INFO_LOG、ERROR_LOG 等)来自仓库公共工具头文件 example/utils.h,输出格式统一为 [INFO]/[ERROR] 前缀,方便脚本解析。

5.2 用 RAII 守卫 Stream 生命周期

样例定义了 StreamGuard 类,将 aclrtDestroyStream 的调用封装进析构函数,实现"离开作用域自动销毁",避免异常路径下的资源泄漏:

class StreamGuard {
public:
    explicit StreamGuard(aclrtStream stream) : stream_(stream) {}
    ~StreamGuard()
    {
        if (stream_ != nullptr) {
            CHECK_ERROR_WITHOUT_RETURN(aclrtDestroyStream(stream_));
        }
    }
    // 拷贝构造与赋值被 delete,禁止拷贝
    aclError Destroy() { /* 显式销毁并将 stream_ 置空 */ }
private:
    aclrtStream stream_;
};

这是典型的 RAII(Resource Acquisition Is Initialization)写法:StreamGuard streamGuard(stream); 创建守卫对象,函数末尾无论走正常返回还是提前 return -1,析构函数都会兜底销毁 Stream。Destroy() 方法则提供显式销毁入口,以便在正常路径中主动控制销毁时机并检查返回值。

5.3 配置化创建与属性查询

核心业务函数 RunStreamConfigQuerySample 完整实现了样例主线:

aclrtStream stream = nullptr;
// 1. 以指定的 priority 和 flag 创建 Stream
if (CheckAcl(aclrtCreateStreamWithConfig(&stream, kStreamPriority, kStreamFlags),
             "aclrtCreateStreamWithConfig") != 0) {
    return -1;
}
StreamGuard streamGuard(stream);
INFO_LOG("Create stream with priority=%u flags=%u successfully", kStreamPriority, kStreamFlags);

// 2. 查询 Stream 的 ID / Flag / Priority 并校验
if (QueryStreamInfo(stream) != 0) {
    return -1;
}

// 3. 同步等待 Stream 上任务完成
if (CheckAcl(aclrtSynchronizeStream(stream), "aclrtSynchronizeStream") != 0) {
    return -1;
}
// 4. 显式销毁 Stream
if (CheckAcl(streamGuard.Destroy(), "aclrtDestroyStream") != 0) {
    return -1;
}
INFO_LOG("[SUCCESS] Stream config query sample completed successfully");

查询逻辑集中在 QueryStreamInfo 中,三个查询接口按固定顺序调用,并将结果打印后与创建参数比对:

int32_t streamId = -1;
if (CheckAcl(aclrtStreamGetId(stream, &streamId), "aclrtStreamGetId") != 0) { return -1; }
INFO_LOG("Stream id: %d", streamId);

uint32_t flags = 0;
if (CheckAcl(aclrtStreamGetFlags(stream, &flags), "aclrtStreamGetFlags") != 0) { return -1; }
INFO_LOG("Stream flags: %u", flags);

uint32_t priority = 0;
if (CheckAcl(aclrtStreamGetPriority(stream, &priority), "aclrtStreamGetPriority") != 0) { return -1; }
INFO_LOG("Stream priority: %u", priority);

// 回读结果必须与创建参数一致
if ((flags != kStreamFlags) || (priority != kStreamPriority)) {
    ERROR_LOG("Unexpected stream attributes: flags=%u, priority=%u; expected flags=%u, priority=%u",
              flags, priority, kStreamFlags, kStreamPriority);
    return -1;
}

这里体现了一个重要原则:创建时指定的配置参数,应通过查询接口回读并做一致性校验,从而确认 Stream 的实际生效属性与预期相符。需要注意,Stream ID 由 Runtime 内部分配,样例输出中的 1 仅为该进程内实际分配的 ID,并非固定值。

5.4 main 函数:初始化与收尾

int32_t main()
{
    if (CheckAcl(aclInit(nullptr), "aclInit") != 0) {
        return -1;
    }
    if (CheckAcl(aclrtSetDevice(kDeviceId), "aclrtSetDevice") != 0) {
        CHECK_ERROR(aclFinalize());
        return -1;
    }

    int ret = RunStreamConfigQuerySample();

    CHECK_ERROR(aclrtResetDeviceForce(kDeviceId));
    CHECK_ERROR(aclFinalize());
    return ret;
}

顺序为:aclInit 初始化 ACL → aclrtSetDevice(0) 绑定 Device → 执行业务 → aclrtResetDeviceForce(0) 复位 Device → aclFinalize 去初始化。若 aclrtSetDevice 失败,则跳过后续业务直接调用 aclFinalize 清理,避免资源悬挂。

六、示例输出解读

正常运行时,程序输出如下(与样例 README 的"示例输出"一致):

[INFO]  Create stream with priority=0 flags=0 successfully
[INFO]  Stream id: 1
[INFO]  Stream flags: 0
[INFO]  Stream priority: 0
[INFO]  [SUCCESS] Stream config query sample completed successfully
[SUCCESS] Stream config query sample executed successfully.

逐行解读:

  • 前四行来自 main 程序本身:确认以 priority=0 flags=0 成功创建 Stream,随后回读到 id=1、flags=0、priority=0,与创建参数一致,校验通过;
  • 第五行 [INFO] [SUCCESS] Stream config query sample completed successfully 是程序内的业务成功标志;
  • 最后一行 [SUCCESS] Stream config query sample executed successfully. 由 run.sh 在 grep 校验命中成功标志后打印,代表脚本级验证通过。

七、从样例到生产:Flag 选型与进阶方向

本样例以 flags=0 演示了最基础的配置化创建。在实际业务中,可根据场景组合使用 4.2 节的 Flag 宏:

  • 高频反复下发任务的推理/训练循环:优先考虑 ACL_STREAM_FAST_LAUNCH,用创建时的一次性资源预申请换取每次下发任务的时延降低;
  • 对同步时延敏感:优先考虑 ACL_STREAM_FAST_SYNC,将同步等待从"被动等通知"变为"主动查状态",代价是更高的 CPU 占用;
  • 模型构建与绑定场景:使用 ACL_STREAM_PERSISTENT 配合模型运行实例绑定接口(详见 15_model_running_instance_management.md 中的 aclmdlRIBindStream),并在需要重新下发任务时通过 aclrtPersistentTaskClean 清理任务。

同时注意两点约束(详见接口文档):

  1. ACL_STREAM_FAST_SYNC 模式下调用 aclrtSynchronizeStream 的行为与默认 Stream 不同,需按实际语义设计同步策略;
  2. 部分接口(如溢出检测开关、aclrtStreamQuery 的状态查询)对 ACL_STREAM_PERSISTENT、ACL_STREAM_DEVICE_USE_ONLY、ACL_STREAM_CPU_SCHEDULE 创建的 Stream 有特殊约束或不支持,组合使用时务必查阅 06_stream_management.md 中各接口的"约束说明"章节。

八、延伸阅读

登录后查看全文
runtime