多流与控核 API 路由

【免费下载链接】cannbot-skills CANNBot 是面向 CANN 开发的用于提升开发效率的系列智能体，本仓库为其提供可复用的 Skills 模块。 项目地址: https://gitcode.com/cann/cannbot-skills

本文件用于把“执行路径 / 问题类型”映射到上游文档和推荐 API。

上游文档入口

路径要点

Ascend IR / GE 图模式

• 多流主要面向 Cube 资源未完全使用的场景；若 Cube 已吃满，不要默认开启多流。
• 仅适用于 GE 图模式场景。
• 优先接口是 npu_stream_switch 和 npu_wait_tensor。
• 控核分两层：torchair.scope.limit_core_num 是算子级，config.ge_config.aicore_num 是全局 session 级；算子级优先级更高。
• 静态 shape 下不要和 enable_single_stream 混用，也不要直接在 SuperKernel 内手搓多流。
• 动态 shape 默认单流；如果依赖 ENABLE_DYNAMIC_SHAPE_MULTI_STREAM=1 开启多流，脚本内显式多流表达优先级更高。

npugraph_ex / aclgraph

• 多流主要面向 aclgraph 间资源并发；官方路径围绕 torch.npu.Stream、torch.npu.stream、torch.npu.Event、tensor.record_stream。
• record_stream 只在短生命周期 tensor 会被其他流继续使用时才需要补；权重等长生命周期对象一般不需要。
• 控核是 Stream 级，接口为 torch.npu.npugraph_ex.scope.limit_core_num。
• 仅 Ascend C 算子支持控核；micro-batch 多流场景如果夹杂不支持控核的算子，收益可能下降，严重时可能卡死。
• 配置结果优先通过 profiler 结果中的 kernel_details.csv 查看核使用情况。

先判执行路径

再判问题类型

推荐决策顺序

1. 先确定当前是 eager / patch 还是 graph / TorchAir。
2. 先选一套主 API 路径，不要混着写。
3. 先把依赖和同步做对，再确认是否真的有 overlap。
4. 只有在 overlap 正确但拖尾明显时，才进入控核、stream limit、预取调优。

常见误区

• 不要在 eager 路径里照搬 TorchAir 的 tagged event 风格。
• 不要把 limit_core_num 当成默认步骤；它只解决资源分配问题，不解决依赖错误。
• 不要用 npu_prefetch 掩盖一个本来就不该并行的链路；先证明链路没有错误依赖。
• 不要在 aclgraph / eager 路径里省略 record_stream() 的生命周期判断；只切流不管内存同样会出错。
• npu_tagged_event_record 这类高级同步原语优先跟随仓库现有案例代码，不要脱离上下文自己猜语义。

【免费下载链接】cannbot-skills CANNBot 是面向 CANN 开发的用于提升开发效率的系列智能体，本仓库为其提供可复用的 Skills 模块。 项目地址: https://gitcode.com/cann/cannbot-skills