CANN oam-tools 多流优化报告模板解析：整网模块 DAG 到算子级并行性验收的完整落地规范
【免费下载链接】oam-tools本项目为开发者提供故障定位工具，包含故障信息收集，软硬件信息展示，AI core error报错分析等能力，提升故障问题定位效率，文档可在昇腾社区搜索“故障处理简介”（选择社区版）。项目地址: https://gitcode.com/cann/oam-tools
本指南围绕 CANN oam-tools 仓库中
skills/cann-multistream-optimize技能配套的多流优化报告模板展开，系统讲解在昇腾 NPU 上开展"分析 → 开发调试 → 验收"三段式多流优化时，如何以一份固定结构的 Markdown 报告沉淀整网模块拆解、模块级并行性结论、算子级拆解、实施与调试记录以及四类验收结果。读完本文，你将掌握该模板 12 个章节的每一处填写口径、与模块拆解规范和 API 选型路由的联动方式，以及如何让"多流改造"从分析到验收全程可追溯、可复现。
一、模板定位：多流优化任务的标准答案载体
在多流优化（双流、stream overlap、控核、TorchAir 多流改造）这类高度依赖分析和实验的任务中，最常出现的问题是：模块边界拆得随意、同步点说不清、结论缺少证据、验收只看时延数字。cann-multistream-optimize技能（入口见 SKILL.md）把工作主线固定为三步：
- 先拆整网模块，画模块级 DAG，判断模块与模块哪些能并行；
- 再对每个模块拆算子，画模块内算子 DAG，判断模块内哪些算子能并行；
- 在依赖关系明确后再做多流开发、调试和验收。
多流优化报告模板正是这条主线的"标准答案载体"：分析和实施结果统一落到docs/common/multi-stream-analysis/<network_or_case_name>.md（即结果文件按网络或用例命名，固定存放在该目录下）。模板同时给出了三条使用约定：
- 结果文件固定放在
docs/common/multi-stream-analysis/<network_or_case_name>.md； - 如果任务当前只做到分析阶段，开发、调试、验收部分可先写
N/A，但章节必须保留——这保证了报告结构从第一天起就是完整的，后续开发调试只做填充而非重构； - 每个模块的算子级拆解块要求"为每个模块复制下面的块，不要只写部分模块"——避免"只分析热点模块"的偷懒式做法。
二、分析阶段四章：把整网骨架立起来
模板的第 1～5 章对应分析阶段第一层（整网模块拆解），第 6 章是模块级并行性结论的汇总。它们与整网模块拆解规范一一对应。
2.1 第 1 章：分析范围
第 1 章解决"拆的是什么、在什么条件下拆"：
- 模型/网络：整网分析对象的名字，需为小写英文、短横线连接的描述性名称（如
deepseek-r1-decode、longcat-flash-decode、hunyuanimage3-moe-path），而不是某个局部函数名； - 阶段：明确是
prefill还是decode。两者 shape 稳定性、计算/通信比例差异巨大，直接决定并行窗口和收益预期； - 分析对象：整网执行路径的起止描述；
- 代码入口：定位到具体模型或入口文件；
- 当前执行模式：
eager/patch/ge_graph/aclgraph/ 其他。这是模板里最关键的一个字段——按 API 选型路由 的规则，执行模式决定了后续只能选一套主 API 路径，严禁把 eager 和 graph 风格混着套。
2.2 第 2 章：目标优化点
在动手拆模块之前先明确预期，包括：当前希望获得的 overlap 形式、预期并行对象（哪两个路径段在哪个汇合点相遇）、预期收益，以及明确不在本轮处理的范围。划定范围边界能防止优化过程无限扩散，也是后续验收时判断"是否达标"的基准线。
2.3 第 3、4 章：模块清单与依赖清单
第 3 章使用固定七列表格描述整网模块：
| module_id | module_name | module_type | inputs | outputs | side_effect | resource_hint |
|---|
字段口径（对应拆解规范中的一级模块定义）：模块必须语义完整（如Embedding、Attention Main Path、Router Path、Shared Expert、Dispatch、Expert Compute、Combine、KVCache Offload、LM Head）、输入输出明确、可独立讨论调度、足够大——不能是局部 reshape、cast、view 或某个融合算子内部的小步骤。side_effect记录是否写共享状态（如 KVCache、buffer），resource_hint标注该模块偏计算（compute）、偏通信（comm）还是偏搬运（copy/move）。
第 4 章用四列表格描述模块间依赖：
| from | to | dependency_type | reason |
|---|
dependency_type只允许四类（见拆解规范）：
data：后继模块直接消费前驱模块的输出；state：后继模块依赖前驱写完 cache、buffer 或共享状态；event：后继模块依赖前驱的事件、同步或 stream wait；collective_order：通信顺序固定，不能随意重排。
模板与拆解规范都强调一点：共同输入不是依赖。如果两个模块（如router_path与shared_expert）都消费同一个hidden_states，不能直接画依赖边，而应补一个共同上游节点，否则会人为制造一条本不存在的串行链。
2.4 第 5 章：整网模块 DAG
第 5 章内嵌 Mermaid 图，规范要求统一使用flowchart LR：
- 如果还没决定流归属，节点用
Main Path / Side Path / Comm Path表达； - 只有代码里已经明确是
Stream0 / Stream1时，才用流名做subgraph； - 边规则：
-->表示data或state依赖，-.->表示event依赖； - 汇合点可以单独画成控制节点，例如
merge_shared_router。
拆解规范给出的最小示例骨架如下（MoE 路径）：
三、并行性结论的四分组口径（第 6 章）
模板第 6 章（模块级并行性结论）与第 7 章（模块拆解结论）是分析阶段的"判决书"。拆解规范明确要求：模块级并行性结论不要写成module_a / module_b的二元表，因为整网分析往往涉及多个模块同时并行、一个流里串行一组模块而另一个流里并行另一组模块、多个分叉点和多个汇合点。
因此结论必须按"分组和结构"描述，至少包含四个部分：
- 主串行链：说明哪些模块构成当前主路径，不能打断（例：
embedding -> attention_main -> merge -> lm_head）； - 可并行模块组：说明哪些模块可以成组与主路径或其他组并行（例：组 A：
router_path -> dispatch -> combine；组 B：shared_expert）； - 待验证模块组：逻辑上可并行，但资源冲突、shape 过小、图模式或 runtime 限制、额外 clone/buffer/host 开销尚未确认（例：组 C：
kvcache_reload -> indexer_prolog）； - 建议流分组：用
Stream0 / Stream1 / Stream2或Main Path / Side Path / Comm Path描述推荐分组，不要求现在就和代码中的真实流一一对应（例：Stream0：attention_main -> merge -> lm_head；Stream1：shared_expert；Stream2：router_path -> dispatch -> combine）。
第 7 章"模块拆解结论"进一步收敛为四条决策：哪些模块必须串行、哪些可以并行、哪些并行性待验证、推荐优先实现的多流切入点——这四条直接作为下一阶段开发改动的输入。
四、第 8 章：每个模块的算子级拆解
第二层分析不是"挑重点模块拆"，而是每个模块都要继续下钻。模板第 8 章要求为每个模块复制一个完整块，块内包含：
- 算子清单（七列表格，字段同模块清单，但粒度为算子或无需再拆的算子组）；
- 算子依赖清单（四列表格，依赖类型同样只允许
data/state/event/collective_order）； - 算子 DAG（Mermaid
flowchart LR）； - 算子并行性结论，仍沿用四分组口径：模块内主串行链、模块内可并行算子组、模块内待验证算子组、模块内建议流分组；
- 模块内结论：必须串行/可以并行/待验证的部分，以及可能的流切换点 / 同步点。
算子级拆解仍然优先沿计算、通信、同步、状态边界进行，模块内的共同输入、汇合点、同步点要单独标清。拆解规范给出了 Attention 模块的示例：主串行链qkv_prepare -> attention_score -> merge_out，可并行组如shared_expert_gate -> shared_expert_down_proj、router_topk -> dispatch等。
五、开发阶段：第 9 章实施记录
第 9 章在开发阶段填写，包含三小节：
9.1 方案选择：记录采用的主 API 路径（eager/patch 还是 graph/TorchAir）、enable 开关、保留的回退路径、关键同步设计，以及是否引入控核 / stream limit / prefetch。这一小节直接呼应技能原则中的"开关必须可关闭""同步必须显式"——多流路径必须保留 enable 开关和原始回退路径，方便调试与验收时做 A/B 对照。
9.2 关键改动：三列表格（状态 / 内容 / 文件）逐条记录改动点，状态用于标记已实现、待验证或被回退。
9.3 当前实现结论：当前已实现的 overlap、仍未覆盖的并行点、代码中的主要风险。
API 选型的决策顺序（来自 api-routing.md）：
- 先确定当前是 eager / patch 还是 graph / TorchAir；
- 先选一套主 API 路径，不要混着写；
- 先把依赖和同步做对，再确认是否真的有 overlap；
- 只有在 overlap 正确但拖尾明显时，才进入控核、stream limit、预取调优。
eager / patch 风格优先使用torch.npu.Stream()、record_event()、wait_event()、wait_stream()；graph / TorchAir 风格优先使用npu_stream_switch、npu_wait_tensor、npu_record_tagged_stream、npu_tagged_event_wait；出现"已 overlap 但收益不稳定"时再评估limit_core_num、torch_npu.set_stream_limit/get_stream_limit、torch_npu.npu_prefetch，使用顺序是"先确认依赖和 overlap 正确 → 再看拖尾或资源争抢 → 最后才引入控核、stream limit 或预取"。
六、调试阶段：第 10 章按四类问题分类记录
模板第 10 章把调试问题强制分成四类，避免混在一起排查：
- 10.1 依赖 / 同步问题：检查事件记录、等待顺序、跨流汇合点、共享状态写入次序，典型现象是读到未完成结果、死等、结果偶发错误；
- 10.2 精度 / 功能问题：先对比优化前基线，再按
prefill/decode → 模块 → 算子缩小范围，判断是否是多流引入的状态时序问题； - 10.3 性能无收益问题：重点看 shape 变化、task 数量增加、host bound、带宽争抢、流间资源抢占、拖尾，必要时继续评估控核、预取、superkernel 或缩小 overlap 范围；
- 10.4 图模式 / runtime 限制：重点看 graph break、图模式 API 约束、stream 语义差异、运行时不支持，graph 场景优先按 TorchAir 路径排查，不回退成 eager 思路硬套。
10.5 当前调试结论给出"已解决 / 未解决 / 下一步优先级"三行，保证调试中断后可以无缝续接。
七、验收阶段：第 11 章四类验收
验收必须至少覆盖四类（技能定义在 SKILL.md 第四步），报告模板第 11 章逐类落账：
- 11.1 功能验收：多流 enable 前后输出一致；开关关闭后原路径可正常运行；
- 11.2 同步验收：汇合点前后无缺失等待；共享状态、KVCache、通信结果没有读写乱序；
- 11.3 性能验收：记录优化前/优化后的关键时延、吞吐或单步耗时，确认确实有 overlap 和时延改善，且优化点之外的算子或模块耗时没有劣化；如果无收益，要明确是实现问题还是场景不适合；
- 11.4 Profile 验收：确认确实存在 overlap（而非逻辑上分流但执行上仍串行），确认关键拖尾是否缩短、是否出现新的空洞或资源争抢。
八、第 12 章最终结论与后续建议
最终结论汇总五条：整网最适合做多流优化的位置、模块级并行的主结论、算子级并行的主结论、当前实现是否建议保留、后续建议。这里特别呼应技能原则中的"overlap 不等于收益"——出现拖尾、资源争抢、host bound、shape 劣化时，要继续评估控核、图模式限制，最终结论需要给出"当前实现是否建议保留"的明确判断，而不是含糊其辞。
九、模板与仓库配套资产的联动关系
cann-multistream-optimize技能目录下的参考文档是一个自洽的体系，写报告时按需引用：
| 资产 | 作用 | 与模板的联动 |
|---|---|---|
| SKILL.md | 技能入口，定义工作主线与验收标准 | 决定模板第 1～12 章何时填写、填什么 |
| report-template.md | 固定报告模板（本文主体） | 结果文件结构蓝本 |
| module-decomposition-spec.md | 整网/算子两级拆解规则、DAG 画法、四类依赖 | 支撑模板第 3～8 章的填写口径 |
| analysis-template.md | 纯分析阶段的最小模板（到最终结论为止） | 任务只做分析时可用，完整流程用 report-template |
| api-routing.md | 执行模式 → API 风格 → 问题类型 → 推荐 API 的路由表 | 支撑模板 9.1 方案选择与第 10 章调试 |
| case-routing.md | 按优化模式路由代表案例（MoE 双流、Indexer/Prolog 多流、KVCache offload、prefill micro-batch、多流+控核、patch 形态等） | 帮助确定当前任务属于哪类模式，避免混抄案例 |
| official-docs-latest.md | 官方 API 文档版本索引（每个接口分别取最新可检索版本） | 报告中引用 API 时的版本依据 |
十、使用建议：如何把这份模板用出价值
从仓库的既有约定可以提炼出几条实操建议：
- 从第一天就用完整模板：即使只做分析，开发、调试、验收章节也要以
N/A占位保留，避免后期补结构； - 先整网后局部：未完成模块级 DAG 之前不进入算子级拆解；模块拆解目标永远是"判断模块与模块哪些可并行"，第一层不要过早拆成算子；
- 结论用分组结构表达：主串行链 / 可并行组 / 待验证组 / 建议流分组四件套在模块级和算子级统一复用，禁止退化成二元表；
- 同步必须显式、开关必须可关闭：每条 event / wait / wait_stream / wait_tensor 关系都要写进 9.1 与 9.2，保证可复现；
- 先证明正确再追性能：验收顺序固定为功能 → 同步 → 性能 → Profile，且性能验收必须同时覆盖"确认有收益"与"确认无劣化"两个方向。
这份模板的最终价值在于：它把一次多流优化从"经验性尝试"变成"可审计的工程流程"——每个并行决策都有 DAG 和依赖类型支撑，每个开发改动都有文件和状态记录，每个验收结论都有基线对照，从而让整网 DAG 分析、算子级并行性判断与多流改造收益之间建立起可追溯的完整证据链。
【免费下载链接】oam-tools本项目为开发者提供故障定位工具，包含故障信息收集，软硬件信息展示，AI core error报错分析等能力，提升故障问题定位效率，文档可在昇腾社区搜索“故障处理简介”（选择社区版）。项目地址: https://gitcode.com/cann/oam-tools
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
