YOLOE: Detecção e Segmentação de Vocabulário Aberto em Tempo Real#

Ultralytics YOLOE (Real-Time Seeing Anything) é um modelo de detecção de vocabular aberto e segmentação de instâncias: em vez de uma lista de classes fixa no momento do treinamento, ele aceita as categorias que queres no momento da inferência, seja como um prompt de texto, um exemplo visual ou um vocabulário interno de 4.585 nomes. Construído sobre as arquiteturas Ultralytics YOLO — YOLOv8, YOLO11 e YOLO26 — e inspirado no YOLO-World, o YOLOE alcança precisão zero-shot de ponta com uma velocidade próxima à de um YOLO de conjunto fechado.

Início Rápido#

Nomeia as classes que queres e executa. O YOLOE-26 devolve caixas e máscaras de segmentação de instâncias para categorias em que 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 a set_classes() descarrega um codificador de texto; consulta Instalação e Requisitos antes de fazer o deployment para uma máquina sem acesso à rede.

Escolher um Modo de Prompt#

O YOLOE suporta três modos de prompt, e a escolha determina qual o checkpoint que carregas e como se parecem os teus rótulos de classe. Escolhe a linha que corresponde ao que podes fornecer no momento da inferência.

Instalação e Requisitos#

O YOLOE vem incluído no pacote principal do Ultralytics:

pip install -U ultralytics

O prompt de texto precisa de um codificador de texto além disso, e ele é obtido na primeira utilização em vez de no momento da instalação:

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

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

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

Para ignorar totalmente a descarga do codificador de texto no momento da inferência, incorpora os prompts nos pesos uma vez e reutiliza-os — consulta Reutilizar embeddings de prompt.

Visão geral da arquitetura#

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

• Re-parameterizable Region-Text Alignment (RepRTA) refina embeddings de texto do CLIP através de uma pequena rede auxiliar. Essa rede é executada uma vez por chamada de set_classes() e é recolhida na exportação, pelo que não custa nada por frame. O que é executado em cada passo forward é a comparação dos embeddings de prompt armazenados com as características de região; consulta Limitações para ver o que isso custa com um grande conjunto de prompts.
• Semantic-Activated Visual Prompt Encoder (SAVPE) codifica características semânticas e de ativação a partir de uma caixa de exemplo, condicionando o modelo a objetos que se parecem com ela. Este é o caminho one-shot para alvos que são difíceis de nomear, como um logótipo ou uma peça específica.
• Lazy Region-Prompt Contrast (LRPC) compara embeddings de região com um vocabulário interno de 4.585 nomes, para que os checkpoints sem prompt reconheçam objetos sem prompt externo e sem codificador de texto.

A segmentação de instâncias vem de um ramo de máscara na cabeça de deteção, tal como no YOLOv8-Seg, e cada predição transporta uma máscara em results[0].masks. Uma vez que o modelo é exportado, os módulos de mundo aberto são reparametrizados numa cabeça YOLO padrão, de modo a que o ficheiro exportado execute o caminho 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 prompt de texto ou visual e um ficheiro *-seg-pf.pt para inferência sem prompt; eles não são intercambiáveis, consulta Escolher um Modo de Prompt. 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 minival do LVIS a 640 pixéis, do artigo do Ultralytics YOLO26.

Prompts de texto e visuais#

Cada célula de precisão e parâmetros lê prompt de texto / prompt visual; os FLOPs são indicados uma vez. Os parâmetros e FLOPs são para a configuração de deteção que o artigo avalia. A precisão é o valor Non-E2E do artigo, o único protocolo que relata para todos os modelos na comparação; a cabeça end-to-end do YOLOE-26 fica atrás por no máximo 1.1 AP sob prompts de texto e 2.6 AP sob prompts visuais.

Sem prompt#

Os checkpoints sem prompt respondem a partir do seu vocabulário interno sem nenhum prompt fornecido. Cada célula de precisão lê end-to-end / Non-E2E, os dois protocolos sob os quais o artigo pontua o YOLOE-26; a página do YOLO26 cita a coluna Non-E2E.

