Migration Ascend Torchnpu Skills Migration Execution

Skill: 代码迁移执行

你是一位专注于PyTorch代码迁移至昇腾NPU的工程师。本Skill提供代码迁移的具体操作步骤、替换规则和验证方法。

官方参考文档：

• 训练迁移指导：https://www.hiascend.com/document/detail/zh/Pytorch/2600/ptmoddevg/trainingmigrguide/FrameworkPTAdapter/26.0.0/zh/pytorch_model_migration_fine_tuning/mig_methods_comp.md
• 亲和API替换（性能调优）：https://www.hiascend.com/document/detail/zh/Pytorch/2600/ptmoddevg/trainingmigrguide/FrameworkPTAdapter/26.0.0/zh/pytorch_model_migration_fine_tuning/affinity_api_repl.md
• PyTorch原生接口支持度：https://www.hiascend.com/document/detail/zh/Pytorch/2600/apiref/PyTorchNativeapi/docs/zh/native_apis/pytorch_2-10-0/overview.md
• torch_npu扩展接口：https://www.hiascend.com/document/detail/zh/Pytorch/2600/apiref/Extensionapi/docs/zh/extension_apis/overview.md
• torch_npu官方仓库：https://gitcode.com/Ascend/pytorch

⚠ 版本持续更新，URL中的版本号（如26.0.0）随PyTorch框架适配版本迭代。MUST将URL中的版本号替换为实际使用的版本号，访问对应版本文档。

一、迁移方式选择

昇腾提供两种迁移方式：

1.1 自动迁移（推荐）

通过 transfer_to_npu 自动将运行时的 torch.cuda 等接口映射为 torch.npu 对应接口，无需手动修改代码。

import torch
import torch_npu
from torch_npu.contrib import transfer_to_npu

适用场景：未使用CUDA高阶能力（如自定义算子、直接操作GPU显存等）的简单场景

限制：

• 仅支持PyTorch 1.8.1及以上版本
• 自动迁移适合没有使用CUDA高阶能力的简单场景，如果涉及自定义算子、主动申请GPU显存等操作，则需要额外进行手动迁移适配

1.2 手动迁移

手动修改代码中的CUDA相关调用为NPU对应接口。适用于自动迁移无法覆盖的场景。

前提条件：

• 要迁移的训练任务代码在GPU上多次训练稳定可收敛
• 已完成迁移环境准备

约束和限制：

• 安装插件后，大部分能力能够对应在GPU上的使用，但并不是所有行为和GPU上是一一对应的
• 在torch_npu下，当PyTorch版本低于2.1.0时，一个进程只能操作一张昇腾卡，不支持一个进程操作多卡的能力；在PyTorch 2.1.0及以上版本中torch_npu才支持一个进程中使用多张昇腾卡
• 基于PyTorch上的第三方开发库非常多，例如transformers、accelerate、deepspeed以及Megatron-LM等，这些三方库昇腾也做了类似PyTorch Adapter的适配插件库，可在gitcode.com/Ascend官方仓库按需使用。部分三方库例如最新版本deepspeed已原生支持NPU

二、手动迁移：设备映射替换

2.1 torch_npu初始化

在torch_npu安装后，该部分并没有直接植入到PyTorch中生效，需要用户显式调用。

import torch_npu

调用后，前端会通过monkey-patch的方式注入到torch对象中，后端会注册NPU设备以及HCCL的参数面通信能力。

2.2 基础设备替换规则

2.3 混合精度替换规则

模型从GPU适配到NPU时，需要将代码torch.cuda.amp修改为torch_npu.npu.amp。

昇腾NPU的Cube计算单元仅支持FP16矩阵运算，FP32的矩阵运算无法调用Cube高算力。整网使用FP16数值范围小，容易导致梯度消失，因此混合精度训练（AMP）在NPU上是必要操作，不是可选项。

2.4 分布式训练替换规则

昇腾只支持DDP模式，不支持DP模式。

分布式初始化方式：

# 方式1：通过接口设置
dist.init_process_group(
    backend='hccl',
    init_method="tcp://127.0.0.1:29688",
    world_size=args.world_size,
    rank=args.rank
)

# 方式2：通过环境变量设置
os.environ['MASTER_ADDR'] = '127.0.0.1'
os.environ['MASTER_PORT'] = '29688'
dist.init_process_group(
    backend='hccl',
    world_size=args.world_size,
    rank=args.rank
)

2.5 NPU不支持的接口

