CANN/cannbot-skills科学模型NPU迁移指南

迁移后训练与推理说明（Mig_Readme）

【免费下载链接】cannbot-skillsCANNBot 是面向 CANN 开发的用于提升开发效率的系列智能体，本仓库为其提供可复用的 Skills 模块。项目地址: https://gitcode.com/cann/cannbot-skills

用途：说明迁移完成后如何在当前仓库/环境中做训练（若适用）与推理，便于他人按文档复现。
若本项目仅推理、不涉及 NPU 训练，删除或标注「不适用」对应章节即可。

1. 适用范围

  • 仓库路径：
  • 推理入口：（脚本路径或命令）
  • 训练入口：（如有；无则写「本项目不在昇腾上训练」）

2. 环境准备

2.1 依赖安装

# 示例：按项目实际修改 # pip install -r requirements.txt

2.2 昇腾/CANN 环境变量

以当前 CANN 安装文档为准，下列仅为占位。

# source <CANN_INSTALL_PATH>/set_env.sh # 或项目内自定义 CANN 激活脚本路径（非本 skill 的 environment 快照文件）：

2.3 设备检查

在IDE/沙箱内执行时，npu-smi info与框架 Ascend 插件导入可能检测不到设备或版本（无输出、命令不存在、偶发失败）；须在本机终端（沙箱外）用同一组检查复检后再认定环境是否就绪，并写入mig_docs/working/environment.md（与 skillpart-03§4.0.1 阶段 B 一致）。

npu-smi info python -c "import torch; import torch_npu; print('torch_npu ok')" # 或 MindSpore 等等价检查

2.4 环境准备目标清单（与environment.md）

本仓库不再附带可执行的「一键环境配置」脚本；只约定目标，详见docs/environment-setup-objectives.md（与 skillpart-03§4.0、§4.2 一致）。

交叉引用：

  • 数据根目录 / 短测·冒烟路径：须与§3.1数据集对照表中对应行的本地路径一致（或写明团队约定的映射关系）；下载与目录约定见§3.2。
  • 环境快照：见§2.5mig_docs/working/environment.md；命令级自检示例（若需要）见 skill part-07-commands.md。

2.5 环境快照environment.md（推荐）

  • 路径：固定为mig_docs/working/environment.md。迁移开始时应已存在mig_docs/（无则创建）。
  • 历史快照：若存在旧版mig_docs/env.md或误命名的env.md.exe，将有效内容合并入mig_docs/working/environment.md后删除旧文件，避免双份并存或二进制合规问题。
  • 已有快照文件：若需刷新内容，应重新执行part-03门禁与docs/environment-setup-objectives.md所列检测目标，并覆盖更新environment.md（避免与过期事实混用）。

2.6 基线侧 GPU 训练与推理调用接口（无完整训练日志时补齐）

何时需要本节：项目内已有完整训练日志且指标满足Compare.md§2.1 时，直接引用日志，本节可填N/A或仅补日志中缺失的推理性能项。
填写时机（推荐）：短测、冒烟、约定性能路径已在昇腾 NPU跑通并写入Compare.md（至少 NPU 列或等价日志）之后；若无可用训练日志，在本节给出GPU（默认 baseline）上的可复现入口，供用户自行执行并回填Compare.md基线列。
目的：与§4～§5的 NPU 推理/训练说明对称，专门承载「非昇腾、默认 GPU」基线命令，避免与 NPU 侧入口混在同一小节难以检索。

场景设备入口（脚本或命令）关键参数（如--device、CUDA_VISIBLE_DEVICES、batch、权重路径）与 §3.1 哪一行数据集对齐备注
推理 baseline（默认）GPU
训练 baseline（若适用，默认）GPU
CPU 对照（可选）CPU
  • 环境：GPU 栈的 conda/venv、框架版本（与Compare.md§2.1 一致处请互链）。
  • 与 Golden：同一固定输入时，建议先落 NPU 输出，再由用户按上表在GPU（或日志已含基线则引用日志）补跑基线，误差阈值见Compare.md§3.1。

3. 数据与预处理

交叉引用：

  • 数据根目录自检（见§2.4）：须与本章§3.1表中「本地路径」对齐（或写明相对关系）。
  • 基线 GPU 调用：见§2.6（无完整训练日志时默认 GPU；有日志则优先引用；由用户自行执行补采）。
  • 迁移报告中的数据集摘要：见Mig_report.md§2.1。
  • 精度/性能表中的数据集列：见Compare.md§2.4。
  • 命令与自检模板：见 skill part-07-commands.md。

3.1 数据集与测试用途对照（必填）

说明分别在哪个数据集上完成短测、冒烟、训练与推理；若某类测试与另一项共用同一数据集，须写明「与 xxx 相同」并给出唯一数据源标识（名称、版本、校验和）。

测试类型使用的数据集子集/规模（如样本数、划分）与基线/全量是否一致本地路径（相对仓库根或绝对路径）
短测推理向：最小前向（如 1～3 样本）。训练向（若适用，代码迁移后）：少 step/短子集上观测loss是否稳定明显下降约 30%～50%（相对短测起点）；达到即停止本阶段短测，不重复多轮（见 skillpart-05 §8.1.1、part-02 §3.6）
冒烟测试（推理 smoke：跑通、shape/无 NaN）
Golden / 数值对齐（若单独数据集）
全量精度 / 性能评测
训练（若适用）
推理（线上/验收口径）
  • 训练数据：（路径、格式、划分；与上表「训练」行一致）
  • 推理输入：（尺寸、NCHW/NHWC、归一化参数；须与Mig_report.md中 IO 契约一致；与上表「推理」行一致）

