Начать

Экспорт ST Edge AI для моделей Ultralytics YOLO

Экспортируй модели Ultralytics YOLO с помощью format="stedgeai", чтобы получить модель ONNX, адаптированную для ST Edge AI Core — инструментария STMicroelectronics для компиляции нейронных сетей под микроконтроллеры STM32, включая STM32N6 с ускорителем Neural-ART. По умолчанию при экспорте создаётся модель с плавающей точкой; также можно получить полностью квантизированную модель INT8 с quantize=8. Ultralytics запускает оба файла на компьютере с помощью yolo predict и yolo val, чтобы ты мог оценить точность до компиляции для устройства.

Проверено на хосте

Ultralytics проверяет эти модели с помощью ONNX Runtime на компьютере, а STMicroelectronics скомпилировала экспорты INT8 для всех семи задач под STM32N6 с помощью ST Edge AI Core. Измерение точности, задержки и объёма памяти на плате STM32 выполняется с помощью инструментов ST; см. раздел Развёртывание на STM32.

Зачем нужен специальный формат ST Edge AI?#

Микроконтроллеры работают с моделями INT8, а стандартный экспорт ONNX не позволяет качественно квантизировать модель целиком:

  • Разные диапазоны в одном выходе. Голова детекции YOLO объединяет координаты боксов в пикселях (примерно от 0 до 640) и оценки классов (от 0 до 1) в одном тензоре. При INT8-квантизации всему тензору назначается один масштаб, поэтому оценки теряют почти всю точность. Экспорт ST Edge AI нормализует координаты боксов и ключевых точек до [0, 1] относительно размера входного изображения — так же, как Ultralytics нормализует координаты для Edge TPU. Благодаря этому можно квантизировать весь граф.
  • Большие плотные выходы. Модели семантической сегментации и оценки глубины обычно повышают разрешение до размера входного изображения внутри графа. Экспорт ST Edge AI останавливается до этого этапа: буфер выходных данных становится в 64 раза меньше для семантической сегментации и в 16 раз меньше для оценки глубины. Кроме того, глубина остаётся в логарифмической области, где уровни INT8 распределены равномерно.
  • Постобработка внутри графа. Встроенный NMS и голова YOLO26 без NMS добавляют после головы модели операторы TopK и gather. Экспорт исключает их и всегда возвращает необработанные предсказания, поэтому NMS выполняется в твоём приложении.

Если тебе нужен стандартный формат (координаты в пикселях, карты полного разрешения, возможность встроить NMS), используй экспорт ONNX.

Поддерживаемые задачи#

Все задачи Ultralytics YOLO экспортируются и запускаются на хосте. Формы выходных данных указаны для imgsz=640:

ЗадачаРезультат
Обнаружение[1, 4 + nc, 8400]: боксы с координатами, нормализованными до [0, 1], оценки классов
Сегментация экземпляров[1, 4 + nc + 32, 8400] с боксами, координаты которых нормализованы до [0, 1], а также прототипы масок [1, 32, 160, 160]
Семантическая сегментацияЛогиты классов [1, nc, 80, 80] с разрешением 1/8; сначала увеличь разрешение, затем вычисли argmax для каждого пикселя
Оценка глубиныЛогарифм глубины [1, 1, 160, 160] с разрешением 1/4; примени exp(x) для получения метрической глубины, затем увеличь разрешение
КлассификацияВероятности классов [1, nc]
Оценка позы[1, 4 + nc + nk, 8400]: боксы и ключевые точки с координатами, нормализованными до [0, 1]
Обнаружение ориентированных объектов[1, 4 + nc + 1, 8400]: боксы с координатами, нормализованными до [0, 1], угол в радианах; требуется квадратный imgsz

Модели RT-DETR и YOLO-NAS не поддерживаются.

Использование#

Экспорт
from ultralytics import YOLO

# Загрузи модель YOLO26
model = YOLO("yolo26n.pt")

