npu-migration-ascend

name	npu-migration-ascend
description	生成面向华为 Ascend（昇腾）设备的 NPU 迁移流程，包括环境与版本校验、模型导出/编译生成 OM、INT8 校准与量化、部署验证以及精度/性能对比。Use when the user mentions NPU迁移、昇腾、Ascend、ATC、OM、MindIR、StreamManager，或谈到模型编译/量化、精度回归与延迟吞吐评估。
argument-hint	[model-format] [soc-or-chip] [FP16|INT8]

NPU 迁移到昇腾（Ascend）

Additional resources

• 端到端流程的 Mermaid 图见 WorkFlow.md（与正文步骤一致，便于单独预览/分享）。
• 交付文档模板目录 mig_docs/：Mig_report.md（迁移变更与产物）、Mig_Readme.md（迁移后训练/推理）、Compare.md（性能与精度对比）。详见 mig_docs/README.md。

Instructions

当用户要把“现有模型/推理链路迁移到 NPU（昇腾/Ascend）”时，生成一个端到端迁移方案：环境校验 -> 导出/编译生成 OM ->（可选）INT8 校准与量化 -> 部署运行与基准评测 -> 精度/性能回归报告。并在关键节点给出命令模板（由 agent 按用户环境补齐参数）。

当用户通过参数调用本 skill（例如 /npu-migration-ascend ...）时：

• 优先从输入中抽取：$ARGUMENTS[0]=模型格式（MindSpore/ONNX/其他）、$ARGUMENTS[1]=目标芯片/型号（如 310P/910 等）、$ARGUMENTS[2]=目标精度（FP16/INT8）
• 若缺少关键参数，则像“快速开始”一样发起补充提问，避免直接编造命令。

1) 先收集关键信息（缺什么就问什么）

请优先向用户确认以下要点（没有就让 agent 采用合理默认，并在最后列出“仍需确认项”）：

• 目标硬件：Ascend 型号（例如 310/310P/910 等）、是否支持动态 shape
• 软件栈版本：驱动版本、CANN 版本、推理/编译工具链版本（至少能拿到 npu-smi 与 atc --version 输出）
• 模型来源与格式：框架（MindSpore/ONNX/其他）、输入/输出名称与 shape、算子是否包含自定义算子
• 精度与性能目标：允许的精度下降范围、指标口径（mAP/Top1/MAE 等）、延迟/吞吐目标（batch size、测量方式）
• 数据：用于 INT8 校准的数据集/样本数量；用于精度评估的数据集与划分（最好与基线一致）
• 工程与依赖：仓库中 requirements.txt、environment.yml、setup.sh、Dockerfile 等；基线推理入口脚本/命令；Python 版本与关键库版本（与基线一致）
• 部署形态：板卡/服务器、是否容器、推理服务框架（StreamManager / 自研 C++/Python / 其他）

安全与合规：提醒用户不要在对话中粘贴密钥、内网地址、未脱敏的客户数据；校准集与日志分享前做脱敏。

快速开始（最短可执行路径）

如果用户希望你“立刻给可走的流程”，至少请补齐/确认这 3 项，然后直接进入“编译生成 OM”分支：

1. 模型格式（MindSpore 或 ONNX）
2. 目标芯片/型号（用于 soc_version/编译目标选择）
3. 精度目标（FP16 或 INT8；若 INT8 则需要校准数据集来源/规模）

2) 定义成功标准与基线（防止“迁移后没人知道好不好”）

让 agent 输出一段“成功标准”并要求基线对齐：

1. 明确基线环境（CPU/GPU 原推理栈、版本、batch size）
2. 记录基线的精度与性能指标（至少一套可复现的输入）
3. 明确回归判定规则（例如：精度不低于基线的 99%，延迟提升不超过 X ms 等）

3) 可编译性预判（编译前“尽调”和降风险）

