Начать

Экспорт моделей YOLO26 в ONNX

ONNX (открытый формат обмена нейросетями) — это открытый формат моделей, который поддерживается большинством сред выполнения для инференса. При экспорте модели Ultralytics YOLO26 с помощью format="onnx" создаётся один файл .onnx, который работает с ONNX Runtime на CPU, графических процессорах NVIDIA и AMD, устройствах с чипами Apple и устройствах Windows.

Краткий обзор#

СвойствоОписание
Аргумент formatonnx
Результатyolo26n.onnx, один файл с именами классов, задачей и размером изображения, сохранёнными в метаданных; yolo26n_int8.onnx для экспорта откалиброванной модели quantize=8
Поддерживаемые устройстваCPU, графические процессоры NVIDIA (CUDA), графические процессоры AMD (MIGraphX), устройства с чипами Apple (провайдер выполнения Core ML) и устройства Windows ML
Среда выполненияONNX Runtime или OpenCV DNN с dnn=True
ТочностьFP32, FP16, INT8. YOLO26n занимает 9.9 MB в FP32, 5.0 MB в FP16 и 3.1 MB в INT8
Среда для экспортаLinux, macOS или Windows, с графическим процессором или без него
Экспорт в облаке

Ultralytics Platform может экспортировать обученную модель в ONNX за тебя, поэтому локальная среда для экспорта не нужна.

Быстрый старт#

Установи пакет Ultralytics. При первом экспорте будут установлены onnx, onnxslim и onnxruntime, если они отсутствуют (onnxruntime-gpu, если экспортировать с device=0 на графическом процессоре NVIDIA).

pip install ultralytics

Другие способы установки описаны в руководстве по установке. Затем экспортируй модель и загрузи экспортированный файл, чтобы запустить инференс или проверить точность.

Экспорт
from ultralytics import YOLO

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

# Экспортировать модель в формат ONNX
model.export(format="onnx")  # создаёт 'yolo26n.onnx'

# Экспорт ONNX-модели с квантованием INT8 и калибровочными данными
model.export(format="onnx", quantize=8, data="coco8.yaml")  # создает 'yolo26n_int8.onnx'
Предсказание
from ultralytics import YOLO

# Загрузи экспортированную модель ONNX
model = YOLO("yolo26n.onnx")

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

# Загрузи экспортированную модель ONNX
model = YOLO("yolo26n.onnx")

# Проверить точность на наборе данных COCO8
metrics = model.val(data="coco8.yaml")

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

Экспорт в ONNX поддерживает все семь задач Ultralytics с моделями YOLOv8, YOLO11 и YOLO26: обнаружение объектов, сегментацию, семантическую сегментацию, оценку глубины, классификацию, оценку позы и OBB. Семантическая сегментация и оценка глубины доступны только в YOLO26 — единственном семействе, в котором есть соответствующие выходные головы.

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

АргументТипПо умолчаниюОписание
formatstr'onnx'Целевой формат экспортируемой модели, определяющий совместимость с различными средами развертывания.
imgszint или tuple640Размер входного изображения модели: целое число для квадратных изображений или кортеж (height, width). Если значение не задано, при экспорте используется размер, на котором обучалась модель из чекпойнта. В официальных чекпойнтах YOLO26 используется 640 для моделей обнаружения объектов, сегментации, оценки позы и семантических моделей, предобученных на ADE20K; 1024 для OBB и семантических моделей, предобученных на Cityscapes; 768 для оценки глубины и 224 для классификации.
quantizeint или strNoneТочность квантования: 16 (FP16; при экспорте для CPU входы и выходы остаются FP32, а при экспорте для GPU они тоже становятся FP16) или 8 (статическое квантование INT8 с помощью ONNX Runtime и калибровочных изображений из data, в результате создаётся модель _int8.onnx); значение 32 или отсутствие параметра означает FP32. Чекпойнт, обученный с quantize=8, экспортируется в INT8, если quantize не задан или равен 8 (для других значений возникает ошибка): создаются узлы Q/DQ на основе имеющихся в чекпойнте диапазонов, без калибровки и с обычным именем .onnx. Заменяет устаревшие флаги half/int8.
datastrNoneYAML-файл датасета, используемый для калибровки INT8; для классификации вместо него указывают каталог датасета или имя встроенного датасета. Если параметр не задан вместе с quantize=8, Ultralytics выбирает стандартный калибровочный датасет для задачи модели; контрольной точке, обученной с quantize=8, он не требуется.
fractionfloat, int или list1.0Подмножество для калибровки, заданное как доля, количество изображений или [train, val, test] отношения/количества. Если список содержит два элемента, test остаётся без изменений, а 0 пропускает его.
dynamicboolFalseДелает пакет, высоту и ширину входных данных динамическими осями, поэтому один файл принимает разные размеры пакета (до размера экспорта batch с nms=True) и изображения. См. экспорт с динамическими размерами.
simplifyboolTrueУпрощает граф модели с помощью onnxslim.
opsetintNoneЗадаёт версию opset ONNX для совместимости с разными парсерами и средами выполнения ONNX. Если значение не задано, используется opset 18 (меньше при PyTorch < 2.4), но не выше установленной версии onnx. См. минимальную версию opset.
nmsbool, необязательноNoneВыбирает исходный вывод (None, по умолчанию), встроенный NMS (True) или голову без NMS (False). См. формат вывода.
batchint1Размер пакета экспортированной модели. При статическом экспорте этот размер фиксируется во входной форме. При использовании dynamic=True и nms=True укажи наибольший размер пакета, который планируешь использовать.
devicestrNoneУстройство для экспорта: cpu (по умолчанию, в том числе на машине с GPU), 0 для графического процессора CUDA или mps для устройств с чипами Apple. Результат меняется только при quantize=16; см. входы FP16.

