一、迁移分析前置工作

概述： 迁移分析不是直接从GPU代码跳到NPU代码，而是需要先在第三方平台（GPU）上建立"基线"，再在昇腾平台上进行对标验证。没有基线，后续所有分析都缺少参照系。

1.1 三方平台获取基线

步骤	内容	目的
选模型	确定目标模型及版本（如 GLM-4-9B、BERT-base 等）	明确迁移对象
跑通推理	确保模型在GPU上前向推理正确输出	验证模型可用性
跑通训练（可选）	确保 loss 能正常收敛	确认训练流程完整
记录精度基线	loss / acc / cos_sim 等指标	后续精度的对标依据
记录性能基线	throughput / latency / peak_memory	后续性能的对标依据
保存固定输入	将输入张量保存为 .pt 文件	NPU 侧用同一份输入做对比

精度基线记录示例：

{
  "model": "GLM-4-9B",
  "device": "NVIDIA A100 80G",
  "framework": "PyTorch 2.1 + transformers 4.36",
  "precision": {
    "fp32": { "loss": 2.341, "acc_top1": 0.7234 },
    "fp16": { "loss": 2.345, "acc_top1": 0.7228 }
  },
  "performance": {
    "throughput": 420.5,
    "latency_p50": 8.2,
    "peak_memory_gb": 58.2
  }
}

1.2 昇腾环境搭建

# 1. 确认昇腾驱动和 CANN 版本
npu-smi info                  # 查看芯片型号、显存、驱动
cat /usr/local/Ascend/version.cfg   # 查看 CANN 版本

# 2. 安装 torch_npu（与 PyTorch 版本严格对应）
pip install torch_npu==2.1.0  # 对应 PyTorch 2.1

芯片与 CANN 版本对应关系：

昇腾芯片	推荐 CANN 版本	适用场景
Ascend 310/310P	CANN 7.0+	仅推理
Ascend 910/910B	CANN 7.0+	训练 + 推理
Ascend 910C	CANN 8.0+	训练 + 推理

环境验证脚本（env_check.py）：

import torch
import torch_npu

print(f"PyTorch: {torch.__version__}")
print(f"NPU available: {torch.npu.is_available()}")
print(f"NPU count: {torch.npu.device_count()}")
print(f"Device name: {torch.npu.get_device_name(0)}")

# 基础算子测试
x = torch.randn(100, 100).npu()
y = torch.randn(100, 100).npu()
z = torch.mm(x, y)
print(f"MatMul test passed: {z.shape}")
print(f"Memory: {torch.npu.memory_allocated(0)/1024**3:.2f} GB")

---

二、算子支持情况分析

 msFmkTrans（华为官方迁移分析工具）

概述： 这是迁移分析最核心的一步——扫描训练脚本中所有的 torch API 和 CUDA API，逐一判断在昇腾上是否支持。支持状态分为四级，并给出精度和性能的专家调优建议。

2.1 工具与用法

• 工具： msFmkTrans（华为官方迁移分析工具）
• 安装： pip install msfmktrans
• 说明：用户提供待分析的PyTorch训练脚本，可快速获得该训练脚本中不支持的torch API和cuda API信息，并输出训练脚本中API精度和性能调优的专家建议

msfmktrans --input=train.py \
           --output=./analysis \
           --framework=pytorch

2.2 输出产物

输出文件	格式	内容
api_support_report.csv	CSV	全部 API 的支持状态清单
unsupported_api_detail.json	JSON	不支持 API 的详细说明
expert_suggestions.md	Markdown	精度和性能的专家优化建议
report.html	HTML	可视化报告

2.3 API 支持状态四级分类

状态	标识	含义	处理方式
完全支持	✅	昇腾原生支持，无差异	无需修改
部分支持	⚠️	功能可用但有精度/性能差异	需验证后酌情修改
不兼容	🚫	当前 CANN 版本不支持	必须寻找替代方案
需验证	❓	文档未覆盖，需实际运行确认	上机实测

2.4 报告内容示例

