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.txt2.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.5
mig_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:04.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一致，可按项目改写数值与指标名：
- loss 或其它约定指标改善不明显时：在资源允许下适当增大 iteration（或 epoch /
max_steps），并记录每次调整与 tensorboard/日志路径。 - 若累计 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），仅供参考