atc-model-converter

Files (13)

• SKILL.md
• AIPP_CONFIG.md · references/
• CANN_VERSIONS.md · references/
• EXAMPLE_README.md · references/
• FAQ.md · references/
• INFERENCE.md · references/
• PARAMETERS.md · references/
• check_env_enhanced.sh · scripts/
• compare_precision.py · scripts/
• export_onnx.py · scripts/
• get_onnx_info.py · scripts/
• infer_om.py · scripts/
• setup_env.sh · scripts/

SKILL.md (first lines)

# ATC Model Converter

华为昇腾 NPU 上完整的 **PT -> ONNX -> OM** 模型转换与端到端推理适配工具链。支持任意标准 PyTorch 或 ONNX 模型。

**支持的 CANN 版本：** 8.1.RC1, 8.3.RC1, 8.5.0+

> **⚠️ 环境兼容性警告：** Python **必须 ≤ 3.10**（推荐 3.10），NumPy **必须 < 2.0**，ONNX opset **推荐 11**。
> 违反这三条是最常见的转换失败原因。详见 [FAQ.md](references/FAQ.md)。

---

## 开始之前：用户必须提供的信息

> **Agent 在执行本 Skill 的任何 Workflow 之前，必须先向用户收集以下信息。**
> 缺少任何一项时，Agent 应主动询问用户，而不是猜测或跳过。

| 必需信息 | 说明 | 示例 |
|---------|------|------|
| **模型权重路径** | `.pt` / `.pth` / `.onnx` 文件的本地路径或下载地址 | `/home/user/models/yolo26n.pt` |
| **代码仓库地址** | 模型所属项目的 Git 仓库 URL 或本地路径 | `https://github.com/ultralytics/ultralytics` |

| 可选信息 | 说明 | 默认行为 |
|---------|------|---------|
| 目标任务类型 | 分类/检测/分割/姿态/OBB 等 | Agent 从代码仓中自动识别 |
| 目标输入尺寸 | 模型推理时的输入分辨率 | Agent 通过 Workflow 1 自动发现 |
| 测试图片/数据 | 用于验证端到端推理的样例输入 | Agent 使用随机数据或从仓库中寻找 |

**Agent 收集信息后的标准开场白模板：**

```
收到以下信息：
- 模型权重：<path>
- 代码仓库：<url_or_path>
- 任务类型：<type_or_待确认>

我将按以下流程执行：
1. 分析代码仓库，发现模型参数 (Workflow 1)
2. 导出 ONNX (Workflow 2)
3. ATC 转换为 OM (Workflow 3)
4. 端到端推理适配 (Workflow 4)
5. 精度与推理验证 (Workflow 5)
6. 生成可复现 README (Workflow 6)
```

---

## Workflow 1: 代码分析与参数发现 (Source Code Analysis & Parameter Discovery)

> **Anti-Hardcoding Rule (反硬编码铁律):**
> Agent 在执行本 Skill 时，**绝对禁止**猜测或使用任何"常见默认值"（如 640x640、224x224、batch_size=1）作为转换参数。
> 所有 `input_shape`、`input_names`、`opset_version` 等关键参数，**必须有用户项目代码层面的证据支撑**。
> 如果无法从代码中确认，必须明确询问用户，而不是静默填入默认值。

### Phase 1: 静态代码审查 (Static Analysis)

收到用户的项目路径后，Agent 应按以下优先级搜索代码线索，提取 `input_shape` 和预处理参数：

**1.1 搜索预处理管道 (Preprocessing Pipeline)**

在项目代码中搜索以下模式，提取目标分辨率：

```python
# 搜索关键词（按优先级排列）
cv2.resize(img, (W, H))                     # OpenCV resize -> 提取 (W, H)
transforms.Resize((H, W))                   # torchvision -> 提取 (H, W)，注意 HW 顺序
transforms.CenterCrop(size)                  # torchvision -> 提取 crop size
Image.resize((W, H))                         # PIL -> 提取 (W, H)
F.interpolate(x, size=(H, W))               # torch functional -> 提取 (H, W)
albumentations.Resize(height=H, width=W)     # albumentations -> 提取 H, W
```

```bash
# Agent 应执行的搜索命令示例
grep -rn "cv2.resize\|transforms.Resize\|Image.resize\|F.interpolate\|\.resize(" /path/to/project --include="*.py"
grep -rn "img_size\|image_size\|input_size\|imgsz\|resolution" /path/to/project --include="*.py" --include="*.yaml" --include="*.json"
```

**1.2 搜索配置入口 (Configuration Entry Points)**

查找 CLI 参数定义和配置文件中的 shape 信息：

```python
# argparse 定义中的线索
parser.add_argument('--img-size', type=int, default=640)      # -> input H/W = 640
parser.add_argument('--batch-size', type=int, default=1)      # -> batch dimension
parser.add_argument('--input-size', nargs=2, default=[224,224]) # -> H, W

# 配置文件中的线索 (.yaml / .json / .cfg)
input_size: [3, 224, 224]    # -> C, H, W
image_shape: [640, 640]      # -> H, W
```

```bash
# Agent 应执行的搜索命令示例
grep -rn "add_argument.*size\|add_argument.*shape\|add_argument.*resolution\|add_argument.*dim" /path/to/project --include="*.py"
find /path/to/project -name "*.yaml" -o -name "*.yml" -o -name "*.json" -o -name "*.cfg" | head -20
```

**1.3 搜索模型前向传播 (Model Forward Pass)**

查找代码中已有的 dummy_input 或 forward 函数签名：

```python
# 已有的导出代码
dummy_input = torch.randn(1, 3, 224, 224)   # -> 直接提取 shape
torch.onnx.export(model, dummy, ...)         # -> 查看 dummy 的定义

# forward 函数的类型注解或 docstring
def forward(self, x: Tensor) -> Tensor:
    """Args: x: (B, 3, H, W) input tensor"""  # -> 提取 channel=3

# 数据加载器中的线索
DataLoader(dataset, batch_size=8)            # -> batch dimension
```

```bash
# Agent 应执行的搜索命令示例
grep -rn "dummy_input\|dummy\|torch.randn\|torch.zeros\|torch.ones" /path/to/project --include="*.py"
grep -rn "def forward" /path/to/project --include="*.py"

From Ascend/agent-skills, MulanPSL-2.0.

More from Ascend/agent-skills