Ascend for PyTorch框架Skills实战系列——NPUGraph问题定位

NPUGraph问题难在三点。一是调用链跨 Python API → C++ 核心 → op-plugin → ACL 运行时四层，开发者看到的通常只是一条表面报错，真正原因可能藏在任意一环；二是问题可能发生在 Capture、Compile、Replay、Update、Memory 任一阶段，同一现象对应多种根因；三是日志量大，TORCH_NPU_LOGS 动辄上百 MB，人工翻找容易漏掉关键信息。

难点并不是读懂某一行代码，而是那条「先做什么、再做什么、出错往哪查」的路径——过去它更多藏在资深工程师的经验里，难以复用、难以验证。npu-graph-skill 的目标就是把这条路径固化为标准流程：一个入口按意图路由到五个子技能（知识问答、端到端诊断、性能分析、日志分析、MCP 集成），并把每次诊断沉淀为可复用案例。

成果预览

案例1 环境自检：一条命令输出CANN、NPU设备、torch_npu版本、NPUGraph 功能、日志变量与内存状态共8项体检结果，先区分「环境问题」还是「代码问题」。在 CANN 9.2.0 / torch_npu 2.10.0 / 昇腾A2设备上实测为 8通过 / 2失败，两项FAIL均定位为脚本版本适配问题，而非环境异常（见Step 5）。

案例2 默认流捕获违规：模型在capture_begin处报NPU graphs must be captured on a non-default stream.。Skill路由到graph-mode-diagnostics，锚定Capture阶段；匹配known-patterns.md后判定既有模式未覆盖、属新问题；沿graphs.py:359下钻到NPUGraph.cpp锁定校验层，给出非默认流捕获的修复写法并验证通过（完整过程见Step 11）。

环境准备清单
分步实施
Step 1：获取技能包

git clone --depth 1 https://gitcode.com/Ascend/agent-skills.gitcd agent-skills/official/PyTorch && ls npu-graph-skill

图 1　克隆 agent-skills 仓库（git clone --depth 1，2900 个对象）

Step 2：安装到 Skills 目录

整个目录原样拷入，目录名与内部结构都不要改：

mkdir -p .claude/skillscp -r /path/to/npu-graph-skill .claude/skills/ls .claude/skills/npu-graph-skill # 确认 5 个子技能 + knowledge/ + SKILL.md

图 2　复制技能目录后 ls 确认结构完整

Step 3：确认 Agent 已加载

新建会话后问一句「你现在有哪些图模式相关的 skill？」，或在 Claude Code 里输入/skills 查看。顶层SKILL.md 的 description声明了NPUGraph、ACLGraph、capture/replay、graph OOM、graph logs等触发词，命中即加载，再由 Gate 0 路由表分派到子技能。

图 3　在 /skills 发现 npu-graph-skill（project 级，约 90 tok）

Step 4：配置 NPU 运行环境

source /usr/local/Ascend/ascend-toolkit/set_env.sh # 路径按实际安装调整npu-smi info # 校验设备python -c "import torch, torch_npu; print(torch.__version__, torch_npu.__version__)"

Step 5：跑通环境自检（安装后第一个验证动作）

python graph-mode-expert/scripts/check_graph_health.py -v

脚本依次检查8项：CANN环境、PyTorch、torch_npu、NPU设备、NPUGraph API、日志变量、基础捕获/重放、内存与npu-smi。

判读要点：只看[CRIT]项。在CANN 9.2.0 / torch_npu 2.10.0 / Ascend910B2 上实测为「8 通过 / 2 失败 / 0 严重」，两项FAIL属版本适配问题、待更新脚本：① 脚本在默认流上 capture_begin，被「必须非默认流捕获」拒绝；② graph() 少传 npu_graph 参数。二者与CANN、驱动、硬件无关。

图 4　健康检查真实输出：8 通过 / 2 失败（0 严重）

Step 6：本地验证辅助脚本

4个脚本只依赖标准库，可离线验证：

