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, а результаты детекции и сегментации дополнительно содержат результаты по отдельным изображениям и кривые точности, полноты и F1 по классам в metrics.box. Результаты детекции, сегментации и классификации содержат metrics.confusion_matrix, а классификация добавляет metrics.top1 и metrics.top5. Другие задачи возвращают ключи, осмысленные для них: например, 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=Truelibreyolo 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 с указанием на новое, так что существующий код продолжает работать, пока вы его обновляете.

Почему имя чекпойнта не позволяет скачать его?

Используйте точное имя файла из таблицы чекпойнтов на странице модели. Имена FCN и Mask R-CNN с суффиксами задач не размещены; ошибка загрузчика перечисляет поддерживаемые формы. LingBot-Vision g не имеет опубликованного чекпойнта: используйте s, b, l или локальный чекпойнт.