FAQ

С какой модели начать?

YOLOv9 — если нужен CNN-детектор, RF-DETR — если трансформерный. Обе модели относятся к флагманскому уровню: новые возможности сначала проектируются и проверяются на GPU именно на них и только потом на всём остальном. Смотрите YOLOv9 и RF-DETR, а про остальные — все модели.

Нужна ли GPU?

Нет. Каждая модель работает на CPU, и всё в быстром старте написано так, чтобы запускаться именно там. GPU меняет то, сколько времени занимают обучение и инференс на видео, а не то, работают ли они вообще.

Как LibreYOLO выбирает устройство?

По умолчанию стоит device="auto": используется CUDA, когда PyTorch сообщает, что она доступна, затем Metal Performance Shaders, когда доступны они, и CPU во всех остальных случаях. Чтобы зафиксировать устройство, передайте device модели или в predict, train, val и export. Принимаются "cpu", "cuda", "cuda:0", "mps", просто целое число вроде 0 или строка из цифр; последние два варианта разворачиваются в cuda:<n>.

libreyolo checks печатает сборку Torch, её версии CUDA и cuDNN и все GPU, которые она видит. Если эта команда не показывает CUDA, значит, установлен wheel PyTorch, собранный под CPU; о его замене рассказывает установка.

Куда попадают скачанные веса?

В weights/ относительно рабочего каталога. Ссылка на модель без указания каталога разрешается именно туда и скачивается при первом использовании; ссылка, в которой каталог есть, используется ровно так, как написана, и не скачивается никогда. Смотрите чекпойнты и веса.

Можно ли работать без доступа к сети?

Да. Скачайте чекпойнты один раз на машине с сетью, перенесите каталог weights/, и больше ничего в сеть не пойдёт. Общий путь, доступный только на чтение, тоже подходит: ссылка с каталогом понимается буквально. Датасеты ищутся в ~/datasets или в каталоге из LIBREYOLO_DATASETS_DIR.

Можно ли использовать LibreYOLO в коммерческих проектах?

Код под лицензией MIT. Предобученные веса — отдельный вопрос: они могут наследовать условия проекта или датасета, из которого получены, и эти условия неодинаковы даже внутри одного семейства. Решает лицензия конкретного репозитория на Hugging Face, и на странице каждой модели есть раздел о лицензировании, который её воспроизводит. Там, где веса ограничены, LibreYOLO печатает ограничение до начала скачивания.

Можно ли загрузить чекпойнт из другого проекта?

Обычно да — достаточно передать путь к нему в LibreYOLO(). Распознаваемые форматы чекпойнтов из других проектов конвертируются при загрузке, сохраняя количество классов и их имена, а рядом с исходным файлом записывается чекпойнт LibreYOLO. О том, что распознаётся, а что требует скрипта конвертации, рассказывает импорт существующих весов.

Почему train выбрасывает NotImplementedError?

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

Что возвращает val?

Обычный словарь, а не объект. Для детекции ключи включают metrics/precision, metrics/recall, metrics/mAP50 и metrics/mAP50-95. Другие задачи возвращают ключи, осмысленные для них: например, metrics/accuracy_top1 для классификации или metrics/PQ, metrics/SQ и metrics/RQ для паноптической сегментации.

Как запустить на папке, видео или веб-камере?

Передайте это как источник. Путь к файлу — одно изображение, каталог — все изображения в нём, путь к видео — видео, целое число — индекс веб-камеры, а URL по RTSP, RTMP, TCP, UDP или HLS — живой поток. Файл .streams перечисляет сразу несколько источников. Живым источникам нужен stream=True: он отдаёт по одному Results на кадр вместо того, чтобы собирать список; тот же флаг стоит использовать для длинных видео и больших каталогов. Дополнительная зависимость libreyolo[stream] нужна только для URL страниц YouTube.

Как оставить только часть классов?

Передайте в predict аргумент classes с индексами нужных классов, например classes=[0, 2]. conf задаёт порог уверенности, по умолчанию 0.25, а max_det ограничивает число детекций на изображение, по умолчанию 300.

CLI использует флаги или пары key=value?

Ключ и значение через знак равенства — и так в каждой команде:

libreyolo predict model=yolo9-t source=my-image.jpg save=True
libreyolo train model=yolo9-t data=coco8.yaml epochs=50 imgsz=640

model принимает путь или короткое имя вида family-size, при желании с суффиксом задачи, а libreyolo models перечисляет все допустимые. Команды диагностики и вывода списков принимают ещё и --json: те же данные печатаются в stdout как машиночитаемый объект.

Каждая ли модель экспортируется в каждый формат?

Нет. Покрытие зависит от семейства и от задачи, оно неодинаково, и для каждого формата нужно ставить свою дополнительную зависимость. На странице каждой модели есть матрица экспорта её семейства; про сами форматы рассказывает раздел про экспорт.

Чем отличаются segment, semantic и panoptic?

Это три разные задачи. segment выдаёт по одной маске на каждый найденный объект. semantic присваивает класс каждому пикселю и ничего не разделяет на экземпляры. panoptic даёт каждому пикселю ровно одну метку, объединяя счётные объекты с аморфным фоном. У них разная эталонная разметка (ground truth), разные поля в результате и разные метрики, а семейство поддерживает те из них, что перечислены в его списке задач.

Как обучить на своих классах?

Напишите YAML датасета с train, val и names. Метки лежат рядом с изображениями в параллельном дереве labels/: по одному .txt на изображение, с нормализованными координатами. nc необязателен и, если он есть, должен согласовываться с names. Сначала запустите libreyolo doctor <data.yaml>: команда проверяет датасет на проблемы и завершается с ненулевым кодом, когда находит ошибки, — это позволяет использовать её как проверку в CI.

Почему при загрузке печатается предупреждение о метаданных?

Потому что в чекпойнте нет полных метаданных v1.0. Загрузка продолжается по пути совместимости, а предупреждение точно называет, каких ключей не хватает. Запустите libreyolo metadata path=<file>, чтобы посмотреть, что в нём есть, а о требованиях схемы рассказывают чекпойнты и веса.

После обновления перестал работать импорт. Что изменилось?

Ради единообразия переименованы два класса: LibreYOLORTDETR стал LibreRTDETR, а LibreYOLORFDETR — LibreRFDETR. Старые имена по-прежнему разрешаются и выдают DeprecationWarning с указанием на новое, так что существующий код продолжает работать, пока вы его обновляете.