Ascend for PyTorch框架Skill实战系列——PyTorch用例NPU适配

PyTorch社区用例在NPU上失败，常常要贯穿torch_npu、op-plugin、CANN、torch四层栈才能定位根因。我们将这套“先做什么、再做什么、出错往哪查”的路径地图沉淀成两套Agent Skill——torch-npu-issue-pipeline-core与torch-npu-issue-pipeline-distributed，覆盖基础框架与API、分布式、图模式三大场景。新手一键上手，端到端适配+自验证+多分支交付闭环，效率提升10倍以上。

成果预览

以用例test_get_per_process_memory_fraction为例，当前Skill的成果是：用例验证全部通过，根因已定位，修复方案与修复分支已创建完成。其内容包含：原用例FAIL根因、torch_npu/testing与测试patch的修复位置、原用例及近邻用例的验证结果、复现/根因分析/验证报告/合入描述等产出物归档，以及其余的残余风险提示。这意味着当前问题已具备提交PR或关闭issue的条件，开发者可基于验证结果进行核实，并可复用本次沉淀的结构化记录，支撑后续同类NPU适配问题的排查。

环境准备清单

一键自检：

npu-smi infoecho $ASCEND_HOME_PATHpython -c "import torch, torch_npu; print(torch.__version__, torch_npu.__version__)"

分步实施

Step 1：安装Skill并选择入口

将两套Skill放置在.traecli/skills/目录下，让Trae CLI能自动识别加载：

# 从代码仓克隆到 .traecli/skills/ 目录git clone https://gitcode.com/Ascend/agent-skills.gitcp -r agent-skills/official/PyTorch/torch-npu-issue-pipeline-core ~/.traecli/skills/cp -r agent-skills/official/PyTorch/torch-npu-issue-pipeline-distributed ~/.traecli/skills/

使用时按问题类型选择不同的入口Skill：

分流规则：用例名含inductor/dynamo、运行入口含torch.compile、调用栈触及torch/_inductor/→走Distributed组；其余走Core组。

Step 2：首次配置（仅首次）

Core&API模块Skill首次使用需提供9项配置，示例如下：

- [x] 用例名：test_foo_type_dense_npu- [x] issue_id：issue_145- [x] base_ref：upstream/v2.11.0- [x] branch_scope：["master", "v2.7.1", "v2.9.0", "v2.10.0", "v2.11.0"]- [x] torch_npu_url：https://gitcode.com/<user>/pytorch.git- [ ] pytorch_url：请提供上游PyTorch源码仓库URL- [ ] opplugin_url：请提供你的op-plugin fork仓库URL- [ ] git_user_name：请提供Gitcode用户名- [ ] git_user_email：请提供Git提交邮箱- [ ] gitcode_token：请提供Gitcode PAT

配置齐全后Skill自动克隆三仓库、生成config.json、创建fix/issue_xxx工作分支。后续运行只需用例名+issue_id。

Step 3：一行命令触发完整适配流水线

首次配置完成后，只需向Trae CLI下达一行自然语言指令，Skill会自动完成复现→根因诊断→修复→验证→交付的端到端流程：

> 修复用例test_get_per_process_memory_fraction，issue_id为issue_1

Skill接收指令后自动执行：

整个流水线无需用户介入，产出物自动归档到{workspace}/issues/{case_name}/目录。

常见报错解决（FAQ）

Q1：diagnose修复后仍FAIL

回diagnose重新分析根因；检查是否触发CPU兜底硬红线；确认级联缺失是否走了missing-dispatch-loop。

Q2：图模式`assert not close`但eager通过

确认已设export TORCH_COMPILE_DEBUG=1、已注入5行bootstrap；读output_code.py定位入图状态；先排triton-ascend再看torch_npu。

Q3：流水线报`DELIVERY_BLOCKED`

检查gitcode_token是否过期，确认对目标仓库有push权限。

最终效果展示

产出物目录

{workspace}/issues/{case_name}/ ← 每用例独立├── config.json / 复现报告.md / 根因分析.md├── 修复验证报告.md / delivery_summary.md

{workspace}/issues/{issue_id}/ ← 跨case共享├── patch_manifest.json / 代码合入描述.md

核心竞争力

路径可复用：每步决策物化成文件，下一个接手的人不需要重新理解

判断有依据：硬红线、退出判定都是可执行命令，不是模糊指导

边界有约束：反CPU兜底、反部分修复、反forward-only收尾

报告即产出：任何阶段挂起都有可交接的中间态

结语

当“看懂、动手、守住、修复”每个环节都有Agent护航，开发者才能将更多精力留给没有标准答案的创新问题，欢迎广大开发者关注并使用Ascend for PyTorch Agent Skills。

Skill入口（Ascend for PyTorch Agent Skills仓）：https://gitcode.com/Ascend/agent-skills/tree/master/official/PyTorch

◆往期推荐◆

Ascend for PyTorch框架Skills实战系列——算子适配