Аргументы, общие для всех форматов, описаны в документации по режиму экспорта.

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

Для чекпойнтов, обученных без обучения с учетом квантования, quantize=8 применяет статическое квантование ONNX Runtime только к узлам Conv, Gemm и MatMul. Все остальные узлы остаются в формате с плавающей запятой, включая операции, которые формируют output0: координаты рамок (в пикселях) и оценки классов (от 0 до 1) находятся в одном тензоре, поэтому единый масштаб INT8 для него округлил бы все оценки классов до нуля. Начиная с opset 13 веса квантуются отдельно для каждого канала. Если самостоятельно запускаешь quantize_static для экспортированной модели FP32, исключи те же узлы и задай per_channel=True:

import onnx
from onnxruntime.quantization import quantize_static

model = "yolo26n.onnx"
exclude = [n.name for n in onnx.load(model).graph.node if n.op_type not in {"Conv", "Gemm", "MatMul"}]
quantize_static(model, "yolo26n_int8.onnx", calibration_reader, nodes_to_exclude=exclude, per_channel=True)

Здесь calibration_reader — это onnxruntime.quantization.CalibrationDataReader, который возвращает {"images": array} с размером пакета модели после предобработки для инференса: с добавлением полей до нужного размера при сохранении пропорций (для классификации — с изменением размера и обрезкой по центру), в формате RGB, NCHW, float32 в диапазоне 0–1.

Модель INT8 сохраняет типы входных и выходных данных модели FP32, поэтому код инференса, написанный для модели FP32, запускает её без изменений. Файл INT8 в три-четыре раза меньше файла FP32, но в тестах производительности на GPU и CPU с ONNX Runtime модель работала медленнее, чем FP32. Перед выбором точности измерь задержку на целевом оборудовании.

Формат вывода#

Экспортированная модель принимает один вход с именем images и формой (batch, 3, height, width), в формате RGB и с масштабированием до диапазона 0–1. Тип входа — float32, кроме экспортированных для GPU моделей, созданных с помощью quantize=16: они принимают float16. Аргумент nms задаёт расположение output0. Ниже указаны формы для модели обнаружения YOLO26n с 80 классами, экспортированной при imgsz=640:

nmsФорма output0Содержимое
None (по умолчанию)(1, 84, 8400)Для каждого из 8400 якорей: центр рамки по x, центр по y, ширина и высота в пикселях входного изображения, затем оценки 80 классов. Примени NMS самостоятельно.
True(1, 300, 6)NMS выполняется внутри модели. Каждая строка имеет форму x1, y1, x2, y2, score, class; строки после последнего обнаружения заполнены нулями.
False(1, 300, 6)Голова без NMS. Каждая строка имеет форму x1, y1, x2, y2, score, class; этап NMS отсутствует. Отфильтруй строки по оценке самостоятельно.

Для остальных задач используются тот же вход и следующие выходы. Формы указаны для официальных чекпойнтов YOLO26n при размере экспорта по умолчанию; для семантической сегментации указан чекпойнт Cityscapes yolo26n-sem.pt:

Задачаimgsz по умолчаниюВыход с nms=NoneВыход с nms=False или nms=True
Обнаружение640output0 (1, 84, 8400)output0 (1, 300, 6)
Сегментация640output0 (1, 116, 8400), output1 (1, 32, 160, 160)output0 (1, 300, 38), output1 (1, 32, 160, 160)
Семантическая1024output0 (1, 1024, 1024), uint8 — индекс класса для каждого пикселяТо же, что и nms=None
Глубина768output0 (1, 1, 768, 768), карта глубиныТо же, что и nms=None
Классификация224output0 (1, 1000), вероятности классов после softmaxТо же, что nms=None, для nms=False; nms=True вызывает ошибку
Поза640output0 (1, 56, 8400)output0 (1, 300, 57): 6 значений рамки, затем 17 ключевых точек по 3 значения
OBB1024output0 (1, 20, 21504)output0 (1, 300, 7): center x, center y, width, height, score, class, angle (радианы)

В строках сегментации после значений рамки содержатся 32 коэффициента маски, а output1 содержит прототипы маски. В моделях FP32 и INT8 все выходы имеют тип float32, кроме карты семантических классов.

При использовании nms=True порог уверенности conf (по умолчанию 0.25), порог IoU iou (по умолчанию 0.5), agnostic_nms и max_det (по умолчанию 300) фиксируются в графе при экспорте. Более низкое значение conf во время инференса не вернёт детекции, уже удалённые графом, поэтому для изменения этих значений выполни экспорт заново. max_det и agnostic_nms также применяются к nms=False: max_det=100 задаёт для output0 форму (1, 100, 6).

