Get Started

ST Edge AI Export for Ultralytics YOLO Models

Export Ultralytics YOLO models with format="stedgeai" to get an ONNX model shaped for ST Edge AI Core, the STMicroelectronics toolchain that compiles neural networks for STM32 microcontrollers, including the STM32N6 with its Neural-ART accelerator. The export writes a float model by default and a fully quantized INT8 model with quantize=8. Ultralytics runs either file on your computer with yolo predict and yolo val, so you can measure accuracy before you compile for the device.

Validated on the host

Ultralytics validates these models with ONNX Runtime on a computer, and STMicroelectronics compiled the INT8 exports of all seven tasks for the STM32N6 with ST Edge AI Core. Measuring accuracy, latency and memory on an STM32 board are steps you run with the ST tools; see Deploy to STM32.

Why a Dedicated ST Edge AI Format?#

Microcontrollers run INT8 models, and a standard ONNX export does not quantize well end to end:

  • Mixed ranges in one output. A YOLO detection head joins box coordinates in pixels (about 0 to 640) and class scores (0 to 1) in a single tensor. INT8 quantization gives that tensor one scale, so the scores lose almost all of their resolution. The ST Edge AI export normalizes box and keypoint coordinates to [0, 1] by the input size, the same normalization Ultralytics uses for Edge TPU, so the whole graph can be quantized.
  • Large dense outputs. Semantic segmentation and depth models normally upsample to the input resolution inside the graph. The ST Edge AI export stops before that upsampling, which makes the output buffer 64x smaller for semantic segmentation and 16x smaller for depth, and it keeps depth in the log domain, where INT8 levels are spread evenly.
  • Post-processing in the graph. Embedded NMS and the YOLO26 NMS-free head add TopK and gather operators after the head. The export leaves them out and always returns raw predictions, so NMS runs in your application.

If you want the standard layout instead (pixel coordinates, full-resolution maps, optional embedded NMS), use the ONNX export.

Supported Tasks#

All Ultralytics YOLO tasks export and run on the host. Output shapes are for imgsz=640:

TaskOutput
Detection[1, 4 + nc, 8400]: boxes normalized to [0, 1], class scores
Instance Segmentation[1, 4 + nc + 32, 8400] with boxes normalized to [0, 1], plus mask prototypes [1, 32, 160, 160]
Semantic SegmentationClass logits [1, nc, 80, 80] at 1/8 resolution; upsample, then take the per-pixel argmax
Depth EstimationLog-depth [1, 1, 160, 160] at 1/4 resolution; apply exp(x) for metric depth, then upsample
ClassificationClass probabilities [1, nc]
Pose Estimation[1, 4 + nc + nk, 8400]: boxes and keypoints normalized to [0, 1]
Oriented Detection[1, 4 + nc + 1, 8400]: boxes normalized to [0, 1], angle in radians; requires a square imgsz

RT-DETR and YOLO-NAS models are not supported.

Usage#

Export
from ultralytics import YOLO

# Load a YOLO26 model
model = YOLO("yolo26n.pt")

# Export a float model
model.export(format="stedgeai")  # creates 'yolo26n_stedgeai.onnx'

# Export an INT8 model calibrated on COCO8
model.export(format="stedgeai", quantize=8, data="coco8.yaml")  # creates 'yolo26n_int8_stedgeai.onnx'
Predict and validate on the host
from ultralytics import YOLO

# Load the exported ST Edge AI model
model = YOLO("yolo26n_int8_stedgeai.onnx")

# Run inference
results = model("https://ultralytics.com/images/bus.jpg")

# Measure INT8 accuracy on the COCO8 dataset
metrics = model.val(data="coco8.yaml")

Each export writes one file. Ultralytics recognizes ST Edge AI models by the _stedgeai.onnx ending and then scales the coordinates back to pixels, upsamples semantic and depth maps, and converts log-depth to metric depth. Keep that ending when you rename a file; a plain .onnx name loads as a standard ONNX model and returns boxes in [0, 1].

Export Arguments#

ArgumentTypeDefaultDescription
formatstr'stedgeai'Target format for the exported model.
imgszint or tuple640Model input size, as an integer for square images or a (height, width) tuple. The model has a fixed batch size of 1 and static shapes. OBB models require a square imgsz.
quantizeint or strNonePrecision. Unset or 32 writes a float model; 8 writes an INT8 model.
datastrNoneDataset used for INT8 calibration: a dataset YAML, or a dataset directory or built-in dataset name for classification. Without it, quantize=8 uses the task's default dataset, such as coco8.yaml for detection.
fractionfloat1.0Fraction of the calibration dataset to use.
opsetintNoneONNX opset. Defaults to the newest opset your PyTorch version exports reliably.
simplifyboolTrueSimplifies the ONNX graph with onnxslim.
devicestrNoneDevice used for exporting: GPU (device=0) or CPU (device=cpu).

