DEIM

Установка

Ни одной из версий не нужен дополнительный extra. Всё, что они импортируют, входит в базовую установку.

pip install libreyolo

Исключение — дообучение адаптерами через lora=True: ему нужен extra lora.

pip install "libreyolo[lora]"

Предсказание

Веса скачиваются с Hugging Face при первом запуске и кэшируются локально.

from libreyolo import LibreYOLO, SAMPLE_IMAGE model = LibreYOLO("LibreDEIMn.pt")result = model(SAMPLE_IMAGE, save=True) for box in result.boxes:    print(box.cls, box.conf, box.xyxy)

libreyolo predict model=LibreDEIMn.pt save=True \  source=https://raw.githubusercontent.com/LibreYOLO/libreyolo/release/libreyolo/assets/parkour.jpg

from libreyolo import LibreYOLO # Версия входит в имя файла, а фабрика выбирает по чекпойнту, поэтому# обе загружаются одинаково.model = LibreYOLO("LibreDEIMv2pico.pt") # Любой источник, который принимает библиотека: файл, папка, URL, индекс# веб-камеры, RTSP-поток или список .streamsfor result in model.predict("clip.mp4", stream=True, save=True):    print(len(result.boxes))

Возвращаемый объект Results — тот же, что возвращает любое семейство, поэтому подменить детектор на другой можно одной строкой. conf и max_det фильтруют top-k-декодирование по запросам и классам; шага NMS, который нужно было бы настраивать, здесь нет, а iou принимается, но не используется. Про источники, стриминг и обработку результатов — предсказание.

DEIM принимает прямоугольный imgsz=(height, width) для предсказания. DEIMv2 явно отклоняет прямоугольные входы при предсказании и валидации. Это не означает поддержку прямоугольных входов при обучении или экспорте.

Варианты

Версия 1 поставляется в пяти размерах, все с одинаковым входным разрешением. Версия 2 сохраняет эти пять названий и добавляет три меньших — atto, femto и pico, — первые два из которых нативно работают на меньшем входном разрешении, чем остальные. Поэтому пять кодов размеров существуют в обеих версиях и обозначают разные модели; версия записана в имя файла чекпойнта.

Версия 1 сохраняет архитектуру D-FINE и заменяет её целевую функцию классификации на функцию потерь с учётом сопоставимости из рецепта плотного взаимно однозначного сопоставления, поэтому у двух семейств совпадают почти все ключи state dict, и различают их по метаданным в чекпойнте. Версия 2 сохраняет этот контракт обучения и смешивает бэкбоны: HGNetv2 ниже s и vision transformer DINOv3 с адаптером пространственной подстройки на s и выше. Именно из-за этого бэкбона на этих четырёх чекпойнтах появляется вторая лицензия, так что прежде чем выкатывать такой чекпойнт, прочитайте лицензирование.

Обучение

Обучение начинается с опубликованного чекпойнта. pretrained до обучения не доходит: версия 1 предупреждает, что ключ неизвестен, и игнорирует его, версия 2 его удаляет. Ни та, ни другая не дадут модель со случайной инициализацией.

from libreyolo import LibreYOLO model = LibreYOLO("LibreDEIMn.pt") # coco128.yaml при первом запуске скачивает выборку из 128 изображений.# Для реального запуска укажите в `data` YAML своего датасета.model.train(data="coco128.yaml", epochs=50, batch=8, lr0=1e-4)

libreyolo train model=LibreDEIMn.pt data=coco128.yaml \  epochs=50 batch=8 lr0=1e-4

from libreyolo import LibreYOLO # Если epochs, batch, imgsz и lr0 не заданы, они берутся из# опубликованного рецепта для загруженного размера.model = LibreYOLO("LibreDEIMv2pico.pt")model.train(data="coco128.yaml", epochs=50)

# Требуется extra lora: pip install "libreyolo[lora]"from libreyolo import LibreYOLO model = LibreYOLO("LibreDEIMn.pt")model.train(data="coco128.yaml", epochs=50, lora=True)

libreyolo train model=LibreDEIMn.pt data=coco128.yaml \  epochs=50 device=0,1