YOLO("yolo26n.onnx") считывает расположение данных из метаданных файла, поэтому эти формы нужны только при запуске модели в собственном коде. Метаданные также доступны в коде в виде строк: names, task, imgsz, stride, batch, end2end и args.

import ast

import onnxruntime as ort

meta = ort.InferenceSession("yolo26n.onnx").get_modelmeta().custom_metadata_map
names = ast.literal_eval(meta["names"])  # {0: 'person', 1: 'bicycle', ...}
imgsz = ast.literal_eval(meta["imgsz"])  # [640, 640]

Разверни#

YOLO("yolo26n.onnx") запускает модель с ONNX Runtime и выбирает провайдер выполнения на основе аргумента device. На машине с графическим процессором CUDA используется GPU, если device не задан.

deviceПровайдер выполнения
cpuCPUExecutionProvider
0 на графическом процессоре NVIDIACUDAExecutionProvider из пакета onnxruntime-gpu, который устанавливается при первом использовании
0 на графическом процессоре AMD ROCmMIGraphXExecutionProvider; см. Инференс на графических процессорах AMD с MIGraphX
mps на устройствах с чипами AppleCoreMLExecutionProvider для узлов со статическими формами; узлы с динамическими формами запускаются на CPUExecutionProvider

Строка журнала Using ONNX Runtime 1.31.1 with CUDAExecutionProvider показывает активный провайдер. Поведение во время инференса зависит от способа экспорта модели:

  • Статический экспорт (по умолчанию): модель всегда запускается с параметрами экспорта imgsz и batch, которые Ultralytics считывает из метаданных файла. Переданный в predict параметр imgsz игнорируется. Большие пакеты разбиваются на блоки размером с пакет экспорта, а меньшие дополняются, поэтому поддерживается любое количество изображений.
  • Динамический экспорт (dynamic=True): predict принимает любое значение imgsz, кратное шагу модели. Размер пакета может меняться, но при nms=True он ограничен значением batch, использованным при экспорте, поэтому укажи наибольший размер пакета, который планируешь использовать.
  • Память GPU: при CUDAExecutionProvider статическая модель использует привязку ввода-вывода ONNX Runtime, которая хранит входные и выходные тензоры на GPU. Динамическая модель при каждом вызове копирует их через память CPU.
  • Потоки CPU: Ultralytics ограничивает число потоков ONNX Runtime внутри операций до 8 или до числа физических ядер CPU, доступных процессу, если оно меньше. Чтобы задать другое число, используй переменную среды ORT_INTRA_OP_NUM_THREADS.

Передай dnn=True в predict или val, чтобы запускать модель на CPU с OpenCV DNN вместо ONNX Runtime. OpenCV DNN поддерживает меньше параметров экспорта; см. Ограничения и устранение неполадок.

Чтобы запускать модель вне пакета Ultralytics, воспользуйся следующими ресурсами:

Инференс Windows ML#

В Windows 11 24H2 (сборка 26100) или новее с Python 3.10+ установи onnxruntime-windowsml в отдельное окружение, чтобы Windows ML мог выбирать провайдеры выполнения для твоего оборудования. Установи его вместо других сборок ONNX Runtime, а затем используй ту же экспортированную модель .onnx с YOLO("model.onnx"). Бэкенд сохраняет количество потоков PyTorch и переданные параметры сессии, включая явную политику выбора провайдера. Если политика не задана, Windows ML выбирает оборудование для максимальной производительности, даже если устройство PyTorch — cpu. Прежде чем выбирать эту среду выполнения, измерь задержку предсказания на своём устройстве; она необязательна и по умолчанию не устанавливается.

На интегрированных GPU, которые используют питание совместно с CPU, простаивающие потоки PyTorch при предобработке и постобработке могут замедлять инференс Windows ML. Перед предсказанием вызови torch.set_num_threads(1), чтобы уменьшить эту задержку. Это влияет на весь процесс, поэтому другие модели PyTorch в этом процессе тоже будут работать в одном потоке.

import torch

from ultralytics import YOLO

torch.set_num_threads(1)  # необязательно, измерь на своём устройстве
results = YOLO("yolo26n.onnx")("https://ultralytics.com/images/bus.jpg")

Инференс на GPU AMD с MIGraphX#

Ultralytics запускает экспортированные модели ONNX на графических процессорах AMD через провайдер выполнения MIGraphX для ONNX Runtime. В системе ROCm (HIP) с Python 3.11 или новее и архитектурой x86-64 бэкенд ONNX при первом использовании устанавливает плагин onnxruntime-ep-migraphx и автоматически выбирает MIGraphXExecutionProvider, не требуя изменений в коде; поддерживаются все задачи YOLO26. Предварительные требования, установку, использование, тесты производительности и кэш скомпилированных программ см. в руководстве по инференсу на графических процессорах AMD.

