Migrate any PyTorch model to Huawei Ascend NPU and verify it runs.
Trigger Conditions
Use this skill when the user says:
- "Migrate this model to NPU"
- "Help me adapt it to Ascend"
- "Get this model running on NPU"
- "Migrate to Ascend"
- "Help me check whether this model can run on NPU"
Core Philosophy
Model migration is a task that requires "diagnostic ability", not a simple "find and replace".
Most PyTorch code natively supports NPU; you only need to resolve:
- device detection logic
- third-party library compatibility
- unsupported APIs
Each model encounters different problems, requiringanalyze the problem → locate the root cause → fix → verifyiterative loop.
Migration Process (Seven Phases)
┌─────────────────────────────────────────────┐
│ 阶段 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/ │
└─────────────────────────────────────────────┘
Phase 1: Target Analysis
1.1 Environment Analysis
Obtain key information from the project entry point:
# 查找依赖文件
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
Need to obtain:
- Python version requirements
- PyTorch version
- Key dependencies (numpy, scikit-learn, transformers, etc.)
- Installation method
1.2 Code Analysis
Find the test/run entry point:
# 查找测试目录
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
Analyze the code structure:
- Training process:
compile → fit → evaluateor custom loop - Testing framework: pytest / unittest / manual script
- Device selection logic:
cuda.is_available()location of - Data loading method: DataLoader, batch processing
1.3 README Analysis (Important!)
The README is an important reference for migration work and must be read carefully.
The README usually contains the following key information:
| Content | Importance | Role during migration |
|---|---|---|
| Environment configuration | ⭐⭐⭐ | Determine Python, PyTorch, dependency versions |
| Dataset preparation | ⭐⭐⭐ | Understand data format, download method, storage path |
| Training command | ⭐⭐⭐ | Determine training entry point, parameter configuration, how to verify |
| Test command | ⭐⭐⭐ | Determine testing method, evaluation metrics |
| Pretrained model | ⭐⭐ | Whether pretrained weights need to be downloaded |
| Result reproduction | ⭐⭐ | Reference standard for verifying whether migration succeeded |
Analysis points:
# 查找 README 文件
find . -name "README*.md" -o -name "readme*.md" -o -name "INSTALL.md" | head -5
-
Environment dependencies
- Check
requirements.txtorsetup.py - Confirm Python and PyTorch version requirements
- Record all third-party libraries
- Check
-
Data preparation
- Dataset name, download link
- Data format (CSV, JSON, TFRecord, etc.)
- Data directory structure
- Preprocessing method
-
Training process
- Training command example
- Key hyperparameters
- Training script entry point
- Configurations that need to be modified
-
Verification Method
- How to test the model
- Evaluation metrics (accuracy, loss, AUC, etc.)
- Expected output format
- This is an important reference for successful verification after migration!
Verification after migration should refer to the testing/verification method in the README, ensuring that the output format and metrics are consistent with the original version.
1.4 Migration Difficulty Assessment
| Complexity | Features | Estimated Changes |
|---|---|---|
| Simple | Pure PyTorch model, no third-party library dependencies | Minor device adaptation |
| Medium | Has dependencies such as sklearn and numpy | Device adaptation + dependency fixes |
| Complex | Has custom CUDA operators and multi-GPU distributed processing | Additional adaptation required |
Stage 1.5: Quick Attempt (Strongly Recommended)
After completing the target analysis, be sure to try this "lazy" approach first!
1.5.1 What is transfer_to_npu
torch_npu.contrib.transfer_to_npu is anautomatic redirection tool, which uses monkey-patching to automatically hijack the torch.cuda.* API in the code to torch.npu.*。
It can automatically handle:
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"(distributed)torch.profilerCUDA-related → NPU version- Some APIs of mainstream libraries such as transformers/trl/peft/accelerate
1.5.2 Quick Attempt Method
Add the following at the top of the original code entry file:
import torch_npu
from torch_npu.contrib import transfer_to_npu
Then run the test directly. If successful,no other modifications are needed！
# 使用 NPU 卡 0,1（根据实际情况修改）
ASCEND_VISIBLE_DEVICES=0,1 ASCEND_RT_VISIBLE_DEVICES=0,1 python run.py
1.5.3 Check for Omissions
If transfer_to_npu cannot fully run through, you need to manually check the following omissions:
| Omission | Search Pattern | Fix Method |
|---|---|---|
| autocast device string | autocast.*cuda |
'cuda' → 'npu' |
| Device type check | device.*cuda|is_cuda |
cuda → npu |
| Third-party library CUDA calls | Library-specific | Manual fix required |
# 搜索遗漏项
grep -rn "autocast.*cuda\|'cuda'\|is_cuda\|\.cuda(" --include="*.py" .
1.5.4 Verification Result Assessment
Success Criteria:
- Normal training output:
Epoch 1/10, Loss: 0.123 - Normal inference output:
Output shape: torch.Size([...]) - Normal evaluation output:
AUC: 0.755
Failure Handling:
- If an error occurs, record the error message
- Proceed to Stage 2 for deep migration
Stage 2: Solution Design (for Deep Migration)
⚠️ Enter this stage only after Stage 1.5 (Quick Attempt) fails
2.1 Identify Files That Need Modification
Based on the code analysis, identify the files that need modification:
- Device-related - Files containing
cuda.is_available()、.cuda()files - Entry file - main.py、train.py、run.py
- Configuration-related - config.yaml、args.py
2.2 Determine the Migration Strategy
策略 A: 最小改动（推荐）
├── 保留原代码不变
├── 创建 npu 版本目录
└── 只修改必要的设备相关代码
策略 B: 条件适配
├── 添加 NPU 检测逻辑
├── 同时支持 GPU/NPU
└── 通过环境变量切换
2.3 Provide Feedback to the User (Required)
Before starting modifications, you must confirm with the user:
## 迁移计划
### 目标模型
- 模型名称: xxx
- 仓库: xxx
### 分析结果
- 依赖: torch >= 1.x, sklearn, ...
- 测试方式: pytest tests/xxx.py
- 预估复杂度: 中等
### 快速尝试
- 已尝试 transfer_to_npu: ❌ 失败
- 失败原因: xxx
### 迁移策略
- 策略 A: 最小改动
- 需要修改的文件:
1. xxx.py (设备适配)
2. xxx.py (依赖修复)
### 下一步
- 等待确认后开始修改
- 修改后会在 NPU 服务器上验证
Stage 3: Code Migration (for Deep Migration)
3.1 Device Adaptation (Core)
Principle: modify as little as possible, and only change the necessary device-related code.
3.1.1 Basic Device Detection
# 方案 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
3.1.2 Device Replacement Rules
| Original Code | Replace With | Description |
|---|---|---|
torch.cuda.is_available() |
torch_npu.npu.is_available() |
Device Detection |
torch.cuda.current_device() |
torch_npu.npu.current_device() |
Current Device |
torch.cuda.set_device(x) |
torch_npu.npu.set_device(x) |
Set Device |
.cuda() |
.npu() |
Tensor/Model Movement |
"cuda" |
"npu" |
Device String |
torch.cuda.amp |
torch_npu.npu.amp |
Mixed Precision |
backend="nccl" |
backend="hccl" |
Distributed Training |
3.1.3 Device Initialization Template
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")
3.2 Dependency Fixing
Common Third-Party Library Issues:
| Issue | Cause | Solution |
|---|---|---|
| sklearn version incompatibility | sklearn version is older in the NPU environment | Upgrade or downgrade the version |
| numpy compatibility | Some numpy functions are not supported by NPU | Replace with torch |
| pandas compatibility | Some operations are not supported on NPU | Move back to CPU for computation |
Handling Principles:
- Leave non-core dependencies untouched as much as possible
- For core dependency issues, prioritize trying to upgrade/downgrade the version
- When necessary, move part of the computation back to CPU
3.3 API Replacement
Common APIs that need replacement:
# 需要替换
torch.cuda.get_device_capability() # NPU 无此概念
torch.cuda.comm.scatter/gather # NPU 不支持
# 可以保留（自动兼容）
torch.nn.Module.to("cuda") # 内部会处理
torch.tensor(device="cuda") # 内部会处理
For the detailed API support list, see: references/npu-api-mapping.md
Stage 4: NPU Verification (General)
4.1 Environment Preparation
# 设置 NPU 卡号（根据环境约束）
export ASCEND_VISIBLE_DEVICES=0,1
export ASCEND_RT_VISIBLE_DEVICES=0,1
4.2 Run Tests
Execute directly in the local NPU environment:
# 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
4.3 Verification Criteria
One of the following outputs must be seen to count as success:
- Training process:
Epoch 1/10, Loss: 0.123 - Inference process:
Output shape: torch.Size([...]) - Evaluation metrics:
AUC: 0.755
Prohibited:
- Declaring pass after only seeing "import successful"
- Declaring pass after only seeing "training started"
- No specific numerical output
Stage 5: Debugging and Iteration (General)
5.1 Error Classification
| Error Type | Typical Characteristics | Troubleshooting Direction |
|---|---|---|
ModuleNotFoundError |
Missing module | Install dependencies, check versions |
RuntimeError: NPU not found |
Device issue | Check ASCEND_VISIBLE_DEVICES |
NotImplementedError |
API not supported | Check documentation, find alternatives |
TypeError |
Type mismatch | Check dtype, device |
AssertionError |
Precision/value verification failed | Adjust rtol/atol |
OOM |
Insufficient memory | Reduce batch_size |
5.2 Iteration Process
1. 分析错误信息
2. 判断错误类型
3. 搜索解决方案 (文档/案例)
4. 修改代码
5. 重新运行验证
6. 通过则结束，失败则回到步骤 1
最大迭代次数: 5 次
超过次数应向用户报告困难
5.3 Common Issues Quick Reference
Q: torch_npu not found is reported A: Confirm that the torch and torch_npu versions in the container match
Q: NPU not found is reported A: Check whether the ASCEND_VISIBLE_DEVICES environment variable is set correctly
Q: API not supported is reported A: Check references/npu-api-mapping.md to find a replacement API
Q: Precision does not meet the standard A: Check the HF32 configuration and try adjusting rtol/atol
Q: OOM insufficient memory A: Reduce batch_size and use gradient checkpointing
Stage 6: Output Migration Report (Required)
⚠️ After each model migration is completed, a migration report must be generated and archived
6.1 Report Template
Use the standard template:references/migration-report-template.md
Required content:
- Basic information (model name, type, repository, migration date, status)
- Environment information (NPU device, Python/PyTorch/torch_npu versions)
- Migration process (quick trial results, modified files, dependency fixes)
- Verification results (run commands, output logs, performance comparison)
- Problems encountered and solutions
- Items to be optimized
6.2 Output location
references/cases/<模型名小写>.md
For example:
references/cases/autoint.mdreferences/cases/yolov5.mdreferences/cases/deepfm.md
6.3 Report example
# 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
Output:
AUC: 0.755208
Summary
Migration conclusion: Simple
### 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 # This file └── references/ ├── README.md # Quick reference guide ├── npu-api-mapping.md # API mapping table ├── common-issues.md # Summary of common issues ├── migration-report-template.md # Migration report template └── cases/ # Migration 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*