API 名称	位置	状态	精度说明	性能建议
torch.bmm	model.py:45	✅	—	建议替换为 torch.matmul，性能提升 10-15%
F.scaled_dot_product_attention	attention.py:78	⚠️	flash attention 模式暂不支持	回退到标准 attention
torch.nn.DataParallel	train.py:112	🚫	—	替换为 DDP + HCCL
torch.cuda.Stream	utils.py:34	🚫	—	昇腾不支持自定义 Stream
torch.Tensor.index_add_	embedding.py:156	⚠️	fp16 下精度波动大	建议切换到 fp32 计算

2.5 专家建议示例

## 精度优化建议

### LayerNorm（6处使用）
- 问题：fp16混合精度下，昇腾LayerNorm与GPU存在 ±1e-3 偏差
- 建议：在 autocast 中排除 LayerNorm
  ```python
  with autocast():
      ...
      with autocast(enabled=False):
          x = self.layer_norm(x)  # 强制 fp32

性能优化建议

MatMul（占总耗时42.3%）

• 预期收益：30-50%

---

## 三、三方库套件分析

> **概述：** 现代 PyTorch 项目通常依赖 transformers、deepspeed、accelerate 等三方库。这些库内部可能含有不兼容的 API 调用，需要单独扫描和分析。

### 3.1 工具与用法

```bash
# 方式一：自动扫描依赖目录
msfmktrans --input=./my_project \
           --third-party-dir=./venv/lib/python3.10/site-packages \
           --output=./tp_analysis

# 方式二：手动指定需要分析的库
msfmktrans --input=./my_project \
           --third-party-list=transformers,deepspeed,accelerate \
           --output=./tp_analysis

三：常见三方库兼容性速查

      原理： msFmkTrans 内置了主流三方库的API映射表，不止扫描你自己的代码，还扫描 import 进来的库。

      对应工具：msFmkTrans + 自定义规则扩展

     说明：用户提供待分析的三方库套件源码，可快速获得源码中不支持的三方库API和cuda信息。

三方库	兼容等级	典型不兼容项	解决方案
transformers	⚠️ 大部分兼容	generate() 中采样策略差异	设置环境变量 ASCEND_TORCH_COMPAT=1
deepspeed	🚫 部分不兼容	ZeRO CPU/NVMe offload	关闭 offload 或替换为 AscendSpeed
accelerate	⚠️ 大部分兼容	device_map="auto"	手动指定 device_map
peft	⚠️ 大部分兼容	LoRA 配置参数	使用昇腾适配版 peft
bitsandbytes	🚫 完全不兼容	8bit/4bit 量化算子	替换为昇腾 AMCT 量化工具
triton	🚫 完全不兼容	自定义 Triton kernel	用 TBE/DSL 重写
flash-attn	🚫 不兼容	FlashAttention kernel	替换为昇腾 FlashAttention 算子

3.3 输出示例

{
  "library": "transformers",
  "version": "4.36.0",
  "status": "partial",
  "incompatible_modules": [
    {
      "module": "LlamaFlashAttention2",
      "reason": "flash_attn 依赖不存在于昇腾",
      "fix": "替换为 transformers 默认 attention"
    }
  ]
}

---

四、动态Shape分析

概述： 昇腾 NPU 对动态 Shape 的容忍度远低于 GPU。每次输入 Shape 变化都可能触发算子重新编译（JIT编译），导致性能断崖式下跌。因此迁移前必须识别并消除动态 Shape 来源。

用户提供待分析的PyTorch训练脚本，可快速获得该训练脚本中包含的动态shape信息

4.1 动态Shape的四大来源

来源	典型代码	风险等级	说明
DataLoader 批次不一致	drop_last=False	🔴 高	最后一个 batch 尺寸可能不同
序列长度不固定	tokenizer padding=True	🔴 高	每批序列长度取决于最长文本
条件分支引入不同 Shape	if use_cache: ... else: ...	🟡 中	不同路径输出 Shape 不同
动态 mask	mask 在 forward 中计算	🟡 中	seq_len 每次都可能变化

4.2 静态分析（代码层面）

msfmktrans --input=train.py \
           --dynamic-shape-analysis \
           --output=./dynamic_analysis

