YOLOE: обнаружение и сегментация с открытым словарём в реальном времени#

Ultralytics YOLOE (Real-Time Seeing Anything) — модель обнаружения объектов с открытым словарём и сегментации экземпляров: вместо списка классов, зафиксированного при обучении, она принимает нужные тебе категории во время инференса в виде текстового запроса, визуального примера или встроенного словаря из 4 585 названий. Модель построена на архитектурах Ultralytics YOLO — YOLOv8, YOLO11 и YOLO26 — и создана под влиянием YOLO-World. YOLOE обеспечивает точность zero-shot на уровне передовых решений при скорости, почти равной скорости YOLO с закрытым набором классов.

Быстрый старт#

Укажи нужные классы и запускай модель. YOLOE-26 возвращает рамки и маски сегментации экземпляров для категорий, на которых модель никогда не обучалась.

from ultralytics import YOLOE

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

# «Двухэтажный автобус» — это не класс COCO; YOLOE определяет его только по словам
model.set_classes(["double-decker bus", "person"])

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

При первом вызове set_classes() загружается текстовый энкодер; перед развёртыванием на машине без доступа к сети смотри раздел Установка и требования.

Выбор режима подсказок#

YOLOE поддерживает три режима подсказок. Выбор режима определяет, какую контрольную точку загружать и как будут выглядеть метки классов. Выбери строку, соответствующую тому, что ты можешь предоставить во время инференса.

Установка и требования#

YOLOE входит в основной пакет Ultralytics:

pip install -U ultralytics

Для текстовых подсказок дополнительно нужен текстовый энкодер. Он загружается при первом использовании, а не во время установки:

• При первом вызове set_classes() с GitHub устанавливается ultralytics/CLIP с помощью pip (он предоставляет токенизатор), а текстовый энкодер TorchScript загружается в текущую рабочую директорию. YOLOE-26 загружает mobileclip2_b.ts размером около 254 МБ; YOLOE-11 и YOLOE-v8 загружают mobileclip_blt.ts. Запусти загрузку один раз из директории, из которой будешь работать, или скопируй туда файл, иначе он будет загружен повторно.
• Для обоих шагов нужен доступ к сети, поэтому выполни один прогноз с подсказкой до развёртывания на компьютере без подключения к сети.
• Для визуальных подсказок и контрольных точек без подсказок текстовый энкодер не нужен.

Для контрольных точек YOLOE-26 требуется ultralytics версии 8.4.0 или новее; семейства YOLOE-11 и YOLOE-v8 доступны в более ранних выпусках. Один прогноз с текстовой подсказкой проверяет весь процесс — загрузку контрольной точки, установку CLIP, текстовый энкодер и инференс:

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

Чтобы полностью отказаться от загрузки текстового энкодера во время инференса, один раз встрой подсказки в веса и используй их повторно — смотри раздел Повторное использование эмбеддингов подсказок.

Обзор архитектуры#

YOLOE сохраняет стандартную структуру YOLO — свёрточный бэкбон для извлечения признаков, шейный модуль для многоуровневого объединения и безанкорную разделённую голову, предсказывающую классы и рамки, — и добавляет три модуля, по одному для каждого режима подсказок:

• Перепараметризуемое выравнивание регионов и текста (RepRTA) уточняет текстовые эмбеддинги из CLIP с помощью небольшой вспомогательной сети. Эта сеть запускается один раз при каждом вызове set_classes() и удаляется при экспорте, поэтому не создаёт затрат на каждый кадр. При каждом прямом проходе выполняется сравнение сохранённых эмбеддингов подсказок с признаками регионов; о затратах при большом наборе подсказок смотри раздел Ограничения.
• Кодировщик визуальных подсказок с семантической активацией (SAVPE) кодирует семантические и активационные признаки из примерной рамки, настраивая модель на объекты, похожие на этот пример. Это режим one-shot для целей, которые сложно назвать, например логотипа или конкретной детали.
• Контрастное сопоставление регионов и подсказок с отложенной обработкой (LRPC) сопоставляет эмбеддинги регионов со встроенным словарём из 4 585 названий, поэтому контрольные точки без подсказок распознают объекты без внешних подсказок и текстового энкодера.

