# DINOv2 с регистрами

## Обзор

Модель DINOv2 with Registers была предложена в статье [Vision Transformers Need Registers](https://huggingface.co/papers/2309.16588) авторами Timothée Darcet, Maxime Oquab, Julien Mairal, Piotr Bojanowski.

Модель [Vision Transformer](vit) (ViT) — это трансформер-энкодер (похожий на BERT), изначально предложенный для задачи контролируемой классификации изображений на ImageNet.

Далее были найдены способы, позволяющие ViT эффективно работать в задаче самообучаемого извлечения признаков изображений (то есть обучения осмысленным признакам, также называемым эмбеддингами) без использования каких-либо меток. Среди примеров работ в этой области — [DINOv2](dinov2) и [MAE](vit_mae).

Авторы DINOv2 заметили, что у ViT есть артефакты в картах внимания. Это связано с тем, что модель использует некоторые патчи изображения в качестве «регистров». Авторы предлагают решение: просто добавить несколько новых токенов (называемых «регистровыми» токенами), которые используются только во время предварительного обучения (а затем отбрасываются). В результате:

- без артефактов
- интерпретируемые карты внимания
- и улучшенными показателями производительности.

Аннотация из статьи следующая:

*Недавно трансформеры стали мощным инструментом для обучения визуальных представлений. В данной статье мы выявляем и описываем артефакты в картах признаков как в супервизированных, так и в самообучаемых сетях ViT. Эти артефакты соответствуют токенам с высокой нормой, которые появляются во время инференса преимущественно в фоновых областях изображений с низкой информативностью и используются для внутренних вычислений. Мы предлагаем простое, но эффективное решение, основанное на добавлении дополнительных токенов во входную последовательность Vision Transformer для выполнения этой роли. Мы показываем, что данное решение полностью устраняет эту проблему как для супервизированных, так и для самообучаемых моделей, устанавливает новый уровень качества для самообучаемых визуальных моделей на задачах плотного визуального предсказания, позволяет применять методы обнаружения объектов с более крупными моделями и, что наиболее важно, приводит к более гладким картам признаков и внимания для последующей визуальной обработки.*

<img src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/transformers/model_doc/dinov2_with_registers_visualization.png"
alt="drawing" width="600"/>

 Визуализация карт внимания различных моделей, обученных с регистрами и без них. Источник — оригинальная статья.

Советы:

- Использование DINOv2 с Registers идентично использованию DINOv2 без них, вы просто получите лучшую производительность.

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

## Dinov2WithRegistersConfig[[transformers.Dinov2WithRegistersConfig]]

#### transformers.Dinov2WithRegistersConfig[[transformers.Dinov2WithRegistersConfig]]

```python
transformers.Dinov2WithRegistersConfig(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 = 768, num_hidden_layers: int = 12, num_attention_heads: int = 12, mlp_ratio: int = 4, hidden_act: str = 'gelu', hidden_dropout_prob: float | int = 0.0, attention_probs_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] = 224, patch_size: int | list[int] | tuple[int, int] = 16, num_channels: int = 3, qkv_bias: bool = True, layerscale_value: float = 1.0, drop_path_rate: float | int = 0.0, use_swiglu_ffn: bool = False, num_register_tokens: int = 4, _out_features: list[str] | None = None, _out_indices: list[int] | None = None, apply_layernorm: bool = True, reshape_hidden_states: bool = True)
```

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

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

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

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

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

mlp_ratio (`int`, *optional*, по умолчанию `4`) : Соотношение скрытого размера MLP к размеру эмбеддинга.

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

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

attention_probs_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]]`, *необязательный*, по умолчанию `224`) : Размер (разрешение) каждого изображения.

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

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

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

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

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

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

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

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

reshape_hidden_states (`bool`, *необязательный*, по умолчанию `True`) : Указывает, следует ли преобразовать карты признаков в 4D-тензоры формы `(batch_size, hidden_size, height, width)`, если модель используется как backbone. Если `False`, карты признаков будут 3D-тензорами формы `(batch_size, seq_len, hidden_size)`.

This is the configuration class to store the configuration of a Dinov2WithRegistersModel. It is used to instantiate a Dinov2 With Registers model according to the specified arguments, defining the model architecture. Instantiating a configuration with the defaults will yield a similar configuration to that of the [facebook/dinov2-with-registers-base](https://huggingface.co/facebook/dinov2-with-registers-base)

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

Пример:

```python
>>> from transformers import Dinov2WithRegistersConfig, Dinov2WithRegistersModel

