YOLOE: Rilevamento e segmentazione open-vocabulary in tempo reale#

Ultralytics YOLOE (Real-Time Seeing Anything) è un modello di rilevamento open-vocabulary e segmentazione di istanze: invece di un elenco di classi fisso al momento dell'addestramento, accetta le categorie desiderate al momento dell'inferenza, sotto forma di prompt testuale, esempio visivo o vocabolario integrato di 4.585 nomi. Basato sulle architetture Ultralytics YOLO — YOLOv8, YOLO11 e YOLO26 — e ispirato da YOLO-World, YOLOE raggiunge un'accuratezza zero-shot allo stato dell'arte con una velocità vicina a quella di un YOLO a classi chiuse.

Avvio rapido#

Nomina le classi che desideri ed esegui. YOLOE-26 restituisce bounding box e maschere di segmentazione di istanze per categorie su cui 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 codificatore di testo; consulta Installazione e requisiti prima di effettuare il deployment su una macchina senza accesso alla rete.

Scelta di una modalità di prompt#

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

Installazione e requisiti#

YOLOE è incluso nel pacchetto principale di Ultralytics:

pip install -U ultralytics

Il prompt testuale richiede inoltre un codificatore di testo, che viene recuperato al primo utilizzo anziché durante l'installazione:

• La prima chiamata a set_classes() installa ultralytics/CLIP da GitHub con pip (fornisce il tokenizer) e scarica un codificatore di testo 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 sola volta dalla directory da cui eseguirai il codice, oppure copia lì il file, altrimenti verrà scaricato di nuovo.
• Entrambi i passaggi richiedono l'accesso alla rete, quindi esegui una predizione con prompt prima di effettuare il deployment su una macchina offline o air-gapped.
• I prompt visivi e i checkpoint senza prompt non richiedono alcun codificatore di testo.

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

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

Per saltare completamente il download del codificatore di testo al momento dell'inferenza, incorpora i prompt nei pesi una sola volta 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 priva di anchor che predice classi e box — e aggiunge tre moduli, uno per ciascuna modalità di prompt:

• Re-parameterizable Region-Text Alignment (RepRTA) perfeziona gli embedding di testo da CLIP tramite una piccola rete ausiliaria. Tale rete viene eseguita una volta per chiamata a set_classes() e viene rimossa in fase di esportazione, quindi ha un costo nullo per fotogramma. Ciò che viene eseguito a ogni forward pass è il confronto tra gli embedding dei prompt memorizzati e le feature di regione; consulta Limitazioni per comprendere il costo associato a un ampio set di prompt.
• Semantic-Activated Visual Prompt Encoder (SAVPE) codifica le feature semantiche e di attivazione da un box di esempio, condizionando il modello su oggetti dall'aspetto simile. Questo è il percorso one-shot per obiettivi difficili da nominare, come un logo o una parte specifica.
• Lazy Region-Prompt Contrast (LRPC) confronta gli embedding di regione con un vocabolario integrato di 4.585 nomi, consentendo ai checkpoint senza prompt di riconoscere oggetti senza prompt esterni e senza codificatore di testo.

La segmentazione di istanze deriva da un ramo di maschera sulla head di rilevamento, come in YOLOv8-Seg, e ogni predizione include una maschera su results[0].masks. Una volta che il modello è stato esportato, i moduli open-world vengono riparametrati in una head YOLO standard, in modo che il file esportato esegua il normale percorso di rilevamento/segmentazione.

Modelli disponibili#

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

Prestazioni di YOLOE su LVIS#

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

Prompt testuali e visivi#

Ogni cella di accuratezza e parametri riporta prompt testuale / prompt visivo; i FLOPs sono indicati una sola volta. Parametri e 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 nel confronto; la head end-to-end di YOLOE-26 si posiziona al massimo 1,1 AP al di sotto con prompt testuali e 2,6 AP con prompt visivi.

Senza prompt#

I checkpoint senza prompt rispondono dal loro vocabolario integrato senza che venga fornito alcun prompt. Ciascuna cella di accuratezza riporta end-to-end / Non-E2E, i due protocolli in base ai quali il paper valuta YOLOE-26; la pagina di YOLO26 riporta la colonna Non-E2E.

Con prompt testuali e visivi, i modelli YOLOE-26 superano le controparti YOLOE-11 e YOLOE-v8 a ogni scala corrispondente su mAP_50-95, pur rimanendo al di sotto della linea v8 per quanto riguarda 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 un numero di parametri compreso tra 155 e 232 milioni. Il paper originale di YOLOE aggiunge due risultati per i modelli in scala v8 introdotti. Su LVIS, YOLOE-v8s batte YOLO-Worldv2-S di 3,5 AP con un terzo del costo di addestramento e 1,4 volte la velocità di inferenza. Trasferito su COCO, YOLOE-v8l guadagna 0,6 box AP e 0,4 mask AP rispetto al YOLOv8-L a classi chiuse con un tempo di addestramento quasi 4 volte inferiore.

