ATC Model Converter

Complete guide for converting ONNX models to Ascend AI processor compatible format using ATC (Ascend Tensor Compiler) tool.

Supported CANN Versions: 8.3.RC1, 8.5.0

⚠️ Critical Compatibility Requirements

Before starting, ensure your environment meets these requirements:

Quick Environment Setup:

# Create Python 3.10 environment (recommended)
conda create -n atc_py310 python=3.10 -y
conda activate atc_py310

# Install compatible dependencies
pip install torch torchvision ultralytics onnx onnxruntime
pip install "numpy<2.0" --force-reinstall
pip install decorator attrs absl-py psutil protobuf sympy

⚠️ IMPORTANT: SoC Version Must Match Exactly

SoC version in ATC conversion must exactly match your target device!

# Get exact SoC version from your device
npu-smi info | grep Name
# Output: Name: 910B3 → Use: --soc_version=Ascend910B3
# Output: Name: 310P3 → Use: --soc_version=Ascend310P3

Common Error:

[ACL ERROR] EE1001: supported socVersion=Ascend910B3, 
but the model socVersion=Ascend910B

Fix: Use exact SoC version from npu-smi info, not generic version!

Quick Start

# 1. Check your CANN version and environment
./scripts/check_env_enhanced.sh

# 2. Source the appropriate environment
source /usr/local/Ascend/ascend-toolkit/set_env.sh  # For 8.1.RC1/8.3.RC1
# OR
source /usr/local/Ascend/cann/set_env.sh            # For 8.5.0+

# 3. Basic ONNX to OM conversion
atc --model=model.onnx --framework=5 --output=output_model \
    --soc_version=Ascend910B3

# With input shape specification
atc --model=model.onnx --framework=5 --output=output_model \
    --soc_version=Ascend910B3 \
    --input_shape="input:1,3,640,640"

YOLO Model Conversion & Inference

YOLO Task Types & Output Formats

Note: YOLO ONNX outputs are raw feature maps, not processed detections. The yolo_om_infer.py script handles decode + NMS automatically.

Step 1: Export YOLO to ONNX

from ultralytics import YOLO

model = YOLO('yolo26n.pt')  # or yolo26n-pose.pt, yolo26n-seg.pt, etc.

# Export with opset 11 for CANN 8.1.RC1 compatibility
model.export(format='onnx', imgsz=640, opset=11, simplify=True)

Step 2: Convert to OM

# Get your SoC version first
npu-smi info | grep Name

# Convert
atc --model=yolo26n.onnx --framework=5 --output=yolo26n \
    --soc_version=Ascend910B3 \
    --input_shape="images:1,3,640,640"

Step 3: Run Inference

# Detection (default)
python3 scripts/yolo_om_infer.py --model yolo26n.om \
    --source image.jpg --task detect --output result.jpg

# Pose estimation
python3 scripts/yolo_om_infer.py --model yolo26n-pose.om \
    --source image.jpg --task pose --output result_pose.jpg

# Segmentation
python3 scripts/yolo_om_infer.py --model yolo26n-seg.om \
    --source image.jpg --task segment --output result_seg.jpg

# Oriented Bounding Box
python3 scripts/yolo_om_infer.py --model yolo26n-obb.om \
    --source image.jpg --task obb --output result_obb.jpg

YOLO Python API

from yolo_om_infer import YoloOMInferencer, draw_results

# Initialize for detection
inferencer = YoloOMInferencer(
    model_path="yolo26n.om",
    task="detect",  # or "pose", "segment", "obb"
    device_id=0,
    conf_thres=0.25,
    iou_thres=0.45
)

# Run inference
result = inferencer("image.jpg")

# Access results
print(f"Detections: {result['num_detections']}")
print(f"Inference time: {result['timing']['infer_ms']:.1f}ms")

for det in result['detections']:
    print(f"  {det['cls_name']}: {det['conf']:.2f} at {det['box']}")

# Cleanup
inferencer.free_resource()

