一、迁移分析前置工作
概述： 迁移分析不是直接从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,4096x4096,4096 | 325 |
| 14:23:02 | MatMul | 1,128,4096x4096,4096 | 1280 ← 重编译 |
| 14:23:03 | MatMul | 1,512,4096x4096,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_report5.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方案 │
│ └─ 不建议迁移（阻塞项过多或无法绕过）→ 说明原因 │
└────────────────────────────────────────────────────────────┘