Ultralytics YOLO27:
Get Started

YOLOE: rilevamento e segmentazione in tempo reale con vocabolario aperto#

Ultralytics YOLOE (Real-Time Seeing Anything) è un modello di rilevamento con vocabolario aperto e segmentazione di istanze: invece di usare un elenco di classi fissato durante l'addestramento, accetta le categorie desiderate al momento dell'inferenza, come prompt testuale, esempio visivo o vocabolario integrato di 4.585 nomi. Basato sulle architetture Ultralytics YOLO — YOLOv8, YOLO11 e YOLO26 — e ispirato a YOLO-World, YOLOE raggiunge una precisione zero-shot all'avanguardia, con una velocità quasi pari a quella di YOLO a classi chiuse.



Guarda: Come usare Ultralytics YOLOE-26 (novità) | Vocabolario aperto e rilevamento in tempo reale di qualsiasi cosa 🚀

Guida rapida#

Indica le classi desiderate e avvia l'esecuzione. YOLOE-26 restituisce riquadri e maschere di segmentazione di istanze per categorie su cui non è mai stato addestrato.

Rileva tutto ciò che sai nominare
from ultralytics import YOLOE

model = YOLOE("yoloe-26s-seg.pt")

# "double-decker bus" non è una classe COCO; YOLOE la individua basandosi solo sulle parole
model.set_classes(["double-decker bus", "person"])

results = model.predict("https://ultralytics.com/images/bus.jpg")
results[0].show()

La prima chiamata a set_classes() scarica un encoder testuale; consulta Installazione e requisiti prima di distribuire il modello su una macchina senza accesso alla rete.

Scegliere una modalità di prompt#

YOLOE supporta tre modalità di prompt; la scelta determina quale checkpoint caricare e l'aspetto delle etichette delle classi. Scegli la riga corrispondente a ciò che puoi fornire al momento dell'inferenza.

YOLOE rileva e segmenta oggetti usando prompt testuali, prompt visivi e il proprio vocabolario senza prompt

ModalitàCheckpointFornisciNomi delle classi nei risultatiUsalo quando
Prompt testuale*-seg.ptNomi delle classi come stringheEsattamente i nomi che hai specificatoPuoi descrivere a parole l'oggetto da rilevare: è la scelta più comune
Prompt visivo*-seg.ptRiquadri di esempio su un'immagine di riferimentoobject0 generici, object1, …Non puoi descrivere a parole l'oggetto da rilevare: si tratta di una parte specifica, un logo o un difetto
Senza prompt*-seg-pf.ptNienteNomi dal vocabolario integrato di 4.585 nomiStai catalogando o esplorando e non sai in anticipo cosa cercare
Due sorprese frequenti
  • I prompt visivi non includono le tue etichette. Gli ID delle classi in visual_prompts raggruppano gli esempi; il modello li restituisce come object0, object1 e così via. Devi associarli tu ai nomi che usi.
  • I checkpoint senza prompt rifiutano set_classes(). Se lo chiami su un modello *-seg-pf.pt, viene generato AssertionError: Prompt-free model does not support setting classes. Please try with Text/Visual prompt models. Carica invece un checkpoint *-seg.pt quando hai bisogno delle tue classi.

Installazione e requisiti#

YOLOE è incluso nel pacchetto principale Ultralytics:

pip install -U ultralytics

Il prompt testuale richiede anche un encoder testuale, che viene scaricato al primo utilizzo e non durante l'installazione:

  • La prima chiamata a set_classes() installa ultralytics/CLIP da GitHub con pip (che fornisce il tokenizer) e scarica un encoder testuale TorchScript nella directory di lavoro corrente. YOLOE-26 scarica mobileclip2_b.ts, circa 254 MB; YOLOE-11 e YOLOE-v8 scaricano mobileclip_blt.ts. Esegui il download una volta dalla directory da cui avvierai il programma, oppure copia lì il file; altrimenti verrà scaricato di nuovo.
  • Entrambe le operazioni richiedono l'accesso alla rete, quindi esegui una predizione con prompt prima di distribuire il modello su una macchina offline o isolata dalla rete.
  • I prompt visivi e i checkpoint senza prompt non richiedono affatto un encoder testuale.

I checkpoint YOLOE-26 richiedono ultralytics 8.4.0 o versione successiva; le famiglie YOLOE-11 e YOLOE-v8 sono disponibili nelle versioni precedenti. Una predizione con prompt testuale verifica l'intero flusso: download del checkpoint, installazione di CLIP, encoder testuale e inferenza:

yolo predict model=yoloe-26s-seg.pt source="https://ultralytics.com/images/bus.jpg" classes="person"

Per evitare del tutto il download dell'encoder testuale al momento dell'inferenza, incorpora i prompt nei pesi una volta sola e riutilizzali: consulta Riutilizzare gli embedding dei prompt.

