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

O Ultralytics YOLOE (Real-Time Seeing Anything) é um modelo de deteção com vocabulário aberto e segmentação de instâncias: em vez de usar uma lista de classes fixada durante o treino, recebe as categorias pretendidas 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 ponta, com uma velocidade próxima à do YOLO de conjunto fechado.

Início rápido#

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

from ultralytics import YOLOE

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

# "double-decker bus" não é uma classe COCO; o YOLOE identifica-a apenas pelas palavras
model.set_classes(["double-decker bus", "person"])

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

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

Escolher um modo de prompting#

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

Instalação e requisitos#

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

pip install -U ultralytics

Além disso, o prompting por texto precisa de um codificador de texto, que é transferido na primeira utilização, e não durante a instalação:

• A primeira chamada set_classes() instala ultralytics/CLIP do GitHub com pip (que fornece o tokenizador) e transfere 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 onde vais executar o sistema ou copia o ficheiro para lá; caso contrário, será transferido novamente.
• Ambas as etapas precisam de acesso à rede. Por isso, executa uma previsão com prompt antes de implementar o sistema numa máquina offline ou isolada da rede.
• Os prompts visuais e os checkpoints sem prompt não precisam de nenhum codificador de texto.

Os checkpoints YOLOE-26 exigem ultralytics 8.4.0 ou posterior; as famílias YOLOE-11 e YOLOE-v8 estão disponíveis em versões anteriores. Uma previsão com prompt de texto testa 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 evitar por completo a transferência do codificador de texto no momento da 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 em várias escalas e uma head desacoplada sem âncoras que prevê classes e caixas — e acrescenta três módulos, um para cada modo de prompting:

• O Alinhamento Região-Texto Reparametrizável (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 removida durante a exportação, por isso não tem custo por frame. O que é executado em cada passagem forward é a comparação entre os embeddings de prompt armazenados e as características das regiões; consulta Limitações para saber o custo de usar um conjunto grande de prompts.
• O Codificador de Prompt Visual Ativado por Semântica (SAVPE) codifica características semânticas e de ativação a partir de uma caixa de exemplo, condicionando o modelo a objetos com aspeto semelhante. Este é o caminho de disparo único para alvos difíceis de nomear, como um logótipo ou uma peça específica.
• O Contraste Preguiçoso entre Região e Prompt (LRPC) compara embeddings de regiões com um vocabulário integrado com 4 585 nomes, permitindo que os checkpoints sem prompt reconheçam objetos sem prompt externo nem codificador de texto.

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

Modelos disponíveis#

Todos os checkpoints abaixo são modelos de segmentação de instâncias e suportam 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 é criado a partir de um modelo treinado com prompts de texto. Consulta Treinar os modelos oficiais do zero.

Desempenho do YOLOE no LVIS#

Resultados zero-shot no minival do LVIS a 640 píxeis, retirados 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 única 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 reportado para todos os modelos da comparação; a head end-to-end do YOLOE-26 fica, no máximo, 1,1 AP abaixo com prompts de texto e 2,6 AP abaixo com prompts visuais.

Sem prompt#

Os checkpoints sem prompt respondem usando o vocabulário integrado, sem receber qualquer prompt. Cada célula de precisão apresenta end-to-end / Non-E2E, os dois protocolos em que o artigo avalia o YOLOE-26; a página do YOLO26 apresenta a coluna Non-E2E.

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

Exemplos de uso#

Todos os exemplos de YOLOE abaixo são executados pela API do Python. A predição com prompts de texto, a validação, a exportação, o rastreamento e o treinamento simples também funcionam pela CLI; as receitas de ajuste fino e o prompting visual recebem uma classe de trainer ou predictor como argumento, algo aceito somente pela API do Python.

Utilização no treino#

Ajusta qualquer checkpoint *-seg.pt lançado usando seu próprio conjunto de dados YOLO. Isso segue em grande parte o procedimento padrão de treinamento YOLO; a diferença está no trainer que você passa. YOLOEPESegTrainer incorpora os nomes das suas classes à cabeça e ajusta o modelo a partir daí, que é o que você quer para seus próprios rótulos; o trainer padrão não treina com os nomes das suas 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,  # <- Importante: o trainer de ajuste fino, não o padrão
)

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 com prompt de texto é a mostrada em Início rápido. Cada um dos outros dois modos precisa 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")

# Uma caixa de exemplo por alvo, cada uma com seu próprio ID de classe
visual_prompts = {
    "bboxes": np.array([[221.52, 405.8, 344.98, 857.54], [120, 425, 160, 445]]),  # pessoa, óculos
    "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",  # Imagem-alvo
    refer_image="ultralytics/assets/bus.jpg",  # Onde ficam as caixas de exemplo
    visual_prompts=visual_prompts,
    predictor=YOLOEVPSegPredictor,
)
results[0].show()

# refer_image também define as classes permanentemente, então as chamadas seguintes não precisam de prompts
results = model("ultralytics/assets/bus.jpg")
model.export(format="onnx")  # E a exportação as mantém

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)  # tensor float (1, 3, H, W) em [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: pessoa, óculos
        np.array([[150, 200, 1150, 700]]),  # zidane.jpg: pessoa
    ],
    "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 em qualquer outro modelo, usando um conjunto de dados de segmentação:

