PyPTO 算子性能分析报告模板深度解读从数据采集到瓶颈定位的完整实战指南【免费下载链接】pypto-gymPyPTO-Gym 是基于 PyPTO 编程框架构建的算子与模型样例仓库项目地址: https://gitcode.com/cann/pypto-gym导读本文围绕 CANN pypto-gym 仓库中 PyPTO 算子性能分析报告模板 展开系统讲解 PyPTO 算子性能分析报告从数据采集、指标计算、性能评级到瓶颈定位与调优方向建议的完整方法论。读完本文你将掌握如何借助 perf-analyzer 技能与analyze_perf.py脚本自动生成性能分析报告理解 AIC/AIV 核心利用率、气泡率、负载均衡度等核心指标的计算口径并能够依据报告中的评级标准与调优方向建议驱动开箱调优、深度调优与核内调优三个阶段的迭代流程。1. 模板定位性能分析报告在 PyPTO 调优流程中的位置PyPTOPyTorch 风格算子编程框架算子在昇腾 NPU 上运行时其性能特征由核上计算AICore、数据搬运MTE、任务调度等多层因素共同决定。为了把性能不好这种模糊感受转化为可量化、可对比、可驱动决策的工程数据pypto-op-perf-tune技能家族定义了完整的调优流水线而性能分析报告正是其中连接数据采集与分阶段调优的关键枢纽S2_COLLECT性能数据采集在算子 JIT 装饰器中添加debug_options{runtime_debug_mode: 1}后重新运行算子产出泳道图、气泡分析、性能追踪三类数据文件S3_ANALYZE性能数据分析加载 perf-analyzer 技能从性能数据中提取关键指标、计算性能评级、识别性能瓶颈并生成performance_analysis_report.mdS4_TUNE分步骤调优基于报告中的瓶颈分析与优化建议依次进入开箱调优tune-frontend、深度调优tune-swimlane、核内调优tune-incore三个阶段S5_REPORT生成调优报告最终以阶段交接摘要为骨架整合 perf-analyzer 报告的性能数据与最终状态看板形成完整调优报告。因此这份性能分析报告模板不仅是 perf-analyzer 子技能的产物也是整个 pypto-op-perf-tune 主技能 状态机中 S3_ANALYZE 阶段的交付物标准。它定义了报告应包含的 9 个核心章节确保每一份报告都覆盖指标—统计—评级—瓶颈—建议—数据位置这一完整闭环。2. 报告的两种生成方式2.1 脚本自动生成推荐analyze_perf.py 是仓库提供的一键生成脚本它从bubble_analysis.log中解析核心指标、计算统计量、评级与瓶颈并自动在 output 目录下写出performance_analysis_report.md。其核心调用链为main() → _require_output_dir / _require_bubble_log定位数据 → parse_bubble_analysis正则解析每个核心的任务数/工作时间/等待时间 → calculate_performance_metrics计算利用率、气泡率、负载均衡度等 → analyze_bottlenecks识别利用率/气泡/负载/前驱等待四类瓶颈 → generate_optimization_suggestions按优先级生成优化建议 → generate_report按模板拼装 9 节报告并落盘使用方法# 传入 output 目录路径包含 bubble_analysis.log 的具体时间戳目录 python3 cannbot-skills/ops/pypto-op-perf-tune/perf-analyzer/scripts/analyze_perf.py output_dir # 示例在算子目录下执行时的 output 位置 python3 scripts/analyze_perf.py custom/operator_name/output/output_20260304_171658_543682_529508脚本对输入做了充分的容错设计见 analyze_perf.pyoutput_dir 定位优先查找output_dir/bubble_analysis.log找不到时自动递归搜索子目录中的output_*/bubble_analysis.log错误提示目录不存在或日志缺失时会给出output 目录相对执行算子命令时的工作目录的提示并建议用find . -name bubble_analysis.log快速定位。2.2 手动填充当需要人工撰写或补充报告细节时直接以 performance_report_template.md 为骨架将花括号占位符如{max_work_time}、{avg_core_utilization}替换为实测数值即可。模板明确要求报告必须覆盖 6 项核心内容核心性能指标、性能指标统计、性能评级、性能瓶颈分析、性能优化建议、性能数据文件位置另含调优方向、调优记录与总结章节。3. 核心性能指标读懂 AIC / AIV 核心表报告第 1 节核心性能指标是全篇的数据地基。它由两部分组成3.1 算子实际执行时间**{max_work_time} us**这一数值是所有核心中Core Total Work Time的最大值对应运行 stdoutAICORE Prof Summary中的AICore End-to-End Time。注意这是性能调优的核心判据而非 wall time——wall time 包含 host 下发开销AICPU task 调度、gather 等不能反映核上真实计算效率。主技能中明确声明调优全程「执行时间」与「AICore E2E Time」为同一指标禁止用 wall time 作为调优判据。3.2 AIC 与 AIV 核心性能指标表模板为 AICAI Cube 核心承担 Matmul 等矩阵运算和 AIVAI Vector 核心承担逐元素/归约类计算分别提供一张指标表核心任务数总工作时间(us)总等待时间(us)等待调度时间(us)等待前驱时间(us)AicoreTime(us)核心利用率(%)气泡率(%)AIC_0{task_num}{total_work_time}{total_wait_time}{wait_schedule_time}{wait_predecessor_time}{aicore_time}{core_utilization}{bubble_rate}各列的数据来源与含义可对照 analyze_perf.py 中的 CoreMetrics 数据类 理解任务数task_num该核心上被调度执行的任务个数总工作时间total_work_time核心从开始到结束的完整 span包含实际计算与等待总等待时间total_wait_time等待调度与等待前驱的合计等待调度时间wait_schedule_time任务排队等待被调度的时间即气泡的直接来源等待前驱时间wait_predecessor_time因上游任务未完成而产生的依赖等待AicoreTime核心实际工作时间AicoreTime 总工作时间 - 总等待时间这是衡量单核心真实计算量的指标核心利用率AicoreTime / (AicoreTime 等待总时间) × 100%气泡率等待调度时间 / (AicoreTime 等待调度时间) × 100%。从源码看parse_bubble_analysis通过正则\[(AIC_\d|AIV_\d)\] Execute task num:(\d)\sCore Total Work Time:...逐行解析bubble_analysis.log将每个核心的六项原始数据还原为CoreMetrics对象再由属性计算派生指标。脚本还对所有可能的除零场景做了保护时间为 0 时返回 0保证任意数据下脚本都能正常产出报告。4. 性能指标统计平均值与负载均衡报告第 2 节汇总全局统计量为后续评级提供输入指标数值平均核心利用率{avg_core_utilization}%平均气泡率{avg_bubble_rate}%AIC 平均核心利用率{avg_aic_utilization}%AIV 平均核心利用率{avg_aiv_utilization}%AIC 平均气泡率{avg_aic_bubble_rate}%AIV 平均气泡率{avg_aiv_bubble_rate}%核心负载均衡度{load_balance}%平均核心利用率 / 平均气泡率所有核心对应指标的算术平均_average函数实现空列表返回 0AIC / AIV 分项统计按核心名前缀AIC/AIV分组后分别求平均便于区分 Cube 侧与 Vector 侧的差异核心负载均衡度由 AIC 核心实际工作时间的标准差计算公式为(1 - 标准差 / 均值) × 100%越接近 100% 说明各 AIC 核心工作时间越均衡。当 AIC 核心数 ≤ 1 时直接返回 100。负载均衡度之所以重要是因为算子的执行时间取决于最慢的核心——只要有一个核心拖尾整体 AICore E2E Time 就会被拉长。因此负载不均衡通常与核心利用率低相伴出现是深度调优tune-swimlane阶段的首要排查对象。5. 性能评级星级标准与综合评级报告第 3 节将量化指标转化为直观的星级评价便于快速判断算子处于优秀/良好/一般/较差/很差的哪个档位。5.1 单项评级表指标当前值目标值(⭐⭐⭐⭐⭐)评级描述核心利用率{avg_core_utilization}%90%{util_rating}{util_desc}气泡率{avg_bubble_rate}%2%{bubble_rating}{bubble_desc}负载均衡度{load_balance}%90%{balance_rating}{balance_desc}5.2 评级标准表模板给出了三项指标共用的星级阈值核心利用率、气泡率、负载均衡度均为同表口径评分核心利用率气泡率负载均衡度⭐⭐⭐⭐⭐90%2%90%⭐⭐⭐⭐80%5%80%⭐⭐⭐60%10%60%⭐⭐50%20%50%⭐50%20%50%在脚本实现中评级逻辑封装在get_rating/_higher_is_better_rating/_lower_is_better_rating核心利用率与负载均衡度是越高越好阈值 90/80/60/50气泡率是越低越好阈值 2/5/10/20描述分别为优秀/良好/一般/较差/很差。5.3 综合评级**{overall_rating} ({overall_desc})**综合评级由三项单项描述映射为分数后取平均得到优秀5、良好4、一般3、较差2、很差1平均分 ≥4.5 为 ⭐⭐⭐⭐⭐≥3.5 为 ⭐⭐⭐⭐≥2.5 为 ⭐⭐⭐≥1.5 为 ⭐⭐否则为 ⭐见_overall_rating。综合评级是报告结尾当前状态部分的直接引用项也决定了调优是否继续推进。6. 性能瓶颈分析从症状到根因报告第 4 节基于第 2 节的统计量自动推导瓶颈。脚本的analyze_bottlenecks依次检查四类候选瓶颈类型触发阈值严重程度典型建议核心利用率低平均利用率 50%高调整 Tilesize 增大算术强度或使用 L2 亲和调度核心利用率偏低平均利用率 70%中检查任务调度策略优化内存访问气泡率过高平均气泡率 20%高增大任务粒度使用 loop_unroll 优化气泡率偏高平均气泡率 10%中优化调度策略使用 L1Reuse 优化核心负载不均衡负载均衡度 60%高调整任务分配策略优化 tile size核心负载略有不均负载均衡度 80%中检查任务分配是否均匀等待前驱时间过长AIC 最大等待前驱 500us中减少任务依赖使用 sg_set_scope 合并子图6.1 瓶颈条目结构模板中每个瓶颈按统一结构描述便于报告阅读者快速评估优先级#### 瓶颈 1: {瓶颈名称} - **严重程度**: {高/中/低} - **描述**: {详细描述} - **影响**: {对性能的影响程度}6.2 瓶颈分析图示模板用 ASCII 条形图直观展示三项核心指标与目标值的差距例如性能瓶颈分析 ┌──────────────────────────────────────────┐ │ 核心利用率: {avg_core_utilization}% │ │ ████████████████████░░░░░░░░░░░░░░░░░░░░ │ │ 目标: 90% │ ├──────────────────────────────────────────┤ │ 气泡率: {avg_bubble_rate}% │ │ ░░░░░░░░░░░░░░░░░░░░████████████████████ │ │ 目标: 2% │ ├──────────────────────────────────────────┤ │ 负载均衡度: {load_balance}% │ │ ████████████████████████████░░░░░░░░░░░░ │ │ 目标: 90% │ └──────────────────────────────────────────┘实心块占比直观反映当前值与目标的差距利用率与负载均衡度实心块越长越好气泡率则相反。当脚本检测不到任何瓶颈时第 4 节输出未发现明显的性能瓶颈性能表现良好。6.3 瓶颈与优化点编号的对应关系模板第 4 节负责定位问题而具体解法由 optimization_catalog.md 的按症状索引章节承接——这是调优流程中连接分析与行动的关键索引表例如气泡率 10%症状 A可尝试 F-2 循环体计算量、F-8 内层 unroll、S-9 Stitch 调优stitch_function_max_num: 128、S-14 A5 Mix 合图、S-20 max_workspace_kb 等核心利用率 50%症状 B可尝试 F-1 任务粒度检查、F-9 Cube TileShape、S-2 核填充、S-20 max_workspace_kb 等负载不均衡症状 CAicoreTime 差异 20%可尝试 S-3 负载均衡分析、S-11/S-12 TileShape 深度调优、S-4 手动合图单 task 耗时过长症状 D可尝试 I-1 小 Shape 矩阵乘、I-10 合并 gather、I-11 view 复用等核内优化。7. 性能优化建议按优先级分层执行报告第 5 节将瓶颈分析结果转化为可执行清单并按高→中→低三级优先级组织模板还特别强调优化纪律优先使用高优先级建议、每次只修改一个优化点、修改后立即测试性能、精度失败或性能回退时回退修改。脚本的generate_optimization_suggestions依据瓶颈严重程度自动归类并附带可直接复制的代码示例例如核心利用率 50% 时的高优先级建议使用 L2 亲和调度pypto.frontend.jit(runtime_options{device_sched_mode: 1})调整 Cube Tilesizepypto.set_cube_tile_shapes([128, 128], [128, 512], [128, 128])气泡率 10% 时的高/中优先级建议使用 loop_unrollpypto.loop_unroll(A.shape[0] // 64, unroll_list[64, 16, 4], ...)使用 L1Reusepypto.set_pass_options(cube_l1_reuse_setting{0: 8})负载均衡度 80% 时的中优先级建议调整 vec tile 使任务分配更均匀。这些建议与 optimization_catalog.md 中的 F/S/I 系列优化点编号一一对应且均可在后续阶段的子技能 SKILL 文档中找到完整的操作指南与约束条件。例如 Stitch 调优对应 S-9配置示例为runtime_options{stitch_function_max_num: 128}参数过小如 1时每个任务需同步、调度开销大过大如 512时调度耗时与 workspace 增加而 TileShape 配置则需参考 npu-memory-arch.md 中的硬件约束——例如 950PRDAV_3510上 L0C 为 256KB、单 AIV 可用 UB 为 248KB这是设置 tile 并发占用与判断 spill 的硬边界。8. 调优方向建议三大阶段的衔接入口报告第 6 节是连接分析与调优的桥梁它根据当前指标动态给出后续行动建议并明确指向对应的子技能8.1 开箱性能调优tune-frontend是否需要核心利用率 50% 或气泡率 20% 时为是调优重点Loop 写法优化、TileShape 设置优化、数据操作优化详细指南加载 tune-frontend 技能。开箱调优关注代码级差异例如静态轴应使用 Python for 而非pypto.loop但 n_kv/group 等参与 offset 计算的语义维度循环须保留外层动态轴范围大时应切块、内层动态轴范围大时应 loop_unroll以及 Reshape 全局优化原始输入 reshape 外提 inplaceTrue等 F 系列优化点。8.2 深度性能调优tune-swimlane是否需要气泡率 10% 或负载均衡度 80% 时为是调优重点Stitch 调优、TileShape 深度调优、合图调优、调度策略调优详细指南加载 tune-swimlane 技能。深度调优以泳道图分析为核心典型手段包括stitch_function_max_num调整、device_sched_mode值域 [0,3]调度策略、sg_set_scope手动合图、以及 A5 平台npuarch DAV_3510专属的 Mix 合图S-14与 VF 融合S-16~S-18。注意 Mix 合图存在严格的硬性限制CV 间数据传递须 1:N 或 N:1、shape 变化单调、UB 并发 248KB 等配置前必须先完成数据流分析。8.3 核内性能调优tune-incore是否需要核心利用率 ≥ 70% 且气泡率 10% 时为可能需要否则待前两阶段完成后评估调优重点特殊 Shape 处理、冗余计算优化、尾轴优化、Operation 实现检查详细指南加载 tune-incore 技能。核内调优面向单 task 指令级优化如小 Shape 矩阵乘的 Vector 预处理典型案例从 500us 优化到 40us、L2 Cache 策略tensor.set_cache_policy(pypto.CachePolicy.NONE_CACHEABLE, True)、submit_before_loopTrue计算搬运重叠、valid_shape尾块零填充避免以及 DDR 往返优化I-10 合并 gather、I-11 view 复用。9. 性能数据文件位置与可视化报告第 7 节记录了本次分析的原始数据出处保证报告可追溯、可复现文件类型路径泳道图{output_dir}/merged_swimlane.json气泡分析{output_dir}/bubble_analysis.log性能追踪{output_dir}/machine_runtime_operator_trace.json本报告{output_dir}/performance_analysis_report.md这些文件位于执行算子命令时工作目录下的output/output_时间戳/中在算子目录下执行则为算子目录/output/output_*/在项目根目录执行则为./output/output_*/。其中merged_swimlane.json泳道图数据展示各核心任务的执行顺序、耗时、气泡与依赖关系可通过 PyPTO Toolkit 插件或官方 Perfetto 在线工具上传可视化分析bubble_analysis.log气泡分析报告是analyze_perf.py的数据源machine_runtime_operator_trace.json运行时算子级性能追踪。泳道图是深度调优阶段的核心工具——tune-swimlane 技能 强调每次进入该阶段必须重新采集最新数据禁止复用旧轮次的泳道图代码修改后性能特征已变旧数据会导致错误结论。10. 调优记录与总结让迭代有据可依10.1 调优记录表报告第 8 节以轮次为单位记录每次优化的前后对比是迭代式调优的过程证据轮次优化内容修改前执行时间(us)修改后执行时间(us)提升比例精度结果1{优化内容}{time}{time}{percent}%{通过/失败}该表与主技能的迭代纪律强绑定每次修改一个参数 → 立即验证精度输出必须含 passed/success→ 采集性能对比 → 记录结果 → 判断是否继续。精度失败或性能回退的尝试必须记录避免重试这正是 optimization_catalog.md 中已失败优化避免重试表的设计初衷。10.2 总结章节报告第 9 节收束全文给出三要素当前状态性能评级引用第 3 节综合评级、主要瓶颈列表、推荐的调优方向下一步行动按调优方向建议的顺序执行、每次优化后验证精度并记录、达到性能目标后生成最终报告报告元信息报告生成时间与 PyPTO 版本模板末尾保证不同轮次报告之间的可比性。11. 报告在真实调优流程中的使用建议结合 pypto-op-perf-tune 主技能 的状态机性能分析报告在每个调优轮次中承担三种角色基线锚点调优开始前必须记录基准性能AICore End-to-End Time、核心利用率、气泡率、负载均衡度此后每次优化都与基线对比判断优化方向是否正确——特别强调以 AICore E2E Time 下降为准若 AICore E2E Time 上升而 wall time 下降说明开销被从 host 转移到了核上应回退症状索引报告中的瓶颈类型直接映射到 optimization_catalog 的症状 A/B/C/D可快速锁定 F/S/I 系列优化点编号再加载对应子技能获取操作指南迭代记录每轮优化结果写入第 8 节调优记录表最终整合进{op_name}_tuning_report.md形成从性能数据 → 性能分析 → 调优决策 → 效果验证的完整证据链。结语PyPTO 算子性能分析报告模板将昇腾 NPU 上晦涩的硬件行为核间气泡、调度等待、负载倾斜转化为结构化的九节报告核心指标给出事实、统计与评级给出判断、瓶颈与建议给出方向、数据位置与调优记录给出可追溯性。配合 perf-analyzer 技能与analyze_perf.py脚本它可以被无缝嵌入到 pypto-op-perf-tune 的自动化调优流程中成为驱动开箱调优、深度调优与核内调优迭代闭环的可靠数据基础。无论你是手工分析还是脚本自动生成遵循本模板的结构与指标口径就能产出一份决策友好、可复现、可对比的高质量性能分析报告。【免费下载链接】pypto-gymPyPTO-Gym 是基于 PyPTO 编程框架构建的算子与模型样例仓库项目地址: https://gitcode.com/cann/pypto-gym创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 PyPTO 算子性能分析报告模板深度解读：从数据采集到瓶颈定位的完整实战指南
PyPTO 算子性能分析报告模板深度解读从数据采集到瓶颈定位的完整实战指南【免费下载链接】pypto-gymPyPTO-Gym 是基于 PyPTO 编程框架构建的算子与模型样例仓库项目地址: https://gitcode.com/cann/pypto-gym导读本文围绕 CANN pypto-gym 仓库中 PyPTO 算子性能分析报告模板 展开系统讲解 PyPTO 算子性能分析报告从数据采集、指标计算、性能评级到瓶颈定位与调优方向建议的完整方法论。读完本文你将掌握如何借助 perf-analyzer 技能与analyze_perf.py脚本自动生成性能分析报告理解 AIC/AIV 核心利用率、气泡率、负载均衡度等核心指标的计算口径并能够依据报告中的评级标准与调优方向建议驱动开箱调优、深度调优与核内调优三个阶段的迭代流程。1. 模板定位性能分析报告在 PyPTO 调优流程中的位置PyPTOPyTorch 风格算子编程框架算子在昇腾 NPU 上运行时其性能特征由核上计算AICore、数据搬运MTE、任务调度等多层因素共同决定。为了把性能不好这种模糊感受转化为可量化、可对比、可驱动决策的工程数据pypto-op-perf-tune技能家族定义了完整的调优流水线而性能分析报告正是其中连接数据采集与分阶段调优的关键枢纽S2_COLLECT性能数据采集在算子 JIT 装饰器中添加debug_options{runtime_debug_mode: 1}后重新运行算子产出泳道图、气泡分析、性能追踪三类数据文件S3_ANALYZE性能数据分析加载 perf-analyzer 技能从性能数据中提取关键指标、计算性能评级、识别性能瓶颈并生成performance_analysis_report.mdS4_TUNE分步骤调优基于报告中的瓶颈分析与优化建议依次进入开箱调优tune-frontend、深度调优tune-swimlane、核内调优tune-incore三个阶段S5_REPORT生成调优报告最终以阶段交接摘要为骨架整合 perf-analyzer 报告的性能数据与最终状态看板形成完整调优报告。因此这份性能分析报告模板不仅是 perf-analyzer 子技能的产物也是整个 pypto-op-perf-tune 主技能 状态机中 S3_ANALYZE 阶段的交付物标准。它定义了报告应包含的 9 个核心章节确保每一份报告都覆盖指标—统计—评级—瓶颈—建议—数据位置这一完整闭环。2. 报告的两种生成方式2.1 脚本自动生成推荐analyze_perf.py 是仓库提供的一键生成脚本它从bubble_analysis.log中解析核心指标、计算统计量、评级与瓶颈并自动在 output 目录下写出performance_analysis_report.md。其核心调用链为main() → _require_output_dir / _require_bubble_log定位数据 → parse_bubble_analysis正则解析每个核心的任务数/工作时间/等待时间 → calculate_performance_metrics计算利用率、气泡率、负载均衡度等 → analyze_bottlenecks识别利用率/气泡/负载/前驱等待四类瓶颈 → generate_optimization_suggestions按优先级生成优化建议 → generate_report按模板拼装 9 节报告并落盘使用方法# 传入 output 目录路径包含 bubble_analysis.log 的具体时间戳目录 python3 cannbot-skills/ops/pypto-op-perf-tune/perf-analyzer/scripts/analyze_perf.py output_dir # 示例在算子目录下执行时的 output 位置 python3 scripts/analyze_perf.py custom/operator_name/output/output_20260304_171658_543682_529508脚本对输入做了充分的容错设计见 analyze_perf.pyoutput_dir 定位优先查找output_dir/bubble_analysis.log找不到时自动递归搜索子目录中的output_*/bubble_analysis.log错误提示目录不存在或日志缺失时会给出output 目录相对执行算子命令时的工作目录的提示并建议用find . -name bubble_analysis.log快速定位。2.2 手动填充当需要人工撰写或补充报告细节时直接以 performance_report_template.md 为骨架将花括号占位符如{max_work_time}、{avg_core_utilization}替换为实测数值即可。模板明确要求报告必须覆盖 6 项核心内容核心性能指标、性能指标统计、性能评级、性能瓶颈分析、性能优化建议、性能数据文件位置另含调优方向、调优记录与总结章节。3. 核心性能指标读懂 AIC / AIV 核心表报告第 1 节核心性能指标是全篇的数据地基。它由两部分组成3.1 算子实际执行时间**{max_work_time} us**这一数值是所有核心中Core Total Work Time的最大值对应运行 stdoutAICORE Prof Summary中的AICore End-to-End Time。注意这是性能调优的核心判据而非 wall time——wall time 包含 host 下发开销AICPU task 调度、gather 等不能反映核上真实计算效率。主技能中明确声明调优全程「执行时间」与「AICore E2E Time」为同一指标禁止用 wall time 作为调优判据。3.2 AIC 与 AIV 核心性能指标表模板为 AICAI Cube 核心承担 Matmul 等矩阵运算和 AIVAI Vector 核心承担逐元素/归约类计算分别提供一张指标表核心任务数总工作时间(us)总等待时间(us)等待调度时间(us)等待前驱时间(us)AicoreTime(us)核心利用率(%)气泡率(%)AIC_0{task_num}{total_work_time}{total_wait_time}{wait_schedule_time}{wait_predecessor_time}{aicore_time}{core_utilization}{bubble_rate}各列的数据来源与含义可对照 analyze_perf.py 中的 CoreMetrics 数据类 理解任务数task_num该核心上被调度执行的任务个数总工作时间total_work_time核心从开始到结束的完整 span包含实际计算与等待总等待时间total_wait_time等待调度与等待前驱的合计等待调度时间wait_schedule_time任务排队等待被调度的时间即气泡的直接来源等待前驱时间wait_predecessor_time因上游任务未完成而产生的依赖等待AicoreTime核心实际工作时间AicoreTime 总工作时间 - 总等待时间这是衡量单核心真实计算量的指标核心利用率AicoreTime / (AicoreTime 等待总时间) × 100%气泡率等待调度时间 / (AicoreTime 等待调度时间) × 100%。从源码看parse_bubble_analysis通过正则\[(AIC_\d|AIV_\d)\] Execute task num:(\d)\sCore Total Work Time:...逐行解析bubble_analysis.log将每个核心的六项原始数据还原为CoreMetrics对象再由属性计算派生指标。脚本还对所有可能的除零场景做了保护时间为 0 时返回 0保证任意数据下脚本都能正常产出报告。4. 性能指标统计平均值与负载均衡报告第 2 节汇总全局统计量为后续评级提供输入指标数值平均核心利用率{avg_core_utilization}%平均气泡率{avg_bubble_rate}%AIC 平均核心利用率{avg_aic_utilization}%AIV 平均核心利用率{avg_aiv_utilization}%AIC 平均气泡率{avg_aic_bubble_rate}%AIV 平均气泡率{avg_aiv_bubble_rate}%核心负载均衡度{load_balance}%平均核心利用率 / 平均气泡率所有核心对应指标的算术平均_average函数实现空列表返回 0AIC / AIV 分项统计按核心名前缀AIC/AIV分组后分别求平均便于区分 Cube 侧与 Vector 侧的差异核心负载均衡度由 AIC 核心实际工作时间的标准差计算公式为(1 - 标准差 / 均值) × 100%越接近 100% 说明各 AIC 核心工作时间越均衡。当 AIC 核心数 ≤ 1 时直接返回 100。负载均衡度之所以重要是因为算子的执行时间取决于最慢的核心——只要有一个核心拖尾整体 AICore E2E Time 就会被拉长。因此负载不均衡通常与核心利用率低相伴出现是深度调优tune-swimlane阶段的首要排查对象。5. 性能评级星级标准与综合评级报告第 3 节将量化指标转化为直观的星级评价便于快速判断算子处于优秀/良好/一般/较差/很差的哪个档位。5.1 单项评级表指标当前值目标值(⭐⭐⭐⭐⭐)评级描述核心利用率{avg_core_utilization}%90%{util_rating}{util_desc}气泡率{avg_bubble_rate}%2%{bubble_rating}{bubble_desc}负载均衡度{load_balance}%90%{balance_rating}{balance_desc}5.2 评级标准表模板给出了三项指标共用的星级阈值核心利用率、气泡率、负载均衡度均为同表口径评分核心利用率气泡率负载均衡度⭐⭐⭐⭐⭐90%2%90%⭐⭐⭐⭐80%5%80%⭐⭐⭐60%10%60%⭐⭐50%20%50%⭐50%20%50%在脚本实现中评级逻辑封装在get_rating/_higher_is_better_rating/_lower_is_better_rating核心利用率与负载均衡度是越高越好阈值 90/80/60/50气泡率是越低越好阈值 2/5/10/20描述分别为优秀/良好/一般/较差/很差。5.3 综合评级**{overall_rating} ({overall_desc})**综合评级由三项单项描述映射为分数后取平均得到优秀5、良好4、一般3、较差2、很差1平均分 ≥4.5 为 ⭐⭐⭐⭐⭐≥3.5 为 ⭐⭐⭐⭐≥2.5 为 ⭐⭐⭐≥1.5 为 ⭐⭐否则为 ⭐见_overall_rating。综合评级是报告结尾当前状态部分的直接引用项也决定了调优是否继续推进。6. 性能瓶颈分析从症状到根因报告第 4 节基于第 2 节的统计量自动推导瓶颈。脚本的analyze_bottlenecks依次检查四类候选瓶颈类型触发阈值严重程度典型建议核心利用率低平均利用率 50%高调整 Tilesize 增大算术强度或使用 L2 亲和调度核心利用率偏低平均利用率 70%中检查任务调度策略优化内存访问气泡率过高平均气泡率 20%高增大任务粒度使用 loop_unroll 优化气泡率偏高平均气泡率 10%中优化调度策略使用 L1Reuse 优化核心负载不均衡负载均衡度 60%高调整任务分配策略优化 tile size核心负载略有不均负载均衡度 80%中检查任务分配是否均匀等待前驱时间过长AIC 最大等待前驱 500us中减少任务依赖使用 sg_set_scope 合并子图6.1 瓶颈条目结构模板中每个瓶颈按统一结构描述便于报告阅读者快速评估优先级#### 瓶颈 1: {瓶颈名称} - **严重程度**: {高/中/低} - **描述**: {详细描述} - **影响**: {对性能的影响程度}6.2 瓶颈分析图示模板用 ASCII 条形图直观展示三项核心指标与目标值的差距例如性能瓶颈分析 ┌──────────────────────────────────────────┐ │ 核心利用率: {avg_core_utilization}% │ │ ████████████████████░░░░░░░░░░░░░░░░░░░░ │ │ 目标: 90% │ ├──────────────────────────────────────────┤ │ 气泡率: {avg_bubble_rate}% │ │ ░░░░░░░░░░░░░░░░░░░░████████████████████ │ │ 目标: 2% │ ├──────────────────────────────────────────┤ │ 负载均衡度: {load_balance}% │ │ ████████████████████████████░░░░░░░░░░░░ │ │ 目标: 90% │ └──────────────────────────────────────────┘实心块占比直观反映当前值与目标的差距利用率与负载均衡度实心块越长越好气泡率则相反。当脚本检测不到任何瓶颈时第 4 节输出未发现明显的性能瓶颈性能表现良好。6.3 瓶颈与优化点编号的对应关系模板第 4 节负责定位问题而具体解法由 optimization_catalog.md 的按症状索引章节承接——这是调优流程中连接分析与行动的关键索引表例如气泡率 10%症状 A可尝试 F-2 循环体计算量、F-8 内层 unroll、S-9 Stitch 调优stitch_function_max_num: 128、S-14 A5 Mix 合图、S-20 max_workspace_kb 等核心利用率 50%症状 B可尝试 F-1 任务粒度检查、F-9 Cube TileShape、S-2 核填充、S-20 max_workspace_kb 等负载不均衡症状 CAicoreTime 差异 20%可尝试 S-3 负载均衡分析、S-11/S-12 TileShape 深度调优、S-4 手动合图单 task 耗时过长症状 D可尝试 I-1 小 Shape 矩阵乘、I-10 合并 gather、I-11 view 复用等核内优化。7. 性能优化建议按优先级分层执行报告第 5 节将瓶颈分析结果转化为可执行清单并按高→中→低三级优先级组织模板还特别强调优化纪律优先使用高优先级建议、每次只修改一个优化点、修改后立即测试性能、精度失败或性能回退时回退修改。脚本的generate_optimization_suggestions依据瓶颈严重程度自动归类并附带可直接复制的代码示例例如核心利用率 50% 时的高优先级建议使用 L2 亲和调度pypto.frontend.jit(runtime_options{device_sched_mode: 1})调整 Cube Tilesizepypto.set_cube_tile_shapes([128, 128], [128, 512], [128, 128])气泡率 10% 时的高/中优先级建议使用 loop_unrollpypto.loop_unroll(A.shape[0] // 64, unroll_list[64, 16, 4], ...)使用 L1Reusepypto.set_pass_options(cube_l1_reuse_setting{0: 8})负载均衡度 80% 时的中优先级建议调整 vec tile 使任务分配更均匀。这些建议与 optimization_catalog.md 中的 F/S/I 系列优化点编号一一对应且均可在后续阶段的子技能 SKILL 文档中找到完整的操作指南与约束条件。例如 Stitch 调优对应 S-9配置示例为runtime_options{stitch_function_max_num: 128}参数过小如 1时每个任务需同步、调度开销大过大如 512时调度耗时与 workspace 增加而 TileShape 配置则需参考 npu-memory-arch.md 中的硬件约束——例如 950PRDAV_3510上 L0C 为 256KB、单 AIV 可用 UB 为 248KB这是设置 tile 并发占用与判断 spill 的硬边界。8. 调优方向建议三大阶段的衔接入口报告第 6 节是连接分析与调优的桥梁它根据当前指标动态给出后续行动建议并明确指向对应的子技能8.1 开箱性能调优tune-frontend是否需要核心利用率 50% 或气泡率 20% 时为是调优重点Loop 写法优化、TileShape 设置优化、数据操作优化详细指南加载 tune-frontend 技能。开箱调优关注代码级差异例如静态轴应使用 Python for 而非pypto.loop但 n_kv/group 等参与 offset 计算的语义维度循环须保留外层动态轴范围大时应切块、内层动态轴范围大时应 loop_unroll以及 Reshape 全局优化原始输入 reshape 外提 inplaceTrue等 F 系列优化点。8.2 深度性能调优tune-swimlane是否需要气泡率 10% 或负载均衡度 80% 时为是调优重点Stitch 调优、TileShape 深度调优、合图调优、调度策略调优详细指南加载 tune-swimlane 技能。深度调优以泳道图分析为核心典型手段包括stitch_function_max_num调整、device_sched_mode值域 [0,3]调度策略、sg_set_scope手动合图、以及 A5 平台npuarch DAV_3510专属的 Mix 合图S-14与 VF 融合S-16~S-18。注意 Mix 合图存在严格的硬性限制CV 间数据传递须 1:N 或 N:1、shape 变化单调、UB 并发 248KB 等配置前必须先完成数据流分析。8.3 核内性能调优tune-incore是否需要核心利用率 ≥ 70% 且气泡率 10% 时为可能需要否则待前两阶段完成后评估调优重点特殊 Shape 处理、冗余计算优化、尾轴优化、Operation 实现检查详细指南加载 tune-incore 技能。核内调优面向单 task 指令级优化如小 Shape 矩阵乘的 Vector 预处理典型案例从 500us 优化到 40us、L2 Cache 策略tensor.set_cache_policy(pypto.CachePolicy.NONE_CACHEABLE, True)、submit_before_loopTrue计算搬运重叠、valid_shape尾块零填充避免以及 DDR 往返优化I-10 合并 gather、I-11 view 复用。9. 性能数据文件位置与可视化报告第 7 节记录了本次分析的原始数据出处保证报告可追溯、可复现文件类型路径泳道图{output_dir}/merged_swimlane.json气泡分析{output_dir}/bubble_analysis.log性能追踪{output_dir}/machine_runtime_operator_trace.json本报告{output_dir}/performance_analysis_report.md这些文件位于执行算子命令时工作目录下的output/output_时间戳/中在算子目录下执行则为算子目录/output/output_*/在项目根目录执行则为./output/output_*/。其中merged_swimlane.json泳道图数据展示各核心任务的执行顺序、耗时、气泡与依赖关系可通过 PyPTO Toolkit 插件或官方 Perfetto 在线工具上传可视化分析bubble_analysis.log气泡分析报告是analyze_perf.py的数据源machine_runtime_operator_trace.json运行时算子级性能追踪。泳道图是深度调优阶段的核心工具——tune-swimlane 技能 强调每次进入该阶段必须重新采集最新数据禁止复用旧轮次的泳道图代码修改后性能特征已变旧数据会导致错误结论。10. 调优记录与总结让迭代有据可依10.1 调优记录表报告第 8 节以轮次为单位记录每次优化的前后对比是迭代式调优的过程证据轮次优化内容修改前执行时间(us)修改后执行时间(us)提升比例精度结果1{优化内容}{time}{time}{percent}%{通过/失败}该表与主技能的迭代纪律强绑定每次修改一个参数 → 立即验证精度输出必须含 passed/success→ 采集性能对比 → 记录结果 → 判断是否继续。精度失败或性能回退的尝试必须记录避免重试这正是 optimization_catalog.md 中已失败优化避免重试表的设计初衷。10.2 总结章节报告第 9 节收束全文给出三要素当前状态性能评级引用第 3 节综合评级、主要瓶颈列表、推荐的调优方向下一步行动按调优方向建议的顺序执行、每次优化后验证精度并记录、达到性能目标后生成最终报告报告元信息报告生成时间与 PyPTO 版本模板末尾保证不同轮次报告之间的可比性。11. 报告在真实调优流程中的使用建议结合 pypto-op-perf-tune 主技能 的状态机性能分析报告在每个调优轮次中承担三种角色基线锚点调优开始前必须记录基准性能AICore End-to-End Time、核心利用率、气泡率、负载均衡度此后每次优化都与基线对比判断优化方向是否正确——特别强调以 AICore E2E Time 下降为准若 AICore E2E Time 上升而 wall time 下降说明开销被从 host 转移到了核上应回退症状索引报告中的瓶颈类型直接映射到 optimization_catalog 的症状 A/B/C/D可快速锁定 F/S/I 系列优化点编号再加载对应子技能获取操作指南迭代记录每轮优化结果写入第 8 节调优记录表最终整合进{op_name}_tuning_report.md形成从性能数据 → 性能分析 → 调优决策 → 效果验证的完整证据链。结语PyPTO 算子性能分析报告模板将昇腾 NPU 上晦涩的硬件行为核间气泡、调度等待、负载倾斜转化为结构化的九节报告核心指标给出事实、统计与评级给出判断、瓶颈与建议给出方向、数据位置与调优记录给出可追溯性。配合 perf-analyzer 技能与analyze_perf.py脚本它可以被无缝嵌入到 pypto-op-perf-tune 的自动化调优流程中成为驱动开箱调优、深度调优与核内调优迭代闭环的可靠数据基础。无论你是手工分析还是脚本自动生成遵循本模板的结构与指标口径就能产出一份决策友好、可复现、可对比的高质量性能分析报告。【免费下载链接】pypto-gymPyPTO-Gym 是基于 PyPTO 编程框架构建的算子与模型样例仓库项目地址: https://gitcode.com/cann/pypto-gym创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考