Panoramica dell'architettura#

YOLOE Architecture

YOLOE mantiene la struttura YOLO standard — un backbone convoluzionale per l'estrazione delle caratteristiche, un neck per la fusione multiscala e una head disaccoppiata e senza anchor che predice classi e riquadri — e aggiunge tre moduli, uno per ogni modalità di prompt:

  • Allineamento regione-testo riparametrizzabile (RepRTA) perfeziona gli embedding testuali di CLIP tramite una piccola rete ausiliaria. Questa rete viene eseguita una volta per chiamata a set_classes() e viene rimossa durante l'esportazione, quindi non comporta costi per ogni frame. A ogni passaggio forward viene invece eseguito il confronto tra gli embedding dei prompt memorizzati e le caratteristiche delle regioni; consulta Limitazioni per i costi associati a un insieme ampio di prompt.
  • Encoder dei prompt visivi con attivazione semantica (SAVPE) codifica le caratteristiche semantiche e di attivazione di un riquadro di esempio, condizionando il modello sugli oggetti che gli somigliano. È il flusso one-shot per gli oggetti difficili da nominare, come un logo o una parte specifica.
  • Contrasto regione-prompt lazy (LRPC) confronta gli embedding delle regioni con un vocabolario integrato di 4.585 nomi, così i checkpoint senza prompt riconoscono oggetti senza prompt esterni e senza encoder testuale.

La segmentazione di istanze è realizzata da un ramo delle maschere nella head di rilevamento, come in YOLOv8-Seg, e ogni predizione include una maschera su results[0].masks. Una volta esportato, il modello converte i moduli open-world in una head YOLO standard, così il file esportato esegue il normale flusso di rilevamento/segmentazione.

Modelli disponibili#

Ogni checkpoint qui sotto è un modello di segmentazione di istanze e supporta val, predict, export e track. Carica un file *-seg.pt per i prompt testuali o visivi e un file *-seg-pf.pt per l'inferenza senza prompt: non sono intercambiabili; consulta Scegliere una modalità di prompt. Solo i file *-seg.pt supportano train; un checkpoint senza prompt viene generato a partire da un modello addestrato con prompt testuali: consulta Addestrare da zero i modelli ufficiali.

Prestazioni di YOLOE su LVIS#

Risultati zero-shot sul minival di LVIS a 640 pixel, tratti dal paper Ultralytics YOLO26.

Prompt testuali e visivi#

Ogni cella relativa a precisione e parametri riporta prompt testuale / prompt visivo; i FLOPs sono indicati una sola volta. I parametri e i FLOPs si riferiscono alla configurazione di rilevamento valutata nel paper. La precisione corrisponde al valore Non-E2E del paper, l'unico protocollo riportato per tutti i modelli del confronto; la head end-to-end di YOLOE-26 è inferiore al massimo di 1,1 AP con prompt testuali e di 2,6 AP con prompt visivi.

ModellomAP50-95mAPrmAPcmAPfparametri
(M)
FLOPs
(B)
YOLOE-26n24.7 / 21.920.5 / 17.624.1 / 22.326.1 / 22.43.9 / 3.16.1
YOLOE-26s30.8 / 28.623.9 / 25.129.6 / 27.833.0 / 29.910.7 / 11.021.9
YOLOE-26m35.4 / 33.931.1 / 33.434.7 / 34.036.9 / 33.821.3 / 25.170.6
YOLOE-26l37.8 / 36.335.1 / 37.637.6 / 36.238.5 / 36.125.5 / 29.389.0
YOLOE-26x40.6 / 38.537.4 / 35.340.9 / 38.841.0 / 38.855.2 / 65.2197.7
YOLOE-11s27.5 / 26.321.4 / 22.526.8 / 27.129.3 / 26.410.7 / 10.922.7
YOLOE-11m33.0 / 31.426.9 / 27.132.5 / 31.934.5 / 31.721.0 / 24.870.4
YOLOE-11l35.2 / 33.729.1 / 28.135.0 / 34.636.5 / 33.826.0 / 29.889.5
YOLOE-v8s27.9 / 26.222.3 / 21.327.8 / 27.729.0 / 25.712.3 / 12.629.8
YOLOE-v8m32.6 / 31.026.9 / 27.031.9 / 31.734.4 / 31.126.4 / 28.480.7
YOLOE-v8l35.9 / 34.233.2 / 33.234.8 / 34.637.3 / 34.143.5 / 47.3167.6

Senza prompt#

I checkpoint senza prompt forniscono risultati usando il vocabolario integrato, senza che venga specificato alcun prompt. Ogni cella della precisione riporta end-to-end / Non-E2E, i due protocolli con cui il paper valuta YOLOE-26; la pagina YOLO26 riporta la colonna Non-E2E.

