утилиты libreyolo

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

Команды: version, checks, models, formats, cfg, info, metadata, enroll, compare
Вывод: stdout, в текстовом виде или с json=true — одним объектом с полем schema_version

Синтаксис

bash

libreyolo <command> [key=value ...]

Аргументы — это пары key=value, причём POSIX-форма тоже работает, так что model=x и --model x — один и тот же аргумент. Каждая команда здесь пишет результат в stdout и принимает json=true и quiet=true.

У корневой команды есть собственный флаг, libreyolo --version, который печатает строку версии и завершается. Это более краткий вывод, чем у команды version ниже.

version

Печатает версию LibreYOLO, а также версии Python, torch и CUDA, с которыми она работает.

bash

libreyolo version

Аргумент	По умолчанию	Назначение
`json`	`false`	Вывод JSON в stdout
`quiet`	`false`	Подавить stderr

checks

Печатает окружение подробнее: Python, torch, CUDA, cuDNN, каждую обнаруженную GPU с её названием и объёмом памяти, а также установленную версию каждого необязательного пакета, который используют пути экспорта.

bash

libreyolo checks

Аргумент	По умолчанию	Назначение
`json`	`false`	Вывод JSON в stdout
`quiet`	`false`	Подавить stderr

Список пакетов охватывает onnx, onnxruntime, tensorrt, openvino, paddlepaddle, x2paddle, mnn, ncnn, onnx2tf, ai-edge-litert, transformers и scipy. Неустановленный пакет так и отмечается, а не пропускается, поэтому неудачный экспорт можно свести к недостающей зависимости одной этой командой.

models

Перечисляет все семейства моделей с их задачами, размерами, именами в CLI, которые разрешаются в их чекпойнты, и входным разрешением для каждого размера.

bash

libreyolo models

Аргумент	По умолчанию	Назначение
`json`	`false`	Вывод JSON в stdout
`quiet`	`false`	Подавить stderr

Семейство, у которого не установлена необязательная зависимость, отмечается как недоступное вместе со строкой pip install, которая сделает его доступным. Имена в CLI — это то, что model= принимает как сокращение: yolox-s разрешается в LibreYOLOXs.pt, а задачи, отличные от детекции, несут суффикс своей задачи.

formats

Перечисляет форматы экспорта, которые может выдать установленное окружение, с расширением файла для каждого формата и признаком поддержки FP16 и INT8.

bash

libreyolo formats [family=<family>] [task=<task>]

Аргумент	По умолчанию	Назначение
`family`		Показать уровни поддержки для одного семейства моделей. `model=` принимается как та же опция
`task`		Каноническая задача модели. Если не задана — задача семейства по умолчанию
`json`	`false`	Вывод JSON в stdout
`quiet`	`false`	Подавить stderr

Без family вывод — это только перечень форматов. С ним каждый формат получает уровень поддержки для этого семейства и задачи, причину такого уровня и любое связанное с ним ограничение. Неизвестное семейство или задача, которую семейство не поддерживает, — ошибка использования.

Псевдонимы форматов показываются рядом с каноническим именем: engine для tensorrt, litert для tflite.

cfg

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

bash

libreyolo cfg

Аргумент	По умолчанию	Назначение
`json`	`false`	Вывод JSON в stdout
`quiet`	`false`	Подавить stderr

Значения читаются из dataclass-структур конфигурации, а не из копии, поэтому именно здесь написано, что возьмёт запуск обучения, если не передать аргумент. family_overrides — тот раздел, который отвечает, почему семейство обучалось с настройками, которых вы не просили. О том, как применяются эти переопределения, см. libreyolo train.

info

Загружает модель на CPU и сообщает её семейство, размер, число параметров, классы и уровень поддержки экспорта для каждого формата.

bash

libreyolo info model=<name|path>

Аргумент	По умолчанию	Назначение
`model`		Имя модели или путь к весам. Обязательный
`detailed`	`false`	Включить подробности по каждому параметру
`json`	`false`	Вывод JSON в stdout
`quiet`	`false`	Подавить stderr

metadata

Читает метаданные чекпойнта, не собирая модель, и проверяет их по схеме чекпойнтов LibreYOLO.