以下接口在NPU上不支持或行为不同，MUST手动处理：

• torch.nn.DataParallel：不支持，MUST改为DDP
• amp_C模块：不支持，MUST手动删除
• torch.cuda.get_device_capability：迁移后返回None，如遇报错需手动修改为固定值
• torch.cuda.get_device_properties：返回值不包含minor和major属性，需注释掉相关代码

三、接口等价替换

3.1 替换流程

1. 从接口分析报告中筛选出NPU不支持的接口
2. 查阅昇腾官方接口支持度文档，确认该接口是否已适配：
   • PyTorch原生接口支持度：https://www.hiascend.com/document/detail/zh/Pytorch/2600/apiref/PyTorchNativeapi/docs/zh/native_apis/pytorch_2-10-0/overview.md
   • torch_npu扩展接口：https://www.hiascend.com/document/detail/zh/Pytorch/2600/apiref/Extensionapi/docs/zh/extension_apis/overview.md
3. 如无官方适配方案，按以下优先级寻找替代：
   • 优先级1：使用torch_npu提供的扩展接口
   • 优先级2：使用等价的PyTorch原生接口组合
   • 优先级3：使用自定义实现（MUST论证数学一致性）

3.2 接口支持度查询

昇腾官方提供了按PyTorch版本区分的接口支持度清单，MUST根据实际使用的PyTorch版本查阅对应文档：

以上路径均基于文档根目录 https://www.hiascend.com/document/detail/zh/Pytorch/2600/ 下。版本迭代较快，MUST以官网最新版本文档为准。

查询方法：

1. 确定当前项目使用的PyTorch版本
2. 打开对应版本的接口支持度文档
3. 搜索目标接口名称，查看是否在支持列表中
4. 如在支持列表中，确认接口的行为差异说明
5. 如不在支持列表中，查阅torch_npu扩展接口文档是否有替代

3.3 数学一致性论证模板

对每个等价替换，MUST按以下模板论证：

### 接口替换：[原始接口] → [替换接口]

**数学定义**：
- 原始接口：y = f(x)，数学定义式为...
- 替换接口：y = g(x)，数学定义式为...

**等价性证明**：
- 当满足条件...时，f(x) = g(x)
- 证明过程：...

**数值验证**：
- 测试输入：生成N组随机输入
- 最大绝对误差：{value}
- 最大相对误差：{value}
- 结论：误差在可接受范围内 / 需要进一步处理

四、调试技巧

4.1 定位不支持接口

try:
    output = model(input_npu)
except RuntimeError as e:
    if "not implemented for" in str(e) and "NPU" in str(e):
        print(f"不支持的接口: {e}")

4.2 逐层验证

def verify_layer_by_layer(model, sample_input, device="npu"):
    x = sample_input.to(device)
    for name, layer in model.named_children():
        x = layer(x)
        print(f"Layer {name}: output shape={x.shape}, "
              f"mean={x.mean().item():.6f}, std={x.std().item():.6f}")

4.3 精度对比工具

def compare_outputs(cpu_output, npu_output, atol=1e-5, rtol=1e-3):
    cpu_np = cpu_output.detach().cpu().numpy()
    npu_np = npu_output.detach().cpu().numpy()
    max_abs_diff = abs(cpu_np - npu_np).max()
    max_rel_diff = (abs(cpu_np - npu_np) / (abs(cpu_np) + 1e-8)).max()
    print(f"最大绝对误差: {max_abs_diff:.2e}")
    print(f"最大相对误差: {max_rel_diff:.2e}")
    assert max_abs_diff < atol or max_rel_diff < rtol, "精度超出允许范围"

五、NPU亲和性调优

完成基础迁移（设备映射、接口替换）后，模型已可在NPU上正常运行。但要充分发挥NPU硬件性能，需要进行亲和性调优。以下方法来源于昇腾官方文档： https://www.hiascend.com/document/detail/zh/Pytorch/2600/ptmoddevg/trainingmigrguide/FrameworkPTAdapter/26.0.0/zh/pytorch_model_migration_fine_tuning/affinity_api_repl.md

⚠ 版本持续更新，亲和API列表和用法可能随版本变化，MUST实时查阅上述官网链接获取最新信息。

5.1 亲和API替换概述

在基础迁移完成后，将代码中的部分原生PyTorch接口替换为昇腾NPU亲和接口，可进一步提升训练效率。亲和接口针对NPU硬件架构进行了深度优化，能显著减少算子调度开销、提升内存访问效率。

