cann-perf-ui-json-report：CANN oam-tools 交互式 UI JSON 性能报告的生成、校验与交付-创锋一号

cann-perf-ui-json-report：CANN oam-tools 交互式 UI JSON 性能报告的生成、校验与交付

【免费下载链接】oam-tools本项目为开发者提供故障定位工具，包含故障信息收集，软硬件信息展示，AI core error报错分析等能力，提升故障问题定位效率，文档可在昇腾社区搜索“故障处理简介”（选择社区版）。项目地址: https://gitcode.com/cann/oam-tools

导读

本文围绕 CANN oam-tools 开源仓库中的 Skill 3 组件cann-perf-ui-json-report（定义于 skills/cann-perf-ui-json-report/SKILL.md）展开，讲解如何将上游 Skill 2 产出的架构图、overlay 映射与 Trace 绑定等 JSON 事实，生成为可交互、可独立分发（含file://协议）的 Profiling 性能报告report/index.html。读完本文，你将掌握该 Skill 的完整 CLI 用法（--repo、--handoff、--trace、--hbm-dir、--refresh-template、--check）、四项必备确定性校验的具体检查内容、校验清单状态语义与失败路由规则，以及从源码层面理解生成器的“事务式回滚”“只读检查”与“模板漂移拦截”等工程保障机制。

Skill 3 在性能分析流水线中的定位

在 oam-tools 的模型性能分解流水线中，本 Skill 属于最下游的“报告呈现层”，其上游链条为：

Skill 1（cann-perf-breakdown）：产出后端分析 JSON（如analysis_config_v2规范）、性能 JSON、归一化 Timeline JSON 与原始 Chrome Trace；
Skill 2（cann-perf-breakdown-to-ui-json）：将后端事实投影为 UI 可消费的结构化产物，包括model_architecture_graph.json（模型架构图）、architecture_overlay_map.json（后端节点到架构项的映射）、trace_bindings.json（归一化事件到原始 Trace 事件的绑定），并生成ui_report_handoff.v1交接清单；
Skill 3（cann-perf-ui-json-report，本文主体）：以只读方式消费上述全部输入，渲染生成交互式报告，并通过确定性校验 + 浏览器人工验证双重关卡后才判定通过。

SKILL.md 开篇即给出铁律：“Render backend and source facts without inventing architecture, performance, ownership, diagnoses, or advice.”即 Skill 3 只负责呈现与交互，绝不“发明”架构边、性能数据、归属关系、诊断结论或建议；后端输入一律只读，report/目录被视为“生成的运行时”（generated runtime）。

与相邻 Skill 的关系

本 Skill 依赖 skills/cann-perf-breakdown-to-ui-json/ 产出的model_architecture_graph.v1图、overlay 与 bindings；SKILL.md 明确要求skill3_adapter: generic，即对所有模型家族统一使用通用适配器，拒绝模型专属 builder；
当修改架构投影或图形渲染时，SKILL.md 要求同时同步阅读已安装的pto-json-architecture-graphSkill 及其架构契约，保持内置图校验器同步（源码中 generate-report.mjs 在生成前会强制检查校验器存在，缺失即报错Missing synchronized architecture validator）；
来源溯源（provenance）中声明涉及cann-perf-breakdown与cann-perf-breakdown-to-ui-json两个上游 Skill。

事实边界原则（Preserve fact boundaries）

这是整个 Skill 的灵魂，SKILL.md 列出七条不可逾越的边界，全部在 validate-report.mjs 中有对应断言：

边界原则校验实现（validate-report.mjs 中的断言示例）

仅通过显式稳定身份（stable identity）拼接 analysis / performance / Timeline / raw Trace / Skill 2 产物断言model_id、report_id在 analysis、performance、timeline 三份后端文件中完全一致；traceBindings.model_id/report_id与报告身份一致

架构图仅以model_architecture_graph.v1的 roots 与 edges 渲染，严禁从层级、源码顺序、kernel 顺序、Timeline 顺序或 Trace Flow 推断边校验器要求每条边 source/target 必须能解析到声明项、必须带 tensor 与 provenance；并检测“数据流环”

性能与 Trace 交互仅对显式映射的后端节点开放，source-only 节点保持无指标、无 Trace 断言 source-only 渲染项无 backendNodeId、无 metricBadge，且保留 sourceRefs 可选中