Ограничения и устранение неполадок#

  • Минимальная версия opset: экспорт завершается ошибкой ONNX export requires opset>=N, если значение opset слишком мало для модели. Минимум — 7 для классификации, 9 для обнаружения объектов, сегментации, семантической сегментации, оценки позы и OBB, 11 для оценки глубины, а также для моделей обнаружения объектов, сегментации, оценки позы и OBB, экспортированных с nms=True, и 16 для RT-DETR.
  • Входы FP16: модель FP16, экспортированная на GPU (quantize=16 device=0), ожидает тензоры входных данных FP16 в собственном коде. Модель FP16, экспортированная на CPU, сохраняет входы и выходы FP32 и выполняет преобразование внутри графа. YOLO() передаёт обоим вариантам правильный тип входных данных — и на GPU, и на CPU.
  • Имя файла INT8: quantize=8 создаёт файл yolo26n_int8.onnx и удаляет промежуточный файл FP32, поэтому для инференса загружай файл _int8. Исключение — чекпойнт, обученный с quantize=8: при его экспорте узлы Q/DQ записываются в yolo26n.onnx, а калибровка пропускается.
  • Размер калибровки INT8: при экспорте чекпойнта, не обученного с quantize=8, появляется предупреждение, если в калибровочной выборке меньше 300 изображений. По умолчанию для калибровки используется выборка val, а в coco8.yaml всего 4 проверочных изображения, поэтому для модели, которую планируешь развернуть, используй собственный набор данных.
  • Встроенный NMS: для nms=True требуется PyTorch 1.13 или новее. Для классификации возникает ошибка 'nms=True' is not valid for classification models, а для моделей семантической сегментации, оценки глубины и RT-DETR параметр игнорируется с предупреждением.
  • Голова без NMS: для nms=False нужна модель с головой без NMS, например YOLO26 или YOLOv10. Для других моделей, например YOLO11, при экспорте появится предупреждение This model has no one-to-one head; using one-to-many outputs, а в файл будет записан исходный выход (1, 84, 8400).
  • GPU не используется: если в журнале указано CUDA requested but CUDAExecutionProvider not available. Using CPU..., в установленной сборке ONNX Runtime нет рабочего провайдера CUDA. Установи onnxruntime-gpu вместо onnxruntime и проверь, что версии CUDA и cuDNN в нём соответствуют системе.
  • OpenCV DNN: в OpenCV 4.14.0 dnn=True запускает модели с настройками по умолчанию, nms=False, INT8 и FP16, экспортированные для GPU. Не удаётся загрузить модели, экспортированные с nms=True, с dynamic=True или с quantize=16 на CPU.
  • Динамические формы с NMS: если объединяешь dynamic=True с nms=True, также задай для batch наибольший размер пакета, который планируешь использовать. При значении 1 для batch экспорт выдаст предупреждение.
  • Упрощение графа: если onnxslim завершается ошибкой, при экспорте выводится предупреждение, а модель сохраняется без упрощения.
  • Версия IR: экспортёр ограничивает версию IR ONNX значением 10, чтобы файл можно было загружать в более старых версиях ONNX Runtime. При экспорте с настройками по умолчанию и opset 18 используется версия IR 8.

Другие ошибки описаны в руководстве по распространённым проблемам.

Бенчмарки#

YOLO26n работает с ONNX Runtime на CPU (Intel Xeon CPU @ 2.00 GHz) до 43% быстрее, чем YOLO11n. На странице модели YOLO26 указана скорость ONNX на CPU для каждой модели и всех задач, кроме семантической сегментации.



Смотри: Сравнение инференса Ultralytics YOLO26 и Ultralytics YOLO11 в ONNX | YOLO26 обеспечивает инференс примерно на 43% быстрее 🚀

FP32, FP16 и INT8 с ONNX Runtime#

В таблицах ниже сравниваются PyTorch и модели YOLO26 для обнаружения объектов в форматах ONNX FP32, FP16 и INT8, запущенные с CUDAExecutionProvider для ONNX Runtime. Все значения для GPU измерены на одном графическом процессоре NVIDIA RTX PRO 6000 Blackwell Server Edition.

Миллисекунды на изображение; меньше — лучше. Для каждой модели жирным выделен самый быстрый формат.

МодельimgszPyTorchONNX FP32ONNX FP16ONNX INT8
YOLO26n6402.851.961.883.73
YOLO26s6402.982.141.734.31
YOLO26m6403.293.012.145.37
YOLO26l6404.704.093.087.51
YOLO26x6405.935.563.909.38

YOLO26n на CPU (AMD EPYC 9655, PyTorch и ONNX Runtime — по 8 потоков; процессор отличается от использованного для таблиц моделей YOLO26):

ПоказательPyTorchONNX FP32ONNX FP16ONNX INT8
Задержка (мс/изображение)13.213.413.256.5
mAPval 50–9540.840.940.938.7
  • FP16 уменьшил размер файла вдвое при снижении mAP не более чем на 0.1 относительно FP32 и работал на GPU до 1.4 раза быстрее FP32, но на CPU ускорения не было.
  • INT8 обеспечил наименьший размер файла, но снизил mAP на 2.2–3.0 и работал медленнее FP32 и на GPU, и на CPU.

Измерения выполнены с ultralytics 8.4.211, ONNX Runtime 1.30.0, PyTorch 2.15.0 и CUDA 13.2 при batch=1 13 ноября 2026 года. Задержка относится к этапу инференса, который показывает val, и не включает предобработку и постобработку.

Об ONNX#

ONNX — это общественный проект, который начали Facebook и Microsoft и который сейчас развивается при участии таких организаций, как IBM, Amazon и Google. Он определяет общий набор операторов и формат файлов для моделей машинного обучения, благодаря чему модель, обученная в одном фреймворке, например PyTorch, может работать во многих средах выполнения и на различных аппаратных платформах.

