Co dalej

Każda rodzina domyślnie wykonuje detekcję. Inne zadanie można wybrać na jeden z trzech sposobów, rozstrzyganych w następującej kolejności pierwszeństwa:

Publiczna fabryka LibreYOLO(...) oczekuje rzeczywistego pliku wag, dlatego najprostszym sposobem rozpoczęcia jednego z tych zadań od zera jest bezpośrednie utworzenie klasy rodziny i przekazanie task=. Wytrenowane checkpointy są ponownie wczytywane przez ujednoliconą fabrykę, która automatycznie wykrywa ich zadanie.

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")

Klasyfikacja przypisuje jedną etykietę do całego obrazu. YOLO9 zachowuje swój backbone i dodaje lekką głowicę klasyfikacji, a RF-DETR ponownie wykorzystuje enkoder DINOv2 i dodaje liniową głowicę z agregacją. Oba działają w rozdzielczości 224 na 224.

Inferencja i wynik Probs

Predykcja zwraca obiekt Results, którego pole probs zawiera softmax dla klas.

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

Format zbioru danych i trenowanie

Klasyfikacja używa układu ImageFolder, a nie YAML. Nazwy klas to posortowane nazwy podfolderów, ustalone według podziału treningowego.

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

Argument data= przyjmuje folder, adres URL pliku .zip lub znaną nazwę automatycznego pobierania (imagenette160 i imagenet10). Głowica jest automatycznie przebudowywana, aby odpowiadała liczbie klas w zbiorze danych.

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

Obrócone ramki zawierają kąt obrotu potrzebny w obrazach lotniczych, dokumentach i gęsto wypełnionych scenach. YOLO9 dodaje gałąź kąta do głowicy detekcji, a RF-DETR dodaje uczony embedding kąta do dekodera.

Inferencja i wynik OBB

Obiekt Results udostępnia pole obb. Kąty są podawane w radianach.

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]

Format zbioru danych i trenowanie

OBB używa standardowego pliku danych YAML w stylu detekcji, ale etykiety są plikami tekstowymi YOLO-OBB zawierającymi dokładnie dziewięć pól w każdym wierszu: identyfikator klasy, po którym następują cztery znormalizowane punkty narożne. Kąt jest wyznaczany na podstawie narożników, a nie zapisywany.

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

Zwykłego checkpointu detekcji nie można wczytać bezpośrednio do modelu OBB. Przejście z detekcji do OBB jest dozwolone wyłącznie jako inicjalizacja trenowania: przekaż pretrained=True (YOLO9) lub jawną flagę transferu w RF-DETR. Mosaic i mixup są wyłączone dla OBB do czasu dodania augmentacji uwzględniającej narożniki, a inferencja kafelkowa nie jest obsługiwana.

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

Walidacja używa AP z obróconym IoU, raportowanego jako mAP50 i mAP50-95 w grupie metryk OBB.

Estymacja pozy przewiduje punkty kluczowe każdej wykrytej instancji. Domyślny układ to punkty kluczowe osób COCO-17. Pierwsze wersje estymacji pozy YOLO9 i RF-DETR obsługują wyłącznie jedną klasę osób. Estymacja pozy YOLO-NAS i EdgeCrafter jest już dostępna w drzewie.

Inferencja i wynik Keypoints

Obiekt Results udostępnia pole keypoints o kształcie (N, K, 3), w którym ostatni kanał oznacza widoczność lub pewność, we współrzędnych pikselowych oryginalnego obrazu.

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

Format zbioru danych i trenowanie

Estymacja pozy używa pliku danych YAML, który musi deklarować kpt_shape: [K, 2|3], a w przypadku augmentacji z odbiciem poziomym także flip_idx. Etykiety są wierszami tekstowymi YOLO-pose: identyfikator klasy, znormalizowana ramka, a następnie K trójek punktów kluczowych (x, y, v) z widocznością v należącą do {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 to YOLOv9 z czwartą skalą detekcji o kroku 4. Standardowy YOLOv9 wykrywa z krokami 8/16/32, więc obiekty mniejsze niż około 16 px znajdują się poniżej jego najdrobniejszej siatki. Głowica P2 przechwytuje zakres 4–16 px dominujący na nagraniach lotniczych i z dronów.

W kontrolowanym teście A/B na VisDrone (ta sama procedura, rozdzielczość i inicjalizacja, jedyną zmianą była głowica P2) AP małych obiektów wzrosło o +49% względem standardowego YOLOv9 o tym samym rozmiarze. Wyższa rozdzielczość trenowania i większy rozmiar s w przybliżeniu podwoiły AP małych obiektów w całym projekcie:

VisDrone2019-DET val (548 obrazów), pycocotools, pojedyncze ziarno. Wartość ±1 punkt należy traktować jako szum.

Zapowiedź badawcza VisDrone

Wytrenowany checkpoint opublikowano jako LibreYOLO9P2s-visdrone. Rodzina jest scalona w gałęzi dev, ale nie trafiła jeszcze do wydania PyPI, dlatego do następnego wydania należy instalować ją ze źródeł.

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)

Kiedy używać (a kiedy nie)

Dopasuj architekturę do zastosowania. Na danych podobnych do COCO („małe” oznacza 16–32 px) głowica P2 nie pomaga. Lepszym wyborem jest tam standardowy YOLOv9. Wybierz YOLO9-P2, gdy obiekty mają mniej niż około 16 px: na nagraniach z dronów i lotniczych, z odległych kamer CCTV oraz kafelkach satelitarnych. Dodatkowa skala w przybliżeniu podwaja nakład obliczeniowy i liczbę kotwic. To cena siatki o kroku 4.

Trenowanie własnego modelu

YOLO9-P2 inicjalizuje transfer z checkpointów detekcji standardowego YOLOv9: wczytywane są backbone, wspólny neck i istniejące wieże głowic, a nowe moduły P2 zaczynają od zera. Poniższa procedura zawiera wnioski zdobyte podczas pracy z danymi bardzo małych obiektów:

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
)

Adaptery w stylu LoRA pozwalają dostroić backbone transformera RF-DETR przez trenowanie małego zestawu macierzy niskiego rzędu przy zamrożonych wagach bazowych. Zmniejsza to pamięć potrzebną na optymalizator i gradienty, dzięki czemu dobrze nadaje się do adaptowania silnego checkpointu do nowej domeny na skromnym sprzęcie.

Włączanie

Całe publiczne API sprowadza się do jednej flagi w train(). Nie ma parametrów rzędu, alfa ani modułów docelowych do strojenia. Procedura jest ustalona na dobrze przetestowaną konfigurację. Wewnętrznie implementacja używa DoRA (LoRA z dekompozycją wag, rząd 16) zastosowanego do projekcji zapytania, klucza i wartości w mechanizmie uwagi 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

Checkpointy i eksport

• Checkpointy trenowania zachowują tensory adapterów, a konfiguracja zapisuje użycie LoRA, dlatego wczytywanie i wznawianie automatycznie odtwarza graf adaptera.
• Głowica detekcji zawsze pozostaje trenowalna, więc nadal można dostosować model do nowej liczby klas.
• export() scala adaptery z powrotem w gęste wagi. Wyeksportowane modele są standardowe i nie mają zależności peft.
• LoRA jest dostępne tylko dla RF-DETR. Przekazanie lora=True innym rodzinom zgłasza czytelny błąd.

Aktualny stan każdej funkcji. Wszystko tutaj jest eksperymentalne, a ta tabela przedstawia rzeczywisty obraz.