运行时辅助（runtime auxiliary）游离于源码模型数据流之外图契约要求section/source_architecture与section/runtime_auxiliary两个独立根

保留原始 item/edge ID、元数据、tensor 字段、约束、provenance 与源码引用断言边保留tensor与provenance数组；映射全部能解析到逻辑项且携带 evidence

切换 UI 语言时不得改动源码作者编写的模型标签语言本地化仅作用于标题、按钮等 UI 文案

新报告默认中文，同时尊重已保存的中/英文偏好

断言index.html默认

lang="zh-CN">{ "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" } }

校验规则（validateHandoff源码确认）：schema_version必须为ui_report_handoff.v1；inputs七个键缺一不可；skill3_adapter必须为generic（否则直接拒绝，报错提示需用cann-perf-breakdown-to-ui-json重新生成）；capabilities必须是对象。

七个必需输入

input-files.md定义了七个必需输入，缺任一即生成失败：

Handoff 键	典型产物	权威内容
`inputs.analysis`	`*_analysis_config.json`	后端`node_id`、层级、语义路径、代码引用与观测到的 Layer 实例
`inputs.performance`	`*_perf_data.json`	采集到的节点指标、时序范围、算子数量与占比
`inputs.timeline`	`*_timeline.json`	归一化事件边界、泳道与可选的节点/Layer 归属
`inputs.trace`	`trace_view.json`	原始 Chrome Trace 元数据、duration/counter/flow 事件与物理泳道
`inputs.bindings`	`report/outputs/trace_bindings.json`	归一化事件到原始 Trace 的已评审身份绑定
`inputs.architecture`	`report/outputs/model_architecture_graph.json`	源码层级、重复 Layer 模板、语义边、tensor 元数据与 provenance
`inputs.overlay`	`report/outputs/architecture_overlay_map.json`	后端节点到架构项的已评审分类

可选输入与 HBM 输入目录

optional_inputs缺失时“优雅降级”为空 typed 数据，绝不因缺失而臆造测量、映射或建议：

operator_details（默认report/outputs/operator_details.json）：算子索引、名称、类型、Stream、输入输出 shape 与 dtype；
hbm（默认report/outputs/hbm_series.json）：HBM 带宽、占用量与设备/频率事实；
findings（默认report/outputs/metrics_findings.json）：后端作者撰写的节点级诊断发现；
expert_inventory（默认report/outputs/expert_inventory.json）：声明式 MoE 路由/共享专家清单。