ModellomAP50-95mAPrmAPcmAPfparametri
(M)
FLOPs
(B)
YOLOE-26n-pf16.6 / 17.715.7 / 15.815.3 / 16.417.9 / 19.22.35.3
YOLOE-26s-pf21.4 / 22.616.2 / 20.220.1 / 20.923.5 / 24.59.020.8
YOLOE-26m-pf25.7 / 26.426.7 / 24.524.0 / 25.026.9 / 27.919.468.4
YOLOE-26l-pf27.2 / 28.026.3 / 25.725.7 / 26.828.7 / 29.523.686.8
YOLOE-26x-pf29.9 / 31.127.5 / 28.929.1 / 30.731.1 / 31.753.1194.4

Con prompt testuali e visivi, i modelli YOLOE-26 superano i rispettivi modelli YOLOE-11 e YOLOE-v8 a ogni scala corrispondente in mAP50-95, mantenendosi al di sotto della linea v8 per numero di parametri e FLOPs. Sulla stessa suddivisione, il paper riporta YOLO-Worldv2 a 24.4 (S), 32.4 (M) e 35.5 (L), e i rilevatori basati su Transformer GLIP-T a 26.0, GDINO-T a 27.4 e DetCLIP-T a 34.4, ciascuno con 155-232 M di parametri. Il paper originale di YOLOE aggiunge due risultati per i modelli con scala v8 che ha introdotto. Su LVIS, YOLOE-v8s supera YOLO-Worldv2-S di 3.5 AP con un terzo del costo di addestramento e una velocità di inferenza 1.4× superiore. Trasferito su COCO, YOLOE-v8l guadagna 0.6 box AP e 0.4 mask AP rispetto a YOLOv8-L a insieme chiuso, con un tempo di addestramento quasi 4× inferiore.

Conteggi del paper e checkpoint rilasciati

Il paper di YOLO26 valuta una configurazione di rilevamento. I pesi rilasciati sono checkpoint di segmentazione e includono un ramo per le maschere, SAVPE e la proiezione testuale, perciò un yoloe-26l-seg.pt caricato riporta 35.4 M e 142.0 B invece dei 25.5 M e 89.0 B indicati sopra. In entrambi i casi, il valore FLOPs esclude la similarità tra regione e testo, quindi il costo effettivo aumenta con la dimensione dell'insieme di prompt anche se la colonna non cambia; vedi Limitazioni.

Esempi d'uso#

Ogni esempio YOLOE qui sotto viene eseguito tramite la Python API. Anche la predizione con prompt testuali, la validazione, l'esportazione, il tracking e il semplice addestramento funzionano tramite la CLI; le ricette di fine-tuning e i prompt visivi passano come argomento una classe trainer o predictor, cosa consentita solo dalla Python API.

Utilizzo dell'addestramento#

Esegui il fine-tuning di qualsiasi checkpoint *-seg.pt rilasciato sul tuo dataset YOLO. La procedura segue in gran parte la procedura standard di addestramento YOLO; cambia il trainer da passare. YOLOEPESegTrainer integra i nomi delle tue classi nella head e poi esegue il fine-tuning: è la scelta giusta per le tue etichette; il trainer predefinito non esegue l'addestramento usando i nomi delle tue classi.



Guarda: Come addestrare YOLOE sul dataset di segmentazione di parti di automobili | Modello con vocabolario aperto, predizione ed esportazione 🚀
Esempio
from ultralytics import YOLOE
from ultralytics.models.yolo.yoloe import YOLOEPESegTrainer

model = YOLOE("yoloe-26s-seg.pt")

results = model.train(
    data="coco128-seg.yaml",
    epochs=80,
    patience=10,
    trainer=YOLOEPESegTrainer,  # <- Importante: il trainer per il fine-tuning, non quello predefinito
)
Addestrare invece un modello di rilevamento

Ogni checkpoint rilasciato è un modello di segmentazione. Per addestrare un rilevatore, crea il modello a partire dallo YAML corrispondente, carica i pesi di segmentazione della stessa scala e sostituisci il trainer con quello di rilevamento. Tutto il resto rimane invariato.

from ultralytics import YOLOE
from ultralytics.models.yolo.yoloe import YOLOEPETrainer

model = YOLOE("yoloe-26s.yaml").load("yoloe-26s-seg.pt")

results = model.train(data="coco128.yaml", epochs=80, patience=10, trainer=YOLOEPETrainer)

Uso di predict#

La chiamata con prompt testuale è quella mostrata in Avvio rapido. Per le altre due modalità serve un argomento aggiuntivo:

Esempio

I prompt visivi mostrano al modello un esempio invece di descriverlo. visual_prompts accetta un array bboxes di riquadri di esempio e un array cls di ID di classe, uno per riquadro. Gli ID sono raggruppamenti temporanei, non etichette: devono essere sequenziali a partire da 0 e i risultati vengono restituiti come object0, object1, … e non con i nomi scelti da te.