输出示例：

====================================
动态Shape检测报告
====================================

[来源1] DataLoader 批次不一致
  文件: data_loader.py:35
  代码: for batch in dataloader:
  建议: 设置 drop_last=True

[来源2] 序列长度不固定
  文件: tokenizer.py:48
  代码: tokens = tokenizer(texts, padding=True, truncation=True)
  建议: 固定 max_length=512

[来源3] 动态mask
  文件: attention.py:67
  代码: causal_mask = torch.triu(...)[:seq_len, :seq_len]
  建议: 将mask计算移到DataLoader预处理中

====================================
严重度评估: 高(3处) 中(2处) 低(1处)
====================================

4.3 运行时分析（实际执行）

# 开启Shape dump
export ASCEND_DUMP_SHAPE=1
export ASCEND_DUMP_SHAPE_PATH=./shape_dump
python train.py --epochs=1

输出示例：

时间戳	算子	输入 Shape	编译耗时(us)
14:23:01	MatMul	[1,512,4096]x[4096,4096]	325
14:23:02	MatMul	[1,128,4096]x[4096,4096]	1280 ← 重编译
14:23:03	MatMul	[1,512,4096]x[4096,4096]	1300 ← 又重编译回去

诊断标准： 如果同一个算子的 count=1（只出现一次）且 total_us 远高于稳定值，说明 Shape 变化导致频繁重编译。

4.4 动态Shape修复策略

修复方案	针对场景	预期收益
设置 drop_last=True	DataLoader 批次不一致	消除尾部小 batch
固定 max_length + 统一 padding	序列长度不固定	消除长度变化
预处理阶段生成固定 mask	动态 mask	减少重编译次数
统一走一条分支（padding对齐）	条件分支不同 Shape	消除分支差异

---

五、亲和API分析

概述： "亲和API"指昇腾上经过硬件加速优化的 API 替换建议。保持接口语义一致的前提下，替换为昇腾专有算子可以获得显著的性能提升。不是强制要求，但值得关注。

用户提供待分析的PyTorch训练脚本，可快速获得该训练脚本中可替换的亲和API信息。

5.1 工具与用法

msfmktrans --input=train.py \
           --affinity-api \
           --output=./affinity_report

5.2 三级替换建议

🔥 高收益项（性能提升 > 20%）

原 API	推荐替换	预期收益	替换难度
torch.bmm	torch.matmul	+25%	低（一行改）
F.softmax(dim=-1)	torch_npu.npu_softmax_v2	+30%	中（需 import）
torch.cumsum(fp16)	切换到 fp32 计算	精度 +15%	低（改 dtype）

⚡ 中等收益项（10-20%）

原 API	推荐替换	说明
torch.nn.Dropout	torch_npu.npu_dropout	融合了 mask 生成
torch.Tensor.index_select	torch.gather	gather 在 Cube 上更高效

✅ 建议保持原样（昇腾已有隐式优化）

API	原因
torch.nn.Linear	底层已映射到 CubeUnit
torch.nn.Conv2d	已适配 AI Core
torch.nn.LayerNorm	有 Vector Unit 加速
torch.nn.GELU	已融合进激活算子

5.3 替换风险控制

# 替换前必须验证等效性
x = torch.randn(4, 128, 128).npu()

# 原API
out_old = torch.bmm(x, x.transpose(1, 2))

# 亲和API
out_new = torch.matmul(x, x.transpose(1, 2))

# 验证
diff = (out_old - out_new).abs().max().item()
assert diff < 1e-6, f"精度偏差过大: {diff}"

---

六、工具链全景

概述： 整个迁移分析不是靠一个工具完成的，而是由一套工具链配合使用，覆盖不同阶段和不同维度。

6.1 工具清单