Сегментация экземпляров выполняется с помощью ветви масок в голове обнаружения, как в YOLOv8-Seg, поэтому каждый прогноз содержит маску в results[0].masks. После экспорта модули для открытого мира перепараметризуются в стандартную голову YOLO, и экспортированный файл работает в обычном режиме обнаружения и сегментации.

Доступные модели#

Каждая контрольная точка ниже — это модель сегментации экземпляров, поддерживающая val, predict, export и track. Загружай файл *-seg.pt для текстовых или визуальных подсказок, а файл *-seg-pf.pt — для инференса без подсказок; они не взаимозаменяемы. Подробнее смотри раздел Выбор режима подсказок. Только файлы *-seg.pt поддерживают train; контрольную точку без подсказок получают из обученной модели с текстовыми подсказками. Подробнее смотри раздел Обучение официальных моделей с нуля.

Производительность YOLOE на LVIS#

Результаты zero-shot на LVIS minival при размере 640 пикселей, из статьи Ultralytics YOLO26.

Текстовые и визуальные подсказки#

В каждой ячейке точности и числа параметров указаны значения для текстовой подсказки / визуальной подсказки; FLOPs приведены один раз. Число параметров и FLOPs относятся к конфигурации обнаружения, оцениваемой в статье. Точность — это показатель Non-E2E из статьи, единственный протокол, по которому приведены результаты для всех сравниваемых моделей; голова YOLOE-26 в режиме end-to-end уступает ему не более чем на 1,1 AP при текстовых подсказках и на 2,6 AP при визуальных подсказках.

Без подсказок#

Контрольные точки без подсказок выдают результат на основе встроенного словаря, не требуя подсказок. В каждой ячейке точности указаны значения end-to-end / Non-E2E — два протокола, по которым в статье оценивается YOLOE-26; на странице YOLO26 приведён столбец Non-E2E.

При текстовых и визуальных запросах модели YOLOE-26 превосходят соответствующие модели YOLOE-11 и YOLOE-v8 на каждом совпадающем масштабе по mAP_50-95, при этом у них меньше параметров и FLOPs, чем у линейки v8. На том же сплите в статье приводятся показатели YOLO-Worldv2: 24.4 (S), 32.4 (M) и 35.5 (L), а также детекторов на основе трансформеров GLIP-T (26.0), GDINO-T (27.4) и DetCLIP-T (34.4); у каждого из них от 155 до 232 млн параметров. В оригинальной статье о YOLOE приводятся ещё два результата для представленных в ней моделей масштаба v8. На LVIS YOLOE-v8s превосходит YOLO-Worldv2-S на 3.5 AP, затрачивая на обучение втрое меньше времени и работая на инференсе в 1.4 раза быстрее. При переносе на COCO YOLOE-v8l превосходит YOLOv8-L с закрытым набором классов на 0.6 box AP и 0.4 mask AP, затрачивая на обучение почти в 4 раза меньше времени.

Примеры использования#

Все примеры YOLOE ниже запускаются через Python API. Предсказание по текстовым запросам, валидация, экспорт, трекинг и обычное обучение также доступны через CLI; в рецептах дообучения и визуальном промптинге класс тренера или предиктора передаётся аргументом, что поддерживает только Python API.

Использование для обучения#

Дообучи любой выпущенный чекпойнт *-seg.pt на собственном YOLO-датасете. В основном процесс соответствует стандартной процедуре обучения YOLO; различие — в том, какой тренер ты передаёшь. YOLOEPESegTrainer объединяет названия твоих классов с головой и затем выполняет дообучение — именно это нужно для собственных меток. Тренер по умолчанию не обучается на твоих названиях классов.

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,  # <- Важно: тренер для дообучения, а не тренер по умолчанию
)

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)

Использование для предсказаний#