目标：在真正 atc/生成 OM 之前，尽可能把“会编不过/编得过但跑不对/精度和性能大幅异常”的根因先分类并给出最小验证路径。

预判输出应包含 4 部分内容：编译链路、输入输出契约、算子/后处理风险、最小验证计划。

3.1 编译链路选择与输入输出契约

让 agent 明确并写出“本次编译走哪条链路”，例如：

• MindSpore -> 导出 MindIR -> 编译生成 OM
• ONNX -> atc 编译生成 OM
• 其他格式 ->（先转换到编译链路支持的中间格式）

同时让 agent 对“编译时必须一致”的信息做核对并列清单：

• 输入 tensor 名称、顺序（多输入模型尤其重要）
• 输入 shape（固定 or 动态）与维度排列（NCHW/NHWC）
• 输入 dtype（FP32/FP16/INT8 calibration 相关数据类型要求）
• 输出 tensor 名称与 shape（避免“编译成功但推理结果喂错后处理”的情况）

3.2 算子/后处理风险预判（先定位“最可能失败的点”）

在不具备完整离线工具链评估的前提下，agent 需要基于模型结构做“高概率风险点”分类，并给出建议的验证方式：

• 自定义算子/自研算子：判断是否已有昇腾侧等价实现；如没有，给出“替换/回退”方案优先级
• 复杂后处理链路（如 NMS、解码、重排）：判断是否建议放在编译链路内还是推理侧外置（CPU/GPU 后处理）
• 动态 shape 相关算子：标注哪些算子/路径可能对动态维度敏感（从而导致编译失败或性能下降）
• 精度路径差异：如果要走 INT8，预判哪些算子可能对量化不友好（容易造成精度大幅下降）

3.3 生成“最小可编译”验证计划（从小到大迭代）

让 agent 给出一个分阶段计划，避免一次编译就把问题扩大化：

• Phase 1：用最小静态 shape / 最小 batch 尝试生成 OM（验证“能编过 + 能加载推理”）
• Phase 2：在不改变输入语义的前提下扩展到目标 batch 与目标 shape 策略
• Phase 3：再探索 INT8（如果目标包含 INT8）或更激进的优化选项

Phase 计划要写明：

• 每个 Phase 要验证的成功条件（至少 1 条“编译成功 + 运行能产生正确输出”的判定）
• 每个 Phase 如果失败，优先调整的顺序（例如：tensor name/shape -> precision -> 动态策略 -> 算子替换/回退）

3.4 INT8（量化）预判的额外要求（如果目标精度=INT8）

当精度目标是 INT8 时，agent 除了以上内容，还应额外输出：

• 校准集是否代表推理场景（数据分布、预处理一致性）
• 校准样本数量起步建议（例如 N>=100，并说明按模型复杂度调整）
• 校准/量化失败时的回溯路径（优先从预处理对齐与校准数据开始排查）

4) 准备环境并验证（把“环境问题”从模型问题里切开）

让 agent 按下面顺序做环境检查，并把命令与关键结果回填到最终输出里：

1. GPU/NPU 驱动可见性：使用 npu-smi 或等价命令检查设备
2. 编译工具可用性：确认 atc 存在且版本正确
3. 运行时库路径/环境变量就绪（以 CANN 安装说明为准）

环境信息快照（建议写入迁移报告，便于复现与排障）：

项	值
机器/板卡型号
npu-smi 关键信息（驱动/设备）
CANN / atc --version
推理运行时版本（若与编译分离）
目标 soc_version 与依据

5) 导出/编译模型生成 OM（核心步骤）

根据用户提供的模型格式选择路径，agent 必须先做“分支选择”再给命令：

• 若模型是 MindSpore：MindIR 导出 -> 编译生成 OM
• 若模型是 ONNX：ONNX -> atc 编译生成 OM
• 若模型是其他格式：先转到 ONNX 或编译器支持的中间格式（agent 需要说明采用的转换步骤与风险点）

编译时在输出里强制包含：