5.2 融合转置操作：npu_confusion_transpose

torch_npu.npu_confusion_transpose 用于融合 transpose + view（或 reshape）组合操作，减少中间张量的产生，降低显存占用和算子调度开销。

使用场景：当模型代码中频繁出现 transpose 后紧跟 view/reshape 的模式时（常见于多头注意力等模块），使用此API可提升性能。

# torch原生写法
import torch
data = torch.rand(64, 3, 64, 128).npu()
result = data.transpose(1, 2).view(64, 64, -1)

# torch_npu亲和写法
import torch_npu
data = torch.rand(64, 3, 64, 128).npu()
result = torch_npu.npu_confusion_transpose(data, perm=[0, 2, 1, 3], shape=[64, 64, -1])

5.3 NPU亲和优化器

使用 torch_npu 提供的融合优化器替换原生PyTorch优化器。NPU亲和优化器通过算子融合减少参数更新时的多次kernel launch开销。

前提条件：在替换优化器前，需确保已完成NPU亲和优化器的导入。

常用NPU亲和优化器（以PyTorch 2.6.0版本为例，新版本文档可能新增更多）：

# 原生PyTorch写法
import torch
optimizer = torch.optim.AdamW(model.parameters(), lr=1e-4)

# torch_npu亲和写法
import torch_npu
optimizer = torch_npu.optim.NpuFusedAdamW(model.parameters(), lr=1e-4)

注意事项：

• 并非所有优化器都有NPU融合版本，MUST查阅官方文档确认当前版本支持的融合优化器列表
• 融合优化器的超参数与原生优化器基本一致，但部分特殊参数可能有差异，需对照官方文档确认

5.4 NPU亲和梯度裁剪

在替换为NPU亲和梯度裁剪API之前，MUST确保已使用NPU亲和优化器（参见5.3节）。NPU亲和梯度裁剪与NPU亲和优化器配合使用，可进一步减少参数更新的kernel launch次数。

# 原生PyTorch写法
import torch
optimizer = torch.optim.AdamW(model.parameters(), lr=1e-4)
# ... loss计算 ...
loss.backward()
torch.nn.utils.clip_grad_norm_(model.parameters(), max_norm=1.0)
optimizer.step()

# torch_npu亲和写法
import torch_npu
optimizer = torch_npu.optim.NpuFusedAdamW(model.parameters(), lr=1e-4)
# ... loss计算 ...
loss.backward()
torch_npu.utils.clip_grad_norm_(model.parameters(), max_norm=1.0)
optimizer.step()

注意：梯度裁剪API的具体接口名可能随版本变化，MUST查阅当前版本官方文档确认。

5.5 多流并行优化（补充）

昇腾NPU支持多流（multi-stream）并行执行，可通过显式管理计算流来提升并发度：

# 创建多个stream并行执行不依赖的操作
stream1 = torch.npu.Stream()
stream2 = torch.npu.Stream()

with torch.npu.stream(stream1):
    output1 = model_part1(data1)
with torch.npu.stream(stream2):
    output2 = model_part2(data2)

torch.npu.synchronize()  # 等待所有stream完成

多流并行适用于模型中的独立计算分支，能有效隐藏数据搬运延迟。使用前需确保各分支之间无数据依赖关系。

5.6 性能调优查阅路径

亲和性调优属昇腾性能调优体系的一部分，完整的性能调优方法和最新亲和API列表MUST查阅昇腾官方文档：

• PyTorch训练模型迁移调优总览：https://www.hiascend.com/document/detail/zh/Pytorch/2600/ptmoddevg/trainingmigrguide/FrameworkPTAdapter/26.0.0/zh/pytorch_model_migration_fine_tuning/mig_methods_comp.md
• 亲和API替换（含最新API列表）：https://www.hiascend.com/document/detail/zh/Pytorch/2600/ptmoddevg/trainingmigrguide/FrameworkPTAdapter/26.0.0/zh/pytorch_model_migration_fine_tuning/affinity_api_repl.md
• 性能调优方法总览：https://www.hiascend.com/document/detail/zh/Pytorch/2600/ptmoddevg/trainingmigrguide/FrameworkPTAdapter/26.0.0/zh/pytorch_model_migration_fine_tuning/npu_suit_optimize.md

⚠ 以上URL中的版本号（如26.0.0）对应当前PyTorch框架适配版本。版本会持续更新，MUST将URL中的版本号替换为实际使用的版本号，获取匹配的文档内容。