ST-Edge-AI-Export für Ultralytics-YOLO-Modelle
Exportiere Ultralytics-YOLO-Modelle mit format="stedgeai" als ONNX-Modell, das für ST Edge AI Core ausgelegt ist. Diese Toolchain von STMicroelectronics kompiliert neuronale Netze für STM32-Mikrocontroller, einschließlich des STM32N6 mit seinem Neural-ART-Beschleuniger. Beim Export wird standardmäßig ein Float-Modell und mit quantize=8 ein vollständig quantisiertes INT8-Modell erstellt. Ultralytics führt beide Dateien auf deinem Computer mit yolo predict und yolo val aus, sodass du die Genauigkeit vor dem Kompilieren für das Gerät messen kannst.
Ultralytics validiert diese Modelle mit ONNX Runtime auf einem Computer, und STMicroelectronics hat die INT8-Exporte aller sieben Aufgaben mit ST Edge AI Core für den STM32N6 kompiliert. Die Genauigkeit, Latenz und den Speicherbedarf auf einem STM32-Board zu messen, sind Schritte, die du mit den ST-Tools ausführst; siehe Auf STM32 bereitstellen.
Warum ein dediziertes ST-Edge-AI-Format?#
Mikrocontroller führen INT8-Modelle aus, und ein standardmäßiger ONNX-Export lässt sich nicht durchgängig gut quantisieren:
- Unterschiedliche Wertebereiche in einer Ausgabe. Ein YOLO-Erkennungskopf vereint Box-Koordinaten in Pixeln (etwa
0bis640) und Klassenwerte (0bis1) in einem einzigen Tensor. Bei der INT8-Quantisierung erhält dieser Tensor eine gemeinsame Skalierung, sodass die Werte ihre Auflösung fast vollständig verlieren. Der ST-Edge-AI-Export normalisiert Box- und Keypoint-Koordinaten anhand der Eingabegröße auf[0, 1]– dieselbe Normalisierung, die Ultralytics für Edge TPU verwendet. Dadurch lässt sich der gesamte Graph quantisieren. - Große, dichte Ausgaben. Modelle für semantische Segmentierung und Tiefenschätzung skalieren die Ausgabe im Graphen normalerweise auf die Eingabeauflösung hoch. Der ST-Edge-AI-Export endet vor diesem Hochskalieren. Dadurch ist der Ausgabepuffer bei semantischer Segmentierung 64-mal und bei der Tiefenschätzung 16-mal kleiner. Außerdem bleiben Tiefenwerte im Logarithmusbereich, in dem die INT8-Stufen gleichmäßig verteilt sind.
- Nachbearbeitung im Graphen. Eingebettetes NMS und der NMS-freie YOLO26-Kopf fügen nach dem Kopf TopK- und Gather-Operatoren hinzu. Der Export lässt sie weg und gibt immer rohe Vorhersagen zurück, sodass NMS in deiner Anwendung ausgeführt wird.
Wenn du stattdessen das Standardformat möchtest (Pixelkoordinaten, Karten in voller Auflösung, optional eingebettetes NMS), verwende den ONNX-Export.
Unterstützte Aufgaben#
Alle Ultralytics-YOLO-Aufgaben lassen sich exportieren und auf dem Host ausführen. Die Ausgabeformen beziehen sich auf imgsz=640:
| Aufgabe | Ausgabe |
|---|---|
| Erkennung | [1, 4 + nc, 8400]: Boxen normalisiert auf [0, 1], Klassenwerte |
| Instanzsegmentierung | [1, 4 + nc + 32, 8400] mit Boxen, normalisiert auf [0, 1], sowie Maskenprototypen [1, 32, 160, 160] |
| Semantische Segmentierung | Klassenlogits [1, nc, 80, 80] bei 1/8 der Auflösung; hochskalieren und anschließend das Argmax pro Pixel bestimmen |
| Tiefenschätzung | Log-Tiefe [1, 1, 160, 160] bei 1/4 der Auflösung; exp(x) für metrische Tiefenwerte anwenden und anschließend hochskalieren |
| Klassifizierung | Klassenwahrscheinlichkeiten [1, nc] |
| Posenschätzung | [1, 4 + nc + nk, 8400]: Boxen und Keypoints, normalisiert auf [0, 1] |
| Erkennung orientierter Objekte | [1, 4 + nc + 1, 8400]: Boxen, normalisiert auf [0, 1], Winkel im Bogenmaß; erfordert ein quadratisches imgsz |
RT-DETR- und YOLO-NAS-Modelle werden nicht unterstützt.
Verwendung#
from ultralytics import YOLO
# Ein YOLO26-Modell laden
model = YOLO("yolo26n.pt")
# Ein Float-Modell exportieren
model.export(format="stedgeai") # erstellt 'yolo26n_stedgeai.onnx'
# Ein auf COCO8 kalibriertes INT8-Modell exportieren
model.export(format="stedgeai", quantize=8, data="coco8.yaml") # erstellt 'yolo26n_int8_stedgeai.onnx'from ultralytics import YOLO
# Das exportierte ST-Edge-AI-Modell laden
model = YOLO("yolo26n_int8_stedgeai.onnx")
# Inferenz ausführen
results = model("https://ultralytics.com/images/bus.jpg")
# Die INT8-Genauigkeit auf dem COCO8-Datensatz messen
metrics = model.val(data="coco8.yaml")Bei jedem Export wird eine Datei erstellt. Ultralytics erkennt ST-Edge-AI-Modelle an der Endung _stedgeai.onnx und skaliert dann die Koordinaten zurück auf Pixel, skaliert Karten für semantische Segmentierung und Tiefenschätzung hoch und wandelt Log-Tiefenwerte in metrische Tiefenwerte um. Behalte diese Endung beim Umbenennen einer Datei bei. Ein einfacher .onnx-Dateiname wird als standardmäßiges ONNX-Modell geladen und gibt Boxen in [0, 1] zurück.
Exportargumente#
| Argument | Typ | Standard | Beschreibung |
|---|---|---|---|
format | str | 'stedgeai' | Zielformat für das exportierte Modell. |
imgsz | int oder tuple | 640 | Eingabegröße des Modells: eine Ganzzahl für quadratische Bilder oder ein (height, width)-Tupel. Das Modell hat eine feste Batchgröße von 1 und statische Formen. OBB-Modelle erfordern ein quadratisches imgsz. |
quantize | int oder str | None | Genauigkeit. Ohne Angabe oder mit 32 wird ein Float-Modell erstellt; mit 8 wird ein INT8-Modell erstellt. |
data | str | None | Für die INT8-Kalibrierung verwendeter Datensatz: eine Dataset-YAML-Datei oder ein Dataset-Verzeichnis beziehungsweise ein integrierter Dataset-Name für die Klassifizierung. Ohne diese Angabe verwendet quantize=8 den Standarddatensatz der jeweiligen Aufgabe, beispielsweise coco8.yaml für die Erkennung. |
fraction | float | 1.0 | Anteil des Kalibrierungsdatensatzes, der verwendet werden soll. |
opset | int | None | ONNX-Operatorensatz. Standardmäßig wird der neueste Operatorensatz verwendet, den deine PyTorch-Version zuverlässig exportiert. |
simplify | bool | True | Vereinfacht den ONNX-Graphen mit onnxslim. |
device | str | None | Für den Export verwendetes Gerät: GPU (device=0) oder CPU (device=cpu). |
batch und dynamic=True werden abgelehnt, und nms=True wechselt mit einer Warnung zu rohen Ausgaben.
INT8-Quantisierung#
Mit quantize=8 quantisiert Ultralytics das Modell mithilfe der statischen Quantisierung von ONNX Runtime. Dabei kommt das Verfahren zum Einsatz, das ST Edge AI Core empfiehlt und die STM32-AI-Model-Zoo-Services anwenden:
- QDQ-Format (QuantizeLinear/DequantizeLinear) mit Float-Eingaben und -Ausgaben des Modells.
- Vorzeichenbehaftete symmetrische INT8-Gewichte pro Kanal und vorzeichenbehaftete asymmetrische INT8-Aktivierungen.
- MinMax-Kalibrierung anhand der
data-Bilder, die genau wie bei der Ultralytics-Validierung vorverarbeitet werden.
Anders als beim standardmäßigen ONNX-Export quantize=8, bei dem der Kopf im Float-Format bleibt, wird jeder Operator quantisiert. Um stattdessen mit den ST-Tools zu quantisieren, exportiere das Float-Modell und übergib es an die STM32-AI-Model-Zoo-Services.
Die INT8-Genauigkeit hängt davon ab, wie gut die Kalibrierungsbilder der Einsatzumgebung entsprechen. Übergib data= einen Datensatz mit mindestens 300 repräsentativen Bildern. Die Standard-Kalibrierungsdatensätze enthalten nur wenige öffentliche Beispiele.
Die folgende Tabelle vergleicht YOLO26n mit der standardmäßigen imgsz-Eingabegröße für jedes Modell (640, bei semantischer Segmentierung 1024 und bei Tiefenschätzung 768) auf den kleinen Standard-Validierungsdatensätzen, die mit denselben Bildern kalibriert wurden. Diese Datensätze enthalten jeweils 4 bis 8 Bilder. Daher zeigen die Zahlen lediglich an, welche Aufgaben empfindlich auf INT8 reagieren. Miss dein eigenes Modell mit yolo val.
| Aufgabe | Kennzahl | ONNX Float | ST Edge AI Float | ST Edge AI INT8 |
|---|---|---|---|---|
| Detect | mAP50-95 | 0.686 | 0.686 | 0.639 |
| Segment | Box-/Masken-mAP50-95 | 0.638 / 0.540 | 0.638 / 0.540 | 0.356 / 0.401 |
| Semantisch | mIoU | 0.610 | 0.610 | 0.609 |
| Tiefe | 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 |
Der Float-Export entspricht bei allen Aufgaben dem standardmäßigen ONNX-Export. Instanzsegmentierung und Pose verlieren bei der Quantisierung des gesamten Graphen am meisten Genauigkeit, weil Maskenkoeffizienten und Keypoints dieselbe Ausgabeskalierung wie die Boxen verwenden. Validiere diese beiden Aufgaben sorgfältig mit deinen eigenen Daten, bevor du sie einsetzt.
Auf STM32 bereitstellen#
-
Exportiere das Modell mit
format="stedgeai"und derimgsz, die du auf dem Gerät verwenden wirst. -
Validiere die Float- und INT8-Modelle mit
yolo valauf deinem Datensatz. -
Kompiliere das Modell mit ST Edge AI Core. Die folgenden Befehle folgen der Befehlszeilendokumentation von ST Edge AI Core und der Neural-ART-Einführungsanleitung. Dort findest du Informationen zu Speicherprofilen und Eingabeoptionen.
# 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 -
Stelle das erzeugte Modell in deiner STM32-Anwendung bereit. Die STM32-AI-Model-Zoo-Services bieten Anwendungscode und Tutorials für Ultralytics-YOLO-Modelle auf dem STM32N6.
Code, der das exportierte Modell außerhalb von Ultralytics ausliest, etwa C-Code zur Nachbearbeitung auf dem Gerät, muss die Werte x und w für Boxen und Keypoints mit der Eingabebreite sowie die Werte y und h mit der Eingabehöhe multiplizieren, NMS ausführen, semantische Logits vor der Bestimmung des Argmax hochskalieren und exp auf die Tiefenausgabe anwenden, bevor diese hochskaliert wird. Verwende beim Training, Export und Einsatz überall dasselbe imgsz.
Häufig gestellte Fragen#
Führe
yolo export model=yolo26n.pt format=stedgeai quantize=8 data=coco8.yamlaus, um das INT8-Modellyolo26n_int8_stedgeai.onnxzu erstellen, oder lassquantize=8weg, um das Float-Modellyolo26n_stedgeai.onnxzu erstellen. Kompiliere die Datei dann wie unter Auf STM32 bereitstellen gezeigt mit ST Edge AI Core.Der ST-Edge-AI-Export normalisiert Box- und Keypoint-Koordinaten anhand der Eingabegröße, damit sie denselben Wertebereich
[0, 1]wie die Klassenwerte haben. Dadurch lässt sich der gesamte Graph auf INT8 quantisieren. Multiplizierexundwmit der Eingabebreite sowieyundhmit der Eingabehöhe, um die Pixelkoordinaten zu erhalten. Ultralytics erledigt das automatisch, wenn ein_stedgeai.onnx-Modell geladen wird.Nein. Der Export gibt immer rohe Vorhersagen zurück. Führe NMS daher in deiner Anwendung aus oder verwende die Nachverarbeitung der STM32-AI-Model-Zoo-Services.
Der standardmäßige ONNX-Export gibt Pixelkoordinaten sowie Karten für semantische Segmentierung und Tiefenschätzung in voller Auflösung zurück, kann NMS einbetten und quantisiert mit
quantize=8nur die Faltungs- und Matrixmultiplikationsschichten. Der ST-Edge-AI-Export gibt normalisierte Koordinaten sowie niedrig aufgelöste semantische Logits und Log-Tiefenwerte zurück, hat eine feste Batchgröße von 1, bettet niemals NMS ein und quantisiert mitquantize=8den gesamten Graphen.Ja.
yolo val model=yolo26n_int8_stedgeai.onnx data=coco8.yamlführt das quantisierte Modell mit ONNX Runtime auf deinem Computer aus und gibt dieselben Metriken wie jedes andere Ultralytics-Modell aus. Die Genauigkeit auf dem Gerät kann trotzdem leicht abweichen. Überprüfe sie daher nach dem Kompilieren mit den ST-Tools.
Kommentare
Stell eine Frage, teile deine Ergebnisse oder hilf jemand anderem.