3.2 数据集获取方式与下载过程（必填）

按实际来源填写其一或多项；无公开链接时写「内网/需权限」并给出申请入口或对接人（勿写账号密码）。

  • 官方名称 / 版本 / 许可证：
  • 下载入口：（官网、论文附录、Hugging Face、ModelScope、Kaggle、企业内部对象存储等 URL 或文档章节）
  • 推荐下载方式：
    • 浏览器：步骤摘要（注册、同意协议、获取直链等）
    • 命令行：（示例，按项目替换）
# 示例：wget / curl / huggingface-cli / git lfs 等，二选一或组合 # wget -O <local_archive> "<download_url>" # huggingface-cli download <repo_id> --local-dir ./data/<name>
  • 校验：（可选但强烈建议）sha256sum/certutil -hashfile等与官方公布校验值比对
  • 解压与目录结构：（解压命令、期望得到的顶层目录名）
  • 与代码/脚本的对接：环境变量名或配置文件键（如DATA_ROOT=）；若推理/训练命令使用--input或数据根目录，须与§3.1一致。
  • 与数据路径自检：环境准备目标清单中的「数据路径核对」仅做存在性/可读性类结论；取值须与§3.1中用于环境自检或冒烟的数据路径一致，并在environment.md或Mig_report中互链。
  • 脱敏说明：若不能提交真实路径，写占位规则与团队内约定路径

4. 推理（部署后）

4.1 推理命令示例

# 示例：替换为实际 NPU 推理命令 # python infer_npu.py --config configs/infer_npu.yaml --checkpoint <path> --device npu:0

4.2 参数说明

参数含义默认值

4.3 checkpoint / 权重路径

  • 生产/测试使用的权重或 checkpoint 路径：
  • 与Mig_report.md中代码级迁移要点对应关系：

5. 训练（若在昇腾或混合环境训练）

若无训练，本节可写：本项目推理部署在昇腾，训练仍在 GPU/CPU，见原训练文档。

5.1 启动命令

# 示例

5.2 与迁移前差异

  • 分布式/单卡策略：
  • 精度策略（AMP/FP16）：
  • checkpoint 保存与加载流程：

5.3 训练迭代策略与「步数不够 vs 代码/模型问题」（推荐默认）

与训练短测区分：part-05 §8.1.1的训练短测以loss相对起点稳定下降约 30%～50%为短测通过并即停，禁止同配置下多余重复短测。本节仅针对正式训练仍长期不明显改善时的加iteration与>500步排查；勿用本节对「已通过短测」再堆短跑。

与 skill part-05-performance-accuracy.md§8.2一致，可按项目改写数值与指标名：

  1. loss 或其它约定指标改善不明显时：在资源允许下适当增大 iteration（或 epoch /max_steps），并记录每次调整与 tensorboard/日志路径。
  2. 若累计 iteration（或等价总优化步）> 500 仍无明显效果：按默认准则视为高概率模型实现或训练代码问题，应检查并修复代码（数据与标签、loss、学习率、模型 head、NPU 相关替换层等），而非继续盲目加步数；结论记入Mig_report.md§7。

本项目约定（可覆盖上条默认）：

  • 实际采用的「无明显改善」判定指标：（如验证 loss / mAP / …）
  • 实际累计步数上限或等价阈值：（若与 500 不同请写明）
  • 相关训练命令与日志路径：

6. 常见问题

现象可能原因处理
NPU 初始化或权重加载失败CANN/驱动与框架插件版本不一致对齐版本并重试
输出与基线不一致预处理或输出头接错对照 Mig_report IO 与 Golden 样本
训练已加大 iteration 仍 loss/指标不动步数已 >500（或本项目 §5.3 约定阈值）仍无改善按 §5.3 转查模型与代码；见Mig_report§7

7. 可选测试策略（由本机检测结果决定）

  • 可直接执行：NPU/框架插件/依赖/数据均已就绪，按第 4～5 节直接跑推理或训练 smoke。
  • 暂不执行：任一前置条件缺失，先按docs/environment-setup-objectives.md与part-03补齐环境并更新environment.md，再执行测试。
  • 建议记录：在Mig_report.md中附上检测结果表（检测项、通过/失败、补齐动作）。

8. 相关文档

  • Mig_report.md — 迁移变更与产物
  • Compare.md — 精度与性能对比
  • Summary.md — 测试完成后归档总结
  • environment.md— 环境快照（本 skill 内为占位骨架，复制到目标工程后覆盖填写）
  • environment-setup-objectives.md、docs-index.md— 环境准备操作目标（无仓库内一键脚本）

9. 测试后归档指引（交接必读）

  • 训练/推理测试完成后，将最终结论回填到Mig_report.md的“归档总结”章节。
  • 若本项目仅推理，请在归档中明确“训练不适用”的原因与替代验证方式。
  • 将可直接复现的最终命令、模型版本、数据版本固定到文档，避免口头交接。
  • 若存在异常或回滚，确保Mig_report.md§7与归档结论一致。

【免费下载链接】cannbot-skillsCANNBot 是面向 CANN 开发的用于提升开发效率的系列智能体，本仓库为其提供可复用的 Skills 模块。项目地址: https://gitcode.com/cann/cannbot-skills

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考