此外生成器会在正常生成时发现式读取上游文件：算子详情依次尝试<repo>/work/raw_ops_details.json、<repo>/../work/raw_ops_details.json；findings 依次尝试<repo>/metrics_findings.json、<repo>/../metrics_findings.json；专家清单匹配第一个<repo>/ui_facts/*_expert_inventory.json或<repo>/../ui_facts/*_expert_inventory.json。

当使用--hbm-dir <aligned-hbm-dir>时，Skill 3 精确读取以下四个文件并归一化为report/outputs/hbm_series.json：

hbm_bandwidth_timeline.csv
hbm_occupancy_timeline.csv
sample_op_mix.csv
hbm_summary.json

注意：AICore 频率目前没有独立的通用输入文件，必须由配置好的 HBM/设备档案产物提供；粗粒度的 HBM 采样不能用于推导逐算子带宽归属。

生成命令与运行时配置

标准生成命令

rtk node <skill-dir>/scripts/generate-report.mjs \ --repo <report-repo> \ --handoff <ui-report-handoff.json> \ --refresh-template

可选输入补充：

rtk node <skill-dir>/scripts/generate-report.mjs \ --repo <report-repo> \ --trace <trace_view.json> \ --hbm-dir <aligned-hbm-dir> \ --refresh-template

CLI 参数语义（generate-report.mjs 源码确认）：

参数	含义	约束
`--repo <report-repo>`	报告仓库根目录（必填，缺失直接抛错）	报告生成到`<repo>/report/`
`--handoff <path>`	显式指定交接清单路径	优先于自动发现
`--trace <trace_view.json>`	替换或创建仓库原始 Trace，事务式	源文件必须是已存在文件；复制到`<repo>/trace_view.json`
`--hbm-dir <dir>`	归一化 HBM 输入目录为`hbm_series.json`	走`build-hbm-data.mjs`子流程
`--refresh-template`	用 Skill 模板整体替换可复用 UI 文件	保留/重新生成模型专属配置与 Skill 2 产物
`--check`	严格只读检查	不可与上述三个写操作参数组合

事务式生成与回滚保障

生成器源码实现了一套完整的“事务”机制：

生成前把既有report/整体改名为report.prev，trace_view.json备份为trace_view.prev.json；
--refresh-template时从模板目录assets/report-template整体拷贝到report/，但保留先前模型专属的report-config.js与outputs/（源码打印PRESERVED model-specific report-config.js）；
新报告必须能发现 handoff，否则抛错A new report requires ui-report-handoff.json or an explicit --handoff <path>；旧报告可保留既有report-config.js并打印normalized legacy report-config.js警告；
任一环节失败：删除不完整的report/，把report.prev恢复为report/，并还原或删除未提交的trace_view.json，实现逐字节回滚；
成功时清理备份目录，并生成report/outputs/validation_manifest.json（schema 为model_skill_validation_manifest.v2，确定性状态passed、人工检查not_run、总状态pending_manual_validation）。

运行时配置 report-config.js

report-config.js是生成的传输配置而非模型模板（源码要求其赋值window.ReportRuntimeConfig）。必需键为 analysis、performance、timeline、trace、bindings、architecture、overlay；可选键默认指向report/outputs/下的 operatorDetails、hbm、findings、expertInventory（当前模板版本CURRENT_TEMPLATE_VERSION = 2）。templateOverrides可声明“经过评审、与 Skill 模板有意不同”的运行时文件，除此之外的未声明模板漂移一律视为校验失败。

只读检查`--check`与生成安全测试

rtk node <skill-dir>/scripts/generate-report.mjs --repo <report-repo> --check

--check是严格只读模式：源码开头即断言其不能与--refresh-template、--trace、--hbm-dir组合；不得创建占位文件、不得重命名index.html、不得重写清单、不得触碰时间戳。但--check依然会完整跑一遍架构图校验、bindings 存在性检查、build-operator-details/build-embedded-data的 check 分支以及四个校验器。

生成器修改者必须运行生成安全回归测试：

rtk node <skill-dir>/scripts/test-generation-safety.mjs --repo <known-good-report-repo>

test-generation-safety.mjs 在临时目录构造 fixture 副本，验证四条硬性保证：

--refresh-template不会改变模型专属后端路径（对比前后report-config.js中的 analysis/performance/timeline 路径）；
--check前后对整个仓库做 sha256 快照比对，确认逐字节只读；
人为注入后--check必须失败（拒绝未声明的index.html模板漂移）；
人为构造生成失败（指向不存在的 trace），失败后report/必须与失败前快照完全一致（完整恢复）。

确定性校验链（四项必备检查）

SKILL.md 规定生成流程必须依次执行以下四条命令：

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 <repo>

1. validate-architecture-graph.mjs：架构图契约校验

validate-architecture-graph.mjs 是独立的图校验器，核心检查项：

schema：必须为model_architecture_graph.v1；roots 非空、edges 为数组；所有 item 必须有稳定唯一 id；children 必须是数组；
重复模板：repeatCount必须为正整数，instanceIndices长度必须与repeatCount一致；
边语义：semanticEdgeType仅允许activation/communication/parameter/state/control/residual；每条边必须有tensor对象与非空provenance数组；tensor.role与semanticEdgeType必须兼容（parameter/state/weight/bias 不允许标成 activation）；
residual 边：必须dashed: true；crossInvocation: true时必须带crossStep或crossSteps声明跨调用语义；
sourceRefs：非 synthetic、非 backend_trace_extension 的 source 作用域 item 必须声明 sourceRefs（缺失即失败）；
colorKey：所有 item 的 colorKey 必须在已知色板内（sem:*、module:*、opv:*系列，例如opv:attention、opv:moe、sem:residual等）；
环检测：默认禁止数据流环（--allow-cycles可放开），环报告会标注涉及的折叠模板；
--require-semantic-port-policy：启用端口策略检查——普通语义边必须自上而下（dy > 0，底→顶端口）；parameter 边且横向位移大于纵向时为“侧输入”；crossInvocation边计入跨调用槽位。

2. validate-report.mjs：报告运行时总校验

validate-report.mjs 是断言最密集的校验器，主要分几大类：

模板哈希校验：对TEMPLATE_VERIFIED_FILES中 20 余个文件（index.html、app.js、architecture-data.js、trace-view.js、hbm-view.js、design-system 的 tokens 与 patterns 等）逐一与 Skill 模板比对 sha256，除非在ReportRuntimeConfig.templateOverrides中显式声明，否则任何不一致（STALE）即失败；
身份一致性：analysis/performance/timeline 的model_id与report_id完全一致；analysis 与 performance 的节点 ID 集合精确相等；overlay 映射覆盖每个后端节点且恰好一个分类，映射目标可解析且携带 evidence；
Timeline 一致性：timeline.event_count与事件数组长度一致；mapping_summary.mapped_events/unmapped_events与按 owner 统计一致；每个非空 owner 都能解析到后端节点；
Trace 绑定：每个归一化事件有且仅有一个绑定；每个绑定解析到一个不同的原始 duration 事件（ph === "X"）；绑定覆盖率为 100%；绑定均解析到后端结构节点；
嵌入数据镜像：report-embedded-data.js中的 analysis/performance/timeline/trace/bindings/operatorDetails/architecture/overlay/hbm/findings 与源 JSON逐字相等，保证file://独立运行；
UI 契约断言：性能热力图使用对数 Turbo 色域（#30123B→#DA3907等六个色标）并带本地化图例；正文可见字号不低于 12px（仅允许 11px 指标公式与 10px Trace 标签例外）；无任何网络运行时依赖（index.html中不得出现src/href指向//的外部资源）；默认中文标题与浏览器标题本地化；无 Evidence 区块与冗余推荐；
HBM/AICore 频率：HBM 序列点必须有限；声明aicoreFrequency能力时必须提供声明值/派生值一致性展示且不得发明时变曲线。

3. test-layer-report-metrics.mjs：重复层作用域指标

test-layer-report-metrics.mjs 针对解码器重复层（排除 mtp/runtime/auxiliary/scaffold 模板）验证：

每个模板必须存在性能记录，且每个观测 layer 索引必须有层作用域的 Timeline 事件；
抽样层（首/中/尾）上：operators指标必须等于该层事件数；kernel_sum_ms必须等于该层事件duration_us之和（容差 0.0011 ms）；图上的 time-share 徽章必须等于kernel_sum_ms / total_time_us（容差 0.0051%）；
层导航：必须有且仅有一个全局层 pager（不允许嵌套 pager）；层索引全局唯一、各模板成员互斥、并集覆盖 0..num_main_layers-1；
层选择投影：选中层只渲染其所属模板；模板间同构算子路径必须保持选中（相对路径精确匹配），不得跳转或清空；
若capabilities.repeatedLayers声明为 true 却无解码器模板，直接失败；能力不适用时输出SKIP并非失败。

4. test-projected-fanout.mjs：分支结构校验

test-projected-fanout.mjs 基于model_architecture_graph.json的 activation 边构建邻接表，从三个阶段验证：

Phase 1：发现 fan-out 模式（一个源多分支）与 fan-in 模式（多源汇聚）；
用可达性分析验证折叠/收起后声明分支仍保持连通；
校验并行行布局与声明的最小图证据（如 handoff 中expectedGraphFeatures.fanOutMin等）不被空测试放行。

能力门控与“诚实降级”

SKILL.md 强调：Layer、expert、HBM、expected-graph-features 断言仅在 handoff 声明对应能力时运行；声明了能力却缺证据是失败，真正不适用的能力应标记为not_applicable，而不是伪造通过。

校验清单与状态语义

生成结束时写入report/outputs/validation_manifest.json（schemamodel_skill_validation_manifest.v2），严格区分确定性检查与人工检查：

状态	含义
`deterministic_status: passed`	所有适用的自动化检查通过
人工检查项（browser_smoke_1440x1000 / file_protocol_smoke / visual_review）	取值`passed`/`failed`/`not_run`
`overall_status: pending_manual_validation`	确定性检查通过但人工检查未完成
`overall_status: passed`	确定性 + 全部必需人工检查通过
`not_applicable`	仅用于能力明确缺席；绝不可替代缺失的应有证据

校验矩阵（validation-matrix.md）的确定性检查覆盖：生成安全、配置、模板、后端身份、架构、绑定、Layer、分支、可选数据、独立运行十个方面；并提示“避免把源码字符串出现当作行为证明”，优先纯适配器测试与 DOM/浏览器集成测试，字符串检查仅保留给静态禁用模式。

浏览器终验（Final browser validation）

确定性检查通过后，在1440 × 1000视口下用规范报告 URL 执行一次冒烟测试；若涉及独立交付，还要执行一次file://冒烟。至少验证：

无 console / 资源加载错误；
架构图、Inspector、Trace 加载的是当前数据；
mapped / source-only / aggregate / runtime 各类选择遵守事实边界；
三个不相邻 Layer 切换时，图徽章、Inspector 指标、Sequence 事件与 Flow 同步更新且算子身份不变；
声明的分支、residual 与 Layer 选择桥保持连通；
热力图图例、本地化文案、tooltip、HBM 缺失态与可选专家投影符合 UI 契约；
空画布选择重置与 Trace 的 focus/zoom/pan 均可用。

只有把浏览器、file 协议与视觉检查结果都记入校验清单后，overall_status才能置为passed。

失败路由（Failure routing）

SKILL.md 按失败类型给出明确的归因与处理方向，且禁止直接修改后端 JSON：

失败类型	处理
身份、节点覆盖、Timeline owner 或 Trace 绑定不匹配	回退为 Skill 1/2 的数据需求，不打补丁到后端 JSON
缺边/tensor/provenance、重复成员非法、fan-out/fan-in/residual 不足	回退为 Skill 2 的图需求
Source lock 不匹配	停止并重新提取/评审架构，绝不盲目更新哈希
布局、样式、本地化、交互、选择或运行时传输问题	修 Skill 3 模板并重新生成
无法解析的事实	保持“不可用”呈现；严禁仅凭叶子标签相似就强行映射以提高覆盖率

该路由机制在生成器源码中有自动化支撑：generate-report.mjs 内置UPSTREAM_DIAGNOSTIC错误模式映射表，例如tensor.name is required→ Skill 2 的build_architecture_graph.py（补边上的 tensor 名/形状/dtype）、dataflow cycle detected→ Skill 1（analysis_config_v2）或 Skill 2（检查 children/branches 串行顺序）、repeatCount must be/instanceIndices length→ Skill 2 的build_node_index.py、residual edge but dashed is not true→ Skill 2 标记dashed=true等。子校验器退出码非零时，生成器自动打印“Upstream Skill Diagnostic”帮助定位上游归属。

模板同步与 override 机制

报告的可复用 UI 文件（index.html、app.js、design-system 等）必须与 Skill 模板哈希一致，这是validate-report.mjs的硬性检查；只有两类例外：

--refresh-template：整体重新同步模板，同时保留模型专属的report-config.js与outputs/；
经过评审的逐报告偏差：通过ReportRuntimeConfig.templateOverrides（或 handoff 的template_overrides）显式声明，校验器对声明文件打印OVERRIDE警告而非STALE失败。

这一机制保证了“可复用的视觉与交互行为在 Skill 内集中演进、先改模板再同步”，避免各模型报告之间出现无节制的 UI 分叉。

结语

cann-perf-ui-json-report是 CANN oam-tools 性能分析流水线的“最后一公里”：它把 Skill 1/2 沉淀的后端事实，以严格的事实边界、事务式生成、确定性校验与人工冒烟验证，交付为可直接在浏览器与file://环境下运行的中英文交互式性能报告。其工程价值不只在于“能出图”，更在于一整套可回归、可归因、防漂移的质量护栏——--check的逐字节只读保证、失败时的完整回滚、模板哈希锁定、层作用域指标的数值级验证，以及按错误模式自动路由到上游 Skill 的诊断机制。对于希望在 oam-tools 生态内构建或扩展此类报告能力的开发者，建议从本文引用的四份契约文档与各校验脚本入手，先理解“事实从哪来、边界在哪里”，再动手修改呈现层。

如需进一步深入，可继续阅读：数据契约、输入文件清单、UI 契约、校验矩阵，以及上游衔接 Skill cann-perf-breakdown-to-ui-json。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

标签：网站建设企业官网项目流程 UI设计前端开发

需要专业的网站建设服务？

联系我们获取免费的网站建设咨询和方案报价，让我们帮助您实现业务目标

立即咨询

企业官网建设流程全解析