一、迁移分析前置工作概述迁移分析不是直接从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_npu2.1.0 # 对应 PyTorch 2.1芯片与 CANN 版本对应关系昇腾芯片推荐 CANN 版本适用场景Ascend 310/310PCANN 7.0仅推理Ascend 910/910BCANN 7.0训练 推理Ascend 910CCANN 8.0训练 推理环境验证脚本env_check.pyimport torch import torch_npu print(fPyTorch: {torch.__version__}) print(fNPU available: {torch.npu.is_available()}) print(fNPU count: {torch.npu.device_count()}) print(fDevice 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(fMatMul test passed: {z.shape}) print(fMemory: {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 --inputtrain.py \ --output./analysis \ --frameworkpytorch2.2输出产物输出文件格式内容api_support_report.csvCSV全部 API 的支持状态清单unsupported_api_detail.jsonJSON不支持 API 的详细说明expert_suggestions.mdMarkdown精度和性能的专家优化建议report.htmlHTML可视化报告2.3 API 支持状态四级分类状态标识含义处理方式完全支持✅昇腾原生支持无差异无需修改部分支持⚠️功能可用但有精度/性能差异需验证后酌情修改不兼容当前 CANN 版本不支持必须寻找替代方案需验证❓文档未覆盖需实际运行确认上机实测2.4 报告内容示例API 名称位置状态精度说明性能建议torch.bmmmodel.py:45✅—建议替换为torch.matmul性能提升 10-15%F.scaled_dot_product_attentionattention.py:78⚠️flash attention 模式暂不支持回退到标准 attentiontorch.nn.DataParalleltrain.py:112—替换为 DDP HCCLtorch.cuda.Streamutils.py:34—昇腾不支持自定义 Streamtorch.Tensor.index_add_embedding.py:156⚠️fp16 下精度波动大建议切换到 fp32 计算2.5 专家建议示例## 精度优化建议 ### LayerNorm6处使用 - 问题fp16混合精度下昇腾LayerNorm与GPU存在 ±1e-3 偏差 - 建议在 autocast 中排除 LayerNorm python with autocast(): ... with autocast(enabledFalse): 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-listtransformers,deepspeed,accelerate \ --output./tp_analysis三常见三方库兼容性速查原理 msFmkTrans 内置了主流三方库的API映射表不止扫描你自己的代码还扫描 import 进来的库。对应工具msFmkTrans 自定义规则扩展说明用户提供待分析的三方库套件源码可快速获得源码中不支持的三方库API和cuda信息。三方库兼容等级典型不兼容项解决方案transformers⚠️ 大部分兼容generate()中采样策略差异设置环境变量ASCEND_TORCH_COMPAT1deepspeed 部分不兼容ZeRO CPU/NVMe offload关闭 offload 或替换为 AscendSpeedaccelerate⚠️ 大部分兼容device_mapauto手动指定 device_mappeft⚠️ 大部分兼容LoRA 配置参数使用昇腾适配版 peftbitsandbytes 完全不兼容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_lastFalse 高最后一个 batch 尺寸可能不同序列长度不固定tokenizerpaddingTrue 高每批序列长度取决于最长文本条件分支引入不同 Shapeif use_cache: ... else: ... 中不同路径输出 Shape 不同动态 maskmask 在 forward 中计算 中seq_len 每次都可能变化4.2 静态分析代码层面msfmktrans --inputtrain.py \ --dynamic-shape-analysis \ --output./dynamic_analysis输出示例 动态Shape检测报告 [来源1] DataLoader 批次不一致 文件: data_loader.py:35 代码: for batch in dataloader: 建议: 设置 drop_lastTrue [来源2] 序列长度不固定 文件: tokenizer.py:48 代码: tokens tokenizer(texts, paddingTrue, truncationTrue) 建议: 固定 max_length512 [来源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_SHAPE1 export ASCEND_DUMP_SHAPE_PATH./shape_dump python train.py --epochs1输出示例时间戳算子输入 Shape编译耗时(us)14:23:01MatMul[1,512,4096]x[4096,4096]32514:23:02MatMul[1,128,4096]x[4096,4096]1280 ← 重编译14:23:03MatMul[1,512,4096]x[4096,4096]1300 ← 又重编译回去诊断标准如果同一个算子的count1只出现一次且total_us远高于稳定值说明 Shape 变化导致频繁重编译。4.4 动态Shape修复策略修复方案针对场景预期收益设置drop_lastTrueDataLoader 批次不一致消除尾部小 batch固定max_length 统一 padding序列长度不固定消除长度变化预处理阶段生成固定 mask动态 mask减少重编译次数统一走一条分支padding对齐条件分支不同 Shape消除分支差异五、亲和API分析概述亲和API指昇腾上经过硬件加速优化的 API 替换建议。保持接口语义一致的前提下替换为昇腾专有算子可以获得显著的性能提升。不是强制要求但值得关注。用户提供待分析的PyTorch训练脚本可快速获得该训练脚本中可替换的亲和API信息。5.1 工具与用法msfmktrans --inputtrain.py \ --affinity-api \ --output./affinity_report5.2 三级替换建议 高收益项性能提升 20%原 API推荐替换预期收益替换难度torch.bmmtorch.matmul25%低一行改F.softmax(dim-1)torch_npu.npu_softmax_v230%中需 importtorch.cumsum(fp16)切换到 fp32 计算精度 15%低改 dtype⚡ 中等收益项10-20%原 API推荐替换说明torch.nn.Dropouttorch_npu.npu_dropout融合了 mask 生成torch.Tensor.index_selecttorch.gathergather 在 Cube 上更高效✅ 建议保持原样昇腾已有隐式优化API原因torch.nn.Linear底层已映射到 CubeUnittorch.nn.Conv2d已适配 AI Coretorch.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 工具代码静态扫描msFmkTranspip install msfmktrans无直接对标算子兼容性查询om --optype-list随 CANN 安装—逐层精度比对自定义 Hook adcpip install adcnvbit运行时 Shape DumpASCEND_DUMP_SHAPE环境变量零依赖—算子 DumpASCEND_OP_DUMP环境变量零依赖nvcc --dump性能 Profilingmsprof随 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 报告MarkdownShape 优化方向msFmkTrans 扫描亲和 API 替换建议Markdown性能收益评估msFmkTrans 扫描逐层精度比对报告CSV / HTML精度对齐验证Hook 脚本 / adc环境验证日志文本环境确认env_check.pyShape 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方案 │ │ └─ 不建议迁移阻塞项过多或无法绕过→ 说明原因 │ └────────────────────────────────────────────────────────────┘