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