# ViTMSN

## Обзор

Модель ViTMSN была предложена в статье [Masked Siamese Networks for Label-Efficient Learning](https://huggingface.co/papers/2204.07141) авторами Mahmoud Assran, Mathilde Caron, Ishan Misra, Piotr Bojanowski, Florian Bordes, Pascal Vincent, Armand Joulin, Michael Rabbat, Nicolas Ballas. В статье представлена архитектура совместного встраивания, сопоставляющая прототипы замаскированных патчей с прототипами незамаскированных патчей. Благодаря такой конфигурации их метод обеспечивает превосходные результаты в режимах с малым количеством примеров и экстремально малым количеством примеров.

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

*Мы предлагаем Masked Siamese Networks (MSN) — фреймворк самообучения для получения представлений изображений. Наш подход сопоставляет представление вида изображения со случайно замаскированными патчами с представлением исходного изображения без маски. Эта стратегия самообучения особенно масштабируема при применении к Vision Transformers, поскольку сетью обрабатываются только незамаскированные патчи. В результате MSN повышают масштабируемость архитектур совместного встраивания, одновременно формируя представления высокого семантического уровня, которые демонстрируют конкурентоспособные результаты в задаче классификации изображений с малым количеством примеров. Например, на ImageNet-1K, используя всего 5 000 размеченных изображений, наша базовая модель MSN достигает точности top-1 72,4%, а при использовании 1% меток ImageNet-1K мы получаем точность top-1 75,7%, что устанавливает новый рекорд для самообучения на этом бенчмарке.*

 Архитектура MSN. Взято из оригинальной статьи.

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

## Советы по использованию

- MSN (masked siamese networks) — это метод самообучаемой предварительной настройки Vision Transformers (ViTs). Предварительная настройка
цель состоит в том, чтобы сопоставить прототипы, назначенные немаскированным представлениям изображений, с прототипами маскированных представлений тех же изображений.
- Авторы опубликовали только предобученные веса базовой модели (предобучение на ImageNet-1k). Таким образом, чтобы использовать их на собственном наборе данных для классификации изображений,
используйте класс [ViTMSNForImageClassification](/docs/transformers/v5.23.0/ru/model_doc/vit_msn#transformers.ViTMSNForImageClassification), который инициализируется из [ViTMSNModel](/docs/transformers/v5.23.0/ru/model_doc/vit_msn#transformers.ViTMSNModel). Подробное руководство по дообучению см. в [этом ноутбуке](https://github.com/huggingface/notebooks/blob/main/examples/image_classification.ipynb).
- MSN особенно полезен в режимах low-shot и extreme low-shot. Примечательно, что он достигает точности top-1 75,7% всего на 1% данных ImageNet-1K
labels при дообучении.

### Использование масштабированного внимания на основе скалярного произведения (SDPA)

PyTorch включает в себя нативный оператор масштабированного внимания на основе скалярного произведения (SDPA) в составе `torch.nn.functional`. Эта функция объединяет несколько реализаций, которые могут применяться в зависимости от входных данных и используемого оборудования. Подробнее см. в [официальной документации](https://pytorch.org/docs/stable/generated/torch.nn.functional.scaled_dot_product_attention.html) или на странице [GPU Inference](https://huggingface.co/docs/transformers/main/en/perf_infer_gpu_one#pytorch-scaled-dot-product-attention).

SDPA используется по умолчанию для `torch>=2.1.1`, когда доступна соответствующая реализация, но вы также можете установить `attn_implementation="sdpa"` в `from_pretrained()`, чтобы явно запросить использование SDPA.

```python
from transformers import ViTMSNForImageClassification

model = ViTMSNForImageClassification.from_pretrained("facebook/vit-msn-base", attn_implementation="sdpa", device_map="auto")
...
```

Для достижения максимального ускорения мы рекомендуем загружать модель в половинной точности (например, `torch.float16` или `torch.bfloat16`).

На локальном бенчмарке (A100-40GB, PyTorch 2.3.0, ОС Ubuntu 22.04) с `float32` и моделью `facebook/vit-msn-base` мы наблюдали следующие ускорения при инференсе.

|   Размер пакета |   Среднее время вывода (мс), режим eager |   Среднее время инференса (мс), модель sdpa |   Ускорение, Sdpa / Eager (x) |
|--------------|-------------------------------------------|-------------------------------------------|------------------------------|
|            1 |                                         7 |                                         6 |                      1.17 |
|            2 |                                         8 |                                         6 |                      1.33 |
|            4 |                                         8 |                                         6 |                      1.33 |
|            8 |                                         8 |                                         6 |                      1.33 |

## Ресурсы

Список официальных ресурсов Hugging Face и сообщества (отмечены значком 🌎), которые помогут вам начать работу с ViT MSN.

- [ViTMSNForImageClassification](/docs/transformers/v5.23.0/ru/model_doc/vit_msn#transformers.ViTMSNForImageClassification) поддерживается в этом [ноутбуке](https://colab.research.google.com/github/huggingface/notebooks/blob/main/examples/image_classification.ipynb).
- См. также: [Руководство по задаче классификации изображений](../tasks/image_classification)

Если вы хотите предложить ресурс для включения в этот раздел, пожалуйста, создайте Pull Request, и мы его рассмотрим! В идеале ресурс должен демонстрировать что-то новое, а не дублировать существующие материалы.

## ViTMSNConfig[[transformers.ViTMSNConfig]]

#### transformers.ViTMSNConfig[[transformers.ViTMSNConfig]]

```python
transformers.ViTMSNConfig(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, intermediate_size: int = 3072, 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)
```

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

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

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

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

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

intermediate_size (`int`, *optional*, по умолчанию `3072`) : Размерность представлений 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) к запросам, ключам и значениям.

Это класс конфигурации для хранения настроек модели ViTMSNModel. Он используется для создания модели Vit Msn в соответствии с указанными аргументами, определяя архитектуру модели. Создание конфигурации с параметрами по умолчанию даст конфигурацию, аналогичную конфигурации модели [facebook/vit_msn_base](https://huggingface.co/facebook/vit_msn_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 ViTMSNModel, ViTMSNConfig

>>> # Initializing a ViT MSN vit-msn-base style configuration
>>> configuration = ViTConfig()

>>> # Initializing a model from the vit-msn-base style configuration
>>> model = ViTMSNModel(configuration)

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

## ViTMSNModel[[transformers.ViTMSNModel]]

#### transformers.ViTMSNModel[[transformers.ViTMSNModel]]

```python
transformers.ViTMSNModel(config: ViTMSNConfig, use_mask_token: bool = False)
```

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

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

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

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

Модель Vit Msn без дополнительных слоёв, выводящая необработанные скрытые состояния.

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

```python
forward(pixel_values: typing.Optional[torch.Tensor] = None, bool_masked_pos: typing.Optional[torch.BoolTensor] = None, interpolate_pos_encoding: bool | None = 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/vit_msn/modeling_vit_msn.py#L331)

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

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

bool_masked_pos (`torch.BoolTensor` формы `(batch_size, num_patches)`, *необязательный*) : Позиции с булевым маскированием. Указывает, какие патчи замаскированы (1), а какие нет (0).

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

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

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

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

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

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

- **last_hidden_state** (`torch.Tensor` формы `(batch_size, sequence_length, hidden_size)`) -- Последовательность скрытых состояний на выходе последнего слоя модели.
- **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
>>> from transformers import AutoImageProcessor, ViTMSNModel
>>> import torch
>>> from PIL import Image
>>> from huggingface_hub.utils import httpx
>>> from io import BytesIO

>>> url = "http://images.cocodataset.org/val2017/000000039769.jpg"
>>> with httpx.stream("GET", url) as response:
...     image = Image.open(BytesIO(response.read()))

>>> image_processor = AutoImageProcessor.from_pretrained("facebook/vit-msn-small")
>>> model = ViTMSNModel.from_pretrained("facebook/vit-msn-small")
>>> inputs = image_processor(images=image, return_tensors="pt")
>>> with torch.no_grad():
...     outputs = model(**inputs)
>>> last_hidden_states = outputs.last_hidden_state
```

## ViTMSNForImageClassification[[transformers.ViTMSNForImageClassification]]

#### transformers.ViTMSNForImageClassification[[transformers.ViTMSNForImageClassification]]

```python
transformers.ViTMSNForImageClassification(config: ViTMSNConfig)
```

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

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

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

Модель Vit Msn с головкой для классификации изображений, например, для 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.ViTMSNForImageClassification.forward]]

```python
forward(pixel_values: typing.Optional[torch.Tensor] = None, labels: typing.Optional[torch.Tensor] = None, interpolate_pos_encoding: bool | None = 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/vit_msn/modeling_vit_msn.py#L395)

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

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

labels (`torch.LongTensor` формы `(batch_size,)`, *необязательный*) : Метки для вычисления функции потерь классификации/регрессии изображений.

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

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`), содержащий различные элементы в зависимости от конфигурации ([ViTMSNConfig](/docs/transformers/v5.23.0/ru/model_doc/vit_msn#transformers.ViTMSNConfig)) и входных данных.

Метод forward класса [ViTMSNForImageClassification](/docs/transformers/v5.23.0/ru/model_doc/vit_msn#transformers.ViTMSNForImageClassification) переопределяет специальный метод `__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, ViTMSNForImageClassification
>>> import torch
>>> from PIL import Image
>>> from huggingface_hub.utils import httpx
>>> from io import BytesIO

>>> torch.manual_seed(2)
>>> url = "http://images.cocodataset.org/val2017/000000039769.jpg"
>>> with httpx.stream("GET", url) as response:
...     image = Image.open(BytesIO(response.read())).convert("RGB")

>>> image_processor = AutoImageProcessor.from_pretrained("facebook/vit-msn-small")
>>> model = ViTMSNForImageClassification.from_pretrained("facebook/vit-msn-small")

>>> inputs = image_processor(images=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])
tusker
```

