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

Ultralytics YOLOE (Seeing Anything in tempo reale) è un modello di rilevamento e segmentazione di istanze a vocabolario aperto: invece di usare un elenco di classi fisso al momento dell'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 insieme chiuso.

Avvio rapido#

Indica le classi desiderate ed esegui il modello. YOLOE-26 restituisce riquadri e maschere di segmentazione di istanze per categorie sulle quali non è mai stato addestrato.

from ultralytics import YOLOE

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

# "double-decker bus" is not a COCO class; YOLOE resolves it from the words alone
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.

Scelta della modalità di prompting#

YOLOE supporta tre modalità di prompting; 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.

Installazione e requisiti#

YOLOE è incluso nel pacchetto principale Ultralytics:

pip install -U ultralytics

Il prompting testuale richiede inoltre un encoder testuale, che viene recuperato al primo utilizzo anziché 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 eseguirai il modello oppure copia lì il file; in caso contrario verrà scaricato di nuovo.
• Entrambi i passaggi 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 alcun 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, inferenza:

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

Per evitare completamente il download dell'encoder testuale al momento dell'inferenza, incorpora una volta i prompt nei pesi e riutilizzali: consulta Riutilizzo degli embedding dei prompt.

Panoramica dell'architettura#

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

• Allineamento regione-testo riparametrizzabile (RepRTA) perfeziona gli embedding testuali di CLIP attraverso una piccola rete ausiliaria. Questa rete viene eseguita una volta per chiamata a set_classes() e rimossa durante l'esportazione, quindi non ha alcun costo per fotogramma. A ogni passaggio forward viene invece eseguito il confronto tra gli embedding dei prompt memorizzati e le feature delle regioni; consulta Limitazioni per conoscere il costo con un set di prompt ampio.
• Encoder del prompt visivo attivato semanticamente (SAVPE) codifica le feature semantiche e di attivazione da un riquadro di esempio, condizionando il modello sugli oggetti che gli assomigliano. Questo è il flusso one-shot per obiettivi 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 gli oggetti senza prompt esterni e senza encoder testuale.

La segmentazione di istanze proviene da un ramo delle maschere nella head di rilevamento, come in YOLOv8-Seg, e ogni predizione include una maschera su results[0].masks. Dopo che il modello è stato esportato, i moduli open-world vengono riparametrizzati in una head YOLO standard, quindi il file esportato esegue il normale flusso di rilevamento/segmentazione.

Modelli disponibili#

Ogni checkpoint riportato di seguito è un modello di segmentazione di istanze e supporta val, predict, export e track. Carica un file *-seg.pt per il prompting testuale o visivo e un file *-seg-pf.pt per l'inferenza senza prompt; non sono intercambiabili, consulta Scelta della modalità di prompting. Solo i file *-seg.pt supportano train; un checkpoint senza prompt viene prodotto da un modello addestrato con prompt testuali, consulta Addestramento dei modelli ufficiali da zero.

Prestazioni di YOLOE su LVIS#

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

Prompt testuali e visivi#

Ogni cella di accuratezza e parametri è espressa come 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. L'accuratezza è il valore Non-E2E del paper, l'unico protocollo riportato per ogni modello del confronto; la head end-to-end di YOLOE-26 è inferiore di al massimo 1.1 AP con i prompt testuali e 2.6 AP con quelli visivi.

Senza prompt#

I checkpoint senza prompt rispondono usando il vocabolario integrato, senza alcun prompt fornito. Ogni cella di accuratezza è espressa come end-to-end / Non-E2E, i due protocolli con cui il paper valuta YOLOE-26; la pagina YOLO26 riporta la colonna Non-E2E.

Con prompt testuali e visivi, i modelli YOLOE-26 superano i corrispondenti YOLOE-11 e YOLOE-v8 a ogni scala comparabile in termini di mAP_50-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), mentre i detector basati su Transformer GLIP-T raggiunge 26.0, GDINO-T 27.4 e DetCLIP-T 34.4, con un numero di parametri compreso tra 155 e 232 M. Il paper originale di YOLOE aggiunge due risultati per i modelli con scala v8 introdotti. 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 a COCO, YOLOE-v8l ottiene 0.6 box AP e 0.4 mask AP in più rispetto a YOLOv8-L a insieme chiuso, con un tempo di addestramento quasi 4× inferiore.

Esempi di utilizzo#