Вызов с текстовым запросом показан в разделе Быстрый старт. Для двух остальных режимов нужен дополнительный аргумент:

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]]),  # человек, очки
    "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",  # Целевое изображение
    refer_image="ultralytics/assets/bus.jpg",  # Где находятся примеры рамок
    visual_prompts=visual_prompts,
    predictor=YOLOEVPSegPredictor,
)
results[0].show()

# refer_image также задаёт классы на постоянной основе, поэтому в последующих вызовах запросы не нужны
results = model("ultralytics/assets/bus.jpg")
model.export(format="onnx")  # И при экспорте они сохраняются

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-тензор в диапазоне [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: человек, очки
        np.array([[150, 200, 1150, 700]]),  # zidane.jpg: человек
    ],
    "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()

Использование для валидации#

Валидация выполняется так же, как для любой другой модели, на датасете сегментации:

from ultralytics import YOLOE

model = YOLOE("yoloe-26l-seg.pt")  # или yoloe-26s/m-seg.pt для моделей других размеров

metrics = model.val(data="coco128-seg.yaml")

Другие режимы запросов поддерживаются двумя вариантами того же вызова:

• Визуальные запросы — model.val(data="coco128-seg.yaml", load_vp=True) извлекает визуальное встраивание для каждой категории непосредственно из датасета. Добавь refer_data="coco.yaml", чтобы взять встраивания из другого датасета, который должен содержать точно те же категории.
• Без запросов — загрузи чекпойнт *-seg-pf.pt и передай single_cls=True.

Использование при экспорте#

Встраивания запросов можно сохранить один раз и повторно использовать при создании статических экспортированных моделей, например ONNX, OpenVINO, TensorRT, CoreML, LiteRT и RKNN. Перед экспортом профиль NPZ загружается в исходную модель PyTorch; он не является дополнительным входом во время выполнения, и экспортированной модели файл NPZ не нужен.

from ultralytics import YOLOE

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

# Профиль привязан к исходному чекпойнту и подходит для повторного использования при последующих экспортах.
model = YOLOE("yoloe-26n-seg.pt")
model.load_prompt_embeddings("person-bus.npz")
model.export(format="onnx")

Тот же профиль запросов можно использовать и для настройки модели только для детекции, созданной на основе соответствующей архитектуры YOLOE. Это убирает ветвь масок, сохраняя заданные запросами классы:

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)

Отслеживание объектов#

Классы, заданные запросами, без изменений переходят в трекинг, поэтому ты можешь отслеживать объекты, на которых трекер не обучался:

from ultralytics import YOLOE

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

# persist=True сохраняет идентификаторы треков неизменными между кадрами
for result in model.track("path/to/video.mp4", stream=True, persist=True):
    print(result.boxes.id)

Сравнение YOLOE с другими моделями#

YOLOE занимает промежуточное положение между детектором с закрытым набором классов и ресурсоёмкой моделью с открытым словарём. Чтобы понять, подходит ли тебе YOLOE, сравни его по трём пунктам:

• В сравнении с YOLO с закрытым набором классов. После задания запросов YOLOE выполняет предсказания обычным способом для детекции и сегментации, а экспортируется так же, как любая другая модель. Главное преимущество — возможность менять список классов во время инференса без повторного обучения; недостаток — точность в режиме zero-shot значительно ниже, чем у модели, обученной на твоих классах.
• В сравнении с предыдущими семействами YOLOE. YOLOE-26 наследует от YOLO26 сквозную голову без NMS, охватывает пять масштабов (n/s/m/l/x) вместо трёх у предыдущих моделей (s/m/l) и лидирует на каждом совпадающем масштабе в разделе Производительность.
• В сравнении с детекторами с открытым словарём на основе трансформеров. GLIP и OWL-ViT выполняют инференс с помощью визуально-языкового трансформера. YOLOE кодирует запросы один раз, а затем сравнивает их с признаками регионов внутри свёрточной головы.

Ближайшие альтернативы принимают текстовый запрос, но маски возвращают только YOLOE и SAM 3, и каждая из трёх моделей отвечает на свой вопрос:

Переходишь с YOLO-World? API устроен так же: замени YOLOWorld на YOLOE, загрузи чекпойнт *-seg.pt и оставь вызов set_classes() без изменений. Ты получишь маски и визуальные запросы; примечание об экспорте и фиксированных классах относится к обеим моделям.

Сценарии использования и области применения#

Детекция с открытым словарём позволяет не переобучать модель для каждого класса. Это особенно важно, когда целевой список заранее неизвестен:

• Детекция в открытом мире — робототехника и системы безопасности, которые сталкиваются с объектами, не учтёнными при обучении.
• Однократная детекция по примеру — визуальные запросы позволяют находить конкретную деталь, логотип или дефект по одной эталонной рамке; это полезно для промышленного контроля.
• Каталогизация длинного хвоста — встроенный словарь из 4 585 названий достаточно широк для мониторинга биоразнообразия и инвентаризации розничных товаров.
• Подготовка датасета — предварительно размечай изображения рамками и масками перед проверкой человеком, а затем обучай на полученном датасете быструю модель с закрытым набором классов.
• Сегментация произвольных объектов — выпущенные чекпойнты *-seg.pt возвращают маску для каждого предсказания, поэтому медицинская визуализация и анализ спутниковых снимков получают точный попиксельный результат без второй модели.

Распространённый подход сочетает два режима: сначала один раз запусти модель без запросов, чтобы определить присутствующие объекты, а затем переключись на текстовые запросы для нужных категорий.

Ограничения#

YOLOE жертвует точностью ради возможности менять классы во время инференса. Вот что стоит знать, прежде чем использовать эту модель:

• Точность в режиме zero-shot значительно ниже, чем у модели, обученной на твоих классах. Показатели чекпойнтов с запросами на LVIS minival составляют примерно 22–40 mAP; обученная на твоих данных YOLO с закрытым набором классов покажет лучшие результаты для этих классов. Используй YOLOE для классов, на которых ты не можешь обучить модель, а не вместо обучения.
• Редкие категории — слабое место модели. В столбце mAP_r раздела Производительность приводится точность именно на редких классах LVIS. При текстовых запросах во всех строках она ниже, чем для распространённых и частых классов. Если твои целевые объекты необычны, ориентируйся на этот показатель, а не на общий mAP.
• Запрос описывает внешний вид, а не отношения между объектами. Детекция сравнивает признаки регионов с встраиванием запроса, поэтому запросы, зависящие от состояния, контекста или сравнения — «повреждённый», «крайний слева», «тот, которого несут», — не дают надёжных признаков для сопоставления. Предпочитай формулировки, близкие к обычным названиям категорий.
• Большие наборы запросов увеличивают задержку. Встраивания запросов вычисляются один раз, но при каждом прямом проходе сравниваются с признаками регионов. При измерениях на CPU с yoloe-26s-seg.pt длительность прямого прохода увеличивается примерно на 19% при переходе от 80 к 1 203 классам и примерно на 89% для полного словаря из 4 585 названий. Указанное значение FLOPs совсем не меняется, поскольку сходство регионов с текстом не учитывается, поэтому профиль не предупредит тебя об этом.
• До задания запросов названия классов — лишь заполнители. Свежезагруженный чекпойнт *-seg.pt возвращает nc=80 с числовыми названиями ("0", "1", …), поэтому перед чтением меток вызови set_classes(). В чекпойнтах без запросов уже заполнен весь словарь.

Примечания по развёртыванию#

• Оборудование. Для инференса нужна GPU NVIDIA с 4–8 ГБ VRAM; модели масштабов n и s работают на периферийных GPU, например Jetson, или на CPU при уменьшенном разрешении. Для дообучения нужна одна GPU.
• По умолчанию NMS не зависит от класса. YOLOE выполняет предсказания с agnostic_nms=True. По умолчанию нижние по оценке перекрывающиеся рамки подавляются и между разными классами, а не только внутри одного класса. Это предотвращает дублирование, когда одному объекту соответствуют несколько категорий. При nms=False YOLOE-26 не применяет подавление по IoU; в режиме без учёта классов для каждого якоря сохраняется только класс с наилучшей оценкой, вместо того чтобы позволить одному якорю выдавать метки нескольких классов. Передай agnostic_nms=False, чтобы изменить это поведение.
• Пакетная обработка. Пакетный инференс работает напрямую, а визуальные запросы для каждого изображения в одном вызове могут различаться.