batch and dynamic=True are rejected, and nms=True falls back to raw outputs with a warning.

INT8 Quantization#

With quantize=8, Ultralytics quantizes the model with ONNX Runtime static quantization, using the scheme ST Edge AI Core recommends and the STM32 AI Model Zoo Services apply:

  • QDQ (QuantizeLinear/DequantizeLinear) format with float model inputs and outputs.
  • Signed symmetric per-channel INT8 weights and signed asymmetric INT8 activations.
  • MinMax calibration over the data images, preprocessed exactly as during Ultralytics validation.

Unlike the standard ONNX quantize=8 export, which leaves the head in float, every operator is quantized. To quantize with the ST tools instead, export the float model and pass it to the STM32 AI Model Zoo Services.

Calibrate on your own data

INT8 accuracy depends on how well the calibration images match the deployment scene. Pass data= a dataset with at least 300 representative images; the default calibration datasets hold only a few public samples.

The table below compares YOLO26n at each model's default imgsz (640, semantic segmentation 1024, depth 768) on the small default validation datasets, calibrated on the same images. These datasets have 4 to 8 images each, so read the numbers as an indication of which tasks are sensitive to INT8 and measure your own model with yolo val.

TaskMetricONNX floatST Edge AI floatST Edge AI INT8
DetectmAP50-950.6860.6860.639
Segmentbox / mask mAP50-950.638 / 0.5400.638 / 0.5400.356 / 0.401
SemanticmIoU0.6100.6100.609
Depthdelta10.8520.8520.840
Posebox / pose mAP50-950.697 / 0.4590.697 / 0.4590.650 / 0.267
OBBmAP50-950.8940.8940.806

The float export matches the standard ONNX export on every task. Instance segmentation and pose lose the most accuracy under whole-graph INT8, because mask coefficients and keypoints share one output scale with the boxes; validate these two tasks carefully on your own data before deploying.

Deploy to STM32#

  1. Export the model with format="stedgeai" at the imgsz you will run on the device.

  2. Validate the float and INT8 models on your dataset with yolo val.

  3. Compile the model with ST Edge AI Core. The commands below follow the ST Edge AI Core command-line documentation and Neural-ART getting started guide; see them for memory profiles and input options.

    # Report the model's memory and operator usage for an STM32 target
    stedgeai analyze -m yolo26n_int8_stedgeai.onnx --target stm32
    
    # Generate the C model for an STM32N6 with the Neural-ART accelerator
    stedgeai generate -m yolo26n_int8_stedgeai.onnx --target stm32n6 --st-neural-art
  4. Deploy the generated model in your STM32 application. The STM32 AI Model Zoo Services provide application code and tutorials for Ultralytics YOLO models on the STM32N6.

Outputs need post-processing

Code that reads the exported model outside Ultralytics, such as C post-processing on the device, must multiply box and keypoint x and w values by the input width and y and h values by the input height, run NMS, upsample semantic logits before the argmax, and apply exp to the depth output before upsampling it. Keep imgsz identical across training, export and deployment.

FAQ#

  • Run yolo export model=yolo26n.pt format=stedgeai quantize=8 data=coco8.yaml to write the INT8 model yolo26n_int8_stedgeai.onnx, or omit quantize=8 to write the float model yolo26n_stedgeai.onnx. Then compile the file with ST Edge AI Core as shown in Deploy to STM32.

  • The ST Edge AI export normalizes box and keypoint coordinates by the input size so they share the [0, 1] range of the class scores, which lets the whole graph be quantized to INT8. Multiply x and w by the input width and y and h by the input height to recover pixels. Ultralytics does this automatically when it loads a _stedgeai.onnx model.

  • No. The export always returns raw predictions, so run NMS in your application or use the post-processing in the STM32 AI Model Zoo Services.

  • The standard ONNX export returns pixel coordinates and full-resolution semantic and depth maps, can embed NMS, and with quantize=8 quantizes only the convolution and matrix-multiplication layers. The ST Edge AI export returns normalized coordinates and low-resolution semantic logits and log-depth, has a fixed batch size of 1, never embeds NMS, and with quantize=8 quantizes the whole graph.

  • Yes. yolo val model=yolo26n_int8_stedgeai.onnx data=coco8.yaml runs the quantized model with ONNX Runtime on your computer and reports the same metrics as any other Ultralytics model. Accuracy on the device can still differ slightly, so confirm it with the ST tools after compiling.

Contributors

Comments

Ask a question, share your results, or help someone else.