YOLOE: deteção e segmentação de vocabulário aberto em tempo real#

Ultralytics YOLOE (Seeing Anything em tempo real) é um modelo de deteção e segmentação de instâncias de vocabulário aberto: em vez de usar uma lista de classes fixa no momento do treino, aceita as categorias que queres no momento da inferência, como um prompt de texto, um exemplo visual ou um vocabulário integrado com 4 585 nomes. Baseado nas arquiteturas Ultralytics YOLO — YOLOv8, YOLO11 e YOLO26 — e inspirado no YOLO-World, o YOLOE alcança uma precisão zero-shot de última geração a uma velocidade próxima da do YOLO de conjunto fechado.

Início rápido#

Indica as classes que queres e executa. O YOLOE-26 devolve caixas e máscaras de segmentação de instâncias para categorias com as quais nunca foi treinado.

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

A primeira chamada set_classes() descarrega um codificador de texto; consulta Instalação e requisitos antes de fazeres a implementação numa máquina sem acesso à rede.

Escolher um modo de prompting#

O YOLOE suporta três modos de prompting, e a escolha determina qual checkpoint carregas e qual o aspeto das etiquetas das classes. Escolhe a linha que corresponde ao que consegues fornecer no momento da inferência.

Instalação e requisitos#

O YOLOE está incluído no pacote principal Ultralytics:

pip install -U ultralytics

O prompting de texto também precisa de um codificador de texto, que é obtido na primeira utilização e não no momento da instalação:

• A primeira chamada set_classes() instala ultralytics/CLIP a partir do GitHub com pip (que fornece o tokenizador) e descarrega um codificador de texto TorchScript para o diretório de trabalho atual. O YOLOE-26 obtém mobileclip2_b.ts, com cerca de 254 MB; o YOLOE-11 e o YOLOE-v8 obtêm mobileclip_blt.ts. Executa a transferência uma vez a partir do diretório a partir do qual vais executar o programa ou copia o ficheiro para lá; caso contrário, será obtido novamente.
• Ambos os passos precisam de acesso à rede, por isso executa uma predição com prompt antes de fazeres a implementação numa máquina offline ou isolada da rede.
• Os prompts visuais e os checkpoints sem prompt não precisam de qualquer codificador de texto.

Os checkpoints YOLOE-26 requerem ultralytics 8.4.0 ou posterior; as famílias YOLOE-11 e YOLOE-v8 estão disponíveis em versões anteriores. Uma predição com prompt de texto percorre todo o processo — transferência do checkpoint, instalação do CLIP, codificador de texto e inferência:

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

Para ignorares completamente a transferência do codificador de texto durante a inferência, incorpora os prompts nos pesos uma vez e reutiliza-os — consulta Reutilizar embeddings de prompts.

Visão geral da arquitetura#

O YOLOE mantém a estrutura YOLO padrão — um backbone convolucional para extração de características, um neck para fusão multiescala e uma head sem âncoras e desacoplada que prevê classes e caixas — e adiciona três módulos, um por modo de prompting:

• O alinhamento reparametrizável entre regiões e texto (RepRTA) refina os embeddings de texto do CLIP através de uma pequena rede auxiliar. Essa rede é executada uma vez por chamada set_classes() e é eliminada na exportação, pelo que não tem qualquer custo por frame. O que é executado em cada passagem forward é a comparação dos embeddings de prompt armazenados com as características das regiões; consulta Limitações para saberes qual o custo com um conjunto grande de prompts.
• O codificador de prompts visuais ativado semanticamente (SAVPE) codifica características semânticas e de ativação a partir de uma caixa de exemplo, condicionando o modelo a objetos com uma aparência semelhante. Este é o processo one-shot para alvos difíceis de nomear, como um logótipo ou uma peça específica.
• O contraste preguiçoso entre regiões e prompts (LRPC) compara embeddings de regiões com um vocabulário integrado de 4 585 nomes, permitindo que os checkpoints sem prompt reconheçam objetos sem um prompt externo e sem um codificador de texto.

A segmentação de instâncias provém de um ramo de máscaras na head de deteção, como no YOLOv8-Seg, e cada predição inclui uma máscara em results[0].masks. Depois de o modelo ser exportado, os módulos de mundo aberto são reparametrizados numa head YOLO padrão, pelo que o ficheiro exportado executa o processo normal de deteção/segmentação.