Ogni esempio YOLOE seguente viene eseguito tramite la Python API. La predizione con prompt testuale, la validazione, l'esportazione, il tracking e l'addestramento semplice funzionano anche tramite la CLI; le ricette di fine-tuning e il prompting visivo passano una classe trainer o predictor come argomento, cosa che solo la Python API accetta.

Utilizzo dell'addestramento#

Esegui il fine-tuning di qualsiasi checkpoint *-seg.pt distribuito sul tuo dataset YOLO. La procedura segue in gran parte la procedura standard di addestramento YOLO; la differenza riguarda il trainer che passi. YOLOEPESegTrainer fonde i nomi delle tue classi nella head ed esegue il fine-tuning a partire da lì, che è ciò che ti serve per le tue etichette; il trainer predefinito non esegue l'addestramento sulle tue classi.

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,  # <- Important: the fine-tuning trainer, not the default
)

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)

Utilizzo della previsione#

La chiamata con prompt testuale è quella mostrata in Quick Start. Per ciascuna delle altre due modalità serve un argomento aggiuntivo:

import numpy as np

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

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

# One example box per target, each with its own class ID
visual_prompts = {
    "bboxes": np.array([[221.52, 405.8, 344.98, 857.54], [120, 425, 160, 445]]),  # person, glasses
    "cls": np.array([0, 1]),
}

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

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",  # Target image
    refer_image="ultralytics/assets/bus.jpg",  # Where the example boxes live
    visual_prompts=visual_prompts,
    predictor=YOLOEVPSegPredictor,
)
results[0].show()

# refer_image also sets the classes permanently, so later calls need no prompts at all
results = model("ultralytics/assets/bus.jpg")
model.export(format="onnx")  # And the export keeps them

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) float tensor 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,
)

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: person, glasses
        np.array([[150, 200, 1150, 700]]),  # zidane.jpg: person
    ],
    "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()

Utilizzo della validazione#

La validazione viene eseguita come per qualsiasi altro modello su un dataset di segmentazione:

from ultralytics import YOLOE

model = YOLOE("yoloe-26l-seg.pt")  # or yoloe-26s/m-seg.pt for other sizes

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 prendere gli embedding da 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 quando produci 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 a runtime e il modello esportato non richiede il file NPZ.

from ultralytics import YOLOE

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

# The profile is bound to the source checkpoint and can be reused for later exports.
model = YOLOE("yoloe-26n-seg.pt")
model.load_prompt_embeddings("person-bus.npz")
model.export(format="onnx")

Lo stesso profilo di prompt può anche configurare un modello dedicato alla detection costruito a partire dall'architettura YOLOE corrispondente. In questo modo viene rimosso il ramo delle maschere, mantenendo le classi specificate nel 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)

Utilizzo del tracking#

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

from ultralytics import YOLOE

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

# persist=True keeps track IDs stable across frames
for result in model.track("path/to/video.mp4", stream=True, persist=True):
    print(result.boxes.id)

Confronto tra YOLOE e le alternative#

YOLOE si colloca tra un detector a set chiuso e un modello open-vocabulary più pesante. Tre confronti determinano se è la scelta giusta:

• Rispetto a uno YOLO a set chiuso. Una volta impostati i prompt, YOLOE esegue la predizione tramite il normale percorso di detect/segment ed esporta come qualsiasi altro modello. Il vantaggio è la possibilità di cambiare l'elenco delle classi al momento dell'inferenza invece di riaddestrare il modello; il costo è un'accuratezza zero-shot molto inferiore a quella di un modello addestrato sulle tue classi.
• Rispetto alle famiglie YOLOE precedenti. 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 i migliori risultati a ogni scala corrispondente in Performance.
• Rispetto ai detector open-vocabulary basati su Transformer. GLIP e OWL-ViT eseguono un Transformer visione-linguaggio durante l'inferenza. YOLOE codifica i prompt una volta e poi li confronta con le feature delle regioni all'interno di una head convoluzionale.

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

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

Casi d'uso e applicazioni#

La detection open-vocabulary elimina il passaggio di riaddestramento per ogni classe, un aspetto particolarmente importante quando l'elenco dei target non è noto in anticipo:

• Detection open-world — robotica e sistemi di sicurezza che incontrano oggetti mai enumerati durante l'addestramento.
• Detection one-shot da un esempio — i prompt visivi rilevano una parte, un logo o un difetto specifico a partire da un singolo riquadro di riferimento, una soluzione utile nell'ispezione industriale.
• Catalogazione della coda lunga — il vocabolario integrato di 4.585 nomi è abbastanza ampio per attività di monitoraggio della biodiversità o inventario retail.
• Bootstrap del dataset — pre-etichetta le immagini con riquadri e maschere prima della revisione umana, quindi addestra un modello rapido a set chiuso sul risultato.
• Segmentazione di target arbitrari — i checkpoint *-seg.pt rilasciati restituiscono una maschera con ogni predizione, così l'imaging medicale e l'analisi satellitare ottengono un output preciso a livello di pixel senza un secondo modello.

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