• precision 选择（FP16 或 INT8）
• 输入 shape 策略（固定/动态）
• soc_version/目标芯片相关参数（由用户或 atc/环境推断）
• 指定输入/输出 tensor 名称（避免“模型能编但推理对不上”的问题）

编译前模型检查（ONNX 尤其建议）：

• 用 Netron / onnx 等工具核对 graph 输入输出名、维度、dtype；多输出时列出每个输出用途（便于后处理对齐）
• 若来自 PyTorch/TF 导出：记录 opset 版本 与导出脚本版本，避免“同文件不同导出参数”导致不可比

soc_version 填写原则：必须与目标硬件及当前 CANN 文档一致；不确定时让 agent 要求用户提供板卡型号 + 官方对照表或历史成功编译命令中的取值，避免猜测。

编译后最小验证（在投入大规模评测前）：

1. OM 能成功加载到目标推理路径（无版本/路径类错误）
2. 使用 1～3 个固定输入 跑通一次前向，保存输出 shape 与数值范围（是否与基线同一量级）
3. 将完整 atc 命令行、生成日志路径、OM 文件路径写入迁移记录，便于回滚与对比

产物与命名建议（便于多轮迭代）：

• 目录或文件名中包含：模型名、soc_version、precision、shape 策略、日期/迭代号
• 保留：原始 MindIR/ONNX、量化配置、OM、对应 atc 完整命令与日志

6) INT8 校准与量化（精度回归最常见来源）

让 agent 针对 INT8 给出可执行的校准流程与检查清单：

• 校准数据代表性检查（与精度评估数据分布尽量一致）
• 校准数据量建议（给一个起步范围，如 N>=100 起步，并提醒按模型复杂度与官方建议调整）
• 若精度下降：从量化策略与校准配置排查（例如：操作级精度、校准集/样本数量、是否启用 per-channel 等）
• 校准后是否需要对齐预处理（均值方差/缩放/通道顺序），并要求输出对比清单

7) 性能评估（把延迟/吞吐变成可复现的对比）

目标：在同一输入分布、同一 batch/并发设置、同一测量口径下，给出可与基线对比的延迟与吞吐数据；并在性能不达标时能快速定位瓶颈属于预处理/后处理/IO/推理内核哪一段。

让 agent 在这一节必须输出 5 部分内容：测量范围、实验设置、指标口径、基准复现、性能报告模板。

7.1 测量范围（明确你在算哪段时间）

让 agent 选择并写清楚性能测量口径，至少包含下列一种或多种（推荐“分段”）：

• 端到端延迟：从“输入准备完成”到“输出准备完成”
• 推理纯耗时：只统计模型执行/设备侧推理时间（不含 Python/CPU 后处理）
• 预处理/后处理耗时（如果你的工程里有这两段）

要求：性能报告中要明确“本结果包含/不包含哪些环节”，避免口径不一致导致误判。

7.2 实验设置（减少波动的关键）

让 agent 给出并坚持以下实验设置，并将其写入输出（便于复现）：

• 环境固定：同一台机器，同一驱动/同一 CANN/同一 OM 与配置
• batch size：列出要测的 batch 列表（至少包含 1 和目标 batch）
• 并发/线程：说明是单请求顺序还是并发（若不确定，先从单请求测起）
• warmup：给出 warmup 次数建议（例如 10 次起步）并说明原因（预热缓存/编译初始化）
• 采样次数：给出 iterations 建议（例如 100 次起步）与统计指标（p50/p95/平均）

7.3 指标口径（建议统一成“延迟 + 吞吐”双指标）

让 agent 使用以下指标集合并在报告里逐项填充（没有也要给出计算方法/公式）：

• Latency：p50/p95（单位 ms），以及平均值（可选）
• Throughput：吞吐（如 images/s 或 samples/s），并注明按 batch 计算还是按请求计算
• 可选扩展：显存/内存占用、失败重试次数（如果工程支持）

