# EoMT-DINOv3

  

## Обзор

Семейство **EoMT-DINOv3** расширяет архитектуру [Encoder-only Mask Transformer](eomt) с использованием Vision Transformers, предварительно обученных с помощью [DINOv3](dinov3). Обновление обеспечивает более высокое качество сегментации на бенчмарках ADE20K и COCO, сохраняя при этом дизайн только с энкодером, который сделал EoMT привлекательным для приложений реального времени.

В отличие от моделей на базе DINOv2, варианты DINOv3 используют вращательные позиционные эмбеддинги, необязательные блоки gated MLP и новейшие рецепты предобучения от Meta AI. Эти изменения обеспечивают измеримый прирост производительности в задачах семантической, инстантной и паноптической сегментации, что подчёркивается в [DINOv3 model zoo](https://github.com/tue-mps/eomt/blob/master/model_zoo/dinov3.md).

Исходная архитектура EoMT была представлена в статье *[Your ViT is Secretly an Image Segmentation Model](https://huggingface.co/papers/2503.19108)*, отмеченной как Highlight на CVPR 2025, авторами Tommie Kerssies, Niccolò Cavagnero, Alexander Hermans, Narges Norouzi, Giuseppe Averta, Bastian Leibe, Gijs Dubbelman и Daan de Geus. Обновление DINOv3 сохраняет тот же легкий сегментационный модуль и стратегию вывода на основе запросов, заменяя энкодер на чекпоинты DINOv3 ViT.

Советы:

* Конфигурация предоставляет параметры, специфичные для DINOv3, такие как `rope_theta` и `use_gated_mlp`. Крупные бэкбоны DINOv3, такие как `dinov3-vitg14`, ожидают `use_gated_mlp=True`.
* Модели DINOv3 могут работать с более широким диапазоном разрешений благодаря вращательным позиционным эмбеддингам. Процессор изображений по-прежнему использует квадратные вырезы по умолчанию, но пользовательские размеры можно задать через `AutoImageProcessor`.
* Предобученные контрольные точки, размещённые лабораторией Mobile Perception Systems Lab (TU/e), предоставляют дельта-веса, которые необходимо объединить с исходными бэкбоунами DINOv3. Утилиты конвертации в [официальном репозитории](https://github.com/tue-mps/eomt) подробно описывают этот рабочий процесс.

Эта модель была предоставлена пользователем [nielsr](https://huggingface.co/nielsr). Исходный код можно найти [здесь](https://github.com/tue-mps/eomt).

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

Ниже приведён минимальный пример, демонстрирующий, как выполнить паноптическую сегментацию с моделью EoMT, использующей DINOv3 в качестве основы. Тот же самый процессор изображений можно переиспользовать для семантической или инстантной сегментации, просто заменив контрольную точку.

```python
import requests
import torch
from PIL import Image

from transformers import AutoImageProcessor, AutoModelForUniversalSegmentation

model_id = "tue-mps/eomt-dinov3-coco-panoptic-base-640"
processor = AutoImageProcessor.from_pretrained(model_id)
model = AutoModelForUniversalSegmentation.from_pretrained(model_id, device_map="auto")

image = Image.open(requests.get("http://images.cocodataset.org/val2017/000000039769.jpg", stream=True).raw)

inputs = processor(images=image, return_tensors="pt").to(model.device)

with torch.inference_mode():
    outputs = model(**inputs)

segmentation = processor.post_process_panoptic_segmentation(outputs, target_sizes=[image.size[::-1]])[0]
list(segmentation.keys())
['segmentation', 'segments_info']
```

## EomtDinov3Config[[transformers.EomtDinov3Config]]

#### transformers.EomtDinov3Config[[transformers.EomtDinov3Config]]

```python
transformers.EomtDinov3Config(transformers_version: str | None = None, architectures: list[str] | None = None, output_hidden_states: bool | None = False, return_dict: bool | None = True, dtype: str | torch.dtype | None = None, chunk_size_feed_forward: int = 0, is_encoder_decoder: bool = False, id2label: dict[int, str] | dict[str, str] | None = None, label2id: dict[str, int] | dict[str, str] | None = None, problem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = None, hidden_size: int = 1024, num_hidden_layers: int = 24, num_attention_heads: int = 16, hidden_act: str = 'gelu', hidden_dropout_prob: float | int = 0.0, initializer_range: float = 0.02, layer_norm_eps: float = 1e-06, image_size: int | list[int] | tuple[int, int] = 640, patch_size: int | list[int] | tuple[int, int] = 16, num_channels: int = 3, layerscale_value: float = 1.0, drop_path_rate: float | int = 0.0, num_upscale_blocks: int = 2, attention_dropout: float | int = 0.0, num_blocks: int = 4, no_object_weight: float = 0.1, class_weight: float = 2.0, mask_weight: float = 5.0, dice_weight: float = 5.0, train_num_points: int = 12544, oversample_ratio: float = 3.0, importance_sample_ratio: float = 0.75, num_queries: int = 200, num_register_tokens: int = 4, intermediate_size: int = 4096, rope_parameters: transformers.modeling_rope_utils.RopeParameters | dict | None = None, query_bias: bool = True, key_bias: bool = False, value_bias: bool = True, proj_bias: bool = True, mlp_bias: bool = True, use_gated_mlp: bool = False, pos_embed_shift: float | None = None, pos_embed_jitter: float | None = None, pos_embed_rescale: float | None = 2.0)
```

[Источник](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/eomt_dinov3/configuration_eomt_dinov3.py#L29)

**Параметры:**

hidden_size (`int`, *необязательный*, по умолчанию `1024`) : Размерность скрытых представлений.

num_hidden_layers (`int`, *необязательный*, по умолчанию `24`) : Количество скрытых слоев в декодере Transformer.

num_attention_heads (`int`, *необязательный*, по умолчанию `16`) : Количество головок внимания для каждого слоя внимания в декодере Transformer.

hidden_act (`str`, *необязательный*, по умолчанию `gelu`) : Нелинейная функция активации (функция или строка) в декодере. Например, `"gelu"`, `"relu"`, `"silu"` и т. д.

hidden_dropout_prob (`Union[float, int]`, *необязательный*, по умолчанию `0.0`) : Вероятность dropout для всех полносвязных слоёв в эмбеддингах, энкодере и пулере.

initializer_range (`float`, *необязательный*, по умолчанию `0.02`) : Стандартное отклонение truncated_normal_initializer для инициализации всех матриц весов.

layer_norm_eps (`float`, *необязательный*, по умолчанию `1e-06`) : Значение epsilon, используемое слоями нормализации.

image_size (`Union[int, list[int], tuple[int, int]]`, *необязательный*, по умолчанию `640`) : Размер (разрешение) каждого изображения.

patch_size (`Union[int, list[int], tuple[int, int]]`, *необязательный*, по умолчанию `16`) : Размер (разрешение) каждого патча.

num_channels (`int`, *необязательный*, по умолчанию `3`) : Количество входных каналов.

layerscale_value (`float`, *необязательный*, по умолчанию 1.0) : Начальное значение для параметра LayerScale.

drop_path_rate (`Union[float, int]`, *необязательный*, по умолчанию `0.0`) : Коэффициент drop path для слияния патчей.

num_upscale_blocks (`int`, *optional*, по умолчанию 2) : Количество блоков апсемплинга, используемых в декодере или сегментационной голове.

attention_dropout (`Union[float, int]`, *необязательный*, по умолчанию `0.0`) : Коэффициент dropout для вероятностей внимания.

num_blocks (`int`, *необязательный*, по умолчанию 4) : Количество блоков признаков или стадий в архитектуре.

no_object_weight (`float`, *необязательный*, по умолчанию 0.1) : Вес потерь для класса «нет объекта» в панорамной/инстанс-сегментации.

class_weight (`float`, *необязательный*, по умолчанию `2.0`) : Относительный вес ошибки классификации в стоимости венгерского сопоставления.

mask_weight (`float`, *необязательный*, по умолчанию `5.0`) : Относительный вес фокальной функции потерь в функции потерь паноптической сегментации.

dice_weight (`float`, *необязательный*, по умолчанию `5.0`) : Относительный вес функции потерь dice в функции потерь паноптической сегментации.

train_num_points (`int`, *optional*, по умолчанию 12544) : Количество точек для выборки при вычислении потерь маски во время обучения.

oversample_ratio (`float`, *optional*, по умолчанию 3.0) : Коэффициент оверсэмплинга, используемый при выборке точек для обучения маски.

importance_sample_ratio (`float`, *optional*, по умолчанию 0.75) : Доля точек, отбираемых на основе важности во время обучения.

num_queries (`int`, *optional*, по умолчанию 200) : Количество объектных запросов в Transformer.

num_register_tokens (`int`, *optional*, по умолчанию 4) : Количество обучаемых регистрационных токенов, добавляемых на вход трансформера.

intermediate_size (`int`, *необязательный*, по умолчанию `4096`) : Размерность представлений MLP.

rope_parameters (`Union[~modeling_rope_utils.RopeParameters, dict]`, *optional*) : Словарь, содержащий параметры конфигурации для вложений RoPE. Словарь должен содержать значение для `rope_theta` и, при необходимости, параметры, используемые для масштабирования, если вы хотите использовать RoPE с более длинными `max_position_embeddings`.

query_bias (`bool`, *необязательный*, по умолчанию `True`) : Использовать ли смещение в проекции запроса.

key_bias (`bool`, *необязательный*, по умолчанию `False`) : Использовать ли смещение в проекции ключей.

value_bias (`bool`, *необязательный*, по умолчанию `True`) : Использовать ли смещение в проекции значений.

proj_bias (`bool`, *необязательный*, по умолчанию `True`) : Использовать ли смещение в выходной проекции.

mlp_bias (`bool`, *необязательный*, по умолчанию `True`) : Использовать ли смещение (bias) в слоях up_proj, down_proj и gate_proj в слоях MLP.

use_gated_mlp (`bool`, *необязательный*, по умолчанию `False`) : Использовать ли слои gated MLP.

pos_embed_shift (`float`, *необязательный*) : Сдвиг для позиционных эмбеддингов.

pos_embed_jitter (`float`, *необязательный*) : Значение джиттера для позиционных эмбеддингов.

pos_embed_rescale (`float`, *необязательный*, по умолчанию 2.0) : Коэффициент масштабирования для позиционных эмбеддингов.

Это класс конфигурации для хранения настроек модели Eomt Dinov3Model. Он используется для создания модели Eomt Dinov3 в соответствии с указанными аргументами, определяя архитектуру модели. Создание конфигурации с параметрами по умолчанию даст конфигурацию, аналогичную конфигурации [tue-mps/coco_panoptic_eomt_large_640_dinov3](https://huggingface.co/tue-mps/coco_panoptic_eomt_large_640_dinov3)

Объекты конфигурации наследуются от [PreTrainedConfig](/docs/transformers/v5.23.0/ru/main_classes/configuration#transformers.PreTrainedConfig) и могут использоваться для управления выводами модели. Подробнее см. в документации [PreTrainedConfig](/docs/transformers/v5.23.0/ru/main_classes/configuration#transformers.PreTrainedConfig).

## EomtDinov3PreTrainedModel[[transformers.EomtDinov3PreTrainedModel]]

#### transformers.EomtDinov3PreTrainedModel[[transformers.EomtDinov3PreTrainedModel]]

```python
transformers.EomtDinov3PreTrainedModel(config: PreTrainedConfig, *inputs, **kwargs)
```

[Источник](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/eomt_dinov3/modeling_eomt_dinov3.py#L1061)

**Параметры:**

config ([PreTrainedConfig](/docs/transformers/v5.23.0/ru/main_classes/configuration#transformers.PreTrainedConfig)) : Класс конфигурации модели со всеми параметрами модели. Инициализация с файлом конфигурации не загружает веса, связанные с моделью, только конфигурацию. Используйте метод [from_pretrained()](/docs/transformers/v5.23.0/ru/main_classes/model#transformers.PreTrainedModel.from_pretrained) для загрузки весов модели.

Эта модель наследуется от [PreTrainedModel](/docs/transformers/v5.23.0/ru/main_classes/model#transformers.PreTrainedModel). Общие методы, которые библиотека реализует для всех своих моделей (например, загрузка или сохранение, изменение размера входных эмбеддингов, обрезка головок и т. д.), описаны в документации родительского класса.

Эта модель также является подклассом [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) в PyTorch. Используйте её как обычный модуль PyTorch и обращайтесь к документации PyTorch по всем вопросам, связанным с общим использованием и поведением.

#### forward[[transformers.EomtDinov3PreTrainedModel.forward]]

```python
forward(*args, **kwargs)
```

Мок-значение для пути с точками (например, `torch.float32`): цепочки доступа к атрибутам и вызовы работают как пропускные декораторы, `repr` возвращает путь с точками, а использование в качестве базового класса подменяет его обычным базовым классом `type` (PEP 560 `__mro_entries__`), благодаря чему реальные дочерние классы сохраняют обычный метакласс, а `inspect.signature` читает их реальный `__init__`, а не мок.

## EomtDinov3ForUniversalSegmentation[[transformers.EomtDinov3ForUniversalSegmentation]]

#### transformers.EomtDinov3ForUniversalSegmentation[[transformers.EomtDinov3ForUniversalSegmentation]]

```python
transformers.EomtDinov3ForUniversalSegmentation(config: EomtDinov3Config)
```

[Источник](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/eomt_dinov3/modeling_eomt_dinov3.py#L1167)

**Параметры:**

config ([EomtDinov3Config](/docs/transformers/v5.23.0/ru/model_doc/eomt_dinov3#transformers.EomtDinov3Config)) : Класс конфигурации модели со всеми параметрами модели. Инициализация с файлом конфигурации не загружает веса, связанные с моделью, только конфигурацию. Используйте метод [from_pretrained()](/docs/transformers/v5.23.0/ru/main_classes/model#transformers.PreTrainedModel.from_pretrained) для загрузки весов модели.

Модель EoMT-DINOv3 с головой сверху для сегментации объектов/семантической/паноптической сегментации.

Эта модель наследуется от [PreTrainedModel](/docs/transformers/v5.23.0/ru/main_classes/model#transformers.PreTrainedModel). Общие методы, которые библиотека реализует для всех своих моделей (например, загрузка или сохранение, изменение размера входных эмбеддингов, обрезка головок и т. д.), описаны в документации родительского класса.

Эта модель также является подклассом [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) в PyTorch. Используйте её как обычный модуль PyTorch и обращайтесь к документации PyTorch по всем вопросам, связанным с общим использованием и поведением.

#### forward[[transformers.EomtDinov3ForUniversalSegmentation.forward]]

```python
forward(pixel_values: Tensor, mask_labels: list[torch.Tensor] | None = None, class_labels: list[torch.Tensor] | None = None, patch_offsets: list[torch.Tensor] | None = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[Источник](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/eomt_dinov3/modeling_eomt_dinov3.py#L1231)

**Параметры:**

pixel_values (`torch.Tensor` формы `(batch_size, num_channels, image_size, image_size)`) : Тензоры, соответствующие входным изображениям. Значения пикселей можно получить с помощью [EomtImageProcessor](/docs/transformers/v5.23.0/ru/model_doc/eomt#transformers.EomtImageProcessor). Подробности см. в [EomtImageProcessor.__call__()](/docs/transformers/v5.23.0/ru/model_doc/molmo2#transformers.Molmo2ImageProcessor.__call__) (`processor_class` использует [EomtImageProcessor](/docs/transformers/v5.23.0/ru/model_doc/eomt#transformers.EomtImageProcessor) для обработки изображений).

mask_labels (`list[torch.Tensor]`, *необязательный*) : список меток маски формы `(num_labels, height, width)` для передачи в модель

class_labels (`list[torch.LongTensor]`, *необязательный*) : список целевых классов меток формы `(num_labels, height, width)`, передаваемых в модель. Они идентифицируют метки `mask_labels`, например, метку `mask_labels[i][j]`, если `class_labels[i][j]`.

patch_offsets (`list[torch.Tensor]`, *необязательный*) : список кортежей, указывающих индекс изображения и начальные и конечные позиции патчей для семантической сегментации.

**Возвращает:** `EomtDinov3ForUniversalSegmentationOutput` или `tuple(torch.Tensor)`

Объект `EomtDinov3ForUniversalSegmentationOutput` или кортеж `torch.Tensor` (если передано `return_dict=False` или если `config.return_dict=False`), содержащий различные элементы в зависимости от конфигурации ([EomtDinov3Config](/docs/transformers/v5.23.0/ru/model_doc/eomt_dinov3#transformers.EomtDinov3Config)) и входных данных.

Метод forward класса [EomtDinov3ForUniversalSegmentation](/docs/transformers/v5.23.0/ru/model_doc/eomt_dinov3#transformers.EomtDinov3ForUniversalSegmentation) переопределяет специальный метод `__call__`.

Хотя рецепт для прямого прохода должен быть определён внутри этой функции, после этого следует вызывать экземпляр `Module`, а не эту функцию, поскольку первый выполняет шаги предварительной и постобработки, тогда как второй молча их игнорирует.

- **loss** (`torch.Tensor`, *optional*) -- Вычисленная величина потерь, возвращается при наличии меток.
- **class_queries_logits** (`torch.Tensor`, *optional*) — тензор формы `(batch_size, num_queries, num_labels + 1)`, представляющий предложенные классы для каждого запроса. Обратите внимание, что `+ 1` необходимо, так как мы учитываем нулевой класс.
- **masks_queries_logits** (`torch.Tensor`, *необязательный*) -- тензор формы `(batch_size, num_queries, height, width)`, представляющий предложенные маски для каждого запроса.
- **last_hidden_state** (`torch.Tensor` формы `(batch_size, num_channels, height, width)`) -- Состояния последнего скрытого слоя (финальная карта признаков) последнего слоя.
- **hidden_states** (`tuple(torch.Tensor)`, *необязательный*, возвращается при передаче `output_hidden_states=True` или при `config.output_hidden_states=True`) — Кортеж `torch.Tensor` (один для вывода эмбеддингов + один для вывода каждого этапа) формы `(batch_size, sequence_length, hidden_size)`. Скрытые состояния всех слоёв модели.
- **attentions** (`tuple(tuple(torch.Tensor))`, *optional*, возвращается, если передано `output_attentions=True` или если `config.output_attentions=True`) -- Кортеж `tuple(torch.Tensor)` (по одному для каждого слоя) формы `(batch_size, num_heads, sequence_length, sequence_length)`. Веса Self и Cross Attention из декодера трансформера.
- **patch_offsets** (`list[torch.Tensor]`, *необязательный*) -- список кортежей, указывающих индекс изображения и начальные и конечные позиции патчей для семантической сегментации.