Sob prompts de texto e visuais, os modelos YOLOE-26 lideram os seus homólogos YOLOE-11 e YOLOE-v8 em todas as escalas correspondentes no mAP_50-95, mantendo-se abaixo da linha do v8 em parâmetros e FLOPs. Na mesma divisão, o artigo relata o YOLO-Worldv2 a 24.4 (S), 32.4 (M) e 35.5 (L), e os detetores baseados em Transformer GLIP-T a 26.0, GDINO-T a 27.4 e DetCLIP-T a 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 por 3.5 AP a um terço do custo de treino e 1.4× a velocidade de inferência. Transferido para o COCO, o YOLOE-v8l ganha 0.6 AP de caixa e 0.4 AP de máscara em comparação com o YOLOv8-L de conjunto fechado com quase 4× menos tempo de treino.

Exemplos de uso#

Cada exemplo do YOLOE abaixo é executado a partir da API Python. A predição com prompt de texto, validação, exportação, tracking e treino básico também funcionam a partir da CLI; as receitas de ajuste fino e prompt visual passam uma classe de treinador ou preditor como argumento, o que apenas a API Python aceita.

Utilização do Treino#

Ajusta finamente (fine-tune) qualquer checkpoint *-seg.pt lançado no teu próprio conjunto de dados YOLO. Isto segue principalmente o procedimento padrão de treino YOLO; a diferença é qual o treinador que passas. YOLOEPESegTrainer funde os nomes das tuas classes na cabeça e faz o ajuste fino a partir daí, que é o que queres para os teus próprios rótulos; o treinador padrão não treina contra os 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)

Uso de Predição#

A chamada de prompt de texto é a mostrada em Início Rápido. Os restantes dois modos precisam cada um de um argumento extra:

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

Uso de Validação#

A validação é executada como 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 cobrem os outros modos de prompt:

• 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 deve conter exatamente as mesmas categorias.
• Sem prompt — carrega um checkpoint *-seg-pf.pt e passa single_cls=True.

Uso da Exportação#

Os embeddings de prompt podem ser salvos uma vez e reutilizados ao produzir exports estáticos como ONNX, OpenVINO, TensorRT, CoreML, LiteRT e RKNN. O perfil NPZ é carregado pelo modelo PyTorch original antes da exportação; ele não é uma entrada de runtime adicional e o modelo exportado não requer o arquivo 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 prompt também pode configurar um modelo apenas de detecção construído a partir da arquitetura YOLOE correspondente. Isso remove a branch de máscara enquanto retém as classes solicitadas por 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)

Uso de Rastreamento#

As classes com prompt passam diretamente para o tracking, para que possas seguir objetos em que 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 posiciona-se entre um detetor de conjunto fechado e um modelo de vocabulário aberto pesado. Três comparações decidem se é a escolha certa:

• Contra um YOLO de conjunto fechado. Uma vez definidos os prompts, o YOLOE faz predições através do caminho normal de deteção/segmentação e exporta como qualquer outro modelo. O que ele adiciona é a capacidade de alterar a lista de classes no momento da inferência em vez de re-treinar; o que custa é uma precisão zero-shot bem abaixo de um modelo treinado nas tuas próprias classes.
• Contra as famílias YOLOE anteriores. O YOLOE-26 herda a cabeça end-to-end sem NMS do YOLO26 e cobre cinco escalas (n/s/m/l/x) em contraste com as três anteriores (s/m/l), liderando em todas as escalas correspondentes no Desempenho.
• Contra detetores de vocabulário aberto baseados em Transformer. O GLIP e o OWL-ViT executam um Transformer de visão-linguagem na inferência. O YOLOE codifica os prompts uma vez e depois compara-os com características de região dentro de uma cabeça convolucional.

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

Vens do YOLO-World? A API tem a mesma forma: 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 de exportação sobre classes congeladas aplica-se a ambos.

Casos de Uso e Aplicações#

A deteção de vocabulário aberto remove o passo de re-treino por classe, o que importa mais quando a lista de alvo não é conhecida à partida:

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

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

Limitações#

O YOLOE troca precisão pela capacidade de alterar classes em momento de inferência. As consequências que vale a pena conhecer antes de te comprometeres:

• A precisão zero-shot está bem abaixo de um modelo treinado nas tuas classes. Os checkpoints com prompt situam-se aproximadamente na faixa de 22-40 mAP no minival LVIS; um YOLO de conjunto fechado treinado nos teus próprios dados superará isso nessas classes. Recorre ao YOLOE para cobrir classes para as quais não podes treinar, e não para substituir o treino.
• As categorias raras são o ponto fraco. A coluna mAP_r em Desempenho relata especificamente a precisão nas classes raras do LVIS e, com prompts de texto, fica abaixo das colunas 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 as relações. A deteção funciona comparando caraterísticas de regiões com o embedding do prompt, pelo que prompts que dependem de estado, contexto ou comparação — "danificado", "mais à esquerda", "aquele que está a ser transportado" — não têm um ponto de referência fiável para correspondência. Prefere uma redação próxima dos nomes de categorias do dia a dia.
• Grandes conjuntos de prompts custam latência. Os embeddings dos prompts são calculados uma vez, mas são comparados com as caraterísticas das regiões em cada passagem direta (forward pass). Medido num CPU com yoloe-26s-seg.pt, uma passagem direta 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 de todo, porque a similaridade entre região e texto não é contada, pelo que o perfil não te avisará.
• Os nomes das classes são marcadores de posição até fazeres o prompt. Um checkpoint *-seg.pt recém-carregado reporta nc=80 com nomes numéricos ("0", "1", ...), por isso chama set_classes() antes de ler as etiquetas. Os checkpoints sem prompt trazem o vocabulário completo já preenchido.

Notas de Implementação#

• Hardware. A inferência precisa de uma GPU NVIDIA com 4-8 GB de VRAM; as escalas n e s funcionam em GPUs de edge como Jetson ou num CPU com resolução reduzida. O fine-tuning precisa de uma única GPU.
• O NMS é agnóstico em relação à classe por predefinição. O YOLOE faz previsões com agnostic_nms=True. No YOLOE-11 e YOLOE-v8, isto suprime caixas sobrepostas com pontuações mais baixas em diferentes classes, em vez de apenas dentro da mesma classe, o que evita duplicados quando um objeto corresponde a várias categorias. Os modelos YOLOE-26 de ponta a ponta não aplicam qualquer supressão de IoU; aí, o modo agnóstico apenas mantém a única melhor classe por âncora em vez de deixar que uma âncora emita várias etiquetas de classe. Passa agnostic_nms=False para substituir.
• Lotes. A inferência em lote funciona diretamente, e os prompts visuais podem diferir por imagem na mesma chamada.

Treinar os Modelos Oficiais de Raiz#

A maioria dos leitores nunca precisa disto. Reproduz os checkpoints de vocabulário aberto publicados a partir do 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, que é abordado em Utilização de Treino acima.

O treino precisa de anotações de segmentação. Podes descarregar os ficheiros processados abaixo ou gerar os teus próprios com o script fornecido pela equipa oficial, potenciado por SAM 2.1. A validação usa o minival LVIS.

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

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 de prompt visual e sem prompt começam a partir desse modelo com prompt de texto treinado e atualizam um módulo cada. YOLOESegVPTrainer é a receita de prompt visual e YOLOEPEFreeTrainer a sem prompt, mas nenhum deles congela nada por si só: o treino seletivo vem da lista freeze que passas juntamente, que nomeia cada filho de cabeça exceto savpe (respetivamente cada torre de classificação), e a execução sem prompt também precisa de single_cls=True. O repositório YOLOE principal contém as receitas completas para os modelos à escala v8.

Uma execução sem prompt concluída é reparametrizada num checkpoint que reporta os seus nomes sem prompt na 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 contribuiu para sua pesquisa ou projeto, por favor cite o artigo original por Ao Wang, Lihao Liu, Hui Chen, Zijia Lin, Jungong Han, e Guiguang Ding da 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},
}

Para leitura adicional, o artigo original do YOLOE está disponível no arXiv. O código-fonte do projeto e recursos adicionais podem ser acessados através do seu repositório GitHub.

FAQ#