7.4 基准复现（保证“测出来的就是同一个东西”）

让 agent 给出“可复现输入与数据一致性”要求：

• 使用与精度评估相同的输入数据集划分与预处理配置
• 固定随机种子（若适用）
• 输入数据的尺寸/通道顺序/归一化参数与训练/基线保持一致
• 记录输出的校验方法（例如抽样对比 top1/mAP 或输出统计特征），确保性能测试没有“跑偏数据”

7.5 性能报告模板（agent 必须按字段输出）

要求 agent 在最终输出中给出类似下面的结构（可用 Markdown 表格呈现）：

• 基线 vs 迁移后：延迟 p50/p95、吞吐、batch size、测量口径（端到端/纯推理/分段）
• 对比结论：是否达到目标（通过/不通过）
• 瓶颈定位建议：优先按“预处理/后处理/IO/推理内核”给出一到两个最可能原因

同时要求：强制保存编译/运行日志与 profiling 结果（如果可用），用于回归定位。

8) 精度对比与回归报告（迁移是否成功）

要求 agent 给出一份对比报告框架（即使没有最终数值，也要给出结构与需要的字段）：

• 与基线差异：精度指标、主要错误类型（如果能观察到）
• 性能差异：延迟与吞吐、瓶颈推测（前后处理/IO/批大小）
• 结论：通过/不通过/需调整的具体项

数值一致性（在跑全量指标前强烈建议）：

• Golden 样本：同一批固定输入（含预处理后的 tensor），在基线与 NPU 路径上各跑一次
• 对比：输出 tensor 的 shape、dtype、NaN/Inf、均值/方差/最大绝对误差；分类任务可对比 top-1 是否一致（小批量）
• 若数值差异大：优先查 预处理、输入 layout、后处理是否接错输出头，再查量化与算子替换

8.1 模型级训练/推理测试（与「精度/性能对比」的关系）

精度、延迟、吞吐对比（见第 7～8 节与 mig_docs/Compare.md）主要是在数据集或基准集上算业务指标，回答「效果与速度够不够」。

模型本身的训练/推理测试侧重「实现与图是否健康、能否稳定跑通」，通常在更小粒度上做，与上者互补，不是替代关系：

类型	典型内容	回答的问题
推理侧（模型级）	固定输入的 smoke：shape/dtype、无 NaN/Inf、输出范围合理；Golden 与基线逐元素或统计量对比；多输出头是否接对	推理链路、预处理、导出/编译是否与预期一致
训练侧（模型级，若迁移后仍训练）	单 batch 或极少 step：前向+反向+优化器一步是否跑通；loss 是否为有限值；梯度是否异常（全零/爆炸）；checkpoint 保存再加载是否一致	训练脚本与 NPU 适配层是否可用，而非「收敛好不好」
自动化（可选）	pytest/CI 中的小型用例：CPU 参考 vs NPU 同输入输出一致性（允许量化误差阈值）	回归时快速发现破坏性变更

让 agent 根据项目是否「仅推理」或「仍训练」给出建议，并在 Mig_report.md 的验证摘要中勾选是否已做：推理 smoke、Golden、训练 smoke（若适用）；全量精度/性能仍以 Compare.md 为准。

9) 风险点与回滚策略（让失败可控）

要求 agent 给出回滚与迭代建议：

• 保留基线模型与输入数据版本
• 保留“可编译但未必最优”的中间产物（MindIR/ONNX/quant 配置/OM）
• 出现编译失败/精度显著下降时，优先调整的顺序（环境 -> 模型格式/shape -> precision/量化 -> 后处理）
• 若存在算子不支持：优先走“算子替换/回退实现”，再考虑更换精度或动态 shape 设置
• 版本回滚：保留“上一版可工作的 OM + 对应 atc 命令 + 环境快照”，新 OM 验证通过后再淘汰旧产物

Command Templates（命令模板，agent 需要按版本替换参数）