# Экспорт модели с плавающей точкой
model.export(format="stedgeai")  # создаёт 'yolo26n_stedgeai.onnx'

# Экспорт модели INT8 с калибровкой на COCO8
model.export(format="stedgeai", quantize=8, data="coco8.yaml")  # создаёт 'yolo26n_int8_stedgeai.onnx'
Выполнение предсказаний и валидация на хосте
from ultralytics import YOLO

# Загрузка экспортированной модели ST Edge AI
model = YOLO("yolo26n_int8_stedgeai.onnx")

# Выполнить инференс
results = model("https://ultralytics.com/images/bus.jpg")

# Измерение точности INT8 на наборе данных COCO8
metrics = model.val(data="coco8.yaml")

Каждый экспорт создаёт один файл. Ultralytics распознаёт модели ST Edge AI по окончанию _stedgeai.onnx, после чего масштабирует координаты обратно в пиксели, увеличивает разрешение семантических карт и карт глубины, а также преобразует логарифм глубины в метрическую глубину. При переименовании файла сохрани это окончание: файл с обычным именем .onnx загружается как стандартная модель ONNX и возвращает боксы в [0, 1].

Аргументы экспорта#

АргументТипПо умолчаниюОписание
formatstr'stedgeai'Целевой формат экспортируемой модели.
imgszint или tuple640Размер входных данных модели: целое число для квадратных изображений или кортеж (height, width). Размер пакета модели фиксирован и равен 1, формы статические. Для моделей OBB требуется квадратный imgsz.
quantizeint или strNoneТочность. Если значение не задано или указано 32, создаётся модель с плавающей точкой; 8 создаёт модель INT8.
datastrNoneНабор данных для калибровки INT8: YAML-файл набора данных либо каталог набора данных или встроенное имя набора данных для классификации. Если его не указать, quantize=8 использует набор данных по умолчанию для этой задачи, например coco8.yaml для детекции.
fractionfloat1.0Доля набора данных для калибровки, которую нужно использовать.
opsetintNoneВерсия ONNX opset. По умолчанию используется самая новая версия opset, которую твоя версия PyTorch надёжно экспортирует.
simplifyboolTrueУпрощает граф ONNX с помощью onnxslim.
devicestrNoneУстройство для экспорта: GPU (device=0) или CPU (device=cpu).

batch и dynamic=True отклоняются, а nms=True переключается на необработанные выходы с предупреждением.

Квантование INT8#

При использовании quantize=8 Ultralytics квантизирует модель статической квантизацией ONNX Runtime, используя схему, которую рекомендует ST Edge AI Core и применяют STM32 AI Model Zoo Services:

  • Формат QDQ (QuantizeLinear/DequantizeLinear) с входами и выходами модели с плавающей точкой.
  • Знаковые симметричные веса INT8 с поканальной квантизацией и знаковые асимметричные активации INT8.
  • Калибровка MinMax на изображениях data, предварительно обработанных точно так же, как при валидации Ultralytics.

В отличие от стандартного экспорта ONNX quantize=8, при котором голова остаётся с плавающей точкой, здесь квантизируется каждый оператор. Чтобы выполнить квантизацию с помощью инструментов ST, экспортируй модель с плавающей точкой и передай её в STM32 AI Model Zoo Services.

Калибровка на собственных данных

Точность INT8 зависит от того, насколько изображения для калибровки похожи на сцены, в которых будет использоваться модель. Передай data= набор данных как минимум с 300 репрезентативными изображениями; наборы данных для калибровки по умолчанию содержат лишь несколько общедоступных примеров.

В таблице ниже сравнивается YOLO26n с размером входных данных по умолчанию imgsz для каждой модели (640, 1024 для семантической сегментации и 768 для глубины) на небольших наборах данных для валидации по умолчанию; калибровка выполнена на тех же изображениях. В этих наборах всего от 4 до 8 изображений, поэтому воспринимай значения как ориентир для оценки чувствительности задач к INT8 и измерь показатели своей модели с помощью yolo val.

