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.
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
0to640) and class scores (0to1) 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:
| Task | Output |
|---|---|
| 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 Segmentation | Class logits [1, nc, 80, 80] at 1/8 resolution; upsample, then take the per-pixel argmax |
| Depth Estimation | Log-depth [1, 1, 160, 160] at 1/4 resolution; apply exp(x) for metric depth, then upsample |
| Classification | Class 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#
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'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#
| Argument | Type | Default | Description |
|---|---|---|---|
format | str | 'stedgeai' | Target format for the exported model. |
imgsz | int or tuple | 640 | Model 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. |
quantize | int or str | None | Precision. Unset or 32 writes a float model; 8 writes an INT8 model. |
data | str | None | Dataset 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. |
fraction | float | 1.0 | Fraction of the calibration dataset to use. |
opset | int | None | ONNX opset. Defaults to the newest opset your PyTorch version exports reliably. |
simplify | bool | True | Simplifies the ONNX graph with onnxslim. |
device | str | None | Device 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
dataimages, 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.
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.
| Task | Metric | ONNX float | ST Edge AI float | ST Edge AI INT8 |
|---|---|---|---|---|
| Detect | mAP50-95 | 0.686 | 0.686 | 0.639 |
| Segment | box / mask mAP50-95 | 0.638 / 0.540 | 0.638 / 0.540 | 0.356 / 0.401 |
| Semantic | mIoU | 0.610 | 0.610 | 0.609 |
| Depth | delta1 | 0.852 | 0.852 | 0.840 |
| Pose | box / pose mAP50-95 | 0.697 / 0.459 | 0.697 / 0.459 | 0.650 / 0.267 |
| OBB | mAP50-95 | 0.894 | 0.894 | 0.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#
-
Export the model with
format="stedgeai"at theimgszyou will run on the device. -
Validate the float and INT8 models on your dataset with
yolo val. -
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 -
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.
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.yamlto write the INT8 modelyolo26n_int8_stedgeai.onnx, or omitquantize=8to write the float modelyolo26n_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. Multiplyxandwby the input width andyandhby the input height to recover pixels. Ultralytics does this automatically when it loads a_stedgeai.onnxmodel.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=8quantizes 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 withquantize=8quantizes the whole graph.Yes.
yolo val model=yolo26n_int8_stedgeai.onnx data=coco8.yamlruns 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.
Comments
Ask a question, share your results, or help someone else.