CANN oam-tools 技能详解：基于 Skill 2 产物生成 PTO 交互式 Profiling UI 报告

CANN oam-tools 技能详解基于 Skill 2 产物生成 PTO 交互式 Profiling UI 报告【免费下载链接】oam-tools本项目为开发者提供故障定位工具包含故障信息收集软硬件信息展示AI core error报错分析等能力提升故障问题定位效率文档可在昇腾社区搜索“故障处理简介”选择社区版。项目地址: https://gitcode.com/cann/oam-tools导读本文围绕 skills/cann-perf-ui-json-report/SKILL_en.md 展开系统讲解 CANN oam-tools 仓库中cann-perf-ui-json-reportSkill 3如何将模型架构图、性能数据、归一化 Timeline 与原始 Chrome Trace 等后端事实渲染为可直接在浏览器中打开、支持 Layer 导航、指标联动与 Trace 交互的 PTO 风格 profiling 报告。读完本文你将掌握generate-report.mjs的完整调用方式、ui_report_handoff.v1清单结构、确定性校验矩阵、浏览器验收流程与失败路由策略并能用--check只读模式安全地诊断报告问题。背景Skill 3 在 profiling 流水线中的位置在 oam-tools 的技能体系中模型性能分析被拆分为三个可独立执行的技能Skillcann-perf-breakdownSkill 1从模型源码与 Trace 中提取分析配置、结构、性能指标与 Kernel 数据cann-perf-breakdown-to-ui-jsonSkill 2将 Skill 1 的产物加工为架构图、overlay 映射与 Trace 绑定关系输出ui_report_handoff.v1交接清单cann-perf-ui-json-reportSkill 3本文主角消费 Skill 2 的全部产物与后端分析数据生成、刷新、校验并预览report/index.html。Skill 3 的职责边界非常清晰它只拥有展示presentation、交互interaction、布局、语言/主题、选区同步、本地传输与校验它绝不修复任何后端事实。这一边界在>rtk node skill-dir/scripts/generate-report.mjs \ --repo report-repo \ --handoff ui-report-handoff.json \ --refresh-template其中skill-dir指向本技能目录skills/cann-perf-ui-json-report。可选输入可追加:rtk node skill-dir/scripts/generate-report.mjs \ --repo report-repo \ --trace trace_view.json \ --hbm-dir aligned-hbm-dir \ --refresh-template参数语义参数作用--repo报告仓库根目录必填缺失会直接抛错生成产物位于其下report/--handoff显式指定交接清单路径缺省时按repo/ui-report-handoff.json、repo/ui_facts/ui-report-handoff.json顺序发现--trace以事务方式替换或创建仓库内的原始 Tracerepo/trace_view.json--hbm-dir指向对齐后的 HBM 输入目录用于生成hbm_series.json--refresh-template替换可复用的运行时 UI 文件但保留/重新生成模型特定配置并保留 Skill 2 产物ui_report_handoff.v1 清单结构交接清单同时充当配置与溯源configuration and provenance并声明实际的模型侧文件名。完整示例见>{ schema_version: ui_report_handoff.v1, model_family: deepseek_v3_2, skill3_adapter: generic, inputs: { analysis: ../model_analysis_config.json, performance: ../model_perf_data.json, timeline: ../model_timeline.json, trace: ../trace_view.json, bindings: ./outputs/trace_bindings.json, architecture: ./outputs/model_architecture_graph.json, overlay: ./outputs/architecture_overlay_map.json }, optional_inputs: { operator_details: ./outputs/operator_details.json, hbm: ./outputs/hbm_series.json, findings: ./outputs/metrics_findings.json, expert_inventory: ./outputs/expert_inventory.json }, capabilities: { repeatedLayers: true, expertInventory: true, expectedGraphFeatures: { fanOutMin: 2, fanInMin: 2, residualEdgesMin: 2, parallelRowsMin: 1 } }, provenance: { skills: [cann-perf-breakdown, cann-perf-breakdown-to-ui-json], modelSource: models/modeling_example.py, extractorModel: model-name } }关键校验点实现在 report-runtime-config.mjs 的validateHandoff中schema_version必须为ui_report_handoff.v1七个inputs路径analysis、performance、timeline、trace、bindings、architecture、overlay缺一不可缺失即报 field-specific 错误skill3_adapter只允许generic——Skill 3拒绝模型专属适配器模型族本身不能授权单独的 builder缺失的可选产物降级为类型化的空数据typed empty data缺失的必需输入直接失败。七个必需输入与四个可选输入根据 input-files.md必需输入的职责划分如下Handoff key典型产物权威内容inputs.analysis*_analysis_config.json后端node_id、层级、语义路径、代码引用与观测到的 Layer 实例inputs.performance*_perf_data.json捕获的节点指标、计时范围、算子数量与占比inputs.timeline*_timeline.json归一化事件边界、泳道及可选节点/Layer 归属inputs.tracetrace_view.json原始 Chrome Trace 元数据、duration/counter/flow 事件与物理泳道inputs.bindingsreport/outputs/trace_bindings.json已评审的归一化事件到原始 Trace 的绑定inputs.architecturereport/outputs/model_architecture_graph.json源码层级、重复 Layer 模板、语义边、tensor 元数据与溯源inputs.overlayreport/outputs/architecture_overlay_map.json已评审的后端节点到架构条目的分类映射可选输入及其缺省产物Handoff key缺省产物用途operator_detailsreport/outputs/operator_details.json算子索引、名称、类型、Stream、输入/输出 shape 与 dtypehbmreport/outputs/hbm_series.jsonHBM 带宽、占用率及设备/频率事实findingsreport/outputs/metrics_findings.json后端撰写的节点级诊断发现expert_inventoryreport/outputs/expert_inventory.json已声明的 MoE 路由/共享专家清单Skill 3 在正常生成过程中还会按固定顺序发现上游产物算子详情依次查repo/work/raw_ops_details.json与repo/../work/raw_ops_details.json诊断发现依次查repo/metrics_findings.json与repo/../metrics_findings.json专家清单取repo/ui_facts/*_expert_inventory.json或repo/../ui_facts/*_expert_inventory.json中第一个命中文件。当使用--hbm-dir时只读取以下四个文件并归一化为report/outputs/hbm_series.jsonhbm_bandwidth_timeline.csvhbm_occupancy_timeline.csvsample_op_mix.csvhbm_summary.json注意两条限制AICore 频率目前没有独立的通用输入文件必须由配置好的 HBM/device-profile 产物提供粗粒度 HBM 采样不能用于推导每个算子的带宽归属。report-config.js生成式运行期配置report-config.js是生成的传输配置而非模型模板。必需的键为 analysis、performance、timeline、trace、bindings、architecture、overlay可选的缺省键为 operatorDetails、hbm、findings、expertInventory均位于report/outputs/下。templateOverrides允许列出与技能模板有意的差异文件但未声明的模板漂移undeclared template drift属于校验失败。从report-runtime-config.mjs可以看到实现细节readRuntimeConfig用vm.runInNewContext在沙箱中执行report-config.js并要求赋值window.ReportRuntimeConfig随后按REQUIRED_CONFIG_KEYS逐项校验字符串键缺失即抛出ReportRuntimeConfig is missing required key(s)。configFromHandoff将清单转换为运行期配置并默认templateVersion: 2CURRENT_TEMPLATE_VERSION。--check 只读检查与生成安全只读模式rtk node skill-dir/scripts/generate-report.mjs --repo report-repo --check--check严格只读不能与--refresh-template、--trace、--hbm-dir组合不得创建占位文件、不得重命名index.html、不得重写 manifest、不得触碰时间戳。在源码中该约束由generate-report.mjs第 56–58 行显式检查并在违规时抛错。生成安全测试修改生成器后应对已知良好的报告仓库运行rtk node skill-dir/scripts/test-generation-safety.mjs --repo known-good-report-repo事务式生成生成是事务式的transactionalgenerate-report.mjs会先把既有报告整体重命名为report.prev任何步骤失败都会删除未完成的reportRoot、恢复report.prev并在--trace被替换时恢复trace_view.prev.json保证失败后旧报告与旧 Trace逐字节还原restore byte-for-byte。成功后才清理备份目录。确定性校验矩阵生成后必须执行的检查每次生成都必须依次运行rtk node skill-dir/scripts/validate-architecture-graph.mjs \ repo/report/outputs/model_architecture_graph.json \ --source-root section/source_architecture \ --require-semantic-port-policy rtk node skill-dir/scripts/validate-report.mjs --repo repo rtk node skill-dir/scripts/test-layer-report-metrics.mjs --repo repo rtk node skill-dir/scripts/test-projected-fanout.mjs --repo repovalidate-architecture-graph.mjs架构图合法性该校验器用法输出见脚本第 32 行检查每个边必须有受支持的semanticEdgeType未知类型直接 fail需要 tensor 的边类型必须携带tensor.name、tensor.shape、tensor.dtypetensor.role若存在必须与semanticEdgeType兼容例如activation边的 role 期望值不符会 failresidual 边必须dashed: true否则 fail数据流不得有非法环可用--allow-cycles显式放开、不得自环、source/target 必须引用已声明 item、不得存在推断边。validate-report.mjs运行时整体校验该脚本共 613 行的检查内容与 validation-matrix.md 对应核心包括模板哈希校验TEMPLATE_VERIFIED_FILES列出的 24 个文件index.html、app.css/app.js、report-data.js、architecture-data.js、trace-view.js、hbm-view.js、design-system 下 tokens/css/patterns 等必须与技能模板逐字节哈希一致不一致时若在templateOverrides中声明则放行warn否则记为 STALE 失败运行期文件存在性对runtimeFiles数组执行Promise.all(access(...))覆盖 index.html、embedded-data、config、各 JS/CSS、outputs 下五个 JSON 与 design-system 资源可选数据诚实降级findings 缺失时以{schema_version:1, advisory_only:true, nodes:[]}兜底expertInventory 缺失时以{schema_version:1, available:false}兜底operatorDetails 缺失时以{schema_version:1, source:null, count:0, details:{}}兜底HBM 缺失时以空 bandwidth/occupancy 兜底JS 语法沙箱编译对 app.js、report-embedded-data.js、report-config.js、report-data.js、architecture-data.js、trace-view.js、hbm-view.js、timeline-time-selection/pattern.js 逐一执行new vm.Script(...)以捕获语法/运行期装配错误溯源校验从runtimeConfig.provenance或analysis.generation_provenance读取 skills 与 modelSource禁止把 mock 身份当生产事实输出。能力门控与验证清单Layer、专家、HBM、预期图特征等断言只在交接清单声明了相应能力时运行。声明了能力却拿不出证据是失败能力确实不适用时应标记为not_applicable而不是伪造一次通过。生成成功后写入report/outputs/validation_manifest.jsonschemamodel_skill_validation_manifest.v2将确定性状态与手工状态分开记录deterministic_status: passed仅代表全部适用的自动化检查通过overall_status先为pending_manual_validation直到浏览器与视觉检查完成并逐项记录后才置为passed手工条目取passed/failed/not_run三值之一。从generate-report.mjs的 manifest 写入代码可以看到repeatedLayers能力为 false 时该检查标记为not_applicable其余确定性检查置 true手工检查初始均为not_run。最终浏览器验收确定性检查通过后在1440 × 1000视口对规范报告 URL 做一次冒烟测试若需要独立交付再对report/index.html的file://协议做一次冒烟。至少验证无 console/resource 错误架构图、Inspector、Trace 均加载当前数据mapped / source-only / aggregate / runtime 四类选择各自遵守事实边界三个不相邻的 Layer 切换时图徽标、Inspector 指标、Sequence 事件、Flow 同步更新且算子身份不变已声明的分支、残差边、Layer 选择桥保持连通热力图例、本地化标签、提示框、HBM 缺失态、可选专家投影符合 UI 契约空白画布可清空选区Trace 的聚焦/缩放/平移可用。只有将浏览器、file 协议与视觉结果全部记入校验清单后才允许把overall_status置为passed。UI 契约要点速览ui-contract.md 定义了报告界面的行为规范节选如下架构图自上而下语义数据流、下进上出端口并行兄弟节点需声明独立分支或同行布局串行后代依次占行折叠多边到同一端点时必须保留每条投影边的身份residual 边走稳定虚线外左正交泳道并圆角时间占比热力默认开启使用单一对数 Turbo 域统一节点徽标、Operator List 徽标、图例与 Layer 圆点缺失值保持灰色Expert Inventory 仅应用于显式 role 标记的 MoE 结构Router、代表路由专家、外部 Shared Expert、Combine融合执行时不得伪造逐专家耗时。重复 Layer模板node_id与具体layer_index/structure_instance_node_id是不同身份一个渲染事务内跨架构图、Inspector、Operator List、Sequence、Trace、Flow 维持唯一活动 Layer 上下文同构兄弟模板间按精确相对路径保持选中算子找不到精确对应时保留语义选择并显示指标不可用而不是跳变或清空。Inspector 与 Operator List四个核心指标wall_ms、busy_union_ms、kernel_sum_ms、total_cost_ms优先展示wall 时间标中性 Primary Metric 标签随后一行整宽的时间占比卡片加 Operators/HBM 估算/MFU INT8/MFU BF16 四张等宽卡片不可用事实显示–指标提示框说明精确定义与证据边界禁用原生title属性。TraceView保留全部有效原始 metadata/duration/counter/flow 事件与物理泳道泳道高 22 px、任务条高 18 pxFlow 只为当前选中映射后端节点的严格上下游端点渲染支持跨泳道时间选区、精确事件选中、Ctrl/Command 滚轮缩放、键盘平移、fit、focus 与选区重置。HBM 与可选证据HBM 区块标题始终可见无有效带宽/占用率时默认折叠展开后才显示本地化的未采集说明有数据时用完整源数组渲染独立的连续 Read/Write/占用率折线AICore 频率仅在提供时作为独立可折叠区块渲染并在图表提示框中展示声明/派生值一致性与限频状态不得用常量值虚构时间序列。布局与语言默认中文并保留已保存语言复用共享 PTO tokens、workbench、IDE frame、tab、graph、tooltip、swimlane、selection pattern可见文本不小于 12 px10 px Trace 标签与 11 px 指标公式除外支持明暗双主题。失败路由问题出在哪一环就回到哪一环SKILL_en.md 给出了清晰的排障决策树现象处理身份、节点覆盖、Timeline owner 或 Trace 绑定不一致回退到 Skill 1/2 数据要求不打补丁式修改后端 JSON缺边/tensor/溯源、重复成员非法、fan-out/fan-in/residual 不足回退到 Skill 2 图要求源码锁source lock不匹配停止并重新提取/评审架构绝不盲目更新哈希布局、样式、本地化、交互、选择或运行期传输问题修复 Skill 3 模板并重新生成无法解决的事实保持为 unavailable禁止仅按叶子标签相似度映射来提升覆盖率在实现层面generate-report.mjs还内置了一张UPSTREAM_DIAGNOSTIC错误模式表例如遇到tensor.name is required、unsupported semanticEdgeType、dataflow cycle detected、repeatCount must、residual edge but dashed is not true、fan-out minimum等典型错误串时会打印 Upstream Skill Diagnostic 区块直接给出应当回到 Skill 1/2 的哪个脚本如build_architecture_graph.py、build_node_index.py去修复极大降低了跨技能排障成本。另外请牢记报告中的计数与观测能力一律来自当前文件绝不引用历史示例或旧数据。小结cann-perf-ui-json-report以事实边界不可逾越、模板漂移不可容忍、失败必须逐字节回滚三条铁律把 Skill 2 的架构图、overlay、绑定与后端 analysis/performance/Timeline/Trace 数据安全地变成可交互的中文优先 profiling 报告。整个流程交接清单 → 事务式生成 → 确定性校验 → 浏览器冒烟 → 验收清单既适合作为可复现的 CI 门禁也适合作为 Agent 按契约自主完成报告生成、修复与验证的操作手册。建议进一步阅读 SKILL.md中文版操作入口、data-contract.md 与 validation-matrix.md 获取完整契约并结合 generate-report.mjs 与 validate-report.mjs 的源码深入理解实现。【免费下载链接】oam-tools本项目为开发者提供故障定位工具包含故障信息收集软硬件信息展示AI core error报错分析等能力提升故障问题定位效率文档可在昇腾社区搜索“故障处理简介”选择社区版。项目地址: https://gitcode.com/cann/oam-tools创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考