Что дальше

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

Поскольку публичная фабрика LibreYOLO(...) ожидает настоящий файл весов, удобнее всего начать одну из этих задач с нуля, напрямую создав класс семейства и передав task=. Обученные чекпойнты загружаются через единую фабрику, которая автоматически определяет их задачу.

1
from libreyolo import LibreYOLO, LibreYOLO9, LibreRFDETR
2
3
# Start a task from scratch via the family class
4
m = LibreYOLO9(None, size="t", task="classify", nb_classes=10)
5
6
# Load a trained checkpoint via the unified factory (task auto-detected)
7
m = LibreYOLO("LibreYOLO9t-obb.pt")

Классификация присваивает всему изображению одну метку. YOLO9 сохраняет свой бэкбон и добавляет лёгкую голову классификации, а RF-DETR повторно использует энкодер DINOv2 и добавляет линейную голову с пулингом. Обе модели работают с разрешением 224 на 224.

Инференс и результат Probs

Предсказание возвращает объект Results, поле probs которого содержит softmax по классам.

1
from libreyolo import LibreYOLO
2
3
model = LibreYOLO("LibreYOLO9t-cls.pt")
4
r = model.predict("cat.jpg")
5
6
print(r.probs.top1)        # class id of the argmax
7
print(r.probs.top1conf)    # its probability
8
print(r.probs.top5)        # [id, id, id, id, id]
9
print(model.names[r.probs.top1])  # human-readable label

Формат датасета и обучение

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

1
dataset/
2
  train/
3
    cat/   img001.jpg ...
4
    dog/   img104.jpg ...
5
  val/
6
    cat/   ...
7
    dog/   ...

Аргумент data= принимает папку, URL файла .zip или известное имя для автоматического скачивания (imagenette160 и imagenet10). Голова автоматически перестраивается под число классов в датасете.

1
from libreyolo import LibreYOLO9
2
3
model = LibreYOLO9(None, size="t", task="classify", nb_classes=10)
4
result = model.train(
5
    data="imagenette160",   # folder, .zip URL, or known name
6
    epochs=10, batch=64, imgsz=224,
7
    optimizer="adamw", lr0=1e-3,
8
)
9
# Validation reports metrics/accuracy_top1 and metrics/accuracy_top5

Повёрнутые рамки содержат угол поворота, необходимый для аэроснимков, документов и сцен с плотно расположенными объектами. YOLO9 добавляет ветвь угла к голове детекции, а RF-DETR добавляет обучаемый эмбеддинг угла в декодер.

Инференс и результат OBB

В Results доступно поле obb. Углы задаются в радианах.

1
from libreyolo import LibreYOLO
2
3
model = LibreYOLO("LibreYOLO9t-obb.pt")
4
r = model.predict("aerial.jpg")
5
6
for i in range(len(r.obb.cls)):
7
    cx, cy, w, h, angle = r.obb.xywhr[i]  # angle in radians
8
    corners = r.obb.xyxyxyxy[i]           # 4 (x, y) corner points
9
    conf, cls = r.obb.conf[i], r.obb.cls[i]

Формат датасета и обучение

Для OBB используется стандартный YAML данных в формате детекции, но метки хранятся в текстовых файлах YOLO-OBB, где каждая строка содержит ровно девять полей: идентификатор класса и четыре нормализованные угловые точки. Угол вычисляется по углам рамки, а не хранится отдельно.

1
# class_id  x1 y1  x2 y2  x3 y3  x4 y4   (all normalized to [0, 1])
2
0  0.51 0.32  0.66 0.38  0.62 0.55  0.47 0.49
3
2  0.10 0.71  0.18 0.69  0.20 0.80  0.12 0.82

Обычный чекпойнт детекции нельзя напрямую загрузить в модель OBB. Переход от детекции к OBB разрешён только для инициализации обучения: передайте pretrained=True для YOLO9 или явный флаг переноса для RF-DETR. Mosaic и mixup отключены для OBB до появления аугментации с учётом углов, а потайловый инференс не поддерживается.

1
from libreyolo import LibreYOLO9
2
3
model = LibreYOLO9(None, size="t", task="obb")
4
# Warm-start the backbone from a same-family detect checkpoint
5
result = model.train(data="dota8.yaml", pretrained=True, epochs=100, imgsz=640)
6
7
# CLI equivalent
8
# libreyolo train model=LibreYOLO9t.pt data=dota8.yaml --task obb

Для валидации используется AP по повёрнутому IoU, который сообщается как mAP50 и mAP50-95 в группе метрик OBB.

Оценка позы предсказывает ключевые точки для каждого обнаруженного экземпляра. По умолчанию используется схема ключевых точек человека COCO-17. В первой версии оценка позы YOLO9 и RF-DETR работает только с одним классом людей, а модели позы YOLO-NAS и EdgeCrafter уже доступны в дереве исходного кода.

Инференс и результат Keypoints

В Results доступно поле keypoints формы (N, K, 3), где последний канал содержит видимость или уверенность, а координаты заданы в пикселях исходного изображения.

1
from libreyolo import LibreYOLO
2
3
model = LibreYOLO("LibreYOLO9t-pose.pt")
4
r = model.predict("athletes.jpg")
5
6
kp = r.keypoints
7
print(kp.xy.shape)   # (N, 17, 2) pixel coordinates
8
print(kp.conf)       # (N, 17)    per-keypoint visibility / confidence
9
print(kp.xyn)        # normalized coordinates
10
print(r.boxes.xyxy)  # person boxes still come along

Формат датасета и обучение