Limitazioni#

YOLOE sacrifica accuratezza per la possibilità di cambiare le classi al momento dell'inferenza. Ecco le conseguenze da conoscere prima di impegnarti:

• 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; uno YOLO a set chiuso addestrato sui tuoi dati li supererà su quelle classi. Scegli YOLOE per coprire classi per le quali non puoi addestrare un modello, non per sostituire l'addestramento.
• Le categorie rare sono il punto debole. La colonna mAP_r in Performance riporta l'accuratezza specifica sulle classi rare di LVIS e, con il prompting testuale, è inferiore alle colonne delle classi comuni e frequenti in ogni riga. Controlla questo valore, anziché il mAP principale, quando i tuoi target sono insoliti.
• Un prompt descrive l'aspetto, non le relazioni. La detection funziona confrontando le feature delle regioni con l'embedding del prompt, quindi i prompt che dipendono da stato, contesto o confronto — "danneggiato", "più a sinistra", "quello trasportato" — non offrono un riferimento affidabile da abbinare. Preferisci formulazioni vicine ai nomi delle categorie di uso comune.
• Set di prompt numerosi aumentano la latenza. Gli embedding dei prompt vengono calcolati una volta, ma sono confrontati con le feature delle regioni a ogni passaggio forward. Misurato su CPU con yoloe-26s-seg.pt, un passaggio forward cresce 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 un 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 vengono distribuiti con il vocabolario completo già popolato.

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 o su CPU a risoluzione ridotta. Il fine-tuning richiede una singola GPU.
• NMS è indipendente dalla classe per impostazione predefinita. YOLOE prevede con agnostic_nms=True. Per impostazione predefinita, questo sopprime i riquadri sovrapposti con punteggi inferiori tra classi diverse anziché solo all'interno della stessa classe, il che impedisce 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 singola classe migliore per ancora anziché consentire a un'ancora di emettere più etichette di classe. Passa agnostic_nms=False per eseguire l'override.
• Batching. L'inferenza batch funziona direttamente e i prompt visivi possono differire per immagine nella stessa chiamata.

Addestrare da zero i modelli ufficiali#

La maggior parte dei lettori non ne ha mai 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 è correlata al fine-tuning sui tuoi dati, descritto nella sezione Utilizzo dell'addestramento qui sopra.

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 utilizza LVIS minival.

Il modello con prompt testuale viene addestrato per primo e le altre due modalità di prompting ne sono perfezionamenti:

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,  # or the path to a YAML file holding the same structure
    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 con prompt visivo e senza prompt partono da quel modello addestrato con prompt testuale e aggiornano un modulo ciascuno. YOLOESegVPTrainer è la ricetta per i prompt visivi e YOLOEPEFreeTrainer quella senza prompt, ma nessuna delle due modalità congela qualcosa autonomamente: l'addestramento selettivo deriva dall'elenco freeze che passi insieme ad essa, il quale nomina ogni elemento figlio della head tranne savpe (rispettivamente, ogni tower di classificazione), mentre l'esecuzione senza prompt richiede inoltre single_cls=True. Il repository YOLOE upstream contiene le ricette complete per i modelli con scala v8.

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

from ultralytics import YOLOE

# Weights written by the prompt-free run and by the text-prompt run it started from. Each
# rerun creates a new directory (train-2, train-3, ...), so take the paths the runs printed.
model = YOLOE("runs/segment/train-2/weights/best.pt")  # prompt-free run, its head is already fused
text_model = YOLOE("runs/segment/train/weights/best.pt")  # text-prompt run, its head is still unfused

names = list(YOLOE("yoloe-26l-seg-pf.pt").model.names.values())  # the 4,585-name vocabulary, or your own list
vocab = text_model.get_vocab(names)

model.set_vocab(vocab, names)
model.save("yoloe-26l-seg-pf-custom.pt")  # never overwrite the released checkpoint

Citazioni e ringraziamenti#

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

@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 paper originale di YOLOE è disponibile su arXiv. Il codice sorgente del progetto e ulteriori risorse sono accessibili tramite il relativo repository GitHub.

FAQ#