>>> # Initializing a Dinov2WithRegisters base style configuration
>>> configuration = Dinov2WithRegistersConfig()

>>> # Initializing a model (with random weights) from the base style configuration
>>> model = Dinov2WithRegistersModel(configuration)

>>> # Accessing the model configuration
>>> configuration = model.config
```

## Dinov2WithRegistersModel[[transformers.Dinov2WithRegistersModel]]

#### transformers.Dinov2WithRegistersModel[[transformers.Dinov2WithRegistersModel]]

```python
transformers.Dinov2WithRegistersModel(config: Dinov2WithRegistersConfig)
```

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

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

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

Модель Dinov2 With Registers, выводящая необработанные скрытые состояния без какого-либо специализированного слоя на выходе.

Эта модель наследуется от [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.Dinov2WithRegistersModel.forward]]

```python
forward(pixel_values: typing.Optional[torch.Tensor] = None, bool_masked_pos: typing.Optional[torch.Tensor] = None, attention_mask: typing.Optional[torch.Tensor] = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

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

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

pixel_values (`torch.Tensor` формы `(batch_size, num_channels, image_size, image_size)`, *необязательный*) : Тензоры, соответствующие входным изображениям. Значения пикселей можно получить с помощью `image_processor_class`. Подробности см. в `image_processor_class.__call__` (`processor_class` использует `image_processor_class` для обработки изображений).

bool_masked_pos (`torch.BoolTensor` формы `(batch_size, sequence_length)`) : Булевы позиции маски. Указывает, какие патчи замаскированы (1), а какие нет (0). Актуально только для предварительного обучения.

attention_mask (`torch.Tensor` формы `(batch_size, sequence_length)`, *необязательный*) : Маска для предотвращения применения внимания к индексам токенов отсечки. Значения маски выбираются из `[0, 1]`:  - 1 для токенов, которые **не замаскированы**, - 0 для токенов, которые **замаскированы**.  [Что такое маски внимания?](../glossary#attention-mask)

**Возвращает:** [BaseModelOutputWithPooling](/docs/transformers/v5.23.0/ru/main_classes/output#transformers.modeling_outputs.BaseModelOutputWithPooling) или `tuple(torch.Tensor)`

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

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

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

- **last_hidden_state** (`torch.Tensor` формы `(batch_size, sequence_length, hidden_size)`) -- Последовательность скрытых состояний на выходе последнего слоя модели.
- **pooler_output** (`torch.Tensor` формы `(batch_size, hidden_size)`) -- Скрытое состояние последнего слоя для первого токена последовательности (токен классификации) после дополнительной обработки слоями, используемыми для вспомогательной задачи предварительного обучения. Например, для моделей семейства BERT это возвращает токен классификации после обработки линейным слоем и функцией активации tanh. Веса линейного слоя обучаются по задаче предсказания следующего предложения (классификации) во время предварительного обучения.
- **hidden_states** (`tuple(torch.Tensor)`, *необязательный*, возвращается при передаче `output_hidden_states=True` или когда `config.output_hidden_states=True`) -- Кортеж `torch.Tensor` (один для вывода слоя встраиваний, если модель имеет слой встраиваний, + один для вывода каждого слоя) формы `(batch_size, sequence_length, hidden_size)`.

  Скрытые состояния модели на выходе каждого слоя, а также необязательные выходные значения начального слоя встраивания.
- **attentions** (`tuple(torch.Tensor)`, *необязательный*, возвращается при передаче `output_attentions=True` или при `config.output_attentions=True`) -- Кортеж `torch.Tensor` (по одному на каждый слой) формы `(batch_size, num_heads, sequence_length, sequence_length)`.

  Веса внимания после softmax в механизме внимания, используемые для вычисления взвешенного среднего в головах само-внимания.

Пример:

```python
```

## Dinov2WithRegistersForImageClassification[[transformers.Dinov2WithRegistersForImageClassification]]

#### transformers.Dinov2WithRegistersForImageClassification[[transformers.Dinov2WithRegistersForImageClassification]]

```python
transformers.Dinov2WithRegistersForImageClassification(config: Dinov2WithRegistersConfig)
```

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

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

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

Модель Dinov2WithRegisters — трансформер с головной частью для классификации изображений (линейный слой поверх финального скрытого состояния токена [CLS]), например, для ImageNet.

Эта модель наследуется от [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.Dinov2WithRegistersForImageClassification.forward]]

```python
forward(pixel_values: typing.Optional[torch.Tensor] = None, labels: typing.Optional[torch.Tensor] = None, attention_mask: typing.Optional[torch.Tensor] = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

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

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

pixel_values (`torch.Tensor` формы `(batch_size, num_channels, image_size, image_size)`, *необязательный*) : Тензоры, соответствующие входным изображениям. Значения пикселей можно получить с помощью `image_processor_class`. Подробности см. в `image_processor_class.__call__` (`processor_class` использует `image_processor_class` для обработки изображений).

labels (`torch.LongTensor` формы `(batch_size,)`, *необязательный*) : Метки для вычисления потерь классификации/регрессии изображений. Индексы должны находиться в диапазоне `[0, ..., config.num_labels - 1]`. Если `config.num_labels == 1`, вычисляется потеря регрессии (среднеквадратичная потеря), если `config.num_labels > 1`, вычисляется потеря классификации (кросс-энтропия).

attention_mask (`torch.Tensor` формы `(batch_size, sequence_length)`, *необязательный*) : Маска для предотвращения применения внимания к индексам токенов отсечки. Значения маски выбираются из `[0, 1]`:  - 1 для токенов, которые **не замаскированы**, - 0 для токенов, которые **замаскированы**.  [Что такое маски внимания?](../glossary#attention-mask)

**Возвращает:** [ImageClassifierOutput](/docs/transformers/v5.23.0/ru/main_classes/output#transformers.modeling_outputs.ImageClassifierOutput) или `tuple(torch.Tensor)`

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

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

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

- **loss** (`torch.Tensor` формы `(1,)`, *необязательный*, возвращается, если задан `labels`) -- Потери классификации (или регрессии, если config.num_labels==1).
- **logits** (`torch.Tensor` формы `(batch_size, config.num_labels)`) — Оценки классификации (или регрессии, если config.num_labels==1) до применения SoftMax.
- **hidden_states** (`tuple(torch.Tensor)`, *необязательный*, возвращается при передаче `output_hidden_states=True` или при `config.output_hidden_states=True`) — Кортеж из `torch.Tensor` (один для вывода слоя встраиваний, если модель имеет такой слой, + один для вывода каждого этапа) формы `(batch_size, sequence_length, hidden_size)`. Скрытые состояния (также называемые картами признаков) модели на выходе каждого этапа.
- **attentions** (`tuple(torch.Tensor)`, *необязательный*, возвращается, если передано `output_attentions=True` или если `config.output_attentions=True`) -- Кортеж `torch.Tensor` (по одному на каждый слой) формы `(batch_size, num_heads, patch_size, sequence_length)`.

  Веса внимания после softmax в механизме внимания, используемые для вычисления взвешенного среднего в головах само-внимания.

Пример:

```python
>>> from transformers import AutoImageProcessor, Dinov2WithRegistersForImageClassification
>>> import torch
>>> from datasets import load_dataset

>>> dataset = load_dataset("huggingface/cats-image")
>>> image = dataset["test"]["image"][0]

>>> image_processor = AutoImageProcessor.from_pretrained("facebook/dinov2-with-registers-base")
>>> model = Dinov2WithRegistersForImageClassification.from_pretrained("facebook/dinov2-with-registers-base")

>>> inputs = image_processor(image, return_tensors="pt")

>>> with torch.no_grad():
...     logits = model(**inputs).logits

>>> # model predicts one of the 1000 ImageNet classes
>>> predicted_label = logits.argmax(-1).item()
>>> print(model.config.id2label[predicted_label])
...
```