Для оценки позы используется YAML данных, в котором нужно объявить kpt_shape: [K, 2|3], а для аугментации с горизонтальным отражением — flip_idx. Метки представляют собой текстовые строки YOLO-pose: идентификатор класса, нормализованная рамка, затем K троек ключевых точек (x, y, v) с видимостью v из множества {0, 1, 2}.

1
path: coco8-pose
2
train: images/train
3
val: images/val
4
nc: 1
5
names:
6
  0: person
7
kpt_shape: [17, 3]
8
flip_idx: [0, 2, 1, 4, 3, 6, 5, 8, 7, 10, 9, 12, 11, 14, 13, 16, 15]

1
from libreyolo import LibreYOLO9
2
3
# Warm-start from a detection checkpoint; the keypoint head is reinitialized
4
model = LibreYOLO9("LibreYOLO9t.pt", size="t", task="pose")
5
model.train(data="coco8-pose.yaml", epochs=100, imgsz=640)
6
7
# Validation reports OKS-based AP via the pose validator

YOLO9-P2 — вариант YOLOv9 с четвёртым масштабом детекции при шаге 4. Обычная YOLOv9 выполняет детекцию с шагами 8/16/32, поэтому объекты меньше ~16 px оказываются мельче самой точной сетки. Голова P2 охватывает диапазон 4–16 px, преобладающий на аэроснимках и видео с дронов.

В контролируемом A/B-тесте на VisDrone с одинаковыми рецептом, разрешением и инициализацией, где отличалась только голова P2, AP малых объектов вырос на +49% относительно обычной YOLOv9 того же размера. Более высокое разрешение обучения и увеличенный размер s примерно удвоили AP малых объектов во всём проекте:

VisDrone2019-DET val (548 изображений), pycocotools, одно начальное значение. Разницу ±1 пункт следует считать шумом.

Исследовательская превью-версия VisDrone

Обученный чекпойнт опубликован как LibreYOLO9P2s-visdrone. Семейство слито в dev, но ещё не вошло в релиз PyPI, поэтому до следующего релиза устанавливайте его из исходного кода.

1
from libreyolo import LibreYOLO
2
3
# Auto-downloads from the LibreYOLO Hugging Face org
4
model = LibreYOLO("LibreYOLO9P2s-visdrone.pt")
5
6
# Evaluate/predict at 768 - the resolution it was trained at
7
results = model.predict("aerial.jpg", imgsz=768, conf=0.25)

Когда использовать и когда не использовать

Выбирайте архитектуру под задачу. На данных, похожих на COCO, где «малые» объекты имеют размер 16–32 px, голова P2 не помогает, и обычная YOLOv9 будет лучше. Используйте YOLO9-P2 для объектов меньше ~16 px: на видео с дронов и аэросъёмке, удалённых камерах видеонаблюдения и спутниковых тайлах. Дополнительный масштаб примерно удваивает объём вычислений и число якорей. Такова цена сетки с шагом 4.

Обучение своей модели

YOLO9-P2 инициализируется переносом из обычных чекпойнтов детекции YOLOv9: загружаются бэкбон, общий neck и существующие башни головы, а новые модули P2 начинают с нуля. В рецепте ниже отражены уроки, полученные при работе с очень малыми объектами:

1
from libreyolo import LibreYOLO9P2
2
3
model = LibreYOLO9P2(None, size="s")
4
model.train(
5
    data="/abs/path/tiny_objects.yaml",
6
    imgsz=768,                # resolution is the biggest lever for tiny objects
7
    lr0=0.005,                # the family default 0.01 diverges on transfer init
8
    mosaic_prob=0.0,          # mosaic tiling shrinks tiny objects below detectability
9
    mixup_prob=0.0,
10
    hsv_prob=1.0, flip_prob=0.5,
11
    max_labels=600,           # dense aerial frames exceed the default 100-box cap
12
    pretrained="LibreYOLO9s.pt",  # transfer init from stock YOLOv9
13
    epochs=60,
14
)

Адаптеры в стиле LoRA позволяют дообучать бэкбон-трансформер RF-DETR на небольшом наборе низкоранговых матриц, пока основные веса остаются замороженными. Это сокращает память для оптимизатора и градиентов, что удобно для адаптации сильного чекпойнта к новой области на скромном оборудовании.

Включение

Весь публичный API сводится к одному флагу в train(). Настраивать ранг, alpha или целевые модули не нужно: рецепт зафиксирован в хорошо проверенной конфигурации. Внутри реализация использует DoRA (LoRA с разложением весов, ранг 16) для проекций запросов, ключей и значений механизма внимания DINOv2.

1
from libreyolo import LibreYOLO
2
3
model = LibreYOLO("rf-detr-nano.pth")   # sizes n, s, m, l
4
result = model.train(
5
    data="data.yaml",
6
    lora=True,        # DoRA on the frozen DINOv2 backbone
7
    epochs=100, batch_size=4, lr=1e-4,
8
)
9
10
# Resume: LoRA is auto-detected from the checkpoint, no need to repeat the flag
11
model.train(data="data.yaml", resume=True)

1
# CLI equivalent
2
libreyolo train --model rf-detr-nano.pth --data data.yaml --lora

Чекпойнты и экспорт

• Обучающие чекпойнты сохраняют тензоры адаптеров, а конфигурация записывает использование LoRA, поэтому при загрузке и продолжении обучения граф адаптеров восстанавливается автоматически.
• Голова детекции всегда остаётся обучаемой, поэтому модель можно адаптировать к новому числу классов.
• export() снова объединяет адаптеры с плотными весами. Экспортированные модели остаются обычными и не зависят от peft.
• LoRA доступна только для RF-DETR. Передача lora=True другим семействам вызывает понятную ошибку.

Текущее состояние каждой функции. Всё здесь экспериментально, и эта таблица показывает реальную картину.