Уровни стабильности

Уровни поддержки экспорта

Уровень, который решает, сработает ли вызов. Он относится к тройке (family, task, format), и у каждой комбинации он ровно один.

И validated, и available выполняются без подтверждения от пользователя и без общего предупреждения. Разница — в свидетельствах, а не в разрешении: за записью validated стоит тест на соответствие и релиз в поле since, а за записью available — пока нет. Например, конвертация в CoreML без прогона предсказания на macOS — это available, а не validated.

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

В каждой ячейке validated записано ограничение, описывающее конфигурацию, из которой получено число соответствия: обычно это фиксированный размер входа, батч 1, FP32 и конкретная версия среды выполнения. Читать его нужно как утверждение об этой конфигурации, а не о формате вообще. Правила, по которым заполняются ячейки без явной записи, описаны на странице матрицы экспорта.

from libreyolo.models.registry import GROUPS, group_offrom libreyolo.export.support import get_support, validated_alternatives family = "yolo9" group = group_of(family)print(group, GROUPS[group]) print(get_support(family, "detect", "onnx").tier)print(validated_alternatives(family, "detect"))

Уровни API

Уровень, который решает, как выглядит вызов. Семейство относится ровно к одному, и уровень определяется контрактом вызова, а не архитектурой.

Три родственных уровня намеренно не регистрируются в фабрике детекторов — поэтому LibreYOLO("some-alias") до них не добирается. Они загружаются по алиасу размера с автоскачиванием, а не по распознаванию чекпойнта.

Все четыре возвращают один и тот же Results, поэтому код дальше по цепочке не меняется. Различается лишь то, какие методы работают: родственные уровни выбрасывают NotImplementedError для train(), val() и export(), а уровни SAM и открытого словаря — ещё и для track(). На странице каждого уровня перечислены свои исключения.

Группы покрытия

Классификация, которая решает, какие семейства попадают в прогон тестов, охватывающий сразу несколько семейств, и та, с которой читатель скорее всего встретится на странице модели. Каждое зарегистрированное семейство записано ровно в одну группу, и тест падает, если зарегистрированное семейство не записано ни в одну из них. GROUPS в libreyolo/models/registry.py — источник колонки «Значение» ниже; MODEL_GROUPS в том же файле распределяет каждое семейство, а колонка «Семейства» напрямую считает это распределение. Колонка «Метка» — более короткое имя, под которым сайт показывает ту же группу в заголовке страницы модели.

Итого 87 семейств в шести группах. В одной только g3 семейств больше, чем во всех остальных группах вместе взятых: большая часть реестра — это линии только для инференса и музейное покрытие, а не активно обучаемые детекторы.

Читателю, который выбирает модель, группа говорит, где ждать инженерного внимания, а не насколько семейство точное. В g0 и g1 новую возможность проектируют, и туда она попадает в первую очередь; g2 держат зелёной в CI, но новая возможность доходит туда, когда получится, а не на той же волне релиза. g3 фиксирует отсутствие, а не ограничение: предсказание, валидация и — там, где семейство это поддерживает — экспорт по-прежнему работают, а train() на семействе из g3 или g4 выбрасывает NotImplementedError с указанием причины вместо того, чтобы молча сделать что-то наполовину. Семейства из s в этом компромиссе не участвуют вовсе, потому что загружаются через собственную фабрику, а не через LibreYOLO(). О том, как группа сочетается с задачей, семейством и размером при чтении имени файла чекпойнта, см. основные понятия.

Сама по себе группа не даёт и не ограничивает пользовательские возможности. Поддержка следует из реализованного API семейства и из проверок возможностей, специфичных для формата, но никогда — из одной лишь принадлежности к группе. Группы классифицируют семейства, а не задачи, поэтому прогон покрытия в рамках одной задачи называет её явно — как в «g1 detect».

Есть два места, где группа читается во время работы, а не только в тестах. collect_model_inventory() в libreyolo/models/inventory.py добавляет группу к каждой записи, которую печатает инвентарь в CLI, а pretrained=False запускает особый путь переинициализации с нуля только для семейств из g0 и g1. За пределами этих двух групп проверка в libreyolo/models/base/model.py пропускается целиком, и pretrained=False доходит до собственного train() семейства как обычный именованный аргумент.

Обучение

У семейства из g3 или g4 нет реализации обучения, и вызов train() на нём выбрасывает исключение. Это свойство кода семейства, а не его группы: группа фиксирует факт, а не создаёт его.

Для семейства, которое обучается, вопрос о том, доходит ли отдельный параметр аугментации до пайплайна, — отдельный, и у него свой словарь из трёх значений: used, gated_by_mosaic и ignored. См. матрицу аугментаций.

О чём уровень не говорит

Уровень — не утверждение о точности. Экспорт со статусом validated говорит, что артефакт воспроизводит исходную модель в пределах заявленного порога, и ничего не говорит о том, какие метрики исходная модель показывает на датасете. Числа бенчмарков — на страницах моделей.

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