Modelos disponíveis#

Cada checkpoint abaixo é um modelo de segmentação de instâncias e suporta val, predict, export e track. Carrega um ficheiro *-seg.pt para prompting de texto ou visual e um ficheiro *-seg-pf.pt para inferência sem prompt; não são intercambiáveis, consulta Escolher um modo de prompting. Apenas os ficheiros *-seg.pt suportam train; um checkpoint sem prompt é produzido a partir de um modelo treinado com prompt de texto, consulta Treinar os modelos oficiais de raiz.

Desempenho do YOLOE no LVIS#

Resultados zero-shot no LVIS minival a 640 píxeis, provenientes do artigo do Ultralytics YOLO26.

Prompts de texto e visuais#

Cada célula de precisão e parâmetros apresenta prompt de texto / prompt visual; os FLOPs são indicados uma vez. Os parâmetros e FLOPs correspondem à configuração de deteção avaliada no artigo. A precisão é o valor Non-E2E do artigo, o único protocolo que este apresenta para todos os modelos da comparação; a head end-to-end do YOLOE-26 fica no máximo 1.1 AP abaixo desse valor com prompts de texto e 2.6 AP abaixo com prompts visuais.

Sem prompt#

Os checkpoints sem prompt respondem a partir do seu vocabulário integrado, sem que seja fornecido um prompt. Cada célula de precisão apresenta end-to-end / Non-E2E, os dois protocolos com que o artigo avalia o YOLOE-26; a página do YOLO26 cita a coluna Non-E2E.

Com prompts de texto e visuais, os modelos YOLOE-26 superam os seus equivalentes YOLOE-11 e YOLOE-v8 em todas as escalas correspondentes no mAP_50-95, mantendo-se abaixo da linha v8 em parâmetros e FLOPs. Na mesma divisão, o artigo apresenta YOLO-Worldv2 com 24.4 (S), 32.4 (M) e 35.5 (L), e os detetores baseados em Transformer GLIP-T com 26.0, GDINO-T com 27.4 e DetCLIP-T com 34.4, cada um com 155 a 232 M de parâmetros. O artigo original do YOLOE adiciona dois resultados para os modelos à escala v8 que introduziu. No LVIS, o YOLOE-v8s supera o YOLO-Worldv2-S em 3.5 AP, com um terço do custo de treino e uma velocidade de inferência 1.4× superior. Transferido para o COCO, o YOLOE-v8l obtém mais 0.6 box AP e 0.4 mask AP do que o YOLOv8-L de conjunto fechado, com quase 4× menos tempo de treino.

Exemplos de utilização#

Todos os exemplos de YOLOE abaixo são executados a partir da API Python. A predição com prompt de texto, a validação, a exportação, o tracking e o treino normal também funcionam a partir da CLI; as receitas de fine-tuning e o prompting visual passam uma classe de trainer ou predictor como argumento, algo que apenas a API Python aceita.

Utilização do treino#

Faz fine-tuning de qualquer checkpoint *-seg.pt lançado no teu próprio conjunto de dados YOLO. Isto segue em grande parte o procedimento padrão de treino YOLO; a diferença está no trainer que passas. YOLOEPESegTrainer funde os nomes das tuas classes na head e faz fine-tuning a partir daí, que é o que queres para as tuas próprias etiquetas; o trainer predefinido não treina com base nos nomes das tuas classes.

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)

Utilização de Predict#

A chamada com prompt de texto é a apresentada em Início rápido. Os outros dois modos precisam de um argumento adicional cada:

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

Utilização de Val#

A validação é executada como em qualquer outro modelo, num conjunto de dados de segmentação:

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

Duas variantes da mesma chamada abrangem os outros modos de prompting:

• Prompts visuais — model.val(data="coco128-seg.yaml", load_vp=True) extrai um embedding visual por categoria a partir do próprio conjunto de dados. Adiciona refer_data="coco.yaml" para obter os embeddings de um conjunto de dados diferente, que tem de conter exatamente as mesmas categorias.
• Sem prompt — carrega um checkpoint *-seg-pf.pt e passa single_cls=True.

Utilização da exportação#