bash

libreyolo metadata path=<checkpoint.pt>

Аргумент	По умолчанию	Назначение
`path`		Путь к `.pt`-чекпойнту. Обязательный
`json`	`false`	Вывод JSON в stdout
`quiet`	`false`	Подавить stderr

Крупные записи с тензорами сводятся к краткой сводке, а не печатаются целиком, поэтому вывод остаётся читаемым и на полном чекпойнте обучения. Чекпойнт, которого не существует, завершается с checkpoint_not_found, а тот, чьи метаданные не проходят проверку, печатает ошибки и завершается с кодом 1.

enroll

Собирает галерею лиц из дерева «папка на человека», чтобы последующие предсказания могли называть найденные лица.

bash

libreyolo enroll model=<embedder> source=<people-dir> gallery=<gallery.npz>

Аргумент	По умолчанию	Назначение
`model`		Модель эмбеддингов лиц, путь или имя. Обязательный
`source`		Дерево «папка на человека», `source/<identity>/*.jpg`. Обязательный
`gallery`		Выходной файл галереи `.npz`. Если он уже есть, дополняется на месте. Обязательный
`face_detector`		Детектор лиц: YuNet `.onnx` или детектор LibreYOLO. Если не задан — детектор семейства по умолчанию
`device`	`auto`	Устройство: `0`, `cpu`, `mps`, `auto`
`json`	`false`	Вывод JSON в stdout
`quiet`	`false`	Подавить stderr

bash

# в people/ лежит по одной папке на личность; имя папки становится личностью.
libreyolo enroll model=librefacerec-l.onnx source=people/ gallery=people.npz

Имя подпапки — это личность. Эталонное изображение, на котором лицо не обнаружено, пропускается со строкой в stderr, а остальные обрабатываются дальше; источник без подпапок с личностями, как и источник, в котором не нашлось ни одного лица, — ошибка.

Передайте полученный файл в libreyolo predict как gallery=people.npz, чтобы детекции несли личность и оценку совпадения.

compare

Сообщает косинусное сходство двух изображений лиц и то, проходит ли оно порог одной и той же личности.

bash

libreyolo compare model=<embedder> source=<a.jpg> source2=<b.jpg>

Аргумент	По умолчанию	Назначение
`model`		Модель эмбеддингов лиц, путь или имя. Обязательный
`source`		Первое изображение. Обязательный
`source2`		Второе изображение для сравнения. Обязательный
`face_detector`		Детектор лиц: YuNet `.onnx` или детектор LibreYOLO
`threshold`	`0.4`	Порог косинусного сходства для решения о том, что это одна и та же личность
`device`	`auto`	Устройство: `0`, `cpu`, `mps`, `auto`
`json`	`false`	Вывод JSON в stdout
`quiet`	`false`	Подавить stderr

bash

libreyolo compare model=librefacerec-l.onnx source=a.jpg source2=b.jpg

libreyolo verify зарегистрирована как второе имя этой команды и принимает те же аргументы.

И compare, и enroll требуют модель, задача которой — эмбеддинг лиц. Всё остальное завершается с config_unsupported. Источниками принимаются и локальные пути к изображениям, и http- или https-URL.

Примеры

Окружение

libreyolo versionlibreyolo checks

Что доступно

libreyolo modelslibreyolo formats family=yolo9 task=detect

Просмотр чекпойнта

libreyolo info model=LibreYOLO9s.ptlibreyolo metadata path=weights/LibreYOLO9s.pt

Примечания

Результат идёт в stdout; прогресс и предупреждения — в stderr. json=true печатает один объект с schema_version — именно эту форму стоит читать из скрипта. Текстовый вывод используется по умолчанию и рассчитан на чтение человеком.

Коды выхода следуют той же схеме, что и в остальной CLI: 0 при успехе, 2 при ошибке использования или конфигурации, 3 когда источник не найден, 4 когда не удаётся загрузить модель или чекпойнт, и 1 для прочих сбоев во время выполнения.

Смотрите также: libreyolo doctor — команда осмотра со стороны датасета, и libreyolo profile — со стороны производительности.