libreyolo doctor

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

Команда: libreyolo doctor
Обязательный: data
Вывод: Отчёт о находках в stdout. Код возврата 1, если найдены ошибки

Синопсис

bash

libreyolo doctor <data.yaml> [key=value ...]

Датасет передаётся позиционно, и как альтернатива принимается data=<path>. Если указать оба с разными значениями, команда завершится с config_conflict. Всё остальное — пары key=value, причём POSIX-форма тоже работает, так что imgsz=1024 и --imgsz 1024 — один и тот же аргумент.

Аргументы

Аргумент	По умолчанию	Описание
`data`		Позиционный. YAML датасета в формате детекции YOLO, например `coco8.yaml`. Обязателен
`imgsz`	`640`	Размер изображения при обучении, используется в проверках на уровне пикселей, например для крошечных объектов
`fast`	`false`	Пропустить декодирование изображений, из-за чего отключаются проверки на повреждения, дубликаты и утечки
`skip`		Id проверок или семейства через запятую, которые нужно пропустить, например `images,labels.tiny_object`
`only`		Id проверок или семейства через запятую, которые нужно выполнить исключительно
`strict`	`false`	Предупреждения тоже влияют на код возврата, для CI-гейтов
`download`	`false`	Разрешить скачивание датасета по URL, если его нет. Никаких скриптов
`json`	`false`	Вывод JSON в stdout
`quiet`	`false`	Подавить stderr
`help_json`	`false`	Вывести схему команды как JSON и выйти

Семейства проверок

skip и only принимают как полный id проверки, так и префикс семейства, так что images выбирает все проверки images.*.

Семейство	Что охватывает
`config`	Сам YAML датасета: отсутствующие `names`, `nc` против `names`, отсутствующие сплиты, неразрешимый `path`, дублирующиеся имена классов
`files`	Сопоставление изображений и разметки: отсутствующие файлы разметки, отсутствующие изображения, осиротевшая разметка, неподдерживаемые расширения, коллизии регистра
`labels`	Содержимое разметки: синтаксис, строки полигонов, id классов вне диапазона, координаты вне диапазона, вырожденные рамки, крошечные объекты, огромные рамки, экстремальные соотношения сторон, дублирующиеся рамки, перегруженные изображения, идентичные файлы
`images`	Данные пикселей: повреждённые файлы, ориентация EXIF, необычные цветовые режимы, крошечные или экстремальные размеры, однородные изображения, точные и почти точные дубликаты
`splits`	Утечки между сплитами, точные и почти точные
`balance`	Распределение классов: классы с нулём или малым числом экземпляров, дисбаланс, покрытие сплитов, доля фона, перекос между сплитами

Примеры

Базовый запуск

# download=true разрешает встроенному coco8.yaml скачать изображения, если их нет.libreyolo doctor coco8.yaml download=true

Быстрый проход, без декодирования изображений

libreyolo doctor coco8.yaml download=true fast=true

CI-гейт по выбранным проверкам

libreyolo doctor coco8.yaml download=true strict=true json=true \  only=labels,files,config

Примечания

Коды возврата

0, если ошибок не нашлось, 1, если хотя бы одна находка — ошибка. При strict=true предупреждения тоже поднимают код возврата до 1, и именно эта настройка нужна CI-гейту.

У проблем с использованием свои коды: 2 для неизвестного id проверки или семейства в skip или only, 3, если датасет не найден, и 3, если датасет не имеет формата детекции.

Выбор проверок разрешается до сканирования

skip и only разрешаются по реестру проверок ещё до того, как что-либо читается с диска, поэтому опечатка приводит к ошибке сразу, а не после долгого прохода по изображениям. Селектор, который ни с чем не совпал, — ошибка, и в сообщении перечислены известные семейства.

Если после сочетания skip, only и fast не остаётся ни одной проверки, это тоже ошибка, а не молчаливый успех.

Скачивание

Датасет не скачивается, если не указано download=true, и выполняются только загрузки по URL. Встроенный в YAML датасета Python-скрипт скачивания эта команда не выполняет никогда, каким бы ни был флаг.

Область применения

Проверки написаны для датасетов детекции. Датасет, разметка которого имеет формат позы, сегментации или повёрнутых рамок, распознаётся и отклоняется с data_invalid, а не оценивается по неподходящим правилам.

Вывод

Человекочитаемый отчёт идёт в stdout, а json=true заменяет его структурированным объектом со сводными счётчиками, статистикой датасета, всеми находками и списком пропущенных проверок.

Связанное: libreyolo train — запуск, перед которым эту команду и стоит выполнять.