parse_npu_logs.py --test 是内置自检，不读真实日志：自己造9条样例日志跑一遍并断言，因此「错误数: 2」和匹配模式 E-003 / E-002 都是样例里的预埋错误，只表示自检通过。

图 5　日志解析器自检：SELF TEST PASSED

Step 7：准备源码仓（让诊断能落到行号）

git clone https://gitcode.com/Ascend/pytorch.git # torch_npu 主仓git clone https://gitcode.com/Ascend/op-plugin.git -b master # 算子仓

拉取后确认5个关键文件存在：npu/graphs.py、npu/_graph_tree.py、csrc/core/npu/NPUGraph.cpp、csrc/npu/Graph.cpp、op-plugin/ops/。

图 6　拉取 torch_npu（95994 个对象）与 op-plugin（-b master）

Step 8：加载 Skill 并提问

无需记子技能名，直接用自然语言提问，四类典型入口：

? 知识问答：NPUGraph 的 capture_begin 内部做了什么？

? 问题诊断：我的图模式报错了：[贴完整堆栈]

? 性能分析：图模式比 Eager 慢，从哪里开始排查？

? 日志分析：TORCH_NPU_LOGS 输出 200MB，帮我分析

子技能的Iron Law会强制先索取完整堆栈与最小复现用例，材料不全时会把材料要回来。

图 7　提问 capture_begin 实现：读到 NPUGraph.cpp:240-348，给出 7 步逐行实现，并追问是否记录到知识库

Step 9：端到端诊断流程（五阶段）

整体方法四步：识别所处阶段 → 补齐现场证据 → 沿调用链定位 → 给出处理与验证。未完成层级定位前不提出修复方案。

Phase 1 —— 按错误特征确定阶段：

Capture aclmdlRICaptureBegin/End 失败 -> Phase 2AReplay aclmdlRIExecuteAsync 失败 -> Phase 2BMemory OOM / allocator 错误 -> Phase 2CUpdate update_graph() 失败 -> Phase 2DCompile torch.compile 卡死 / Dynamo 异常 -> Phase 2E

Phase 2 —— 分阶段诊断要点：

常用日志开关：

export TORCH_NPU_LOGS=+aclgraph,+dispatch ｜ TORCH_NPU_GRAPHS_LOG_LEVEL=DEBUG ｜ TORCH_NPUGRAPH_GC=1

Phase 3 —— 模式匹配：先查 known-patterns.md（19 条，按捕获/重放/内存/Update/编译分组，如 P-CAP-001 图内 CPU 同步、P-REP-002 图被 LRU 淘汰）与 error-code-map.md，未匹配再深入源码。

Phase 4 —— 深度追踪：Python graphs.py → _graph_tree.py；C++ NPUGraph.cpp → NPUGraph.h；ACL 侧查 /var/log/npu/。

Phase 5 —— 报告四段：问题概况（错误/阶段/层级）→ 根因分析（直接原因/触发条件/影响范围）→ 修复建议（短期/长期+文件定位）→ 验证步骤。

Step 10：ACL 错误码速查

看到错误码先查表。高频两个：0x100000 MODEL_EXECUTE_FAILED（图重放失败，先确认图已正确编译）、0x100003 STREAM_CONTEXT（捕获与重放 Stream 不一致）。完整表见 error-code-map.md。

Step 11：完整案例 —— 默认流捕获违规

把报错、环境与最小复现脚本一次性交给 Agent，可直接套用下列prompt：