Обучение официальных моделей с нуля#

Большинству читателей это не понадобится. Здесь воспроизводятся опубликованные чекпойнты с открытым словарём на основе Objects365, GQA и Flickr30k — около 1,4 млн обучающих примеров на 8× RTX 4090. Это не связано с дообучением на собственных данных, которое описано выше в разделе Обучение.

Для обучения нужны сегментные аннотации. Скачай обработанные файлы ниже или создай собственные с помощью скрипта официальной команды, работающего на базе SAM 2.1. Для валидации используется LVIS minival.

Сначала обучается модель с текстовыми запросами, а два остальных режима запросов получаются её доработкой:

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,  # или путь к YAML-файлу с той же структурой
    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",
)

Контрольные точки для визуальных подсказок и работы без подсказок создаются на основе обученной модели с текстовыми подсказками, и в каждой обновляется один модуль. YOLOESegVPTrainer — рецепт для визуальных подсказок, а YOLOEPEFreeTrainer — для работы без подсказок, но сами по себе эти классы ничего не замораживают: выборочное обучение обеспечивается списком freeze, который ты передаёшь вместе с классом. В нём перечислены все дочерние модули головы, кроме savpe (соответственно, все классификационные башни), а для запуска без подсказок дополнительно нужен single_cls=True. В исходном репозитории YOLOE приведены полные рецепты для моделей масштаба v8.

После завершения запуска без подсказок модель повторно параметризуется в контрольную точку, которая при инференсе сообщает названия классов без подсказок, с помощью get_vocab и set_vocab:

from ultralytics import YOLOE

# Веса, записанные запуском без подсказок и запуском с текстовыми подсказками, на основе которого он был создан. Каждый
# повторный запуск создаёт новую директорию (train-2, train-3, ...), поэтому используй пути, выведенные запусками.
model = YOLOE("runs/segment/train-2/weights/best.pt")  # в запуске без подсказок голова уже объединена
text_model = YOLOE("runs/segment/train/weights/best.pt")  # в запуске с текстовыми подсказками голова ещё не объединена

names = list(YOLOE("yoloe-26l-seg-pf.pt").model.names.values())  # словарь из 4,585 названий или свой список
vocab = text_model.get_vocab(names)

model.set_vocab(vocab, names)
model.save("yoloe-26l-seg-pf-custom.pt")  # не перезаписывай выпущенную контрольную точку

get_vocab возвращает ветвь, выбранную флагом модели end2end, а set_vocab повторно параметризует эту ветвь. В выпущенных файлах YOLOE-26 для каждой ветви используется отдельный словарь — именно это позволяет nms выбирать между ними. Чтобы воспроизвести такое поведение, возьми второй словарь из другой копии модели с текстовыми подсказками. У YOLOE-11 и YOLOE-v8 одна ветвь, поэтому для них вызов выше остаётся без изменений.

one2one_model = YOLOE("runs/segment/train/weights/best.pt")  # get_vocab объединяет голову, из которой читает данные, поэтому загрузи вторую копию
one2one_model.model.end2end = True  # прочитай ветвь без NMS

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

Цитирование и благодарности#

Если YOLOE помогла твоему исследованию или проекту, процитируй оригинальную статью Ao Wang, Lihao Liu, Hui Chen, Zijia Lin, Jungong Han и Guiguang Ding из Университета Цинхуа:

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

Дополнительную информацию можно найти в оригинальной статье о YOLOE на arXiv. Исходный код проекта и другие материалы доступны в репозитории GitHub.

Часто задаваемые вопросы#