ЗадачаПоказательONNX с плавающей точкойST Edge AI с плавающей точкойST Edge AI INT8
ОбнаружениеmAP50-950.6860.6860.639
СегментацияmAP50-95 для боксов / масок0.638 / 0.5400.638 / 0.5400.356 / 0.401
СемантическаяmIoU0.6100.6100.609
Глубинаdelta10.8520.8520.840
ПозаmAP50-95 для боксов / позы0.697 / 0.4590.697 / 0.4590.650 / 0.267
OBBmAP50-950.8940.8940.806

Экспорт с плавающей точкой совпадает со стандартным экспортом ONNX для всех задач. При полной квантизации графа наибольшая потеря точности наблюдается в сегментации экземпляров и оценке позы, поскольку коэффициенты масок и ключевые точки используют один масштаб выходных данных вместе с боксами. Перед развёртыванием тщательно проверь обе задачи на собственных данных.

Развёртывание на STM32#

  1. Экспортируй модель с помощью format="stedgeai", указав imgsz, который будешь использовать на устройстве.

  2. Проверь модели с плавающей точкой и INT8 на своём наборе данных с помощью yolo val.

  3. Скомпилируй модель с помощью ST Edge AI Core. Приведённые ниже команды соответствуют документации по командной строке ST Edge AI Core и руководству Neural-ART для начала работы; см. эти материалы, чтобы узнать о профилях памяти и параметрах входных данных.

    # 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. Разверни созданную модель в приложении STM32. STM32 AI Model Zoo Services содержат код приложения и руководства для моделей Ultralytics YOLO на STM32N6.

Выходные данные требуют постобработки

Код для чтения экспортированной модели вне Ultralytics, например постобработки на C на устройстве, должен умножать значения x и w боксов и ключевых точек на ширину входных данных, а значения y и h — на высоту входных данных; выполнять NMS; увеличивать разрешение семантических логитов до вычисления argmax; а также применять exp к выходу глубины перед увеличением разрешения. Параметр imgsz должен быть одинаковым при обучении, экспорте и развёртывании.

Часто задаваемые вопросы#

  • Запусти yolo export model=yolo26n.pt format=stedgeai quantize=8 data=coco8.yaml, чтобы создать модель INT8 yolo26n_int8_stedgeai.onnx, или опусти quantize=8, чтобы создать модель с плавающей точкой yolo26n_stedgeai.onnx. Затем скомпилируй файл с помощью ST Edge AI Core, как описано в разделе Развёртывание на STM32.

  • Экспорт ST Edge AI нормализует координаты боксов и ключевых точек относительно размера входных данных, чтобы они соответствовали диапазону [0, 1] оценок классов. Благодаря этому весь граф можно квантизировать до INT8. Чтобы восстановить координаты в пикселях, умножь x и w на ширину входных данных, а y и h — на высоту входных данных. Ultralytics делает это автоматически при загрузке модели _stedgeai.onnx.

  • Нет. Экспорт всегда возвращает необработанные предсказания, поэтому выполняй NMS в приложении или используй постобработку из STM32 AI Model Zoo Services.

  • Стандартный экспорт ONNX возвращает координаты в пикселях и семантические карты и карты глубины полного разрешения, позволяет встроить NMS, а с quantize=8 квантизирует только слои свёртки и матричного умножения. Экспорт ST Edge AI возвращает нормализованные координаты, семантические логиты и логарифм глубины с низким разрешением, использует фиксированный размер пакета 1 и никогда не встраивает NMS; с quantize=8 он квантизирует весь граф.

  • Да. yolo val model=yolo26n_int8_stedgeai.onnx data=coco8.yaml запускает квантованную модель с помощью ONNX Runtime на компьютере и показывает те же метрики, что и для любой другой модели Ultralytics. Точность на устройстве может немного отличаться, поэтому после компиляции проверь её с помощью инструментов ST.

Участники

Комментарии

Задай вопрос, поделись результатами или помоги кому-нибудь.