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:

Component	Requirement	Why
Python	3.7, 3.8, 3.9, or 3.10	Python 3.11+ incompatible with CANN 8.1.RC1
NumPy	< 2.0 (e.g., 1.26.4)	CANN uses deprecated NumPy API
ONNX Opset	11 or 13 (for CANN 8.1.RC1)	Higher opset versions not supported

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

Task	Model Example	ONNX Output	Post-processing
Detection	yolo26n.pt	`(1, 84, 8400)`	decode + NMS
Pose	yolo26n-pose.pt	`(1, 300, 57)`	filter only
Segmentation	yolo26n-seg.pt	`(1, 116, 8400)`	decode + NMS + mask
OBB	yolo26n-obb.pt	`(1, 15, 8400)`	decode + NMS

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

Metric	Description	Good Value
`cosine_similarity`	1.0 = identical	>0.99
`max_abs_diff`	Maximum absolute difference	<1e-3 (FP32)
`is_close`	Pass/fail based on atol/rtol	True

CANN Version Guide

CANN Version	Environment Path	Notes
8.3.RC1	`/usr/local/Ascend/ascend-toolkit/set_env.sh`	Standard installation
8.5.0+	`/usr/local/Ascend/cann/set_env.sh`	Must install matching ops package

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

Core Parameters

Parameter	Required	Description	Example
`--model`	Yes	Input ONNX model path	`--model=resnet50.onnx`
`--framework`	Yes	Framework type (5=ONNX)	`--framework=5`
`--output`	Yes	Output OM model path	`--output=resnet50`
`--soc_version`	Yes	Must match device exactly	`--soc_version=Ascend910B3`
`--input_shape`	Optional	Input tensor shapes	`--input_shape="input:1,3,224,224"`
`--precision_mode`	Optional	Precision mode	`--precision_mode=force_fp16`

For complete parameters, see PARAMETERS.md.

SoC Version Reference

Device	SoC Version	How to Check
Atlas 910B3	Ascend910B3	`npu-smi info \| grep Name`
Atlas 310P	Ascend310P1/P3	`npu-smi info \| grep Name`
Atlas 200I DK A2	Ascend310B4	`npu-smi info \| grep Name`

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

atc-model-converter