For detailed YOLO guide, see YOLO_GUIDE.md.

OM Model Inference (General)

After converting your model to OM format, use ais_bench for Python inference.

Install ais_bench

# Download pre-built wheel packages (recommended)
# See: https://gitee.com/ascend/tools/blob/master/ais-bench_workload/tool/ais_bench/README.md

# Example for Python 3.10, aarch64:
wget https://aisbench.obs.myhuaweicloud.com/packet/ais_bench_infer/0.0.2/ait/aclruntime-0.0.2-cp310-cp310-linux_aarch64.whl
wget https://aisbench.obs.myhuaweicloud.com/packet/ais_bench_infer/0.0.2/ait/ais_bench-0.0.2-py3-none-any.whl

pip3 install ./aclruntime-*.whl ./ais_bench-*.whl

Basic Inference

# Print model info
python3 scripts/infer_om.py --model model.om --info

# Run inference with random input
python3 scripts/infer_om.py --model model.om --input-shape "1,3,640,640"

# Run inference with actual input
python3 scripts/infer_om.py --model model.om --input test.npy --output result.npy

Python API

from ais_bench.infer.interface import InferSession
import numpy as np

session = InferSession(device_id=0, model_path="model.om")
print("Inputs:", [(i.name, i.shape) for i in session.get_inputs()])
print("Outputs:", [(o.name, o.shape) for o in session.get_outputs()])

input_data = np.random.randn(1, 3, 640, 640).astype(np.float32)
outputs = session.infer([input_data], mode='static')

print(f"Inference time: {session.summary().exec_time_list[-1]:.3f} ms")
session.free_resource()

See INFERENCE.md for detailed ais_bench usage.

Precision Comparison

Verify conversion accuracy by comparing ONNX (CPU) vs OM (NPU) outputs.

# Basic comparison
python3 scripts/compare_precision.py --onnx model.onnx --om model.om --input test.npy

# With custom tolerances
python3 scripts/compare_precision.py --onnx model.onnx --om model.om --input test.npy \
    --atol 1e-3 --rtol 1e-2

CANN Version Guide

# Auto-detect CANN version
./scripts/setup_env.sh

Core Parameters

For complete parameters, see PARAMETERS.md.

SoC Version Reference

Always verify with npu-smi info - do not assume version!

Troubleshooting

Error: Opname not found in model

# Verify input names
python3 scripts/get_onnx_info.py model.onnx

# Use correct name in conversion
atc --model=model.onnx --input_shape="correct_name:1,3,224,224" ...

Error: Invalid soc_version

# Check actual chip version - must be EXACT match
npu-smi info | grep Name
# Use: Ascend + Name value (e.g., Ascend910B3, not Ascend910B)

Conversion Too Slow

export TE_PARALLEL_COMPILER=16
atc --model=model.onnx ...

YOLO Detection Results Look Wrong

• Ensure you're using correct --task parameter
• Detection models need decode + NMS (script handles this)
• Pose models output top-300 detections (no NMS needed)

See FAQ.md for more troubleshooting.

Resources

scripts/

Conversion & Environment:

• check_env_enhanced.sh - ⭐ Comprehensive compatibility check
• get_onnx_info.py - Inspect ONNX model inputs/outputs
• setup_env.sh - Auto-setup CANN environment with SoC warning
• convert_onnx.sh - Batch conversion helper

Inference & Testing:

• yolo_om_infer.py - ⭐ End-to-end YOLO inference (detect/pose/segment/obb)
• infer_om.py - ⭐ Python inference for OM models using ais_bench
• compare_precision.py - ⭐ Compare ONNX vs OM output precision

references/

• YOLO_GUIDE.md - ⭐ YOLO detailed guide (formats, post-processing)
• PARAMETERS.md - Complete ATC parameter reference
• AIPP_CONFIG.md - AIPP configuration guide
• INFERENCE.md - ais_bench inference guide
• FAQ.md - Frequently asked questions
• CANN_VERSIONS.md - Version-specific guidance