说明：昇腾/ATC/编译器参数会随 CANN 版本与工具链变化。agent 在给出最终命令前，应先让用户确认 CANN/atc 版本（或从 atc --version 推断），并只在确定的参数上写死，其余用占位符。

环境验证

# 设备是否可见（以系统命令为准；不同安装包可能有等价命令）
npu-smi info

# 验证 atc 存在与版本
atc --version

编译：ONNX -> OM（示例模板）

atc --model="<path/to/model.onnx>" \
  --framework=<ONNX_framework_id> \
  --output="<path/to/output_dir>" \
  --input_format=<NCHW_or_NHWC> \
  --input_shape="<input_name>:<shape>" \
  --soc_version="<target_soc>" \
  --precision=<FP16_or_INT8>

若启用 INT8 量化/校准，agent 需要补上与你的 CANN 版本匹配的 calib/quant 参数，并明确“这些参数来自哪里”（例如配置文件路径、量化策略文件）。

编译：MindIR -> OM（示例模板）

atc --model="<path/to/model.mindir>" \
  --framework=<MINDIR_framework_id> \
  --output="<path/to/output_dir>" \
  --soc_version="<target_soc>" \
  --precision=<FP16_or_INT8>

部署/基准测试（示例模板）

# 具体工具/入口取决于你使用的推理框架（StreamManager / 推理样例 / 自研）
# agent 应根据当前工程选择“可复现”的基准命令与日志路径。
benchmark_app --model="<path/to/model.om>" --input="<path/to/input>" --batch_size=<N>

Checklist（可直接复制粘贴给进度）

Task Progress:

• 明确目标硬件与 CANN/驱动/工具链版本
• 收集工程依赖与基线推理入口（requirements/setup/脚本）
• 记录基线：精度指标 + 延迟/吞吐（可复现输入）
• 确认模型格式与输入/输出 shape（固定/动态策略）
• 进行可编译性预判（算子/后处理/自定义算子）
• 填写环境信息快照表（见第 4 节）
• 环境验证：npu-smi、atc --version、运行时依赖
• FP16/INT8 路径确定（精度目标先行）
• ONNX/MindIR：核对输入输出名、opset、导出版本
• 生成 OM（导出/编译命令已填充关键参数）
• 编译后最小验证：加载 OM + 少量样本前向 + 记录产物路径与日志
• INT8：校准数据准备完成 + 校准流程可复现
• Golden 样本：基线与 NPU 数值一致性抽查
• （可选）模型级推理 smoke：固定输入、输出 shape/无 NaN
• （若迁移后仍训练）模型级训练 smoke：单 batch 前向+反向一步或极少 step
• 部署运行：模型能稳定加载、无异常日志
• 精度对比：与基线差异在允许范围内
• 性能评估：p50/p95（或约定指标）与吞吐统计方法一致
• 形成回归结论文档及迁移报告（含问题材料清单，便于复盘）
• 填写并落盘 mig_docs/ 三份文档（见下方「规范输出」）

mig_docs 规范输出（交付物）

迁移类任务结束时，agent 应指导或直接在用户仓库中维护一套 mig_docs/，与 skill 内模板结构一致（可从本 skill 目录 复制 mig_docs/ 到项目根目录或 docs/mig_docs/）。

文件	必填内容要点
mig_docs/Mig_report.md	元信息、成功标准、环境快照、模型/OM 路径、完整 atc 命令、代码/配置/依赖变更清单、算子与后处理变更、验证勾选、风险与回滚、日志路径
mig_docs/Mig_Readme.md	环境准备（依赖、CANN env、设备检查）、数据与预处理（与 IO 契约一致）、推理命令与参数表；若存在 NPU 训练则写训练入口与与迁移前差异，否则明确「仅推理」
mig_docs/Compare.md	基线 vs 昇腾环境表、测量口径（延迟定义、warmup、iter、p50/p95、吞吐定义）、精度对比表、Golden 样本摘要、性能对比表、瓶颈与原始日志路径

