From external-gitcode-ascend-skills
Automates migrating PyTorch models to Huawei Ascend NPU with a 7-stage pipeline: analysis, dependency fixing, device adaptation, API replacement, NPU validation, debugging, and report generation.
How this skill is triggered — by the user, by Claude, or both
Slash command
/external-gitcode-ascend-skills:npu-model-migrationThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
将任意 PyTorch 模型迁移到华为昇腾 NPU 并验证运行。
将任意 PyTorch 模型迁移到华为昇腾 NPU 并验证运行。
使用此 skill 当用户说:
模型迁移是一项需要"诊断能力"的任务,而非简单的"查找替换"。
大多数 PyTorch 代码天生支持 NPU,只需要解决:
每个模型遇到的问题都不同,需要分析问题→定位根因→修复→验证的迭代循环。
┌─────────────────────────────────────────────┐
│ 阶段 1: 目标分析 (必做) │
│ 1.1 环境分析 → 依赖、框架、Python 版本 │
│ 1.2 代码分析 → 测试入口、训练/推理流程 │
│ 1.3 迁移难度评估 → 预估需要改动的范围 │
└─────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────┐
│ 阶段 1.5: 快速尝试 (强烈推荐!) │
│ 1.5.1 尝试 transfer_to_npu │
│ 1.5.2 检查是否还有遗漏项 │
│ 1.5.3 验证能否直接跑通 │
└─────────────────────────────────────────────┘
↓ (若失败则进入阶段2)
┌─────────────────────────────────────────────┐
│ 阶段 2: 方案设计 (必做) │
│ 2.1 识别需要修改的文件 │
│ 2.2 确定迁移策略 │
│ 2.3 向用户反馈计划,等待确认 │
└─────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────┐
│ 阶段 3: 代码迁移 │
│ 3.1 设备适配 │
│ 3.2 依赖修复 │
│ 3.3 API 替换 │
└─────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────┐
│ 阶段 4: NPU 验证 (必做) │
│ 4.1 克隆代码到 NPU 服务器 │
│ 4.2 安装依赖、运行测试 │
│ 4.3 收集输出、验证结果 │
└─────────────────────────────────────────────┘
↓
┌─────────────────────────────────┐
│ 阶段 5: 调试与迭代 (循环) │
│ 5.1 分析报错 │
│ 5.2 定位根因 │
│ 5.3 修复代码 │
│ 5.4 重新验证 │
└─────────────────────────────────┘
↓
(循环直到通过)
↓
┌─────────────────────────────────────────────┐
│ 阶段 6: 输出迁移报告 (必做) │
│ 6.1 生成报告 Markdown │
│ 6.2 记录修改内容与验证结果 │
│ 6.3 归档到 references/cases/ │
└─────────────────────────────────────────────┘
从项目入口获取关键信息:
# 查找依赖文件
find . -name "requirements*.txt" -o -name "setup.py" -o -name "pyproject.toml" | head -5
# 查找 README
find . -name "README*.md" -o -name "readme*.md" | head -3
需要获取:
找到测试/运行入口:
# 查找测试目录
find . -type d -name "test*" -o -type d -name "example*" | head -5
# 查找训练/推理脚本
find . -name "train*.py" -o -name "main*.py" -o -name "run*.py" | head -10
分析代码结构:
compile → fit → evaluate 还是自定义循环cuda.is_available() 的位置README 是迁移工作的重要参考依据,必须仔细阅读。
README 通常包含以下关键信息:
| 内容 | 重要性 | 迁移时的作用 |
|---|---|---|
| 环境配置 | ⭐⭐⭐ | 确定 Python、PyTorch、依赖版本 |
| 数据集准备 | ⭐⭐⭐ | 了解数据格式、下载方式、存放路径 |
| 训练命令 | ⭐⭐⭐ | 确定训练入口、参数配置、如何验证 |
| 测试命令 | ⭐⭐⭐ | 确定测试方式、评估指标 |
| 预训练模型 | ⭐⭐ | 是否需要下载预训练权重 |
| 结果复现 | ⭐⭐ | 验证迁移是否成功的参考标准 |
分析要点:
# 查找 README 文件
find . -name "README*.md" -o -name "readme*.md" -o -name "INSTALL.md" | head -5
环境依赖
requirements.txt 或 setup.py数据准备
训练流程
验证方式
迁移后的验证应参考 README 中的测试/验证方式,确保输出格式和指标与原版一致。
| 复杂度 | 特征 | 预估改动 |
|---|---|---|
| 简单 | 纯 PyTorch 模型,无第三方库依赖 | 少量设备适配 |
| 中等 | 有 sklearn、numpy 等依赖 | 设备适配 + 依赖修复 |
| 复杂 | 有自定义 CUDA 算子、多卡分布式 | 需要额外适配 |
在完成目标分析后,务必先尝试这个"偷懒"办法!
torch_npu.contrib.transfer_to_npu 是一个自动重定向工具,通过 monkey-patch 将代码中的 torch.cuda.* API 自动劫持到 torch.npu.*。
它能自动处理:
torch.cuda.is_available() → torch.npu.is_available()tensor.cuda() → tensor.npu()torch.cuda.empty_cache() → torch.npu.empty_cache()torch.cuda.set_device(x) → torch.npu.set_device(x)device='cuda:0' → device='npu:0'backend="nccl" → backend="hccl" (分布式)torch.profiler CUDA 相关 → NPU 版本在原代码入口文件头部添加:
import torch_npu
from torch_npu.contrib import transfer_to_npu
然后直接运行测试。如果成功,无需任何其他修改!
# 使用 NPU 卡 0,1(根据实际情况修改)
ASCEND_VISIBLE_DEVICES=0,1 ASCEND_RT_VISIBLE_DEVICES=0,1 python run.py
如果 transfer_to_npu 不能完全跑通,需要手动检查以下遗漏项:
| 遗漏项 | 搜索模式 | 修复方法 |
|---|---|---|
| autocast 设备字符串 | autocast.*cuda | 'cuda' → 'npu' |
| 设备类型判断 | device.*cuda|is_cuda | cuda → npu |
| 第三方库 CUDA 调用 | 库特定 | 需要手动修复 |
# 搜索遗漏项
grep -rn "autocast.*cuda\|'cuda'\|is_cuda\|\.cuda(" --include="*.py" .
成功标准:
Epoch 1/10, Loss: 0.123Output shape: torch.Size([...])AUC: 0.755失败处理:
⚠️ 只有在阶段 1.5(快速尝试)失败后才进入此阶段
基于代码分析,找出需要修改的文件:
cuda.is_available()、.cuda() 的文件策略 A: 最小改动(推荐)
├── 保留原代码不变
├── 创建 npu 版本目录
└── 只修改必要的设备相关代码
策略 B: 条件适配
├── 添加 NPU 检测逻辑
├── 同时支持 GPU/NPU
└── 通过环境变量切换
在开始修改之前,必须向用户确认:
## 迁移计划
### 目标模型
- 模型名称: xxx
- 仓库: xxx
### 分析结果
- 依赖: torch >= 1.x, sklearn, ...
- 测试方式: pytest tests/xxx.py
- 预估复杂度: 中等
### 快速尝试
- 已尝试 transfer_to_npu: ❌ 失败
- 失败原因: xxx
### 迁移策略
- 策略 A: 最小改动
- 需要修改的文件:
1. xxx.py (设备适配)
2. xxx.py (依赖修复)
### 下一步
- 等待确认后开始修改
- 修改后会在 NPU 服务器上验证
原则:尽量少改,只改必要的设备相关代码。
# 方案 1: 环境变量控制
import os
CPU_ENABLE = os.environ.get("MODEL_CPU_ONLY", "false").upper() == "TRUE"
GPU_ENABLE = torch.cuda.is_available() and not CPU_ENABLE
NPU_ENABLE = not GPU_ENABLE and not CPU_ENABLE
if NPU_ENABLE:
import torch_npu
| 原代码 | 替换为 | 说明 |
|---|---|---|
torch.cuda.is_available() | torch_npu.npu.is_available() | 设备检测 |
torch.cuda.current_device() | torch_npu.npu.current_device() | 当前设备 |
torch.cuda.set_device(x) | torch_npu.npu.set_device(x) | 设置设备 |
.cuda() | .npu() | 张量/模型移动 |
"cuda" | "npu" | 设备字符串 |
torch.cuda.amp | torch_npu.npu.amp | 混合精度 |
backend="nccl" | backend="hccl" | 分布式训练 |
def get_device(prefer_npu=True):
"""自动获取可用设备"""
import os
import torch
# 优先级: 环境变量 > NPU > GPU > CPU
if os.environ.get("MODEL_CPU_ONLY", "").upper() == "TRUE":
return torch.device("cpu")
if prefer_npu:
try:
import torch_npu
if torch_npu.npu.is_available():
return torch.device("npu:0")
except ImportError:
pass
if torch.cuda.is_available():
return torch.device("cuda:0")
return torch.device("cpu")
常见第三方库问题:
| 问题 | 原因 | 解决方案 |
|---|---|---|
| sklearn 版本不兼容 | NPU 环境 sklearn 版本较旧 | 升级或降级版本 |
| numpy 兼容 | 某些 numpy 函数 NPU 不支持 | 用 torch 替代 |
| pandas 兼容 | 某些操作在 NPU 上不支持 | 转回 CPU 计算 |
处理原则:
常见需要替换的 API:
# 需要替换
torch.cuda.get_device_capability() # NPU 无此概念
torch.cuda.comm.scatter/gather # NPU 不支持
# 可以保留(自动兼容)
torch.nn.Module.to("cuda") # 内部会处理
torch.tensor(device="cuda") # 内部会处理
详细 API 支持列表见: references/npu-api-mapping.md
# 设置 NPU 卡号(根据环境约束)
export ASCEND_VISIBLE_DEVICES=0,1
export ASCEND_RT_VISIBLE_DEVICES=0,1
直接在本地 NPU 环境执行:
# 1. 克隆代码(如果不在本地)
git clone <repo-url> -b <branch-name>
cd <project-dir>
# 2. 安装依赖
pip install -r requirements.txt
# 3. 运行测试(使用指定的 NPU 卡)
ASCEND_VISIBLE_DEVICES=0,1 ASCEND_RT_VISIBLE_DEVICES=0,1 python run.py --config config.yaml
# 或
ASCEND_VISIBLE_DEVICES=0,1 ASCEND_RT_VISIBLE_DEVICES=0,1 pytest tests/test_model.py -v
必须看到以下输出之一才算成功:
Epoch 1/10, Loss: 0.123Output shape: torch.Size([...])AUC: 0.755禁止:
| 错误类型 | 典型特征 | 排查方向 |
|---|---|---|
ModuleNotFoundError | 缺少模块 | 安装依赖、检查版本 |
RuntimeError: NPU not found | 设备问题 | 检查 ASCEND_VISIBLE_DEVICES |
NotImplementedError | API 不支持 | 查文档,找替代方案 |
TypeError | 类型不匹配 | 检查 dtype、device |
AssertionError | 精度/值校验失败 | 调整 rtol/atol |
OOM | 内存不足 | 减小 batch_size |
1. 分析错误信息
2. 判断错误类型
3. 搜索解决方案 (文档/案例)
4. 修改代码
5. 重新运行验证
6. 通过则结束,失败则回到步骤 1
最大迭代次数: 5 次
超过次数应向用户报告困难
Q: 提示 torch_npu 找不到 A: 确认容器中 torch 和 torch_npu 版本匹配
Q: 提示 NPU not found A: 检查 ASCEND_VISIBLE_DEVICES 环境变量是否正确设置
Q: 提示 API 不支持 A: 查看 references/npu-api-mapping.md 找替代 API
Q: 精度不达标 A: 检查 HF32 配置,尝试调整 rtol/atol
Q: OOM 内存不足 A: 减小 batch_size,使用 gradient checkpointing
⚠️ 每个模型迁移完成后,必须生成迁移报告并归档
使用标准模板:references/migration-report-template.md
必须包含的内容:
references/cases/<模型名小写>.md
例如:
references/cases/autoint.mdreferences/cases/yolov5.mdreferences/cases/deepfm.md# AutoInt NPU 迁移报告
## 基本信息
| 字段 | 内容 |
|------|------|
| **模型名称** | AutoInt |
| **模型类型** | 推荐系统(CTR 预估) |
| **仓库地址** | https://github.com/FuxiCTR/AutoInt |
| **迁移日期** | 2026-04-03 |
| **迁移状态** | ✅ 成功 |
## 环境信息
- NPU: Ascend 910B4 (30GB)
- Python: 3.9
- PyTorch: 2.3.0
- torch_npu: 2.6.0
## 迁移过程
### 1. 快速尝试
- transfer_to_npu: ❌ 失败
- 失败原因: sklearn 兼容性
### 2. 深度迁移
- 修改 fuxictr/metrics.py (sklearn 兼容性)
- 修改 fuxictr/pytorch/torch_utils.py (NPU 设备支持)
## 验证结果
运行命令:
```bash
ASCEND_VISIBLE_DEVICES=0 python run.py --config config.yaml
输出:
AUC: 0.755208
迁移结论: 简单
### 6.4 注意事项
- **必须归档**:不输出报告 = 迁移未完成
- **验证结果**:必须包含实际运行输出(数值)
- **问题记录**:如实记录遇到的问题和解决方案
- **后续复用**:报告是 future migration 的重要参考
---
## 案例参考
### 案例结构
每个案例应该包含:
1. **模型信息** - 名称、仓库、特点
2. **遇到的问题** - 报错信息、分析过程
3. **解决方案** - 具体修改了什么
4. **验证结果** - 运行输出、指标
### 已验证案例
| 模型 | 复杂度 | 状态 | 关键修改 |
|------|--------|------|----------|
| AutoInt | 简单 | ✅ | sklearn 兼容性、设备检测 |
| DeepFM | 中等 | ✅ | 设备适配、HF32 |
| DIN | 中等 | ✅ | 分布式配置 |
| Wide&Deep | 简单 | ✅ | 设备检测 |
详细案例见:`references/cases/`
---
## 多模型项目处理
如果用户给的是一个**模型框架**(包含多个模型),如:
- TorchEasyRec(DeepFM、DIN、Wide&Deep...)
- FuxiCTR(AutoInt、DeepFM...)
**处理方式:**
1. 先告知用户这是一个框架
2. 询问用户要迁移哪个具体模型
3. 确定后按单模型流程处理
---
## 约束条件
1. **工作目录限制**:根据实际环境配置
2. **NPU 环境**:确保 NPU 驱动和 torch_npu 已正确安装
3. **NPU 卡号**:根据实际可用卡号设置,建议通过环境变量配置
4. **不修改原代码**:建议在并行目录进行修改,或使用 Git 分支
5. **必须验证**:没有在 NPU 上运行过,不说"迁移成功"
---
## 文件结构
npu-model-migration/ ├── SKILL.md # 本文件 └── references/ ├── README.md # 快速参考指南 ├── npu-api-mapping.md # API 映射表 ├── common-issues.md # 常见问题汇总 ├── migration-report-template.md # 迁移报告模板 └── cases/ # 迁移案例 └── autoint.md
---
## 参考资料
- [Ascend PyTorch 官方文档](https://gitcode.com/Ascend/pytorch)
- [RecSDK Benchmark](https://gitcode.com/Ascend/RecSDK)
- [torch_npu API 映射表](references/npu-api-mapping.md)
---
*Skill 版本: 1.2.0* - 新增迁移报告输出流程(阶段 6)
*更新日期: 2026-04-15*
npx claudepluginhub ascend-ai-coding/awesome-ascend-skills --plugin npu-torchair-inferGuides migration of PyTorch models from CPU/GPU to Ascend NPU via torch_npu, covering code adaptation, environment setup, and correctness verification.
Creates, edits, and optimizes skills for Claude Code, including drafting, evaluating with test prompts, iterating on performance, and improving skill descriptions for better triggering accuracy.