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

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

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

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

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

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

Выбор режима промптов#

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

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

YOLOE поставляется в составе основного пакета Ultralytics:

pip install -U ultralytics

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

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

Чекпоинты 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 — сверточный бэкбон (backbone) для извлечения признаков, нек (neck) для многомасштабного слияния и безакорную, разделенную голову (anchor-free, decoupled head), прогнозирующую классы и боксы, — и добавляет три модуля, по одному на каждый режим промптов:

• Репараметризуемое выравнивание регионов и текста (RepRTA) уточняет текстовые эмбеддинги из CLIP через небольшую вспомогательную сеть. Эта сеть запускается один раз за вызов set_classes() и сворачивается при экспорте, поэтому она ничего не стоит на один кадр. То, что действительно работает при каждом прямом проходе (forward pass) — это сравнение сохраненных эмбеддингов промптов с признаками регионов; см. раздел Ограничения, чтобы узнать, во сколько это обходится при большом наборе промптов.
• Энкодер визуальных промптов с активацией семантики (SAVPE) кодирует семантические признаки и признаки активации из примера бокса, настраивая модель на объекты, которые выглядят похоже. Это путь один-выстрел (one-shot) для целей, которые трудно назвать словами, таких как логотип или конкретная деталь.
• Ленивое сопоставление промптов по регионам (LRPC) сопоставляет эмбеддинги регионов со встроенным словарем на 4585 наименований, поэтому чекпоинты без промптов распознают объекты без внешнего промпта и без текстового энкодера.

Сегментация экземпляров обеспечивается веткой масок на голове детекции, как в 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 из статьи — единственному протоколу, который она сообщает для каждой модели в сравнении; голова end-to-end модели YOLOE-26 отстает от него не более чем на 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, оставаясь при этом ниже линии v8 по параметрам и FLOPs. На том же сплите в статье приводятся результаты для 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 получает прирост 0.6 box AP и 0.4 mask AP по сравнению с закрытой моделью YOLOv8-L при почти в 4 раза меньшем времени обучения.

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

Каждый пример YOLOE ниже запускается из Python API. Предсказание с текстовым промптом, валидация, экспорт, трекинг и простое обучение также работают из CLI; рецепты дообучения (fine-tuning) и визуальные промпты передают класс тренера или предиктора в качестве аргумента, что поддерживается только в 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,  # <- 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)

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

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

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

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

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

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

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

• Визуальные промпты — 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")

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

Тот же профиль промпта также может настраивать модель только для детекции, созданную на основе соответствующей архитектуры 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 keeps track IDs stable across frames
for result in model.track("path/to/video.mp4", stream=True, persist=True):
    print(result.boxes.id)

Сравнение с YOLOE#

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

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

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

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

Варианты использования и приложения#

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Завершенный прогон без промптов репараметризуется в чекпоинт, который сообщает свои имена без промпта при инференсе, используя get_vocab и 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

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

Если YOLOE внес вклад в твое исследование или проект, пожалуйста, процитируй оригинальную статью авторов: Ao Wang, Lihao Liu, Hui Chen, Zijia Lin, Jungong Han, and 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.

FAQ#