命名约定：迁移报告文件名为 Mig_report.md（英文 report，避免拼写为 reprot）。

对话中的输出规范（除写文件外，回复正文应包含）：

1. 说明三份文档是否已创建/更新及相对仓库根路径（例如 mig_docs/Mig_report.md）。
2. 用简短摘要覆盖：Mig_report 中的主要变更行数或关键文件列表；Compare 中的达标结论一行话。
3. 若用户未指定路径，默认建议：项目根目录下的 mig_docs/。

Output Format（要求 agent 按以下结构输出）

最终回复建议包含：

1. 一段“迁移结论/下一步”
2. 迁移步骤清单（Checklist）
3. mig_docs/ 交付状态：三份文档路径 + 是否已按模板填关键段（环境快照、ATC 命令、变更清单、对比口径）
4. 可执行的命令（命令模板 + 已知参数填充 + 待确认参数列表）
5. 环境信息快照表（第 4 节）与产物命名/路径说明
6. 精度/性能验证计划（含 Golden 样本与全量指标；对比口径与回归规则）
7. 风险点与回滚策略

Examples（触发与使用）

Example 1 Input: “我有一个 MindSpore 目标检测模型，要部署到昇腾 310P。想做 INT8，加速同时尽量不降精度。” Output: 收集数据与版本（对齐输入预处理）-> MindIR 导出 -> INT8 校准/量化 -> atc 编译生成 OM -> 部署运行与基准评测 -> 精度/延迟回归报告（含错误定位路径）-> 在项目根目录维护 mig_docs/Mig_report.md、Mig_Readme.md、Compare.md。

Example 2 Input: “我只有 ONNX 模型，迁移到 Ascend 跑推理，并希望给出通用 ATC 编译命令。” Output: 要求确认 atc --version、soc_version、输入输出 tensor 名称与 shape -> 给出 ONNX->OM 编译命令模板（按 CANN 补齐参数）-> 部署与基准命令模板 -> 给出“编译失败/运行失败/精度回退”排查路径 -> 将完整命令与对比结果写入 mig_docs/ 三份模板。

Troubleshooting（当事情不顺时怎么做）

1. 编译失败：先核对输入 shape 与 tensor 名称；再检查不支持算子与后处理链路；最后调整动态 shape/固定 batch/precision 的顺序迭代。
2. 运行加载失败：优先检查 OM 与运行时/驱动版本兼容性，以及环境变量/库路径是否就绪；同时保留运行日志用于对比。
3. 精度大幅下降（尤其 INT8）：核对预处理对齐（缩放/均值方差/通道顺序）；检查校准集代表性与样本数量；再回看量化配置与需要的 per-channel/op 级策略。
4. 性能不达标：统一测量口径（warmup、p50/p95、batch、输入数据通道），再定位瓶颈（IO/前后处理/数据搬运/批大小/并发）。

自助诊断 / 问题上报时应收集的材料

让 agent 在用户求助或内部复盘时，按清单索取或整理（脱敏后）：

• 完整 atc 命令行（含所有参数）与 编译日志（或失败时的首尾错误段）
• atc --version、npu-smi 输出、目标 soc_version 与硬件型号
• 模型侧：ONNX/MindIR 路径、输入输出 名称与 shape、是否动态维度、opset（ONNX）
• 若运行失败：加载 OM 的报错栈、推理框架与版本、相关环境变量
• 若精度问题：Golden 样本上基线 vs NPU 的输出对比摘要（shape、误差统计）

常见编译失败归类（便于快速定性）：

• tensor 名/shape 与模型不一致：input_shape / 多输入顺序错误
• 不支持的算子或组合：日志中出现具体 op 名；考虑替换子图或外置后处理
• 动态 shape / batch 策略：先固定最小 shape 验证链路，再恢复动态策略
• 精度路径与数据类型：INT8 需校准与配置齐全；可先 FP16 通路验证“非量化”是否正常