ONNX model portability across deep learning frameworks

ONNX Runtime — кроссплатформенный движок инференса для моделей ONNX. Его провайдеры выполнения используют специализированные для конкретного оборудования библиотеки, чтобы запускать модель на CPU, GPU и выделенных ускорителях.

ONNX Runtime cross-platform inference acceleration

ONNX также служит промежуточным этапом для других форматов экспорта Ultralytics, включая TensorRT, и входным форматом для инструментальных цепочек производителей NPU, таких как Huawei Ascend, Qualcomm QNN и Rockchip RKNN. Спецификацию смотри в документации ONNX.

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

  • Не указывай opset, если среде выполнения не нужна конкретная версия. В таком случае экспортер использует opset 18 в PyTorch 2.4 и новее, opset 17 в PyTorch от 1.13 до 2.3, более низкий opset в старых версиях PyTorch и никогда не превышает версию, поддерживаемую установленным пакетом onnx. По умолчанию используется opset не выше 18, поскольку провайдер CUDA в ONNX Runtime выполняет некоторые операторы opset 19 и новее, например Resize, на CPU. Задай более низкое значение, например opset=12, если старая среда выполнения или конвертер отклоняет значение по умолчанию. Значение не может быть ниже минимального opset для модели.

  • Это зависит от аргумента nms, с которым ты выполнил экспорт. Экспорт по умолчанию возвращает необработанные предсказания, для которых нужны фильтрация по уверенности и NMS. Экспорт с nms=False или nms=True возвращает до max_det (по умолчанию 300) финальных детекций на изображение в формате x1, y1, x2, y2, score, class и в пикселях входного изображения, поэтому достаточно отфильтровать результаты по оценке и масштабировать рамки обратно до размеров исходного изображения. Строки OBB содержат center x, center y, width, height вместо координат углов, а также угол. Формы тензоров смотри в разделе Формат выходных данных.

    Чтение выходных данных без NMS с помощью ONNX Runtime
    # Сначала выполни экспорт: yolo export model=yolo26n.pt format=onnx nms=False
    import numpy as np
    import onnxruntime as ort
    
    session = ort.InferenceSession("yolo26n.onnx")  # экспортировано с nms=False
    image = np.zeros((1, 3, 640, 640), dtype=np.float32)  # предварительно обработанное изображение
    detections = session.run(None, {"images": image})[0][0]  # shape (300, 6)
    detections = detections[detections[:, 4] > 0.25]  # оставить строки выше порога уверенности
  • Задай dynamic=True. Тогда вход images будет иметь форму (batch, 3, height, width), причем размер пакета, высота и ширина задаются динамически, а выход детекции по умолчанию (nms=None) output0 имеет форму (batch, 84, anchors), поэтому при инференсе один и тот же файл поддерживает разные размеры пакетов и изображений. При использовании nms=True размер пакета ограничен значением batch, заданным при экспорте. Высота и ширина должны быть кратны шагу модели, который для официальных чекпойнтов YOLO26, кроме моделей классификации, равен 32. Динамическая модель не использует IO binding на CUDA и не загружается в OpenCV DNN, поэтому при фиксированном размере входных данных оставь статический экспорт по умолчанию.

    Экспорт с динамическими размерами
    from ultralytics import YOLO
    
    model = YOLO("yolo26n.pt")
    model.export(format="onnx", dynamic=True)
  • Используй ONNX, если один файл должен работать на разном оборудовании или если машина для развертывания отличается от машины, на которой ты выполняешь экспорт. Используй TensorRT, чтобы добиться минимальной задержки на конкретном GPU NVIDIA: движок TensorRT собирается для одной архитектуры GPU и одной версии TensorRT и не переносим на другие платформы. Другие варианты смотри в руководстве по развертыванию моделей.

  • Да. У ONNX Runtime есть веб- и мобильные сборки, которые загружают один и тот же файл .onnx. Выполни экспорт с nms=False, чтобы не включать постобработку в код приложения. На телефонах используются нативные форматы: Core ML на iOS и LiteRT на Android.

