NPU Profiling 问题排查指南【免费下载链接】cannbot-skillsCANNBot 是面向 CANN 开发的用于提升开发效率的系列智能体本仓库为其提供可复用的 Skills 模块。项目地址: https://gitcode.com/cann/cannbot-skills按先看产物后看运行时错误的顺序排查。绝大多数profiler 跑完了但没用的情况都是产物问题而非崩溃。问题零框架内置采集enable_profiler产物只有 trace_view.json、所有 CSV 缺失症状enable_profiler: True跑完log_0.log里一串[ERROR] profiler.py: Task [KernelViewParser] run failed. [ERROR] profiler.py: Task [OperatorViewParser] run failed. [ERROR] profiler.py: Task [TraceViewParser] run failed. ... (CANNTimelineParser / TraceStepTimeParser / DbParser 等全 run failed)采的每个阶段prof/prefill、prof/decode的ASCEND_PROFILER_OUTPUT/里只剩一个trace_view.json而且常被截断、不是合法 JSON没有kernel_details.csv/op_statistic.csv/api_statistic.csv。根因profiling 输出目录所在的文件系统/盘不是框架/权限/版本框架enable_profiler的离线解析由 CANN 的msprof工具完成。出现上述症状时最常见的根因是 profiling 输出目录所在的文件系统/盘——某些挂载数据盘 / 网络盘 / 特定容器 bind-mount会让msprof的离线分析产不出 CSV而把输出换到另一个文件系统尤其本地盘就完全正常。排除项实测遇到此故障不要往这些方向查不是框架代码 /ProfilerManager用法逐特征复刻全成功不是目录权限os.access全R/W/XTrue、strace显示对数据的文件操作全成功、零EACCESACL 也授权了不是torch_npu/CANN 版本号、不是算子、不是exe_mode同一份采集数据输出在「坏盘」→ 全部 parser run failed、无 CSV输出在「好盘」→ 框架原样产出kernel_details.csv~47 列 全套 CSV、零 run failed。解决按顺序确认是不是这个故障grep -c run failed res/log_0.log非 0、且kernel_details.csv缺失。首选把 profiling 输出换到另一个目录/文件系统优先本地盘重跑后重新验收。profiler 输出路径 WORK_DIR/RES_PATH/prof/...execution_engine.py:83但function.sh会把WORK_DIR重写成cann-recipes-infer/models/model直接export WORK_DIR会被覆盖。可靠做法是把res软链到本地盘ln -sfn /tmp/recipes_res cann-recipes-infer/models/model/resres 已是非空真实目录则先移走再跑infer.sh。多换几个盘定位哪个文件系统可用。快速坐实是不是输出目录的问题把那份失败的*_ascend_pt原始数据cp -r到另一个盘再python3 -c import torch_npu; torch_npu.profiler.profiler.analyse(新路径)—— 能解析出 CSV就确定是原输出目录所在盘的问题。换了几个盘都不行再回退到注入采集SKILL.md 路径 B /scripts/profile_template.py兜底。具体为什么某些盘上 CANNmsprof离线分析会失败msprof把错误吞了、文件权限/锁/空间都正常属 CANN 原生层未进一步定位但换到本地盘就好可稳定复现、可用。问题零点五框架 prefill 采集是单步active1框架 prefill 用active1, skip_first0每个 request 只采 1 步 prefillprefill 本就只有 1 步。实测只要输出目录没问题见问题零prefill 这份能正常产出 47 列 CSV 合法 trace_view不必担心单步不完整。如需多步 prefill / 自定义 prefill 窗口用注入路径「模式 B」active1后补一次收尾prof.step()。问题一kernel_details.csv只有 9 列缺 shape、stream、aic/aiv 指标症状$ head -1 ASCEND_PROFILER_OUTPUT/kernel_details.csv | tr , \n | wc -l 9或op_statistic.csv/api_statistic.csv整个文件不生成。原因没有传ExperimentalConfig或者profiler_level设成了Level0。默认行为只收最基本的 kernel trace流水线利用率、算子 shape、stream 归属这些字段统统不会记录。解决experimental_config torch_npu.profiler._ExperimentalConfig( profiler_leveltorch_npu.profiler.ProfilerLevel.Level1, aic_metricstorch_npu.profiler.AiCMetrics.PipeUtilization, ) profiler torch_npu.profiler.profile( ..., experimental_configexperimental_config, # ← 必须传 )验证期望 47 列必含这些Stream ID、Input Shapes、Input Data Types、Output Shapes、Output Data Typesaic_mac_time(us)、aic_mac_ratio、aic_mte1_ratio、aic_mte2_ratio、aic_fixpipe_ratioaiv_vec_time(us)、aiv_vec_ratio、aiv_scalar_ratio、aiv_mte2_ratio、aiv_mte3_ratiocube_utilization(%)问题二trace_view.json不以]结尾 / JSON 截断症状[WARNING] Incorrect schedule: Stop profiler while current state is RECORD which may result in incomplete parsed data.以及仅在旧版 torch_npu 上[ERROR] Task [CANNTimelineParser] run failed. [ERROR] Task [RelationParser] run failed. [ERROR] Task [TraceViewParser] run failed. ...版本差异torch_npu 版本warning 行为实际 JSON 产物≤ 2.7.xwarning 触发时大概率 JSON 截断、parser 全 fail无法用≥ 2.8.0.post2已实测warning 仍然打但 CANN 会补齐 JSONparsers 照常成功多数情况下可用但行为未文档化、不要依赖无论哪个版本看到Incorrect schedulewarning 都应视为配置错误要修掉。根本原因schedule 的转换发生在prof.step()被调用时。如果循环结束时 profiler 还停在 RECORD 状态即prof.step()的总调用次数 ≤skip_first warmup activeprofiler 没机会走结束 active → 触发 trace 收尾这条转换__exit__里只能强制停止。正确规则prof.step()总调用次数 ≥skip_first warmup active 1精确边界是skip_first warmup active1 为收尾余量。下面例子都用skip_first0故化简成warmup active 1框架 decode 是skip_first3, active3最小就是3036、留余量取 7。两种等价实现A. 把MAX_STEPS调够大WARMUP, ACTIVE 2, 30 MAX_STEPS 33 # ≥ warmup active 1B. 循环结束后补一次prof.step()WARMUP, ACTIVE, MAX_STEPS 2, 30, 30 with profiler as prof: for _ in range(MAX_STEPS): run_one_step() prof.step() prof.step() # ← 收尾让 schedule 跨出 active 窗口推荐 B保证 profile 窗口就是你关心的那 N 步收尾步只推进 schedule、不采新数据。为什么老文档里写的是MAX_STEPS warmup active这是一条被误传的规则。按它配profiler 在循环结束时一定停在 active 窗口中间、状态为 RECORD —— 正是 warning 想警告的状态。新版 CANN 的兼容处理让这条错误规则看上去有效但它从来都没真正让 profiler 干净收尾过。验证 JSON 完整性tail -c 50 ASCEND_PROFILER_OUTPUT/trace_view.json # 正确结尾示例 ...cat: async_npu}] python3 -c import json; json.load(open(ASCEND_PROFILER_OUTPUT/trace_view.json)); print(OK)问题三采到的是编译时间不是推理时间症状kernel_details.csv里出现大量跟你的模型无关的编译/图构建 opaclnn*大量出现在前几百毫秒之后骤减trace_view前几秒全是 host 侧的 aclnn 绑定、图下发真正的 kernel 非常稀疏第一个 decode step 显示的耗时远大于非 profile 跑的稳态耗时。原因 —— 是图编译不是 prefill常见误解prefill 太慢把 prefill 放窗口外就行。 真正污染采样的是第一次torch.compile/torchair.get_npu_backend/ JIT触发的图构建不管它发生在 prefill 还是 decode。Prefill 只是第一次 forward在 eager 模式下并没有编译成本decode 第一次调用才会触发 torchair /torch.compile的图构建。解决真正要放 profiler 外的是第一次触发框架层面编译/trace 的调用# 1) 跑一次 prefill也顺带暖 prefill 需要的任何 shape 特化 run_prefill(...) torch.npu.synchronize() # 2) 跑一次 decodetorchair/torch.compile 在这里真正编图 warm_one_decode(...) torch.npu.synchronize() # 3) 这之后才进 profiler —— 此时进 profiler 的 prefill 也是真实 kernel 时间 with create_profiler(...) as prof: # 想分别采 prefill / decode见 SKILL.md「关键 3」的四种模式 ... prof.step() # 收尾快速判定有没有踩到看step_trace_time.csv第一行Computing是不是显著大于后面几行差 10× 以上。如果是说明第一次 forward 的编译时间被记进去了——把那次 forward 挪到 profiler 外再跑一遍即可。问题四ASCEND_PROFILER_OUTPUT整个目录为空排查顺序没调prof.step()with profiler as prof: for step in range(MAX_STEPS): run() prof.step() # ← 漏这行就什么都采不到步数少于warmupschedule 还没进 RECORD 循环就退出了。保证MAX_STEPS warmup。权限问题save_path没写权限。换个路径试。on_trace_ready没配必须传tensorboard_trace_handler(save_path)否则默认不落盘。问题五communication.json/communication_matrix.json没生成不是 bug。这两个文件只在多卡分布式场景会生成需要有 HCCL 通信算子被捕获。单卡跑world_size1永远不会有这两个文件不用排查。如果参考产物有、你这边没有先确认两边world_size是否一致。问题六tensorboard 打开看不到 Profile 面板症状$ tensorboard --logdir./prof # 只显示 No scalar data was found原因TensorBoard 默认显示 scalarNPU profile 数据要装torch_tb_profiler插件并切换到 PyTorch Profiler 面板。解决pip install torch_tb_profiler # 重启 tensorboard切 PyTorch Profiler tab或者不用 tensorboard直接在 Chrome 打开chrome://tracing加载trace_view.json。Schedule 状态机参考配置wait0, warmup2, active30, repeat1in_cycle每次prof.step()后 1prof.step()第几次被调in_cycle状态10WARMUP21WARMUP32RECORD开始采......RECORD3231RECORD仍在采3332 → 0新 cycle或 NONErepeat1 已满← 这一步触发收尾回调想让 profiler 干净退出就必须让第 33 次调用发生即MAX_STEPS skip_first warmup active 1本表skip_first0故 33或者 loop 外补一次prof.step()。最佳实践清单ExperimentalConfig(Level1 PipeUtilization)别省。prefill / 图编译放 profiler 外。loop 后补一次prof.step()或MAX_STEPS skip_first warmup active 1。采完先跑「产物自检清单」见 SKILL.md列数不对就不用下一步分析了。用相同 config 复跑一遍对比基线避免看个例波动。环境信息本文档基于以下环境验证组件新文档验证版本旧文档原版本torch_npu2.8.0.post22.7.1.post2.dev20251226CANN8.x/9.x9.0.0平台Atlas A2 / A3Ascend910B新旧版本主要行为差异已在问题二表中列出。【免费下载链接】cannbot-skillsCANNBot 是面向 CANN 开发的用于提升开发效率的系列智能体本仓库为其提供可复用的 Skills 模块。项目地址: https://gitcode.com/cann/cannbot-skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