Esempi di Utilizzo#

Tutti gli esempi di YOLOE di seguito vengono eseguiti dall'API Python. La predizione con prompt testuale, la validazione, l'esportazione, il tracciamento e il normale addestramento funzionano anche dalla CLI; le ricette di fine-tuning e i prompt visivi passano una classe trainer o predictor come argomento, accettata unicamente dall'API Python.

Utilizzo per l'addestramento#

Esegui il fine-tuning di qualsiasi checkpoint *-seg.pt rilasciato sul tuo dataset YOLO. Questo processo segue per lo più la procedura di addestramento YOLO standard; la differenza sta nel trainer che passi. YOLOEPESegTrainer fonde i nomi delle tue classi nella head ed esegui il fine-tuning da lì, che è esattamente ciò che desideri per le tue etichette; il trainer predefinito non si addestra sui nomi delle 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 di Predict#

La chiamata con prompt testuale è quella mostrata in Avvio rapido. Ciascuna delle restanti due modalità richiede 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 di Val#

La validazione si esegue 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 prompt:

• 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 prelevare gli embedding da un dataset differente, 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 sola 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 di runtime aggiuntivo 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 di sola rilevamento costruito dall'architettura YOLOE corrispondente. Questo rimuove il ramo delle maschere mantenendo le classi promptate:

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 di Track#

Le classi soggette a prompt vengono trasferite direttamente nel tracciamento, permettendoti di 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)

Come si posiziona YOLOE#

YOLOE si colloca a metà strada tra un rilevatore a classi chiuse e un modello open-vocabulary pesante. Tre confronti determinano se rappresenta la scelta giusta:

• Rispetto a un YOLO a classi chiuse. Una volta impostati i prompt, YOLOE effettua le predizioni attraverso il normale percorso di rilevamento/segmentazione ed esegue l'esportazione come qualsiasi altro modello. La funzionalità aggiuntiva consiste nella capacità di modificare l'elenco delle classi al momento dell'inferenza anziché riaddestrare il modello; il compromesso è un'accuratezza zero-shot notevolmente inferiore rispetto a un modello addestrato sulle proprie classi.
• Rispetto alle precedenti famiglie YOLOE. YOLOE-26 eredita la head end-to-end senza NMS di YOLO26, copre cinque scale (n/s/m/l/x) rispetto alle tre precedenti (s/m/l) e risulta leader a ogni scala corrispondente nelle Prestazioni.
• Rispetto ai rilevatori open-vocabulary basati su transformer. GLIP e OWL-ViT eseguono un transformer di visione-linguaggio durante l'inferenza. YOLOE codifica i prompt una sola volta e li confronta poi con le feature di regione all'interno di una head convoluzionale.

Le alternative più vicine accettano tutte un prompt testuale, ma solo YOLOE e SAM 3 restituiscono maschere, e i tre modelli rispondono a quesiti differenti:

Proviene da YOLO-World? L'API ha la stessa forma: sostituisci YOLOWorld con YOLOE, carica un checkpoint di *-seg.pt e mantieni la tua chiamata a set_classes() così com'è. Ottieni maschere e prompt visivi; la nota sull'esportazione relativa alle classi congelate si applica a entrambi.

Casi d'uso e applicazioni#

Il rilevamento open-vocabulary elimina il passaggio del riaddestramento per classe, il che è fondamentale quando l'elenco di target non è noto in anticipo:

• Rilevamento open-world — robotica e sistemi di sicurezza che incontrano oggetti non enumerati durante l'addestramento.
• Rilevamento one-shot da un esempio — i prompt visivi individuano una parte specifica, un logo o un difetto da un singolo box di riferimento, utile nell'ispezione industriale.
• Catalogazione a coda lunga — il vocabolario integrato di 4.585 nomi è sufficientemente ampio per il monitoraggio della biodiversità o le scansioni di inventario retail.
• Bootstrap di dataset — pre-etichetta immagini con box e maschere prima della revisione umana, quindi addestra un modello rapido a classi chiuse sul risultato.
• Segmentazione di target arbitrari — i checkpoint di *-seg.pt rilasciati restituiscono una maschera con ogni previsione, consentendo a imaging medico e analisi satellitare di ottenere risultati precisi a livello di pixel senza un secondo modello.