Комментарии77

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

  1. dopeggguyGitHub

    The parameter "half" bost apperence in train and export, what’s difference. when we using this parameter what should we need attention.

    1. Glenn JocherUltralytics(изменено)

      @dopeggguy Good question—summary: training uses mixed precision via amp=True (weights stay FP32; compute is FP16 where safe), while export uses quantize=16 (the former half=True, now deprecated) to write an FP16 model for runtimes that support FP16. During training prefer amp; use FP16 only at export/inference, and don't combine it with INT8 (quantize=8). See the train overview and AMP notes in the Train mode docs and the quantize option details in Model Export – Arguments and Configuration – Export Settings.

      from ultralytics import YOLO
      
      # Mixed-precision training (recommended)
      YOLO("yolo26n.yaml").train(data="data.yaml", amp=True)
      
      # FP16 export for FP16-capable runtimes (e.g., CUDA/TensorRT/OpenVINO FP16)
      YOLO("best.pt").export(format="onnx", quantize=16)
    2. dopeggguyGitHub

      yoloModel = YOLO(path_dir) yoloModel.export(format='onnx', dynamic=False, half=True, imgsz=(640, 640))

      I'm not sure why. I enabled half=True, but the actual size of the exported model doesn't seem to change at all.

    3. Glenn JocherUltralytics(изменено)

      @dopeggguy half=True is deprecated in favor of quantize=16. On older releases a CPU-only ONNX export ignored the flag and stayed FP32, so the file size was almost identical. Current releases convert CPU ONNX exports to FP16 too (keeping float32 inputs/outputs), and GPU exports are FP16 natively. If you have a GPU, you can force export on it and re-check:

      from ultralytics import YOLO
      
      YOLO(path_dir).export(format="onnx", imgsz=(640, 640), dynamic=False, quantize=16, device=0)

      You can then open the ONNX in Netron or inspect it with the onnx Python API to confirm the weights are float16; for pure CPU deployments it is often better to keep ONNX as FP32 or use a CPU‑oriented backend (e.g. OpenVINO) for FP16/INT8 optimization instead, with some general ONNX background outlined in the ONNX: Open Neural Network Exchange overview.

  2. bastinj98GitHub

    Hi, I trained d a YOLOV8-segn model to detect and segment a single class (nc=1) and then exported in to onnx (simplify, nms, half are all False) with opset = 17. The output shape is 1x37x8400.

    I am building a C++ pipeline to use this model to run inference. How can I process this output to get the final segmentation mask ?

  3. NgZimingGitHub

    I exported a yolo 11 segment model to onnx format, and used onnx-runtime to infer. It responded two ndarrays of shapes (1, 37, 21504) and (1, 32, 256, 256). (imgsz=1024) So, how can i extract masks from these two arrays?

    1. Glenn JocherUltralytics

      @NgZiming 这两个输出正是分割模型的“检测头 + 原型掩码”:(1, 37, 21504) = 4(xywh) + nc + 32(mask系数),(1, 32, 256, 256) 为32个原型;掩码可由原型与对应检测的32维系数线性组合并裁剪到框内,最小示例(Python/NumPy)如下:

      import numpy as np
      import cv2
      
      def sigmoid(x): return 1 / (1 + np.exp(-x))
      
      def mask_from_outputs(det, proto, img_h, img_w, det_idx):
          # det: (1, C, N) -> (C, N), proto: (1, 32, 256, 256) -> (32, 256, 256)
          det = det[0]; proto = proto[0]
          nm, ph, pw = proto.shape  # 32, 256, 256
          nc = det.shape[0] - 4 - nm
      
          # 1) 取该检测的框、类别分数与32维掩码系数
          cx, cy, w, h = det[0, det_idx], det[1, det_idx], det[2, det_idx], det[3, det_idx]
          coeff = det[4+nc:4+nc+nm, det_idx]  # (32,)
      
          # 2) 原型 × 系数 -> 原始掩码 (ph, pw)
          m = sigmoid((proto.reshape(nm, -1).T @ coeff).reshape(ph, pw))
      
          # 3) 可选:按框在原型分辨率下裁剪(坐标为[0,1]比例)
          x0 = int(max(0, (cx - w/2) * pw)); x1 = int(min(pw, (cx + w/2) * pw))
          y0 = int(max(0, (cy - h/2) * ph)); y1 = int(min(ph, (cy + h/2) * ph))
          crop = np.zeros_like(m); crop[y0:y1, x0:x1] = m[y0:y1, x0:x1]
      
          # 4) 上采样到原图尺寸并二值化
          mask = cv2.resize(crop, (img_w, img_h), interpolation=cv2.INTER_LINEAR)
          return (mask > 0.5).astype(np.uint8)

      要点:确保与推理时的预处理一致(letterbox 缩放与填充、RGB/归一化等),否则框与掩码会错位。关于分割导出产生两个输出(output0 检测+系数,output1 原型)的由来,可见导出实现参考的 export_onnx 说明:export_onnx 函数参考.

      1
  4. User

    I have a question. If it's convenient, please answer it. Thank you! I'm working with cell images, and the image size is 3072*2048. I trained with imagesize=3072, but if I use imagesize=640, I can't detect objects. I can predict with a 3072 imagesize using a pt file, but now I'm trying to switch to C++ and call onnx, and the 3072 inference is very slow. Is this normal?

    1. Glenn JocherUltralytics

      @giter915 Yes—running 3072×2048 through ONNX/C++ will be much slower; inference time grows quickly with input area. Two practical options: use a faster backend or reduce effective input while keeping accuracy. For GPU, prefer TensorRT; for CPU, OpenVINO FP16/INT8 gives the largest gains. Examples:

      from ultralytics import YOLO
      
      # GPU-optimized
      YOLO("best.pt").export(format="engine", imgsz=1536, half=True, dynamic=True)
      
      # CPU-optimized
      YOLO("best.pt").export(format="openvino", imgsz=1536, half=True)  # add int8=True with calibration if desired

      If you must keep 3072, tile the image (e.g., 1024×1024 patches), run ONNX per tile, then merge detections with NMS in C++; this is a common approach for microscopy. Also ensure preprocessing in C++ exactly matches Python (letterbox padding, RGB order, 1/255 scaling)—agree with @DennisJcy here. For backend choices and supported export targets, see the export formats table in Object Detection – Ultralytics YOLO Docs, and for high‑throughput GPU serving consider Triton Inference Server with YOLO11.

    2. Glenn JocherUltralytics

      Glad it helped—one extra tip for ONNX Runtime C++: enable full graph optimizations and tune threads to squeeze more speed from large inputs like 3072×2048.

      #include <onnxruntime_cxx_api.h>
      #include <thread>
      
      Ort::Env env(ORT_LOGGING_LEVEL_WARNING, "yolo");
      Ort::SessionOptions so;
      so.SetGraphOptimizationLevel(GraphOptimizationLevel::ORT_ENABLE_ALL);
      so.SetIntraOpNumThreads(std::thread::hardware_concurrency());
      so.SetInterOpNumThreads(1);  // often fine to leave at 1
      
      Ort::Session session(env, "best.onnx", so);
  5. denni281GitHub(изменено)

    Hello, I use ultratics to export YOLO11 half-Precision onnx model, but when I load the .onnx model to eval by onnxruntime, exception shows :Unexpected input data type. Actual: (tensor(float16)) , expected: (tensor(float)). And I compare the Float32 and Float16(half) .onnx model,These two files are exactly the same in size and input type.So the "half" keyword doesn't take effect when exporting ONNX, right? I remember Ultralytics didn't have this issue last year.

    Here is my python script to export half-precision onnx model:

    def main(opt):
        model = YOLO(opt.model)
        model.export(
            format="onnx",
            # opset=12,
            simplify=True,
            dynamic=False,
            imgsz=opt.imgsz,
            half=opt.half,
            batch=opt.batch,
        )
    
    
    if __name__ == "__main__":
        multiprocessing.freeze_support()
        parser = argparse.ArgumentParser()
        parser.add_argument(
            "--model",
            type=str,
            default="/home/ultralytics/runs/detect/SHFY/weights/best.pt",
        )
        parser.add_argument("--imgsz", type=int, default=640)
        parser.add_argument("--half", type=bool, default=True)
        parser.add_argument("--batch", type=int, default=1)
        opt, unparsed = parser.parse_known_args()
        print(opt)
        main(opt)
    
    1. denni281GitHub(изменено)

      Fine... It's my fault. My docker environment is Python-3.11.9 torch-2.4.1+cu118 CPU (unknown). The error is made by my cpu environment

    2. Glenn JocherUltralytics(изменено)

      @DennisJcy thanks for the update. On older releases half=True had no effect on CPU ONNX exports, so the file stayed FP32. Current Ultralytics uses quantize=16 (replacing the deprecated half) and also converts CPU ONNX exports to FP16 while keeping float32 inputs/outputs, whereas GPU exports (device=0) are FP16 natively and need an FP16-capable ONNX Runtime provider. For CPU-optimized FP16 you can also export OpenVINO. For example:

      from ultralytics import YOLO
      
      # FP16 ONNX
      YOLO("best.pt").export(format="onnx", quantize=16)
      
      # CPU-optimized FP16 (OpenVINO)
      YOLO("best.pt").export(format="openvino", quantize=16)

      Details on OpenVINO export are in the export_openvino reference.

  6. ShuaibZyxGitHub

    def yolo_to_onnx(model_path, input_shape=(600, 600)): # Load the YOLOv8 model model = YOLO(model_path)

    # Export the model to ONNX format
    model.export(format='onnx', 
                 imgsz=input_shape,
                 dynamic=True,
                 batch=1,
                 device="0")

    Ultralytics YOLOv8.0.220 🚀 Python-3.9.18 torch-2.1.1+cu121 CUDA:0 (Tesla T4, 14931MiB) Model summary (fused): 268 layers, 43610463 parameters, 0 gradients, 164.8 GFLOPs

    PyTorch: starting from 'best.pt' with input shape (1, 3, 640, 640) BCHW and output shape(s) (1, 9, 8400) (83.6 MB)

    ONNX: starting export with onnx 1.18.0 opset 17... ONNX: export success ✅ 3.3s, saved as 'best.onnx' (166.5 MB) 我的模型在训练时是5个类别的目标检测,导出的模型的输出格式是(1, 9, 8400)。 我想请问您其中9具体代表的是什么呢? 如果是为了预测5个类别(1, 9, 8400)的输出格式是正确的嘛? 期待您的帮助!感谢!

    1. xiaoqiang-lGitHub

      9指的是:[x,y,w,h,class1_scores,class2_scores,class3_scores,class4_scores,class5_scores],即四个坐标及N个类别分数。 8400指的是:640下采样8倍、16倍、32倍特征图的anchor总数,(640/8)(640/8)+(640/16)(640/16)+(640/32)(640/32)=8080+4040+2020=8400

    2. Glenn JocherUltralytics

      @ShuaibZyx you're welcome! @xiaoqiang-l provided an excellent explanation. Just to confirm, the output shape (1, 9, 8400) is indeed correct for your 5-class detection model - the 9 channels represent the 4 bounding box coordinates (x, y, w, h) plus 5 class confidence scores. The 8400 represents all detection anchors across the three feature map scales (80×80 + 40×40 + 20×20 = 8400 total anchors).

  7. UltralyticsAssistantGitHubUltralytics

    👋 Hello, thank you for your interest in Ultralytics 🚀! We recommend a visit to the Docs for new users where you can find many Python and CLI usage examples, as well as detailed guides about exporting YOLO models to ONNX and other formats.

    If this is a 🐛 Bug Report, please provide a minimum reproducible example to help us debug it.

    If you have a custom training ❓ Question or require help with ONNX export, please include as much detail as possible—such as your command, model version, logs, and environment details. Also, check out our Tips for Best Training Results for optimal performance.

    Join the Ultralytics community where it suits you best! For real-time chat, head to Discord 🎧. For in-depth discussions, try Discourse, or join the conversation on our Subreddit.

    Upgrade

    Upgrade to the latest ultralytics package including all requirements in a Python>=3.8 environment with PyTorch>=1.8 to ensure you’re using the most up-to-date features and bug fixes:

    pip install -U ultralytics

    Environments

    YOLO can be run in these up-to-date verified environments, with all dependencies including CUDA/CUDNN, Python, and PyTorch preinstalled:

    Status

    Ultralytics CI

    If this badge is green, all Ultralytics CI tests are currently passing. CI tests verify correct operation of all YOLO Modes and Tasks on macOS, Windows, and Ubuntu every 24 hours and on every commit.

    This is an automated response 🤖. An Ultralytics engineer will review your discussion and assist you soon!

    1. Glenn JocherUltralytics

      Hello! Thanks for your interest in exporting YOLO11 models to ONNX format. This is a great option for deployment across different platforms with performance benefits.

      Exporting to ONNX is straightforward with Ultralytics:

      from ultralytics import YOLO
      
      # Load model
      model = YOLO("yolo11n.pt")  # or your custom trained model
      
      # Export to ONNX with optional parameters
      model.export(format="onnx", dynamic=True, simplify=True)  # creates 'yolo11n.onnx'
      
      # Use the exported model
      onnx_model = YOLO("yolo11n.onnx")
      results = onnx_model("https://ultralytics.com/images/bus.jpg")

      ONNX export can provide up to 3x CPU speedup compared to PyTorch models. You can customize the export with several parameters like half=True for FP16 precision, dynamic=True for variable input sizes, or opset to specify the ONNX version.

      For deployment, you can use ONNX Runtime or integrate with platforms like NVIDIA Triton Inference Server for production-scale serving.

      If you have specific questions about exporting your models or encounter any issues during the process, please let us know!

  8. UltralyticsAssistantGitHubUltralytics

    👋 Hello, thank you for your interest in Ultralytics 🚀! For users exploring ONNX integration and YOLO11, we recommend checking out the Docs where you’ll find dedicated Python and CLI tutorials, as well as specific ONNX integration guidance.

    If this is a 🐛 Bug Report, please provide a minimum reproducible example to help us investigate further.

    For custom deployment or export ❓ questions, please include as many details as possible, such as your export commands, model versions, and error logs. Make sure you review our Tips for Best Training Results for optimal performance.

    Join the Ultralytics community where it suits you best: jump into real-time conversations on Discord 🎧, post or search on Discourse, or connect on our Subreddit.

    Upgrade

    Upgrade to the latest ultralytics package, including all requirements, in a Python>=3.8 environment with PyTorch>=1.8 to ensure you have the latest features and fixes:

    pip install -U ultralytics

    Environments

    YOLO can be run in any of the following up-to-date verified environments (with all dependencies including CUDA/CUDNN, Python and PyTorch preinstalled):

    Status

    Ultralytics CI

    If this badge is green, all Ultralytics CI tests are currently passing. CI tests verify correct operation of all YOLO Modes and Tasks on macOS, Windows, and Ubuntu every 24 hours and on every commit.

    This is an automated response. An Ultralytics engineer will assist you here soon!

    1. Glenn JocherUltralytics

      Yes, you can adjust the batch size dynamically when exporting to ONNX format by using the dynamic=True parameter in your export call. When this is enabled, the batch dimension becomes dynamic, allowing you to use various batch sizes during inference without reexporting the model.

      Here's a simple example:

      from ultralytics import YOLO
      
      # Load your model
      model = YOLO("yolo11n.pt")
      
      # Export with dynamic input size
      model.export(format="onnx", dynamic=True)

      This creates dynamic dimensions in the exported ONNX model, where the batch dimension (as well as height and width) can vary during inference. The resulting model will be more flexible for production deployments where batch size requirements might change.

  9. skyceeeeGitHub

    First of all, thank you for everything. Can we adjust the batch size dynamically when exporting the model as onnx?

  10. xiaoqiang-lGitHub

    When I export the YOLOV11 onnx model, I use: model.export(format='onnx', imgsz=640, device='cpu'). Then I use onnxruntime (1.14.0) to deploy it on the C++ side, but an error is reported during runtime: onnxruntime::Model::Model Unsupported model IR version: 9, max supported IR version: 8. Is there any parameter or method to set the exported model to support IR version: 8? Because I cannot upgrade onnxruntime to other higher versions locally, I look forward to your help

    1. Glenn JocherUltralytics

      @xiaoqiang-l to resolve the ONNX IR version compatibility issue, you can specify an older opset version during export. Try adding opset=13 to your export command:

      model.export(format='onnx', imgsz=640, device='cpu', opset=13)

      This will generate an ONNX model compatible with IR version 8. For detailed version mapping, see the ONNX operator version matrix in the ONNX documentation.