Le prossime novità

Ogni famiglia usa il rilevamento per impostazione predefinita. Puoi scegliere un altro task in uno dei tre modi seguenti, risolti in questo ordine di precedenza:

Poiché la factory pubblica LibreYOLO(...) richiede un file di pesi reale, il modo più semplice per avviare uno di questi task da zero è creare direttamente la classe della famiglia e passare task=. I checkpoint addestrati vengono ricaricati tramite la factory unificata, che ne rileva automaticamente il 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")

La classificazione assegna una singola etichetta a un'intera immagine. YOLO9 mantiene il proprio backbone e aggiunge una testa di classificazione leggera; RF-DETR riutilizza il proprio encoder DINOv2 e aggiunge una testa lineare con pooling. Entrambi operano a 224 per 224.

Inferenza e risultato Probs

La predizione restituisce un oggetto Results il cui campo probs contiene una softmax sulle classi.

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

Formato del dataset e addestramento

La classificazione usa una struttura ImageFolder, non un file YAML. I nomi delle classi corrispondono ai nomi ordinati delle sottocartelle, fissati in base allo split di addestramento.

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

L'argomento data= accetta una cartella, l'URL di un file .zip o il nome di un download automatico noto (imagenette160 e imagenet10). La testa viene ricostruita automaticamente in base al numero di classi del dataset.

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

I box orientati includono un angolo di rotazione, necessario per immagini aeree, documenti e scene con elementi molto ravvicinati. YOLO9 aggiunge un ramo per l'angolo alla propria testa detect; RF-DETR aggiunge al decoder un embedding dell'angolo apprendibile.

Inferenza e risultato OBB

Results espone un campo obb. Gli angoli sono espressi in radianti.

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]

Formato del dataset e addestramento

OBB usa un file YAML dei dati standard in stile detect, ma le etichette sono file di testo YOLO-OBB con esattamente nove campi per riga: un ID di classe seguito da quattro punti d'angolo normalizzati. L'angolo viene derivato dai vertici, non memorizzato.

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

Un normale checkpoint di rilevamento non può essere caricato direttamente in un modello OBB. Il passaggio da detect a OBB è consentito solo come inizializzazione dell'addestramento: passa pretrained=True per YOLO9 o il flag di trasferimento esplicito per RF-DETR. Mosaic e mixup sono disabilitati per OBB finché non sarà disponibile una data augmentation che gestisce i vertici, mentre l'inferenza a tasselli non è supportata.

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

La validazione usa l'AP con IoU ruotata, riportata come mAP50 e mAP50-95 nel gruppo di metriche OBB.

La stima della posa predice i keypoint per ogni istanza rilevata. La struttura predefinita usa i keypoint COCO-17 delle persone. Nella prima versione, la posa di YOLO9 e RF-DETR supporta una sola classe, le persone; la posa di YOLO-NAS ed EdgeCrafter è già disponibile nel codice.

Inferenza e risultato Keypoints

Results espone un campo keypoints di forma (N, K, 3), dove l'ultimo canale rappresenta visibilità o confidenza, in coordinate pixel dell'immagine originale.

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

Formato del dataset e addestramento

La posa usa un file YAML dei dati che deve dichiarare kpt_shape: [K, 2|3] e, per la data augmentation con ribaltamento orizzontale, un flip_idx. Le etichette sono righe di testo YOLO-pose: un ID di classe, un box normalizzato, quindi K terne di keypoint (x, y, v) con visibilità v in {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 con una quarta scala di rilevamento a stride 4. YOLOv9 standard rileva agli stride 8/16/32, quindi gli oggetti sotto ~16 px sfuggono alla griglia più fine; la testa P2 copre l'intervallo 4-16 px dominante nei filmati aerei e dei droni.

In un confronto A/B controllato su VisDrone, con stessa configurazione, risoluzione e inizializzazione e con la sola modifica della testa P2, l'AP dei piccoli oggetti è migliorata del +49% rispetto a YOLOv9 standard della stessa dimensione. L'aggiunta di una risoluzione di addestramento maggiore e della dimensione s più grande ha quasi raddoppiato l'AP dei piccoli oggetti nel progetto:

VisDrone2019-DET val (548 immagini), pycocotools, un singolo seed; considera ±1 punto come rumore.

L'anteprima di ricerca VisDrone

Un checkpoint addestrato è pubblicato come LibreYOLO9P2s-visdrone. La famiglia è integrata in dev ma non ancora in una release PyPI, quindi installala dal sorgente fino alla prossima release.

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)

Quando usarlo e quando non usarlo

Adatta l'architettura al contesto. Su dati simili a COCO, dove "piccolo" significa 16-32 px, la testa P2 non aiuta; in quel caso YOLOv9 standard è la scelta migliore. Scegli YOLO9-P2 quando i tuoi oggetti sono sotto ~16 px: filmati di droni e aerei, videosorveglianza distante, tasselli satellitari. La scala aggiuntiva raddoppia approssimativamente il calcolo e il numero di anchor. È il prezzo della griglia stride 4.

Addestrare il tuo modello

YOLO9-P2 viene inizializzato per trasferimento dai checkpoint detect di YOLOv9 standard: vengono caricati il backbone, il neck condiviso e le torri delle teste esistenti; i nuovi moduli P2 partono da zero. La configurazione seguente raccoglie ciò che abbiamo imparato con fatica sui dati di oggetti minuscoli:

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
)

Gli adattatori in stile LoRA consentono di fare fine-tuning del backbone transformer di RF-DETR addestrando un piccolo insieme di matrici a rango ridotto, mentre i pesi di base restano congelati. In questo modo si riduce la memoria usata dall'ottimizzatore e dai gradienti, una soluzione ideale per adattare un checkpoint potente a un nuovo dominio con hardware modesto.

Abilitazione

L'intera API pubblica consiste in un singolo flag su train(). Non ci sono impostazioni di rank, alpha o moduli di destinazione da regolare; la procedura usa una configurazione fissa e ben collaudata. Dietro le quinte, l'implementazione usa DoRA (LoRA con scomposizione dei pesi, rank 16) applicato alle proiezioni query, key e value dell'attenzione 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

Checkpoint ed esportazione

• I checkpoint di addestramento conservano i tensori degli adattatori e la configurazione registra l'uso di LoRA, quindi il caricamento e la ripresa ricostruiscono automaticamente il grafo degli adattatori.
• La testa di rilevamento resta sempre addestrabile, quindi puoi comunque adattarla a un nuovo numero di classi.
• export() riunisce gli adattatori nei pesi densi. I modelli esportati sono standard e non richiedono la dipendenza peft.
• LoRA è disponibile solo per RF-DETR; passare lora=True ad altre famiglie genera un errore chiaro.

Lo stato attuale di ogni funzionalità. Tutto ciò che trovi qui è sperimentale; questa tabella ne offre una panoramica trasparente.