from ultralytics import YOLOE

model = YOLOE("yoloe-26l-seg.pt")  # ou yoloe-26s/m-seg.pt para outros tamanhos

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 do próprio conjunto de dados um embedding visual por categoria. Adicione refer_data="coco.yaml" para obter os embeddings de outro conjunto de dados, que precisa conter exatamente as mesmas categorias.
• Sem prompt — carregue um checkpoint *-seg-pf.pt e passe single_cls=True.

Uso da exportação#

Os embeddings de prompt podem ser salvos uma vez e reutilizados ao gerar exportações estáticas como ONNX, OpenVINO, TensorRT, CoreML, LiteRT e RKNN. O perfil NPZ é carregado pelo modelo original PyTorch antes da exportação; não é uma entrada adicional em tempo de execução, e o modelo exportado não precisa do arquivo NPZ.

from ultralytics import YOLOE

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

# O perfil está vinculado ao checkpoint de origem e pode ser reutilizado em exportações posteriores.
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, criado a partir da arquitetura YOLOE correspondente. Isso remove o ramo de máscara, mantendo 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 do rastreamento#

As classes solicitadas por prompt são transferidas diretamente para o rastreamento, para que você possa acompanhar objetos para os quais o tracker nunca foi treinado:

from ultralytics import YOLOE

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

# persist=True mantém os IDs de rastreamento estáveis entre os quadros
for result in model.track("path/to/video.mp4", stream=True, persist=True):
    print(result.boxes.id)

Comparação do YOLOE#

O YOLOE fica entre um detector de conjunto fechado e um modelo de vocabulário aberto mais pesado. Três comparações ajudam a decidir se é a escolha certa:

• Em comparação com um YOLO de conjunto fechado. Depois de definir os prompts, o YOLOE faz predições pelo fluxo comum de detecção/segmentação e é exportado como qualquer outro modelo. O que ele acrescenta é a capacidade de alterar a lista de classes no momento da inferência, sem retreinar; o custo é uma precisão zero-shot muito inferior à de um modelo treinado com suas próprias classes.
• Em comparação com as 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), em comparação com as três anteriores (s/m/l), além de liderar em todas as escalas correspondentes em Desempenho.
• Em comparação com detectores de vocabulário aberto baseados em Transformer. O GLIP e o OWL-ViT executam um Transformer de visão e linguagem durante a inferência. O YOLOE codifica os prompts uma vez e depois os compara com os recursos das regiões 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 retornam máscaras, e os três respondem a perguntas diferentes:

Vindo do YOLO-World? A API tem o mesmo formato: substitua YOLOWorld por YOLOE, carregue um checkpoint *-seg.pt e mantenha sua chamada set_classes() como está. Você ganha máscaras e prompts visuais; a nota sobre exportação referente às classes congeladas se aplica a ambos.

Casos de uso e aplicações#

A detecção de vocabulário aberto elimina a etapa de retreinamento por classe, o que é especialmente importante quando a lista de alvos não é conhecida de antemão:

• Detecção em ambientes abertos — robótica e sistemas de segurança que encontram objetos não enumerados durante o treinamento.
• Detecção one-shot a partir de um exemplo — os prompts visuais identificam uma peça, um logotipo ou um defeito específico usando uma única caixa de referência, algo útil na inspeção industrial.
• Catalogação de cauda longa — o vocabulário integrado de 4,585 nomes é amplo o bastante para levantamentos de monitoramento da biodiversidade ou de estoque no varejo.
• Inicialização de conjuntos de dados — faça a pré-rotulagem de imagens com caixas e máscaras antes da revisão humana e, em seguida, treine um modelo rápido de conjunto fechado com os resultados.
• Segmentação de alvos arbitrários — os checkpoints *-seg.pt lançados retornam uma máscara para cada predição, então a imagiologia médica e a análise de imagens de satélite obtêm resultados precisos ao nível do pixel sem precisar de um segundo modelo.

Um padrão comum combina dois modos: execute uma vez sem prompt para descobrir o que está presente e, em seguida, use prompts de texto para as categorias relevantes.

Limitações#

O YOLOE troca precisão pela capacidade de alterar classes no momento da inferência. Estas são as consequências que você deve conhecer antes de adotá-lo:

• A precisão zero-shot é muito inferior à de um modelo treinado com suas classes. Os checkpoints com prompts ficam aproximadamente na faixa de 22-40 mAP no LVIS minival; um YOLO de conjunto fechado treinado com seus próprios dados terá melhor desempenho nessas classes. Use o YOLOE para abranger classes para as quais você não pode treinar, não para substituir o treinamento.
• Categorias raras são o ponto fraco. A coluna mAP_r em Desempenho informa a precisão especificamente nas classes raras do LVIS e, com prompts de texto, fica abaixo das colunas de classes comuns e frequentes em todas as linhas. Confira esse valor, não apenas o mAP principal, quando seus alvos forem incomuns.
• Um prompt descreve a aparência, não as relações. A detecção funciona comparando os recursos das regiões com o embedding do prompt, então prompts que dependem de estado, contexto ou comparação — "danificado", "o mais à esquerda", "o que está sendo carregado" — não oferecem um critério confiável para correspondência. Prefira termos próximos aos nomes de categorias usados no dia a dia.
• Conjuntos grandes de prompts aumentam a latência. Os embeddings de prompt são calculados uma vez, mas são comparados com os recursos das regiões em cada passagem forward. Medida na 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 informados não mudam, pois a similaridade entre região e texto não é contabilizada, então o perfil não vai alertar você.
• Os nomes das classes são provisórios até você definir os prompts. Um checkpoint *-seg.pt recém-carregado informa nc=80 com nomes numéricos ("0", "1", …), então chame set_classes() antes de ler os rótulos. Os checkpoints sem prompt já vêm com o vocabulário completo.

Notas de implantaçã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 borda como Jetson ou na CPU com resolução reduzida. O ajuste fino precisa de uma única GPU.
• Por padrão, o NMS não considera as classes. O YOLOE faz predições com agnostic_nms=True. Por padrão, isso suprime caixas sobrepostas com pontuação menor entre classes diferentes, em vez de apenas dentro da mesma classe, evitando duplicatas quando um objeto corresponde a várias categorias. Com nms=False, o YOLOE-26 não aplica supressão por IoU; o modo independente de classe mantém apenas a melhor classe por âncora, em vez de permitir que uma âncora emita vários rótulos de classe. Passe agnostic_nms=False para substituir esse comportamento.
• Processamento em lote. A inferência em lote funciona diretamente, e os prompts visuais podem ser diferentes para cada imagem na mesma chamada.

Treinar os modelos oficiais do zero#

A maioria das pessoas não precisa fazer isso. Esse processo reproduz os checkpoints de vocabulário aberto publicados a partir do Objects365, GQA e Flickr30k — cerca de 1.4 M de amostras de treinamento em 8× RTX 4090 — e não tem relação com o ajuste fino nos seus próprios dados, abordado acima em Uso do treinamento.

O treinamento precisa de anotações de segmentos. Você pode baixar os arquivos processados abaixo ou gerar os seus com o script fornecido pela equipe oficial, baseado no SAM 2.1. A validação usa o LVIS minival.

O modelo com prompt de texto é treinado primeiro, e os outros dois modos de prompting 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,  # ou o caminho para um arquivo YAML com a mesma estrutura
    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 partem desse modelo treinado com prompt de texto e atualizam um módulo cada. YOLOESegVPTrainer é a receita de prompt visual e YOLOEPEFreeTrainer é a receita sem prompt, mas nenhuma das classes congela nada por si só: o treinamento seletivo vem da lista freeze que você passa junto, que inclui todos os filhos da cabeça, exceto savpe (ou todas as torres de classificação), e a execução sem prompt também precisa de single_cls=True. O repositório upstream do YOLOE contém as receitas completas para os modelos da escala v8.

Uma execução sem prompt concluída é reparametrizada em um checkpoint que apresenta seus nomes sem prompt durante a inferência, usando get_vocab e set_vocab:

from ultralytics import YOLOE

# Pesos gravados pela execução sem prompt e pela execução com prompt de texto a partir da qual ela começou. Cada
# nova execução cria um diretório (train-2, train-3, ...), então use os caminhos exibidos pelas execuções.
model = YOLOE("runs/segment/train-2/weights/best.pt")  # execução sem prompt, a cabeça já está fundida
text_model = YOLOE("runs/segment/train/weights/best.pt")  # execução com prompt de texto, a cabeça ainda não está fundida

names = list(YOLOE("yoloe-26l-seg-pf.pt").model.names.values())  # o vocabulário de 4.585 nomes ou sua própria lista
vocab = text_model.get_vocab(names)

model.set_vocab(vocab, names)
model.save("yoloe-26l-seg-pf-custom.pt")  # nunca sobrescreva o checkpoint publicado

get_vocab retorna o ramo selecionado pela flag end2end do modelo, e set_vocab reparametriza esse ramo. Já os arquivos YOLOE-26 publicados trazem um vocabulário por ramo, o que permite que nms continue selecionando entre eles; reproduza esse comportamento obtendo o segundo vocabulário de outra cópia do modelo com prompt de texto. YOLOE-11 e YOLOE-v8 têm um único ramo, então usam a chamada acima sem alterações.

one2one_model = YOLOE("runs/segment/train/weights/best.pt")  # get_vocab funde a cabeça que lê, então carregue uma segunda cópia
one2one_model.model.end2end = True  # leia o ramo sem NMS

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

Citações e agradecimentos#

Se o YOLOE contribuiu para sua pesquisa ou projeto, cite o artigo original de Ao Wang, Lihao Liu, Hui Chen, Zijia Lin, Jungong Han e Guiguang Ding, da Universidade 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 saber mais, o artigo original do YOLOE está disponível no arXiv. O código-fonte do projeto e recursos adicionais podem ser acessados pelo repositório no GitHub.

Perguntas frequentes#