分析能力	工具/方法	安装/获取方式	对标 NVIDIA 工具
代码静态扫描	msFmkTrans	pip install msfmktrans	无直接对标
算子兼容性查询	om --optype-list	随 CANN 安装	—
逐层精度比对	自定义 Hook + adc	pip install adc	nvbit
运行时 Shape Dump	ASCEND_DUMP_SHAPE 环境变量	零依赖	—
算子 Dump	ASCEND_OP_DUMP 环境变量	零依赖	nvcc --dump
性能 Profiling	msprof	随 CANN 工具包	nsys (Nsight Systems)
算子级性能分析	msvp	随 CANN 工具包	ncu (Nsight Compute)
性能基准对比	自定义 benchmark 脚本	纯 Python	自定义脚本

6.2 工具定位图

使用阶段        工具                 解决的问题
──────────────────────────────────────────────────
迁移前评估  ──  msFmkTrans  ──  "能不能迁？改多少？"
环境验证    ──  env_check   ──  "环境装好了吗？"
算子验证    ──  前向运行     ──  "跑起来报错吗？"
精度对齐    ──  Hook + adc  ──  "输出对得上吗？"
性能分析    ──  msprof       ──  "哪里慢？为什么慢？"
持续优化    ──  环境变量调优  ──  "还能再快吗？"

---

七、输出产物清单

概述： 迁移分析最终会产出一系列结构化的文档和数据，作为后续实际迁移工作的依据和参考。

产物	格式	用途	产出阶段
API 支持状态报告	CSV / HTML	评估迁移工作量	msFmkTrans 扫描
不兼容 API 详情	JSON	具体修改依据	msFmkTrans 扫描
专家优化建议	Markdown	精度/性能调优指导	msFmkTrans 扫描
三方库兼容报告	JSON	三方依赖风险评估	msFmkTrans 扫描
动态 Shape 报告	Markdown	Shape 优化方向	msFmkTrans 扫描
亲和 API 替换建议	Markdown	性能收益评估	msFmkTrans 扫描
逐层精度比对报告	CSV / HTML	精度对齐验证	Hook 脚本 / adc
环境验证日志	文本	环境确认	env_check.py
Shape dump 记录	CSV	运行时 Shape 变化	ASCEND_DUMP_SHAPE
算子 dump 数据	二进制	算子级调试	ASCEND_OP_DUMP
性能 Profiling 报告	HTML / JSON	性能瓶颈定位	msprof
最终迁移可行性报告	Markdown	管理层决策	综合所有产物

---

八、建议迁移分析工作流

概述： 从拿到项目代码到产出迁移可行性报告，建议按以下五个步骤有序推进，每一步产出的结果决定是否进入下一步。

┌────────────────────────────────────────────────────────────┐
│  步骤1：全面扫描 —— msFmkTrans                              │
│  输入：训练脚本                                             │
│  输出：API支持状态 + 三方库兼容 + 动态Shape + 亲和API        │
│  决策：如果有 >10% 的红色（不兼容）项，需评估是否值得迁移    │
└────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌────────────────────────────────────────────────────────────┐
│  步骤2：算子验证 —— 实际跑一次前向                          │
│  输入：固定输入张量（GPU 基线同款）                          │
│  输出：是否跑通 + 是否报错                                   │
│  决策：跑不通则需先解决算子报错                              │
└────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌────────────────────────────────────────────────────────────┐
│  步骤3：精度对齐 —— Hook 脚本 / adc                         │
│  输入：GPU 逐层输出 + NPU 逐层输出                           │
│  输出：逐层 cos_sim + max_diff                               │
│  决策：cos_sim < 0.999 的层需要定位和修复                    │
└────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌────────────────────────────────────────────────────────────┐
│  步骤4：性能分析 —— msprof + benchmark 脚本                  │
│  输入：完整训练/推理流程                                    │
│  输出：算子级耗时分布 + 内存使用 + 通信开销                  │
│  决策：通过 环境变量调优 + 亲和API替换 优化性能              │
└────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌────────────────────────────────────────────────────────────┐
│  步骤5：输出迁移可行性报告                                   │
│  内容：                                                     │
│  ├─ 能迁移（所有阻塞项已解决）→ 进入实际迁移                 │
│  ├─ 有条件迁移（阻塞项可绕过）→ 列出workaround方案           │
│  └─ 不建议迁移（阻塞项过多或无法绕过）→ 说明原因             │
└────────────────────────────────────────────────────────────┘

---