Що далі

Типовою задачею кожного сімейства є виявлення. Іншу задачу можна вибрати одним із трьох способів, які застосовуються в такому порядку пріоритету:

Оскільки загальнодоступна фабрика 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 пікселів потрапляють під її найдрібнішу сітку. Голова P2 охоплює діапазон 4-16 пікселів, який переважає на аерознімках і відео з дронів.

У контрольованому 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 пікселі), голова P2 не допомагає. Стандартна YOLOv9 там є кращим вибором. Використовуйте YOLO9-P2, коли ваші об'єкти менші за ~16 пікселів: на відео з дронів та аерознімках, віддалених камерах спостереження й супутникових тайлах. Додатковий масштаб приблизно подвоює обсяг обчислень і кількість якорів. Це ціна сітки з кроком 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(). Немає параметрів рангу, альфи чи цільових модулів для налаштування, рецепт зафіксовано в добре перевіреній конфігурації. Усередині реалізація використовує 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 іншим сімействам спричиняє зрозумілу помилку.

Поточний стан кожної функції. Усе тут є експериментальним, а ця таблиця чесно показує ситуацію.