I riquadri di esempio possono trovarsi sull'immagine su cui stai eseguendo la predizione:

import numpy as np

from ultralytics import YOLOE
from ultralytics.models.yolo.yoloe import YOLOEVPSegPredictor

model = YOLOE("yoloe-26l-seg.pt")

# Un riquadro di esempio per ogni oggetto target, ciascuno con il proprio ID di classe
visual_prompts = {
    "bboxes": np.array([[221.52, 405.8, 344.98, 857.54], [120, 425, 160, 445]]),  # persona, occhiali
    "cls": np.array([0, 1]),
}

results = model.predict(
    "ultralytics/assets/bus.jpg",
    visual_prompts=visual_prompts,
    predictor=YOLOEVPSegPredictor,
)
results[0].show()

Oppure possono trovarsi su un'immagine di riferimento separata passata come refer_image; in tal caso, bboxes e cls descrivono gli oggetti nell'immagine di riferimento, non nel target:

import numpy as np

from ultralytics import YOLOE
from ultralytics.models.yolo.yoloe import YOLOEVPSegPredictor

model = YOLOE("yoloe-26l-seg.pt")

visual_prompts = {"bboxes": np.array([[221.52, 405.8, 344.98, 857.54]]), "cls": np.array([0])}  # person

results = model.predict(
    "ultralytics/assets/zidane.jpg",  # Immagine target
    refer_image="ultralytics/assets/bus.jpg",  # Dove si trovano i riquadri di esempio
    visual_prompts=visual_prompts,
    predictor=YOLOEVPSegPredictor,
)
results[0].show()

# refer_image imposta anche le classi in modo permanente, quindi le chiamate successive non richiedono alcun prompt
results = model("ultralytics/assets/bus.jpg")
model.export(format="onnx")  # E l'esportazione le mantiene
Nota

Quando source è un video o uno stream, il primo frame diventa automaticamente refer_image, quindi i prompt passati vengono applicati a quel frame e mantenuti per il resto del video. Passa esplicitamente refer_image per scegliere un altro frame.

Sia source sia refer_image accettano direttamente tensori torch, utile quando le immagini provengono già da una pipeline esistente. Fornisci i riquadri nelle coordinate dei pixel del tensore:

import numpy as np
import torch

from ultralytics import YOLOE
from ultralytics.models.yolo.yoloe import YOLOEVPSegPredictor

model = YOLOE("yoloe-11l-seg.pt")

img_tensor = torch.rand(1, 3, 480, 480)  # (1, 3, H, W) tensore float in [0, 1]
visual_prompts = {"bboxes": np.array([[10, 10, 50, 50]]), "cls": np.array([0])}

results = model.predict(
    img_tensor,
    refer_image=img_tensor,
    visual_prompts=visual_prompts,
    predictor=YOLOEVPSegPredictor,
    imgsz=640,
)

Per eseguire la predizione su più immagini contemporaneamente, annida i prompt un livello più in profondità: un array bboxes e un array cls per ogni immagine sorgente, nello stesso ordine delle sorgenti.

import numpy as np

from ultralytics import YOLOE
from ultralytics.models.yolo.yoloe import YOLOEVPSegPredictor

model = YOLOE("yoloe-26l-seg.pt")

visual_prompts = {
    "bboxes": [
        np.array([[221.52, 405.8, 344.98, 857.54], [120, 425, 160, 445]]),  # bus.jpg: persona, occhiali
        np.array([[150, 200, 1150, 700]]),  # zidane.jpg: persona
    ],
    "cls": [np.array([0, 1]), np.array([0])],
}

results = model.predict(
    ["ultralytics/assets/bus.jpg", "ultralytics/assets/zidane.jpg"],
    visual_prompts=visual_prompts,
    predictor=YOLOEVPSegPredictor,
)
results[0].show()

Uso di val#

La validazione si esegue come con qualsiasi altro modello su un dataset di segmentazione:

Esempio
from ultralytics import YOLOE

model = YOLOE("yoloe-26l-seg.pt")  # oppure yoloe-26s/m-seg.pt per altre dimensioni

metrics = model.val(data="coco128-seg.yaml")

Due varianti della stessa chiamata coprono le altre modalità di prompting:

  • Prompt visivi — model.val(data="coco128-seg.yaml", load_vp=True) estrae un embedding visivo per categoria direttamente dal dataset. Aggiungi refer_data="coco.yaml" per usare gli embedding di un dataset diverso, che deve contenere esattamente le stesse categorie.
  • Senza prompt — carica un checkpoint *-seg-pf.pt e passa single_cls=True.

Utilizzo dell'esportazione#

