---
name: ascend-cv-delivery
description: 面向 ModelArts 上的昇腾 NPU，交付 YOLO、RT-DETR 目标检测流程，包括本地数据与权重、训练及评估、ONNX 导出、ATC 转 OM、pyACL 推理服务和分阶段验收。用于生成或适配这条 CV 链路；仅构建通用镜像时使用 ascend-npu-image-build，不用于 LLM 或未经适配的其他模型任务。
license: MIT
metadata:
  version: 0.1.0
  author: xuopoj
  homepage: https://github.com/xuopoj/ascend-delivery
---

# ModelArts 昇腾 CV 训练与推理交付

训练部分面向 **ModelArts 训练作业中的昇腾 NPU**，覆盖 YOLO / RT-DETR。
本技能与 `ascend-llm-training` 独立：LLaMA-Factory / ms-swift 大模型训练使用后者。
将目标检测需求整理为训练、转换、推理三个可独立交付的阶段。
当前模板仅面向 Ultralytics YOLO 检测模型和 RT-DETR；分类、分割、姿态、
其他 YOLO 输出布局或其他框架需要单独适配，不能仅换权重后宣称支持。

## 先确认目标

确认用户需要哪些阶段，不必为已有 OM 的客户重新准备训练环境。
收集模型架构、框架版本、训练芯片与推理芯片的确切 SoC、CPU 架构、
ModelArts 训练作业配置，或推理阶段的 ModelArts 推理 1.0 / 推理 2.0 / 独立 Docker、
网络条件、已选基础镜像，
以及代码、数据、权重、本地输出的挂载路径。A3 的 ModelArts 推理只使用 2.0。
缺少信息时先推进独立工作，记录缺口，不推断 SoC、版本配套或设备可用性。

## 按需读取

| 用户任务 | 读取内容 | 可复制资产 |
|---|---|---|
| 制作镜像 | [references/images.md](references/images.md) | `assets/images/` |
| 准备数据、训练或评估 | [references/training.md](references/training.md) | `assets/train.py` |
| 导出 ONNX、转换 OM | [references/conversion.md](references/conversion.md) | `assets/train.py`、`assets/convert_om.py` |
| 部署检测 HTTP 服务 | [references/serving.md](references/serving.md) | `assets/om_infer.py`、`assets/serve.py` |
| 验收、分享或追溯来源 | [references/validation.md](references/validation.md) | 阶段状态与交付要求 |

## 生成交付目录

按所需阶段复制并适配资产，不依赖本技能目录之外的源码。
模型权重、训练数据和 CANN 安装包由用户提供，默认挂载，不放入技能或 ZIP。
输出中文 README、所需启动命令和配置、镜像信息及 `meta.yaml`：至少包含
来源、生成日期、模型与框架版本、架构 / SoC、挂载约定、各阶段验证状态和缺口。
`verified: false` 直到所声称的目标环境端到端验收通过。

ModelArts 训练通过 OBS 配置输入通道时，容器路径以
`/home/ma-user/modelarts/inputs/` 为基础目录，使用页面实际分配的通道名称，
例如 `MODEL_0`、`DATA_1`；不得默认使用 `/model`、`/data` 或 `/scripts`。
代码使用训练作业的“代码目录”，容器位置为 `/home/ma-user/modelarts/user-job-dir`，
不额外配置 SCRIPTS 输入通道；.sh 入口使用 bash 执行。
同步修改启动参数和数据 YAML 的 `path`，不能只改 `--data` 文件位置。
训练输出使用 `/home/ma-user/modelarts/outputs/OUTPUT_0`，可在其下按运行名建子目录。
独立 Docker 可自定义挂载；确认输出可写及平台持久化设置。
先写本地盘，再按客户平台约定同步产物；不得把 OBS 挂载默认为可写本地盘。

## 不可丢失的约束

- 每个阶段只承担自己的职责：训练输出权重 / ONNX，ATC 输出目标 SoC 的 OM，
  推理读取 OM。转换通过不等于模型正确，也不等于已在目标卡上运行。
- 禁止隐式下载和静默 CPU 回退。所有模型 / 数据输入指向已存在的本地文件；
  用户明确指定 CPU 时才用 CPU。运行时不安装缺失依赖。
- 不覆盖基础镜像已验证的 torch / torch_npu / CANN；补包后检查版本是否变化。
  不自动给所有框架注入全局 `transfer_to_npu`，仅在对应版本确实需要时适配。
- ONNX 输入、输出布局和精度属于模型契约。模板采用静态输入方案，不将其
  限制概括为“ATC 永远不支持动态输入”。按实际导出图核对后处理。
- 单实例 pyACL 模型只在明确的上下文和并发策略下使用；模板串行执行。
  启动器应传递退出信号、正确释放资源，失败不得继续宣称服务就绪。
- 分享前删除项目路径、凭证和现场配置；标明代码来源与依赖许可证。
  不把 来源示例 的历史记录当成新生成布局的验证证据。