Un pattern comune combina due modalità: esegui il rilevamento senza prompt una volta per scoprire cosa è presente, quindi passa ai prompt testuali per le categorie che contano.

Limitazioni#

YOLOE sacrifica l'accuratezza in cambio della capacità di cambiare classi al momento dell'inferenza. Le conseguenze da conoscere prima di procedere:

• L'accuratezza zero-shot è nettamente inferiore a quella di un modello addestrato sulle tue classi. I checkpoint con prompt si collocano all'incirca nella fascia 22-40 mAP su LVIS minival; un YOLO a classi chiuse addestrato sui tuoi dati supererà questo valore su quelle classi. Scegli YOLOE per coprire classi per cui non puoi addestrare un modello, non per sostituire l'addestramento.
• Le categorie rare rappresentano il punto debole. La colonna mAP_r in Performance riporta specificamente l'accuratezza sulle classi rare di LVIS e, con il prompt testuale, si posiziona al di sotto delle colonne comuni e frequenti in ogni riga. Controlla questo valore anziché il mAP generale quando i tuoi target sono insoliti.
• Un prompt descrive l'aspetto, non le relazioni. Il rilevamento funziona confrontando le feature delle regioni con l'embedding del prompt; di conseguenza, i prompt che dipendono da stato, contesto o confronto — come "danneggiato", "all'estrema sinistra", "quello che viene trasportato" — non hanno un riferimento affidabile con cui effettuare il matching. Preferisci formulazioni vicine ai nomi di categoria di uso comune.
• Grandi set di prompt influiscono sulla latenza. Gli embedding dei prompt vengono calcolati una sola volta, ma vengono confrontati con le feature delle regioni a ogni forward pass. Misurato su CPU con yoloe-26s-seg.pt, un forward pass aumenta di circa il 19% passando da 80 a 1.203 classi e di circa l'89% con l'intero vocabolario di 4.585 nomi. I FLOP riportati non subiscono variazioni poiché la somiglianza regione-testo non viene conteggiata, quindi il profilo non ti avviserà di questo.
• I nomi delle classi sono segnaposto finché non inserisci un prompt. Un checkpoint di *-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 forniti con l'intero vocabolario già popolato.

Note di deployment#

• 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 è agnostico rispetto alle classi per impostazione predefinita. YOLOE esegue previsioni con agnostic_nms=True. Su YOLOE-11 e YOLOE-v8 questo sopprime i box sovrapposti con punteggio inferiore tra diverse classi anziché solo all'interno della stessa classe, prevenendo duplicati quando un oggetto corrisponde a più categorie. I modelli YOLOE-26 end-to-end non applicano alcuna soppressione IoU; in quel caso, la modalità agnostica mantiene solo la classe migliore per anchor invece di consentire a un anchor di emettere più etichette di classe. Passa agnostic_nms=False per ignorare questo comportamento.
• Batching. L'inferenza in batch funziona direttamente e i prompt visivi possono variare per ogni immagine nella stessa chiamata.

Addestramento dei modelli ufficiali da zero#

La maggior parte dei lettori non ne ha bisogno. Riproduce i checkpoint open-vocabulary pubblicati da Objects365, GQA e Flickr30k — circa 1,4 milioni di campioni di addestramento su 8× RTX 4090 — e non è correlata al fine-tuning sui tuoi dati, trattato nella sezione Utilizzo dell'addestramento sopra.

L'addestramento richiede annotazioni di segmentazione. Scarica i file elaborati qui sotto oppure genera i 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, mentre le altre due modalità di prompt sono perfezionamenti di quest'ultimo:

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 il prompt visivo e YOLOEPEFreeTrainer quella per la modalità senza prompt, ma nessuna delle due classi blocca nulla autonomamente: l'addestramento selettivo deriva dall'elenco freeze che passi insieme ad esso, il quale nomina ogni figlio della testa eccetto savpe (rispettivamente ogni torre di classificazione), e l'esecuzione senza prompt richiede inoltre single_cls=True. Il repository YOLOE upstream contiene le ricette complete per i modelli in scala v8.

Un'esecuzione senza prompt completata viene riparameterizzata in un checkpoint che restituisce i suoi nomi senza alcun prompt durante l'inferenza, utilizzando 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 riconoscimenti#

Se YOLOE ha contribuito alla tua ricerca o progetto, ti preghiamo di citare l'articolo 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 ulteriori letture, il paper originale su YOLOE è disponibile su arXiv. Il codice sorgente del progetto e risorse aggiuntive sono accessibili tramite il loro repository GitHub.

FAQ#