Gli embedding dei prompt possono essere salvati una volta e riutilizzati per creare esportazioni statiche come ONNX, OpenVINO, TensorRT, CoreML, LiteRT e RKNN. Il profilo NPZ viene caricato dal modello PyTorch originale prima dell'esportazione; non è un input aggiuntivo in fase di esecuzione e il modello esportato non richiede il file NPZ.

I modelli esportati sono statici

Le classi configurate con set_classes() (o tramite refer_image per i prompt visivi) vengono incorporate nei pesi esportati. Dopo l'esportazione, il modello non può più accettare nuovi prompt: una chiamata a set_classes() o il passaggio di visual_prompts=... a predict() su un'esportazione caricata genererà un errore. Per modificare le classi rilevate, esegui una nuova esportazione dal checkpoint .pt originale con i nuovi prompt configurati. Il file esportato si comporta come un modello YOLO standard e può anche essere caricato con YOLO() invece che con YOLOE().

Riutilizzare gli embedding dei prompt
from ultralytics import YOLOE

model = YOLOE("yoloe-26n-seg.pt")
model.set_classes(["person", "bus"])
model.save_prompt_embeddings("person-bus.npz")

# Il profilo è associato al checkpoint sorgente e può essere riutilizzato per le esportazioni successive.
model = YOLOE("yoloe-26n-seg.pt")
model.load_prompt_embeddings("person-bus.npz")
model.export(format="onnx")

Lo stesso profilo dei prompt può anche configurare un modello di solo rilevamento creato a partire dall'architettura YOLOE corrispondente. In questo modo si rimuove il ramo delle maschere mantenendo le classi specificate dai prompt:

from ultralytics import YOLOE

model = YOLOE("yoloe-26n.yaml").load("yoloe-26n-seg.pt")
model.load_prompt_embeddings("person-bus.npz")
model.export(format="rknn", name="rk3588", quantize=16)

Tracciamento#

Le classi specificate dai prompt passano direttamente al tracking, così puoi seguire oggetti su cui il tracker non è mai stato addestrato:

Esempio
from ultralytics import YOLOE

model = YOLOE("yoloe-26s-seg.pt")
model.set_classes(["forklift", "pallet"])

# persist=True mantiene stabili gli ID di tracking tra i frame
for result in model.track("path/to/video.mp4", stream=True, persist=True):
    print(result.boxes.id)

Confronto tra YOLOE e altri modelli#

YOLOE si colloca tra un rilevatore a insieme chiuso e un modello open-vocabulary di grandi dimensioni. Tre confronti aiutano a stabilire se è la scelta giusta:

  • Rispetto a un modello YOLO a insieme chiuso. Una volta impostati i prompt, YOLOE esegue la predizione tramite il normale percorso di rilevamento/segmentazione e si esporta come qualsiasi altro modello. Il vantaggio è poter modificare l'elenco delle classi in fase di inferenza invece di riaddestrare; il costo è un'accuratezza zero-shot molto inferiore a quella di un modello addestrato sulle tue classi.
  • Rispetto alle precedenti famiglie YOLOE. YOLOE-26 eredita la head end-to-end senza NMS di YOLO26 e copre cinque scale (n/s/m/l/x) rispetto alle tre precedenti (s/m/l), ottenendo risultati migliori a ogni scala corrispondente nella sezione Prestazioni.
  • Rispetto ai rilevatori open-vocabulary basati su Transformer. GLIP e OWL-ViT eseguono un Transformer visione-linguaggio in fase di inferenza. YOLOE codifica i prompt una sola volta e poi li confronta con le feature delle regioni all'interno di una head convoluzionale.

Le alternative più simili accettano tutte un prompt testuale, ma solo YOLOE e SAM 3 restituiscono maschere; i tre modelli rispondono a domande diverse:

YOLOESAM 3YOLO-World
Progettato perRilevamento e segmentazione in tempo reale di classi specificate per nomeSegmentazione di concetti e tracking guidato da promptRilevamento open-vocabulary in tempo reale
MaschereSì, con i checkpoint *-seg.ptSìNo, solo riquadri
Prompt visiviSì (SAVPE)SìNo
Modalità senza promptSì, vocabolario di 4,585 nomiNoNo
Sceglilo quandoTi serve throughput e puoi specificare le classiTi serve la migliore segmentazione di concetti e puoi sostenere il costo computazionaleLo stai già usando — vedi la nota sulla migrazione qui sotto

Stai passando da YOLO-World? L'API ha la stessa struttura: sostituisci YOLOWorld con YOLOE, carica un checkpoint *-seg.pt e lascia invariata la chiamata set_classes(). Ottieni maschere e prompt visivi; la nota sull'esportazione relativa alle classi bloccate vale per entrambi.

Casi d'uso e applicazioni#