/npu-graph-skill我这边 NPUGraph 捕获阶段报错了，帮我定位。【错误信息】 File "/home/LucciC/test.py", line 26, in <module> g.capture_begin() File ".../torch_npu/npu/graphs.py", line 359, in capture_beginRuntimeError: NPU graphs must be captured on a non-default stream.(However, after capture, it's ok to replay them on the default stream.)【环境】CANN 9.2.0-beta.2 / torch_npu 2.10.0 / Ascend910B2 x8 / Python 3.13【使能方式】torch_npu.npu.NPUGraph 手动 capture_begin / capture_end【最小复现脚本】g = NPUGraph(); g.capture_begin() # line 26 抛错; g.capture_end(); g.replay()【已排查】改用非默认流后均通过；check_graph_health.py 报同样错误；环境其余项正常。【想请你】1) 判定阶段与层级；2) 解释捕获流约束与校验位置；3) 短期修复与长期写法；4) 如何验证。

诊断过程：路由到npu-graph-mode-diagnostics → 锚定 Capture阶段 → 匹配 known-patterns.md 发现 P-CAP-004（讲的是op跑错流）并不匹配，应判定为新模式 → 沿 graphs.py:359 下钻到 csrc/core/npu/NPUGraph.cpp 的 capture_begin（真正校验点）→ 结论：阶段Capture，层级L2 C++ 核心，根因默认流捕获违规。

修复：捕获前切非默认流——capture_stream = torch_npu.npu.Stream()；capture_stream.wait_stream(当前流)；with torch_npu.npu.stream(capture_stream): capture_begin / capture_end；完成后让当前流 wait_stream(capture_stream)。重放可在默认流进行。

图 8 Phase 5 诊断报告：阶段=捕获阶段、层级=L2 C++ 核心，并指出 P-CAP-004 不完全匹配

Step 12：日志分析与性能分析

python graph-log-analyzer/scripts/parse_npu_logs.py <log> --output json --summarygrep -E "ERROR|FATAL" <log> # 手工快速定位export ACL_PROFILE=1 && python script.py # 开 Profilemsprof --query=on --output=profiling_data --iteration-id=1

日志异常判据：捕获 >10s、编译 >30s、重放 P99 > P50×3。性能结论须有数据支撑，每次比较记录 CANN 版本、NPU 型号、warmup 次数与测次。

Step 13：DFX 知识沉淀

每次问答/诊断结束，Agent 会主动问「是否记录到知识库？[Y/n]」。选 Y 后按 CASE_TEMPLATE.md 生成条目追加到 knowledge/history.md，并更新分类计数；不匹配任何已知模式时会提示同步更新 known-patterns.md。症状须原文引用、层级定位精确到函数+行号。用得越多，团队案例库越厚。

关键约束速查

1.捕获期间禁止CPU-NPU同步（.item() / .cpu() / print(tensor) / .numpy()）。

2. 捕获必须发生在非默认流上；捕获完成后可在默认流重放。

3. 动态形状需 update 机制；TND + Dropout（keep_prob < 1.0）必须 fallback。

4. 捕获中禁止分配新 NPU 内存，首次调用的 lazy init 需在捕获前用 Eager 跑热。

5. 捕获与重放须在同一 Stream；图内所有算子也须在同一 Stream 上。

6. 不支持嵌套捕获，在已捕获的 Stream 上再次 capture_begin 会失败。

Troubleshooting（常见问题FAQ）
技能加载了但没被触发

确认目录在 .claude/skills/ 或 .trae/skills/ 下，SKILL.md 命名严格大写，内部结构完整。

健康检查报捕获/重放、graph() 两项 FAIL

版本适配问题而非环境异常：前者脚本在默认流上捕获，后者 graph() 少传npu_graph。无CRIT项即可用。

诊断卡在「无法定位到行号」

源码仓未准备。按Step 7 拉取torch_npu与op-plugin，提问时给出本地路径。

pta / triton_ascend / CANN 版本不匹配

推荐PyTorch 2.7.1 + triton_ascend 3.2.2 + CANN 9.2.0，更多配套见昇腾官网。

结语
NPUGraph问题定位Skill的价值，不是用一句结论替代开发者思考，而是把资深工程师脑中的路径地图，变成可复用、可验证的标准流程：对初入图模式的开发者，它降低了跨层定位的门槛；对熟悉框架的工程师，它减少了重复排查。

当判断依据、日志开关、源码入口与验证方法都沉淀进 Skill，效率提升就不再依赖某位专家是否在线。

npu-graph-skill：

https://gitcode.com/Ascend/agent-skills/tree/master/official/PyTorch/npu-graph-skill

torch_npu：

https://gitcode.com/Ascend/pytorch

op-plugin：

https://gitcode.com/Ascend/op-plugin