На версии 1 задавайте lr0 сами. В сигнатуре Python-метода train() по умолчанию стоит 4e-4 — скорость обучения из опубликованного рецепта для COCO, — тогда как в конфиге обучения этого семейства значением по умолчанию для дообучения записано 1e-4, и именно это меньшее значение подставляет CLI, если аргумент не передан. В конфиге записано и измерение, которое за этим стоит: при размерах батча, которые реально используются при дообучении, на небольших датасетах скорость обучения из рецепта COCO заметно ухудшала перенос.

Версия 2 разрешает эти значения по умолчанию сама. Если epochs, batch, imgsz и lr0 не заданы, каждое из них читается из опубликованного рецепта для загруженного размера, поэтому маленькие размеры обучаются на своём входном разрешении без дополнительных указаний, а переданное вами значение перекрывает рецепт. Ограничение накладывается на imgsz: он должен быть положительным числом, кратным 32, иначе версия 2 выбросит ошибку ещё до старта запуска.

Про датасеты, аугментацию, обучение на нескольких GPU и логгеры — обучение.

DEIM по умолчанию включает AMP с amp_dtype="float16". Для обучения в FP32 передайте amp=False.

Валидация

val() возвращает словарь с ключами metrics/, которые покрывают точность, полноту, mAP 50 и mAP 50-95, посчитанные на любом датасете в том формате, на котором вы обучались.

from libreyolo import LibreYOLO model = LibreYOLO("LibreDEIMn.pt") # val() возвращает обычный dict, а не объектmetrics = model.val(data="coco128.yaml") print(metrics["metrics/mAP50-95"])print(metrics["metrics/mAP50"])print(metrics["metrics/precision"], metrics["metrics/recall"])

libreyolo val model=LibreDEIMn.pt data=coco128.yaml

# coco-val-only.yaml скачивает 5000 изображений val2017 и пропускает# обучающий набор. Внутри него есть встроенный скрипт загрузки, поэтому# нужно явное разрешение, если датасета ещё нет локально.libreyolo val model=LibreDEIMn.pt data=coco-val-only.yaml \  allow_download_scripts=True

Строки в таблице бенчмарков выше получены на бенчмарк-стенде LibreYOLO; в примечании под этой таблицей указано, на каком датасете они получены, и даны ссылки на записи о запусках.

Экспорт

Матрица описывает обе версии на одной странице: там, где они расходятся по формату, в ячейке показан более слабый из двух вариантов, так что здесь ничего не приукрашено — какую бы версию вы ни загрузили.

Экспортированный артефакт загружается обратно через LibreYOLO() по суффиксу файла, поэтому файл .onnx или .engine ведёт себя как чекпойнт и возвращает тот же Results.

# Требуется extra onnx: pip install "libreyolo[onnx]"from libreyolo import LibreYOLO model = LibreYOLO("LibreDEIMn.pt")path = model.export(format="onnx")print(path)

libreyolo export model=LibreDEIMn.pt format=onnx

from libreyolo import LibreYOLO, SAMPLE_IMAGE # Фабрика выбирает по суффиксу файла, поэтому экспортированный артефакт# загружается как обычный чекпойнт и возвращает тот же объект Results.model = LibreYOLO("LibreDEIMn.onnx")result = model(SAMPLE_IMAGE) print(result.boxes.xyxy)

Входы и выходы ONNX

Чекпойнты

Все опубликованные файлы весов этого семейства.

Лицензирование

Цитирование

@misc{huang2024deim,
      title={DEIM: DETR with Improved Matching for Fast Convergence},
      author={Shihua, Huang and Zhichao, Lu and Xiaodong, Cun and Yongjun, Yu and Xiao, Zhou and Xi, Shen},
      booktitle={Proceedings of the IEEE/CVF Conference on Computer Vision and Pattern Recognition},
      year={2025},
}

DEIMv2 — отдельная статья, и у неё свой блок цитирования на github.com/Intellindust-AI-Lab/DEIMv2; ссылайтесь на него, если использовали чекпойнт версии 2.