Il rilevamento open-vocabulary elimina la necessità di riaddestrare il modello per ogni classe, un vantaggio importante soprattutto quando l'elenco dei target non è noto in anticipo:

  • Rilevamento in scenari aperti — robotica e sistemi di sicurezza che incontrano oggetti non enumerati durante l'addestramento.
  • Rilevamento one-shot a partire da un esempio — i prompt visivi individuano un componente, un logo o un difetto specifico a partire da un singolo riquadro di riferimento, una funzione utile nell'ispezione industriale.
  • Catalogazione delle classi a coda lunga — il vocabolario integrato di 4,585 nomi è abbastanza ampio per attività di monitoraggio della biodiversità o inventario retail.
  • Creazione iniziale del dataset — pre-etichetta immagini con riquadri e maschere prima della revisione umana, quindi addestra sul risultato un modello veloce a insieme chiuso.
  • Segmentazione di target arbitrari — i checkpoint *-seg.pt rilasciati restituiscono una maschera con ogni predizione, così l'imaging medico e l'analisi satellitare ottengono risultati precisi a livello di pixel senza un secondo modello.

Un approccio comune combina due modalità: esegui una volta la modalità senza prompt per scoprire cosa è presente, poi passa ai prompt testuali per le categorie rilevanti.

Limitazioni#

YOLOE sacrifica l'accuratezza per consentire di modificare le classi in fase di inferenza. Ecco cosa conviene sapere prima di adottarlo:

  • L'accuratezza zero-shot è molto inferiore a quella di un modello addestrato sulle tue classi. I checkpoint con prompt raggiungono circa 22-40 mAP su LVIS minival; un modello YOLO a insieme chiuso addestrato sui tuoi dati otterrà risultati migliori su quelle classi. Scegli YOLOE per coprire classi per cui non puoi addestrare un modello, non per sostituire l'addestramento.
  • Le categorie rare sono il punto debole. La colonna mAPr in Prestazioni riporta specificamente l'accuratezza sulle classi rare di LVIS e, con i prompt testuali, è inferiore alle colonne delle classi comuni e frequenti in ogni riga. Se i tuoi target sono insoliti, controlla questo valore invece del mAP principale.
  • Un prompt descrive l'aspetto, non le relazioni. Il rilevamento funziona confrontando le feature delle regioni con l'embedding del prompt, quindi i prompt che dipendono da stato, contesto o confronto — «danneggiato», «il più a sinistra», «quello che viene trasportato» — non offrono un riferimento affidabile da abbinare. Preferisci formulazioni simili ai nomi di categorie di uso comune.
  • Gli insiemi di prompt grandi aumentano la latenza. Gli embedding dei prompt vengono calcolati una sola volta, ma a ogni passaggio forward sono confrontati con le feature delle regioni. Su CPU con yoloe-26s-seg.pt, il tempo di un passaggio forward aumenta di circa il 19% passando da 80 a 1,203 classi e di circa l'89% con il vocabolario completo di 4,585 nomi. I FLOPs riportati non cambiano affatto, perché la similarità tra regione e testo non viene conteggiata, quindi il profilo non ti avviserà.
  • I nomi delle classi sono segnaposto finché non imposti i prompt. Un checkpoint *-seg.pt appena caricato restituisce nc=80 con nomi numerici ("0", "1", …), quindi chiama set_classes() prima di leggere le etichette. I checkpoint senza prompt includono già l'intero vocabolario.

Note sulla distribuzione#

  • Hardware. L'inferenza richiede una GPU NVIDIA con 4-8 GB di VRAM; le scale n e s funzionano su GPU edge come Jetson oppure su CPU a risoluzione ridotta. Il fine-tuning richiede una singola GPU.
  • Per impostazione predefinita, NMS non distingue le classi. YOLOE esegue la predizione con agnostic_nms=True. Per impostazione predefinita, questa sopprime i riquadri sovrapposti con punteggio inferiore tra classi diverse, invece di agire solo all'interno della stessa classe, evitando i duplicati quando un oggetto corrisponde a più categorie. Con nms=False, YOLOE-26 non applica alcuna soppressione IoU; la modalità agnostica mantiene solo la classe migliore per anchor, invece di consentire a un anchor di produrre più etichette di classe. Passa agnostic_nms=False per modificare questo comportamento.
  • Elaborazione in batch. L'inferenza in batch funziona direttamente e i prompt visivi possono essere diversi per ogni immagine nella stessa chiamata.

Addestrare da zero i modelli ufficiali#

La maggior parte dei lettori non ne ha bisogno. Questa procedura riproduce i checkpoint open-vocabulary pubblicati a partire da Objects365, GQA e Flickr30k — circa 1.4 M di campioni di addestramento su 8× RTX 4090 — e non riguarda il fine-tuning sui tuoi dati, descritto sopra in Utilizzo dell'addestramento.

Attenzione