Os embeddings dos prompts podem ser guardados uma vez e reutilizados ao produzir exportações estáticas como ONNX, OpenVINO, TensorRT, CoreML, LiteRT e RKNN. O perfil NPZ é carregado pelo modelo PyTorch original antes da exportação; não é uma entrada adicional de runtime, e o modelo exportado não necessita do ficheiro 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")

O mesmo perfil de prompts também pode configurar um modelo apenas de deteção, criado a partir da arquitetura YOLOE correspondente. Isto remove o ramo de máscaras, mantendo as classes definidas pelos prompts:

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)

Utilização de Track#

As classes definidas pelos prompts passam diretamente para o tracking, pelo que podes acompanhar objetos nos quais o tracker nunca foi treinado:

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)

Como o YOLOE se compara#

O YOLOE situa-se entre um detetor de conjunto fechado e um modelo de vocabulário aberto pesado. Três comparações determinam se é a escolha certa:

• Em relação a um YOLO de conjunto fechado. Depois de definidos os prompts, o YOLOE prevê através do percurso normal de deteção/segmentação e é exportado como qualquer outro modelo. O que acrescenta é a capacidade de alterar a lista de classes no momento da inferência, em vez de voltar a treinar; o custo é uma precisão zero-shot muito inferior à de um modelo treinado nas tuas próprias classes.
• Em relação às famílias YOLOE anteriores. O YOLOE-26 herda a cabeça end-to-end sem NMS do YOLO26 e abrange cinco escalas (n/s/m/l/x), contra as três anteriores (s/m/l), liderando em todas as escalas correspondentes em Desempenho.
• Em relação aos detetores de vocabulário aberto baseados em Transformer. GLIP e OWL-ViT executam um Transformer de visão-linguagem durante a inferência. O YOLOE codifica os prompts uma vez e compara-os depois com as features das regiões dentro de uma cabeça convolucional.

As alternativas mais próximas aceitam todas um prompt de texto, mas apenas YOLOE e SAM 3 devolvem máscaras, e os três respondem a perguntas diferentes:

Vens do YOLO-World? A API tem a mesma estrutura: troca YOLOWorld por YOLOE, carrega um checkpoint *-seg.pt e mantém a tua chamada set_classes() tal como está. Ganhas máscaras e prompts visuais; a nota sobre exportação relativa às classes congeladas aplica-se a ambos.

Casos de utilização e aplicações#

A deteção de vocabulário aberto elimina a etapa de novo treino por classe, o que é especialmente importante quando a lista de alvos não é conhecida antecipadamente:

• Deteção em mundo aberto — robótica e sistemas de segurança que encontram objetos que ninguém enumerou durante o treino.
• Deteção one-shot a partir de um exemplo — os prompts visuais identificam uma peça, um logótipo ou um defeito específico a partir de uma única caixa de referência, sendo úteis na inspeção industrial.
• Catalogação de cauda longa — o vocabulário integrado com 4 585 nomes é suficientemente abrangente para campanhas de monitorização da biodiversidade ou de inventário de retalho.
• Inicialização de conjuntos de dados — pré-etiqueta imagens com caixas e máscaras antes da revisão humana e, depois, treina um modelo rápido de conjunto fechado com o resultado.
• Segmentação de alvos arbitrários — os checkpoints *-seg.pt disponibilizados devolvem uma máscara com cada previsão, pelo que a imagiologia médica e a análise de imagens de satélite obtêm resultados precisos ao nível do píxel sem um segundo modelo.

Um padrão comum combina dois modos: executa primeiro o modo sem prompt para descobrir o que está presente e, depois, muda para prompts de texto para as categorias relevantes.

Limitações#

O YOLOE troca precisão pela capacidade de alterar as classes no momento da inferência. Estas são as consequências que deves conhecer antes de te comprometeres:

• A precisão zero-shot é muito inferior à de um modelo treinado nas tuas classes. Os checkpoints com prompts obtêm aproximadamente entre 22 e 40 mAP no LVIS minival; um YOLO de conjunto fechado treinado nos teus próprios dados terá melhores resultados nessas classes. Escolhe YOLOE para abranger classes para as quais não consegues treinar, não para substituir o treino.
• As categorias raras são o ponto fraco. A coluna mAP_r em Desempenho apresenta especificamente a precisão nas classes raras do LVIS e, com prompts de texto, fica abaixo das colunas de classes comuns e frequentes em todas as linhas. Consulta-a em vez do mAP principal quando os teus alvos forem invulgares.
• Um prompt descreve a aparência, não relações. A deteção funciona comparando as features das regiões com o embedding do prompt, pelo que prompts dependentes de estado, contexto ou comparação — "danificado", "mais à esquerda", "o que está a ser transportado" — não têm uma característica fiável com a qual estabelecer correspondência. Prefere uma formulação próxima dos nomes de categorias usados no dia a dia.
• Conjuntos grandes de prompts aumentam a latência. Os embeddings dos prompts são calculados uma vez, mas são comparados com as features das regiões em cada passagem forward. Medida em CPU com yoloe-26s-seg.pt, uma passagem forward aumenta cerca de 19% ao passar de 80 para 1 203 classes e cerca de 89% com o vocabulário completo de 4 585 nomes. Os FLOPs reportados não mudam, porque a similaridade região-texto não é contabilizada, pelo que o perfil não te irá avisar.
• Os nomes das classes são placeholders até definires um prompt. Um checkpoint *-seg.pt acabado de carregar reporta nc=80 com nomes numéricos ("0", "1", …), por isso chama set_classes() antes de leres as etiquetas. Os checkpoints sem prompt já incluem todo o vocabulário preenchido.

Notas de implementação#

• Hardware. A inferência requer uma GPU NVIDIA com 4–8 GB de VRAM; as escalas n e s funcionam em GPUs de edge como Jetson ou em CPU com resolução reduzida. O fine-tuning requer uma única GPU.
• O NMS é agnóstico em relação às classes por padrão. O YOLOE faz previsões com agnostic_nms=True. Por padrão, isso suprime caixas sobrepostas com pontuação mais baixa em diferentes classes, em vez de apenas dentro da mesma classe, o que evita duplicatas quando um objeto corresponde a várias categorias. Com nms=False, o YOLOE-26 não aplica supressão de IoU; o modo agnóstico mantém apenas a melhor classe por âncora em vez de permitir que uma âncora emita vários rótulos de classe. Passa agnostic_nms=False para substituir.
• Batching. A inferência em batch funciona diretamente, e os prompts visuais podem ser diferentes para cada imagem na mesma chamada.

Treinar os modelos oficiais de raiz#

A maioria dos leitores nunca precisará disto. Este processo reproduz os checkpoints de vocabulário aberto publicados a partir de Objects365, GQA e Flickr30k — cerca de 1,4 M de amostras de treino em 8× RTX 4090 — e não está relacionado com o fine-tuning nos teus próprios dados, abordado acima em Utilização do treino.

O treino requer anotações de segmentos. Podes descarregar os ficheiros processados abaixo ou gerar os teus próprios ficheiros com o script fornecido pela equipa oficial, que utiliza SAM 2.1. A validação utiliza LVIS minival.

O modelo com prompt de texto é treinado primeiro, e os outros dois modos de prompting são refinamentos desse modelo:

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

Os checkpoints com prompt visual e sem prompt começam a partir desse modelo treinado com prompt de texto e atualizam um módulo cada um. YOLOESegVPTrainer é a receita de prompt visual e YOLOEPEFreeTrainer é a receita sem prompt, mas nenhum deles congela classes por si só: o treino seletivo provém da lista freeze que passas juntamente com ele, a qual nomeia todos os elementos-filhos da cabeça exceto savpe (respetivamente, todas as torres de classificação), e a execução sem prompt também requer single_cls=True. O repositório YOLOE upstream contém as receitas completas para os modelos à escala v8.

Uma execução sem prompt concluída é reparametrizada num checkpoint que apresenta os seus nomes sem prompt durante a inferência, utilizando 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

Citações e agradecimentos#

Se o YOLOE tiver contribuído para a tua investigação ou projeto, cita o artigo original de Ao Wang, Lihao Liu, Hui Chen, Zijia Lin, Jungong Han e Guiguang Ding, da Universidade de Tsinghua:

@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},
}

Para mais informações, o artigo original do YOLOE está disponível no arXiv. O código-fonte do projeto e recursos adicionais podem ser acedidos através do seu repositório no GitHub.

Perguntas frequentes#