CANN oam-tools 实战cann-perf-breakdown 三阶段工作流把 NPU Profiling 数据变成可交互性能报告【免费下载链接】oam-tools本项目为开发者提供故障定位工具包含故障信息收集软硬件信息展示AI core error报错分析等能力提升故障问题定位效率文档可在昇腾社区搜索“故障处理简介”选择社区版。项目地址: https://gitcode.com/cann/oam-toolsoam-tools 仓库中的skills/cann-perf-breakdown/目录提供了一套从 NPU profiling 采集数据到可交互 UI 报告的三阶段技能工作流第一阶段基于模型源码建立架构结构并把kernel_details.csv中的性能算子映射到结构节点第二阶段把拆解结果确定性地转换为 UI 所需的 analysis、performance、timeline 与架构图数据第三阶段基于转换后的数据生成可交互的 HTML 报告。读完本文你能掌握该工作流的整体编排逻辑、阶段门禁Stage Gates的判定条件、run_pipeline.py入口的完整参数与状态机语义以及如何按编号顺序调用三个 skill 完成一次从采集目录到报告的端到端运行。一、整体结构三个 skill 与一份工作流导航该目录的核心内容组织为一个三阶段流水线按编号顺序使用阶段目录职责1skills/cann-perf-breakdown/1-perf-breakdown/根据模型源码建立架构并将 profiling 算子映射到结构节点架构提取、算子归属、校验与评分2skills/cann-perf-breakdown/2-adapt-breakdown-to-ui-json/将拆解结果转换为 UI 所需的 analysis、performance、timeline 和架构图数据确定性转换3skills/cann-perf-breakdown/3-generate-ui-json-report/报告资源、运行时数据和前端生成脚本输出可交互 UI 报告每个阶段目录下有自己的SKILL.md定义入口名称frontmatter 的name字段和详细规则references/目录存放字段级契约。三个 skill 的运行时名称分别见各SKILL.md文件头阶段 1 为 cann-perf-breakdown阶段 2 为 adapt-breakdown-to-ui-json阶段 3 为 cann-perf-ui-json-report。完整的阶段衔接、输入输出和门禁说明见 MODEL_BREAKDOWN_TO_UI_WORKFLOW_en.md中文对照 MODEL_BREAKDOWN_TO_UI_WORKFLOW.md。该导航文档定位很克制它只回答下一步该用哪个 skill具体的规则、字段、参数与校验逻辑留在各 skill 的SKILL.md和references/中。需要强调的一个约定数字目录名只表示执行顺序运行时查找必须用各 skill frontmatter 中唯一的name字段。这不是风格问题而是有代码依据的——run_pipeline.py通过扫描同级目录、解析每个SKILL.md的 frontmattername来定位 peer skill# skills/cann-perf-breakdown/2-adapt-breakdown-to-ui-json/scripts/run_pipeline.py STAGE1 find_peer_skill(cann-perf-breakdown) # The preserved UI skill keeps its original frontmatter name. STAGE3 find_peer_skill(cann-perf-ui-json-report)也就是说脚本根本不依赖目录名定位阶段 1 和阶段 3 的实现目录。如果目录被改名但 frontmatter 未同步pipeline 会直接抛出expected exactly one peer skill named ...错误。二、安装与调用方式官方安装方式是浅克隆仓库后把整个cann-perf-breakdown目录复制到 Codex 的 skills 目录以 README_en.md 为准git clone --depth 1 https://gitcode.com/cann/oam-tools.git mkdir -p ~/.codex/skills cp -a oam-tools/skills/cann-perf-breakdown ~/.codex/skills/调用约定英文 README 原文的 invoke 形式Use the $cann-perf-breakdown workflow with capture-directory as the input directory and output-directory as the output directory.即向 Agent 声明使用$cann-perf-breakdown工作流并显式给出输入目录profiling 采集目录与输出目录。中文版本 README.md 给出的等价表述是使用 $cann-perf-breakdown 工作流输入目录为 采集目录输出目录为 输出目录。三、快速入口run_pipeline.py 一条命令跑完全程三阶段工作流有一个确定性 pipeline 入口位于 run_pipeline.pypython3 2-adapt-breakdown-to-ui-json/scripts/run_pipeline.py \ --capture-dir profiling-directory \ --model-id model-id \ --out output-directory该入口会在输入证据满足阶段门禁时依次执行转换和报告生成当需要 AI 语义映射或语义审查时它会写出请求文件并暂停由工作流文档描述的机制继续推进。3.1 输入发现逻辑从工作流文档和源码看pipeline 会自动发现三类输入kernel_details.csvkernel 级性能数据、trace_view.json原始 Chrome Trace和模型源码文件然后在输出目录下写出 breakdown 报告和 UI 报告。源码中的发现与参数处理值得展开因为这里藏着几条关键约束--breakdown与--capture-dir的区分--breakdown指向阶段 1 的正式产物目录必须包含阶段 1 的五个正式文件--capture-dir指向 profiling 采集目录用于 trace/HBM 输入未提供时默认等于--breakdown。脚本 docstring 明确辅助的 raw-op 和 trace 文件对归属和报告组装仍是必需的但它们不能换取门禁通过cannot grant readiness。trace 是阶段 3 的硬依赖如果采集目录中找不到trace_view.jsonpipeline 在ui_report阶段直接失败报错信息为 no trace_view.json in the capture; stage 3 requires the raw trace and it cannot be reconstructed after the fact。这与工作流文档的数据规则一致trace_view.json必须与采集时的 profiling CSV 一起保存。HBM 样本是可选降级项--hbm-dir可重复传入一次采集会把 HBM 样本拆分到derived/hbm和derived/correlation等多个子目录而build-hbm-data.mjs要求四个文件在同一目录。缺少 HBM 文件时报告仍可渲染只是 HBM 面板为空序列——采集到的带宽和占用率缺席而不是被报告为不可用。3.2 pipeline 的实际执行序列阅读 run_pipeline.py 可以看到完整的确定性编排共分为两段阶段 2转换序列check_breakdown_ready.py --breakdown dir --out out/work/readiness.json—— 就绪门禁失败即终止build_node_index.py --breakdown dir --config config --namespace model/model-id --out out/work/node_index.json—— 建立节点索引可重复传--rename-group StructureKeynode-nameattribute_kernels.py --breakdown dir ... --kernels raw_ops.json --kernel-details raw_ops_details.json --out out/work/kernel_attribution.json—— kernel 归属成功时记录100% accountedemit_ui_facts.py --model-id model-id --report-id report-id --peak-bf16-tflops 376 --dtype-bytes 2 --out out/ui_facts可选追加--device-freq—— 产出model-id_analysis_config.json、model-id_perf_data.json、model-id_timeline.json三份 UI 事实build_expert_inventory.py—— MoE 专家清单仅对声明了专家experts的模型写出Dense 模型不产出任何文件且不算失败--ep-rank用于解析专家并行 rank 上的专家身份归属build_architecture_graph.py—— 生成report/outputs/model_architecture_graph.json图一致性回查调用阶段 1 的check_graph_consistency.py对刚生成的图执行 G2/G3/G7 等检查。源码注释解释了为什么必须在 pipeline 里补跑阶段 1 拥有这些图/配置一致性检查层覆盖、重复次数、残差方向但在校验时刻图还不存在如果不在这里重跑G2/G3/G7 对每个经该 pipeline 驱动的采集都是死代码。图中出现错误级 issue 时 pipeline 会终止理由是渲染出的图与配置矛盾基于它构建的报告将展示拆解并未声称的结构validate_conversion.py --out facts --attribution attribution—— 转换校验检查身份一致性、每node_id唯一定义与唯一记录、timeline owner 100% 可解析、kernel 数量守恒等。阶段 3报告组装序列校验trace_view.json存在后把三份 UI 事实复制到报告仓库目录narrow_trace_window.py—— 把 trace 收窄到代表 step 的窗口。源码注释解释了原因报告只渲染一个 step而原始采集跨整个运行阶段 3 会把 trace 内联进单个 JS 字符串未经收窄的数百 MB 采集会撞上 Node 的字符串长度上限收窄后分页器pager与绑定bindings操作的恰好就是报告实际加载的 trace复制阶段 3 的assets/report-template模板文件到out/ui-report/report/HBM 数据构建在derived/hbm、derived/correlation、derived等目录下探测hbm_bandwidth_timeline.csv、hbm_occupancy_timeline.csv、sample_op_mix.csv、hbm_summary.json四个文件齐全则调用build-hbm-data.mjs生成真实hbm_series.json否则在 stages 中记录empty series: missing [...]build_overlay_and_config.py—— 生成 overlay 与运行时配置build_trace_bindings.py --enrich-trace repo/trace_view.json—— 生成 trace 绑定并把args.layer_index直接写进报告将加载的那份 trace源码注释分页器直接从报告加载的 trace 上读取该字段所以富化副本必须就是那份 trace 本身调用阶段 3 的generate-report.mjs --repo repo --handoff ui-report-handoff.json --refresh-template完成最终生成ui_validation阶段标记为deterministic_passed。全部成功后 pipeline 输出一段 JSON 收据其中status为pending_manual_validation并给出ui_report路径out/ui-report/report/index.html与本地预览命令python3 -m http.server 8081后访问/report/。注意浏览器与视觉验收仍是阶段 3 的职责pipeline 的确定性成功不等于最终 passed。四、阶段门禁Stage Gates什么时候才能进入下一阶段MODEL_BREAKDOWN_TO_UI_WORKFLOW_en.md 定义的阶段门禁是整个工作流的质量闸门阶段 1 → 阶段 2必须提供通过的 validation report、可转换convertible的 score且unmapped_ops列表为空阶段 2 → 阶段 3必须通过转换校验且model_id、report_id、representative_step三者保持一致。这些门禁在阶段 2 入口的 check_breakdown_ready.py 中有确定性实现要求同时满足validation_report.status passedcritique_report.status passed且其 SHA256 绑定与所选 config 匹配critique_validation.status passed且detail.clears_candidate truebreakdown_score.passed_at_cap true、convertible true、hard_gates.passed true、critique_gates.passed trueconfig 为 schema v2、unmapped_ops为空、trace_scope.kind已声明合法取值full_model/rank_local/pipeline_stage_local/unknown见脚本中VALID_SCOPE_KINDS、不存在legacy_unverified迁移标记。config 文件的解析默认取analysis_config.json仅当旧产物通过显式--config才接受analysis_config_v2.jsonbreakdown_paths.resolve_config完成该解析防止旧文件名自动覆盖正式文件名。脚本头部注释点明了设计意图一次转换继承拆解声称的一切。探索性运行、迁移的遗留配置和过期的批判都会产出看似权威、实则建立在未验证归属之上的报告所以在这里拒绝而不是留到下游。4.1 两个需要 AI 介入的合法状态工作流文档特别指出有两个状态需要 AI 工作而非脚本失败状态含义继续方式awaiting_ai_mapping算子需要语义映射--breakdown-config fileawaiting_semantic_review源码语义需要审查--semantic-review file其余状态包括带 required actions 的needs_iteration以及带具体阶段与原因的failed。文档明确要求不要仅凭退出码推断完成。这一条在run_pipeline.py中有直接体现——其die()函数对awaiting*状态使用退出码 0对其他状态使用退出码 1同时把status、stage、message写入 JSON 输出。也就是说退出码只表达 CLI 交接结果真正的状态语义在 JSON 的status/stage字段里。五、按输入选择起始阶段工作流文档给出了从哪个阶段起步的决策表可用输入起始阶段profiling 采集 模型源码阶段 1已批准的analysis_config_v2.json与 score阶段 2analysis、performance 与 timeline JSON 文件阶段 3需要刷新 trace 或改 UI 的既有报告阶段 3本地刷新阶段 1 自身还有入口分派Mode 判定见 1-perf-breakdown/SKILL.md同时有模型源码和kernel_details.csv或raw_ops*.json时走完整 12 步闭环Mode A仅有模型源码时走架构提取与校验Mode B仅有性能数据时委托给仓库内的cann-npu-perfanalysisskill 做 8 维诊断Mode C见skills/cann-npu-perfanalysis/。六、数据规则trace、源码与 UI 事实的边界工作流文档的Data rules一节列出了贯穿三阶段的数据纪律每条都有对应的代码实现trace_view.json必须与 profiling CSV 一起保存阶段 3 硬依赖且采集后无法事后重建perf_data.json和timeline.json是阶段 2 对阶段 3 的输入不是阶段 3 的产物——阶段 3 的 SKILL.md 将后端输入声明为只读report/才是生成物源码是架构权威trace 只提供运行时证据不得虚构缺失的层或 pipeline rank。阶段 2 的 SKILL.md 把这条落实为禁止按叶子标签相似度映射 kernel归属证据只能是拆解自身的op_indices、精确的算子名/类型/张量 shape 和连续段内位置每个 kernel 恰好归属一次所有非排除 kernel 必须归属到唯一有证据支撑的节点或明确出现在阶段 1 已验证的excluded_profiler_ops中其余任何余量都是缺陷而非舍入误差。阶段 2 还规定了一条身份契约Identity contract选择唯一id_namespace形如model/model-id所有node_id由拆解的结构路径推导而来并在三份 JSON 中保持model_id、report_id、representative_step完全一致。validate_conversion.py会校验 kernel 数量守恒attributed excluded unattributed total报告结果时要求显式展示零余量账目例如1218 total 1217 attributed 1 excluded 0 unattributed使分段可审计。七、目录布局与深入阅读路径skills/cann-perf-breakdown/1-perf-breakdown/架构提取、算子归属、校验与评分。入口 SKILL.md 定义了 Mode A/B/C 分派、12 步闭环、状态机awaiting_ai_mapping、needs_revision、passed_at_cap、blocked_*等、evidence_cap 证据上限表和硬性否决项脚本包括extract_source_index.py、analyze_kernels.py、run_validation.py、score_breakdown.py、run_breakdown.py等正式接口 schema 在schemas/目录模型族适配在adapters/deepseek/gemma/qwen/longcat。skills/cann-perf-breakdown/2-adapt-breakdown-to-ui-json/拆解结果到 UI 数据契约的确定性转换。核心脚本为check_breakdown_ready.py、build_node_index.py、attribute_kernels.py、emit_ui_facts.py、build_expert_inventory.py、build_architecture_graph.py、validate_conversion.py、run_pipeline.py字段级契约见 schema-mapping英文版 schema-mapping_en.md完整数值示例见 worked-example。tests/下有一组针对架构图、kernel 归属、计数器指标、专家清单和报告交接的测试。skills/cann-perf-breakdown/3-generate-ui-json-report/报告资源、运行时数据与前端生成脚本。assets/report-template/是可复用的报告模板HTML/CSS/JSscripts/包含generate-report.mjs支持--refresh-template与只读--check、validate-architecture-graph.mjs、validate-report.mjs等确定性校验器及对应测试UI 契约与验证矩阵见references/ui-contract.md与references/validation-matrix.md。MODEL_BREAKDOWN_TO_UI_WORKFLOW_en.md三阶段工作流导航阶段选择、门禁、状态表、数据规则。八、端到端使用小结一次完整的从采集到报告流程可以概括为准备输入profiling 采集目录必须含kernel_details.csv和trace_view.json建议连同 HBM 样本与模型源码目录*modeling*.py等运行阶段 1 完成结构拆解并通过门禁产出五个正式文件analysis_config.json、critique_report.json、critique_validation.json、validation_report.json、breakdown_score.json若 pipeline 输出awaiting_ai_mapping/awaiting_semantic_review按请求文件完成语义工作后以--breakdown-config/--semantic-review继续运行run_pipeline.py --breakdown 阶段1产物目录 --capture-dir 采集目录 --model-id model-id --out 输出目录pipeline 自动完成就绪门禁、节点索引、kernel 归属、UI 事实、架构图、图一致性回查、转换校验、trace 收窄、HBM 构建、overlay 与绑定、最终报告生成检查输出 JSON 收据status为pending_manual_validation且stages中各阶段无failed时打开out/ui-report/report/index.html或起本地 http 服务访问/report/完成浏览器与视觉验收若某阶段失败按stage字段定位如readiness、attribution、graph_consistency、conversion_validation失败信息会附带具体错误内容attribution阶段的 hint 还提示了常见根因不等长 invocation span 意味着该 group 不应共享模板应在阶段 1 中把差异层拆成独立 layer_group。这套工作流的设计取向在仓库中体现得很一致确定性脚本只做可机械证明的校验语义判断交给隔离上下文的 LLM 角色阶段之间靠正式文件接口和哈希绑定衔接——报告中的每一个数字都可以回溯到拆解阶段的证据文件而不是某次生成过程的即兴发挥。【免费下载链接】oam-tools本项目为开发者提供故障定位工具包含故障信息收集软硬件信息展示AI core error报错分析等能力提升故障问题定位效率文档可在昇腾社区搜索“故障处理简介”选择社区版。项目地址: https://gitcode.com/cann/oam-tools创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 CANN oam-tools 实战：cann-perf-breakdown 三阶段工作流，把 NPU Profiling 数据变成可交互性能报告
CANN oam-tools 实战cann-perf-breakdown 三阶段工作流把 NPU Profiling 数据变成可交互性能报告【免费下载链接】oam-tools本项目为开发者提供故障定位工具包含故障信息收集软硬件信息展示AI core error报错分析等能力提升故障问题定位效率文档可在昇腾社区搜索“故障处理简介”选择社区版。项目地址: https://gitcode.com/cann/oam-toolsoam-tools 仓库中的skills/cann-perf-breakdown/目录提供了一套从 NPU profiling 采集数据到可交互 UI 报告的三阶段技能工作流第一阶段基于模型源码建立架构结构并把kernel_details.csv中的性能算子映射到结构节点第二阶段把拆解结果确定性地转换为 UI 所需的 analysis、performance、timeline 与架构图数据第三阶段基于转换后的数据生成可交互的 HTML 报告。读完本文你能掌握该工作流的整体编排逻辑、阶段门禁Stage Gates的判定条件、run_pipeline.py入口的完整参数与状态机语义以及如何按编号顺序调用三个 skill 完成一次从采集目录到报告的端到端运行。一、整体结构三个 skill 与一份工作流导航该目录的核心内容组织为一个三阶段流水线按编号顺序使用阶段目录职责1skills/cann-perf-breakdown/1-perf-breakdown/根据模型源码建立架构并将 profiling 算子映射到结构节点架构提取、算子归属、校验与评分2skills/cann-perf-breakdown/2-adapt-breakdown-to-ui-json/将拆解结果转换为 UI 所需的 analysis、performance、timeline 和架构图数据确定性转换3skills/cann-perf-breakdown/3-generate-ui-json-report/报告资源、运行时数据和前端生成脚本输出可交互 UI 报告每个阶段目录下有自己的SKILL.md定义入口名称frontmatter 的name字段和详细规则references/目录存放字段级契约。三个 skill 的运行时名称分别见各SKILL.md文件头阶段 1 为 cann-perf-breakdown阶段 2 为 adapt-breakdown-to-ui-json阶段 3 为 cann-perf-ui-json-report。完整的阶段衔接、输入输出和门禁说明见 MODEL_BREAKDOWN_TO_UI_WORKFLOW_en.md中文对照 MODEL_BREAKDOWN_TO_UI_WORKFLOW.md。该导航文档定位很克制它只回答下一步该用哪个 skill具体的规则、字段、参数与校验逻辑留在各 skill 的SKILL.md和references/中。需要强调的一个约定数字目录名只表示执行顺序运行时查找必须用各 skill frontmatter 中唯一的name字段。这不是风格问题而是有代码依据的——run_pipeline.py通过扫描同级目录、解析每个SKILL.md的 frontmattername来定位 peer skill# skills/cann-perf-breakdown/2-adapt-breakdown-to-ui-json/scripts/run_pipeline.py STAGE1 find_peer_skill(cann-perf-breakdown) # The preserved UI skill keeps its original frontmatter name. STAGE3 find_peer_skill(cann-perf-ui-json-report)也就是说脚本根本不依赖目录名定位阶段 1 和阶段 3 的实现目录。如果目录被改名但 frontmatter 未同步pipeline 会直接抛出expected exactly one peer skill named ...错误。二、安装与调用方式官方安装方式是浅克隆仓库后把整个cann-perf-breakdown目录复制到 Codex 的 skills 目录以 README_en.md 为准git clone --depth 1 https://gitcode.com/cann/oam-tools.git mkdir -p ~/.codex/skills cp -a oam-tools/skills/cann-perf-breakdown ~/.codex/skills/调用约定英文 README 原文的 invoke 形式Use the $cann-perf-breakdown workflow with capture-directory as the input directory and output-directory as the output directory.即向 Agent 声明使用$cann-perf-breakdown工作流并显式给出输入目录profiling 采集目录与输出目录。中文版本 README.md 给出的等价表述是使用 $cann-perf-breakdown 工作流输入目录为 采集目录输出目录为 输出目录。三、快速入口run_pipeline.py 一条命令跑完全程三阶段工作流有一个确定性 pipeline 入口位于 run_pipeline.pypython3 2-adapt-breakdown-to-ui-json/scripts/run_pipeline.py \ --capture-dir profiling-directory \ --model-id model-id \ --out output-directory该入口会在输入证据满足阶段门禁时依次执行转换和报告生成当需要 AI 语义映射或语义审查时它会写出请求文件并暂停由工作流文档描述的机制继续推进。3.1 输入发现逻辑从工作流文档和源码看pipeline 会自动发现三类输入kernel_details.csvkernel 级性能数据、trace_view.json原始 Chrome Trace和模型源码文件然后在输出目录下写出 breakdown 报告和 UI 报告。源码中的发现与参数处理值得展开因为这里藏着几条关键约束--breakdown与--capture-dir的区分--breakdown指向阶段 1 的正式产物目录必须包含阶段 1 的五个正式文件--capture-dir指向 profiling 采集目录用于 trace/HBM 输入未提供时默认等于--breakdown。脚本 docstring 明确辅助的 raw-op 和 trace 文件对归属和报告组装仍是必需的但它们不能换取门禁通过cannot grant readiness。trace 是阶段 3 的硬依赖如果采集目录中找不到trace_view.jsonpipeline 在ui_report阶段直接失败报错信息为 no trace_view.json in the capture; stage 3 requires the raw trace and it cannot be reconstructed after the fact。这与工作流文档的数据规则一致trace_view.json必须与采集时的 profiling CSV 一起保存。HBM 样本是可选降级项--hbm-dir可重复传入一次采集会把 HBM 样本拆分到derived/hbm和derived/correlation等多个子目录而build-hbm-data.mjs要求四个文件在同一目录。缺少 HBM 文件时报告仍可渲染只是 HBM 面板为空序列——采集到的带宽和占用率缺席而不是被报告为不可用。3.2 pipeline 的实际执行序列阅读 run_pipeline.py 可以看到完整的确定性编排共分为两段阶段 2转换序列check_breakdown_ready.py --breakdown dir --out out/work/readiness.json—— 就绪门禁失败即终止build_node_index.py --breakdown dir --config config --namespace model/model-id --out out/work/node_index.json—— 建立节点索引可重复传--rename-group StructureKeynode-nameattribute_kernels.py --breakdown dir ... --kernels raw_ops.json --kernel-details raw_ops_details.json --out out/work/kernel_attribution.json—— kernel 归属成功时记录100% accountedemit_ui_facts.py --model-id model-id --report-id report-id --peak-bf16-tflops 376 --dtype-bytes 2 --out out/ui_facts可选追加--device-freq—— 产出model-id_analysis_config.json、model-id_perf_data.json、model-id_timeline.json三份 UI 事实build_expert_inventory.py—— MoE 专家清单仅对声明了专家experts的模型写出Dense 模型不产出任何文件且不算失败--ep-rank用于解析专家并行 rank 上的专家身份归属build_architecture_graph.py—— 生成report/outputs/model_architecture_graph.json图一致性回查调用阶段 1 的check_graph_consistency.py对刚生成的图执行 G2/G3/G7 等检查。源码注释解释了为什么必须在 pipeline 里补跑阶段 1 拥有这些图/配置一致性检查层覆盖、重复次数、残差方向但在校验时刻图还不存在如果不在这里重跑G2/G3/G7 对每个经该 pipeline 驱动的采集都是死代码。图中出现错误级 issue 时 pipeline 会终止理由是渲染出的图与配置矛盾基于它构建的报告将展示拆解并未声称的结构validate_conversion.py --out facts --attribution attribution—— 转换校验检查身份一致性、每node_id唯一定义与唯一记录、timeline owner 100% 可解析、kernel 数量守恒等。阶段 3报告组装序列校验trace_view.json存在后把三份 UI 事实复制到报告仓库目录narrow_trace_window.py—— 把 trace 收窄到代表 step 的窗口。源码注释解释了原因报告只渲染一个 step而原始采集跨整个运行阶段 3 会把 trace 内联进单个 JS 字符串未经收窄的数百 MB 采集会撞上 Node 的字符串长度上限收窄后分页器pager与绑定bindings操作的恰好就是报告实际加载的 trace复制阶段 3 的assets/report-template模板文件到out/ui-report/report/HBM 数据构建在derived/hbm、derived/correlation、derived等目录下探测hbm_bandwidth_timeline.csv、hbm_occupancy_timeline.csv、sample_op_mix.csv、hbm_summary.json四个文件齐全则调用build-hbm-data.mjs生成真实hbm_series.json否则在 stages 中记录empty series: missing [...]build_overlay_and_config.py—— 生成 overlay 与运行时配置build_trace_bindings.py --enrich-trace repo/trace_view.json—— 生成 trace 绑定并把args.layer_index直接写进报告将加载的那份 trace源码注释分页器直接从报告加载的 trace 上读取该字段所以富化副本必须就是那份 trace 本身调用阶段 3 的generate-report.mjs --repo repo --handoff ui-report-handoff.json --refresh-template完成最终生成ui_validation阶段标记为deterministic_passed。全部成功后 pipeline 输出一段 JSON 收据其中status为pending_manual_validation并给出ui_report路径out/ui-report/report/index.html与本地预览命令python3 -m http.server 8081后访问/report/。注意浏览器与视觉验收仍是阶段 3 的职责pipeline 的确定性成功不等于最终 passed。四、阶段门禁Stage Gates什么时候才能进入下一阶段MODEL_BREAKDOWN_TO_UI_WORKFLOW_en.md 定义的阶段门禁是整个工作流的质量闸门阶段 1 → 阶段 2必须提供通过的 validation report、可转换convertible的 score且unmapped_ops列表为空阶段 2 → 阶段 3必须通过转换校验且model_id、report_id、representative_step三者保持一致。这些门禁在阶段 2 入口的 check_breakdown_ready.py 中有确定性实现要求同时满足validation_report.status passedcritique_report.status passed且其 SHA256 绑定与所选 config 匹配critique_validation.status passed且detail.clears_candidate truebreakdown_score.passed_at_cap true、convertible true、hard_gates.passed true、critique_gates.passed trueconfig 为 schema v2、unmapped_ops为空、trace_scope.kind已声明合法取值full_model/rank_local/pipeline_stage_local/unknown见脚本中VALID_SCOPE_KINDS、不存在legacy_unverified迁移标记。config 文件的解析默认取analysis_config.json仅当旧产物通过显式--config才接受analysis_config_v2.jsonbreakdown_paths.resolve_config完成该解析防止旧文件名自动覆盖正式文件名。脚本头部注释点明了设计意图一次转换继承拆解声称的一切。探索性运行、迁移的遗留配置和过期的批判都会产出看似权威、实则建立在未验证归属之上的报告所以在这里拒绝而不是留到下游。4.1 两个需要 AI 介入的合法状态工作流文档特别指出有两个状态需要 AI 工作而非脚本失败状态含义继续方式awaiting_ai_mapping算子需要语义映射--breakdown-config fileawaiting_semantic_review源码语义需要审查--semantic-review file其余状态包括带 required actions 的needs_iteration以及带具体阶段与原因的failed。文档明确要求不要仅凭退出码推断完成。这一条在run_pipeline.py中有直接体现——其die()函数对awaiting*状态使用退出码 0对其他状态使用退出码 1同时把status、stage、message写入 JSON 输出。也就是说退出码只表达 CLI 交接结果真正的状态语义在 JSON 的status/stage字段里。五、按输入选择起始阶段工作流文档给出了从哪个阶段起步的决策表可用输入起始阶段profiling 采集 模型源码阶段 1已批准的analysis_config_v2.json与 score阶段 2analysis、performance 与 timeline JSON 文件阶段 3需要刷新 trace 或改 UI 的既有报告阶段 3本地刷新阶段 1 自身还有入口分派Mode 判定见 1-perf-breakdown/SKILL.md同时有模型源码和kernel_details.csv或raw_ops*.json时走完整 12 步闭环Mode A仅有模型源码时走架构提取与校验Mode B仅有性能数据时委托给仓库内的cann-npu-perfanalysisskill 做 8 维诊断Mode C见skills/cann-npu-perfanalysis/。六、数据规则trace、源码与 UI 事实的边界工作流文档的Data rules一节列出了贯穿三阶段的数据纪律每条都有对应的代码实现trace_view.json必须与 profiling CSV 一起保存阶段 3 硬依赖且采集后无法事后重建perf_data.json和timeline.json是阶段 2 对阶段 3 的输入不是阶段 3 的产物——阶段 3 的 SKILL.md 将后端输入声明为只读report/才是生成物源码是架构权威trace 只提供运行时证据不得虚构缺失的层或 pipeline rank。阶段 2 的 SKILL.md 把这条落实为禁止按叶子标签相似度映射 kernel归属证据只能是拆解自身的op_indices、精确的算子名/类型/张量 shape 和连续段内位置每个 kernel 恰好归属一次所有非排除 kernel 必须归属到唯一有证据支撑的节点或明确出现在阶段 1 已验证的excluded_profiler_ops中其余任何余量都是缺陷而非舍入误差。阶段 2 还规定了一条身份契约Identity contract选择唯一id_namespace形如model/model-id所有node_id由拆解的结构路径推导而来并在三份 JSON 中保持model_id、report_id、representative_step完全一致。validate_conversion.py会校验 kernel 数量守恒attributed excluded unattributed total报告结果时要求显式展示零余量账目例如1218 total 1217 attributed 1 excluded 0 unattributed使分段可审计。七、目录布局与深入阅读路径skills/cann-perf-breakdown/1-perf-breakdown/架构提取、算子归属、校验与评分。入口 SKILL.md 定义了 Mode A/B/C 分派、12 步闭环、状态机awaiting_ai_mapping、needs_revision、passed_at_cap、blocked_*等、evidence_cap 证据上限表和硬性否决项脚本包括extract_source_index.py、analyze_kernels.py、run_validation.py、score_breakdown.py、run_breakdown.py等正式接口 schema 在schemas/目录模型族适配在adapters/deepseek/gemma/qwen/longcat。skills/cann-perf-breakdown/2-adapt-breakdown-to-ui-json/拆解结果到 UI 数据契约的确定性转换。核心脚本为check_breakdown_ready.py、build_node_index.py、attribute_kernels.py、emit_ui_facts.py、build_expert_inventory.py、build_architecture_graph.py、validate_conversion.py、run_pipeline.py字段级契约见 schema-mapping英文版 schema-mapping_en.md完整数值示例见 worked-example。tests/下有一组针对架构图、kernel 归属、计数器指标、专家清单和报告交接的测试。skills/cann-perf-breakdown/3-generate-ui-json-report/报告资源、运行时数据与前端生成脚本。assets/report-template/是可复用的报告模板HTML/CSS/JSscripts/包含generate-report.mjs支持--refresh-template与只读--check、validate-architecture-graph.mjs、validate-report.mjs等确定性校验器及对应测试UI 契约与验证矩阵见references/ui-contract.md与references/validation-matrix.md。MODEL_BREAKDOWN_TO_UI_WORKFLOW_en.md三阶段工作流导航阶段选择、门禁、状态表、数据规则。八、端到端使用小结一次完整的从采集到报告流程可以概括为准备输入profiling 采集目录必须含kernel_details.csv和trace_view.json建议连同 HBM 样本与模型源码目录*modeling*.py等运行阶段 1 完成结构拆解并通过门禁产出五个正式文件analysis_config.json、critique_report.json、critique_validation.json、validation_report.json、breakdown_score.json若 pipeline 输出awaiting_ai_mapping/awaiting_semantic_review按请求文件完成语义工作后以--breakdown-config/--semantic-review继续运行run_pipeline.py --breakdown 阶段1产物目录 --capture-dir 采集目录 --model-id model-id --out 输出目录pipeline 自动完成就绪门禁、节点索引、kernel 归属、UI 事实、架构图、图一致性回查、转换校验、trace 收窄、HBM 构建、overlay 与绑定、最终报告生成检查输出 JSON 收据status为pending_manual_validation且stages中各阶段无failed时打开out/ui-report/report/index.html或起本地 http 服务访问/report/完成浏览器与视觉验收若某阶段失败按stage字段定位如readiness、attribution、graph_consistency、conversion_validation失败信息会附带具体错误内容attribution阶段的 hint 还提示了常见根因不等长 invocation span 意味着该 group 不应共享模板应在阶段 1 中把差异层拆成独立 layer_group。这套工作流的设计取向在仓库中体现得很一致确定性脚本只做可机械证明的校验语义判断交给隔离上下文的 LLM 角色阶段之间靠正式文件接口和哈希绑定衔接——报告中的每一个数字都可以回溯到拆解阶段的证据文件而不是某次生成过程的即兴发挥。【免费下载链接】oam-tools本项目为开发者提供故障定位工具包含故障信息收集软硬件信息展示AI core error报错分析等能力提升故障问题定位效率文档可在昇腾社区搜索“故障处理简介”选择社区版。项目地址: https://gitcode.com/cann/oam-tools创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考