Tutti i trainer che ereditano da YOLOETrainer rifiutano compile=True, compresi il YOLOESegTrainer predefinito e tutti i trainer da zero qui sotto. Passa compile=False (il valore predefinito). I due trainer per il fine-tuning usati sopra, YOLOEPESegTrainer e YOLOEPETrainer, non hanno questa limitazione.

L'addestramento richiede annotazioni di segmentazione. Puoi scaricare i file elaborati qui sotto oppure generarne di tuoi con lo script fornito dal team ufficiale, basato su SAM 2.1. La validazione usa LVIS minival.

DatasetTipoCampioniRiquadriAnnotazioni di segmentazione elaborate
Objects365v1Rilevamento609k9621kobjects365_train_segm.json
GQAGrounding621k3681kfinal_mixed_train_no_coco_segm.json
Flickr30kGrounding149k641kfinal_flickr_separateGT_train_segm.json

Il modello con prompt testuali viene addestrato per primo; le altre due modalità di prompting sono sue versioni perfezionate:

from ultralytics import YOLOE
from ultralytics.models.yolo.yoloe import YOLOESegTrainerFromScratch

data = {
    "train": {
        "yolo_data": ["Objects365.yaml"],
        "grounding_data": [
            {
                "img_path": "flickr/full_images/",
                "json_file": "flickr/annotations/final_flickr_separateGT_train_segm.json",
            },
            {
                "img_path": "mixed_grounding/gqa/images",
                "json_file": "mixed_grounding/annotations/final_mixed_train_no_coco_segm.json",
            },
        ],
    },
    "val": {"yolo_data": ["lvis.yaml"]},
}

model = YOLOE("yoloe-26l-seg.yaml")
model.train(
    data=data,  # oppure il percorso a un file YAML con la stessa struttura
    batch=128,
    epochs=30,
    close_mosaic=2,
    optimizer="AdamW",
    lr0=2e-3,
    warmup_bias_lr=0.0,
    weight_decay=0.025,
    momentum=0.9,
    workers=4,
    trainer=YOLOESegTrainerFromScratch,
    device="0,1,2,3,4,5,6,7",
)

I checkpoint visual-prompt e prompt-free partono dal modello text-prompt addestrato e aggiornano un modulo ciascuno. YOLOESegVPTrainer è la ricetta visual-prompt e YOLOEPEFreeTrainer quella prompt-free, ma nessuna delle due classi congela qualcosa autonomamente: l'addestramento selettivo dipende dall'elenco freeze che passi insieme alla classe, che include tutti i componenti secondari della head tranne savpe (rispettivamente, ogni torre di classificazione); l'esecuzione prompt-free richiede inoltre single_cls=True. Il repository YOLOE upstream contiene le ricette complete per i modelli di scala v8.

Un'esecuzione prompt-free completata viene riparametrizzata in un checkpoint che riporta i nomi senza prompt durante l'inferenza, usando get_vocab e set_vocab:

from ultralytics import YOLOE

# I pesi scritti dall'esecuzione prompt-free e dall'esecuzione text-prompt da cui è partita. Ogni
# riesecuzione crea una nuova directory (train-2, train-3, ...), quindi usa i percorsi stampati dalle esecuzioni.
model = YOLOE("runs/segment/train-2/weights/best.pt")  # esecuzione prompt-free, la sua head è già fusa
text_model = YOLOE("runs/segment/train/weights/best.pt")  # esecuzione text-prompt, la sua head non è ancora fusa

names = list(YOLOE("yoloe-26l-seg-pf.pt").model.names.values())  # il vocabolario di 4,585 nomi o un tuo elenco
vocab = text_model.get_vocab(names)

model.set_vocab(vocab, names)
model.save("yoloe-26l-seg-pf-custom.pt")  # non sovrascrivere mai il checkpoint rilasciato

get_vocab restituisce il ramo selezionato dal flag end2end del modello e set_vocab riparametrizza quel ramo. I file YOLOE-26 rilasciati contengono invece un vocabolario per ramo, che consente a nms di scegliere tra i due; riproduci questo comportamento prendendo il secondo vocabolario da un'altra copia del modello text-prompt. YOLOE-11 e YOLOE-v8 hanno un solo ramo, quindi usano la chiamata precedente senza modifiche.

one2one_model = YOLOE("runs/segment/train/weights/best.pt")  # get_vocab fonde la head che legge, quindi carica una seconda copia
one2one_model.model.end2end = True  # leggi il ramo senza NMS

model.set_vocab(vocab, names, one2one_vocab=one2one_model.get_vocab(names))

Citazioni e ringraziamenti#

Se YOLOE ha contribuito alla tua ricerca o al tuo progetto, cita il documento originale di Ao Wang, Lihao Liu, Hui Chen, Zijia Lin, Jungong Han e Guiguang Ding della Tsinghua University:

Citazione
@misc{wang2025yoloerealtimeseeing,
      title={YOLOE: Real-Time Seeing Anything},
      author={Ao Wang and Lihao Liu and Hui Chen and Zijia Lin and Jungong Han and Guiguang Ding},
      year={2025},
      eprint={2503.07465},
      archivePrefix={arXiv},
      primaryClass={cs.CV},
      url={https://arxiv.org/abs/2503.07465},
}

Per approfondire, il documento originale di YOLOE è disponibile su arXiv. Puoi accedere al codice sorgente del progetto e ad altre risorse tramite il repository GitHub.

Domande frequenti#

  • Ultralytics YOLOE aggiunge due funzionalità assenti in YOLO-World: prompt visivi, in cui un riquadro di esempio sostituisce il nome della classe, e checkpoint prompt-free che rispondono usando un vocabolario integrato di 4,585 nomi, senza alcun prompt. Ogni predizione dei checkpoint *-seg.pt rilasciati include anche una maschera di segmentazione delle istanze. In termini di accuratezza, il documento originale di YOLOE mostra che YOLOE-v8s supera YOLO-Worldv2-S di 3.5 AP su LVIS, con un terzo del costo di addestramento e una velocità di inferenza 1.4× superiore. Per la migrazione basta una modifica di una riga: consulta Confronto tra YOLOE e altri modelli.

  • Ultralytics YOLOE supporta tre modalità di prompting. Un prompt testuale consiste in nomi di classi sotto forma di stringhe con un checkpoint *-seg.pt ed è la scelta più comune. Un prompt visivo consiste in uno o più riquadri di esempio su un'immagine di riferimento, per oggetti difficili da descrivere a parole. L'inferenza prompt-free usa un checkpoint *-seg-pf.pt separato, che risponde usando un vocabolario integrato di 4,585 nomi senza che tu debba fornire nulla. I prompt testuali e visivi usano gli stessi checkpoint; quelli prompt-free sono file diversi e rifiutano set_classes(). Consulta Scelta di una modalità di prompting per il confronto completo.

  • Inizia con yoloe-26s-seg.pt: la famiglia YOLOE-26 è superiore a YOLOE-11 e YOLOE-v8 a ogni scala corrispondente, e la scala s è la più piccola con oltre 30 mAP su LVIS minival. Passa a m, l o x quando l'accuratezza sulle categorie rare conta più della latenza: confronta la colonna mAPr in Prestazioni. Scegli n solo per la distribuzione su dispositivi edge. Quando vuoi usare il vocabolario integrato anziché i tuoi nomi di classe, carica il file *-seg-pf.pt della stessa scala.

  • Etichette come object0 e object1 indicano che la predizione proviene da un prompt visivo, che raggruppa i riquadri di esempio in classi numerate temporanee anziché usare i tuoi nomi. Gli ID di classe che passi in visual_prompts["cls"] servono solo a creare questi gruppi. Il modello li restituisce come object0, object1 e così via, nell'ordine degli ID assegnati, quindi riconducili alle tue etichette nei risultati. Se vuoi che nell'output compaiano i tuoi nomi, usa invece un prompt testuale.

  • I checkpoint prompt-free (*-seg-pf.pt) risolvono le classi tramite il proprio vocabolario integrato e rifiutano i prompt esterni con AssertionError: Prompt-free model does not support setting classes. Please try with Text/Visual prompt models.. Carica un checkpoint *-seg.pt se ti serve il tuo elenco di classi. Consulta Scelta di una modalità di prompting.

  • Al primo prompt testuale, Ultralytics YOLOE installa ultralytics/CLIP da GitHub con pip e scarica un encoder di testo TorchScript nella directory di lavoro corrente: circa 254 MB per YOLOE-26. Consulta Installazione e requisiti per conoscere l'asset esatto per ogni famiglia di modelli. I prompt visivi e i checkpoint prompt-free non richiedono né l'uno né l'altro. Per evitare il download sulla macchina di destinazione, imposta i prompt una volta e salvali con save_prompt_embeddings(), oppure esporta il modello con le classi già configurate.

  • No: YOLOE incorpora nei pesi le classi specificate con i prompt al momento dell'esportazione, quindi un modello esportato caricato rifiuta sia set_classes() sia visual_prompts=. Riesporta il checkpoint originale .pt dopo aver configurato i nuovi prompt. Il file esportato si comporta come un modello YOLO standard e può essere caricato con YOLO() e YOLOE().

  • Usa YOLOE quando ti serve un throughput in tempo reale e puoi specificare i nomi delle classi; usa SAM 3 quando la qualità della segmentazione di un concetto conta più della velocità. Entrambi accettano esempi visivi; solo YOLOE offre una modalità prompt-free. Il confronto completo è disponibile in Confronto tra YOLOE e altri modelli.

Commenti