# Dilated Neighborhood Attention Transformer

## Обзор

DiNAT был предложен в статье [Dilated Neighborhood Attention Transformer](https://huggingface.co/papers/2209.15001) Али Хассани и Хамфри Ши.

Он расширяет [NAT](https://huggingface.co/papers/2204.07143), добавляя шаблон внимания к разреженным окрестностям (Dilated Neighborhood Attention) для захвата глобального контекста, и демонстрирует значительное улучшение производительности по сравнению с ним.

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

*Transformers стремительно становятся одной из наиболее широко применяемых архитектур глубокого обучения в различных модальностях, областях и задачах. В области компьютерного зрения, помимо продолжающихся работ над «чистыми» трансформерами, значительное внимание привлекают иерархические трансформеры благодаря их производительности и простоте интеграции в существующие фреймворки. Эти модели, как правило, используют механизмы локального внимания, такие как скользящее окно Neighborhood Attention (NA) или Shifted Window Self Attention из Swin Transformer. Хотя это эффективно снижает квадратичную сложность self attention, локальное внимание ослабляет два наиболее желаемых свойства self attention: моделирование долгосрочных взаимозависимостей и глобальное поле восприятия. В данной статье мы представляем Dilated Neighborhood Attention (DiNA) — естественное, гибкое и эффективное расширение NA, способное захватывать более глобальный контекст и экспоненциально расширять поля восприятия без дополнительных затрат. Локальное внимание NA и разреженное глобальное внимание DiNA дополняют друг друга, поэтому мы представляем Dilated Neighborhood Attention Transformer (DiNAT) — новый иерархический vision transformer, построенный на основе обоих подходов. Варианты DiNAT демонстрируют значительное улучшение по сравнению с сильными базовыми моделями, такими как NAT, Swin и ConvNeXt. Наша большая модель работает быстрее и превосходит аналогичную модель Swin на 1,5% box AP в задаче обнаружения объектов COCO, на 1,3% mask AP в задаче сегментации инстансов COCO и на 1,1% mIoU в задаче семантической сегментации ADE20K. В сочетании с новыми фреймворками наш большой вариант становится новой state of the art моделью паноптической сегментации на COCO (58.2 PQ) и ADE20K (48.5 PQ), а также моделью сегментации инстансов на Cityscapes (44.5 AP) и ADE20K (35.4 AP) (без дополнительных данных). Она также соответствует уровню state of the art специализированных моделей семантической сегментации на ADE20K (58.2 mIoU) и занимает второе место на Cityscapes (84.5 mIoU) (без дополнительных данных).*

<img
src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/dilated-neighborhood-attention-pattern.jpg"
alt="drawing" width="600"/>

 Neighborhood Attention с различными значениями дилатации. Изображение взято из оригинальной статьи.

Эта модель была предоставлена [Ali Hassani](https://huggingface.co/alihassanijr). Исходный код можно найти [здесь](https://github.com/SHI-Labs/Neighborhood-Attention-Transformer).

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

DiNAT можно использовать в качестве *базовой архитектуры*. При `output_hidden_states = True` модель выводит как `hidden_states`, так и `reshaped_hidden_states`. Форма `reshaped_hidden_states` составляет `(batch, num_channels, height, width)`, а не `(batch_size, height, width, num_channels)`.

Примечания:

- DiNAT зависит от реализации Neighborhood Attention и Dilated Neighborhood Attention в [NATTEN](https://github.com/SHI-Labs/NATTEN/).
Вы можете установить его с помощью предварительно собранных колёс для Linux, обратившись к [shi-labs.com/natten](https://shi-labs.com/natten), или собрать его на своей системе, выполнив `pip install natten`. Обратите внимание, что второй вариант, скорее всего, займёт время на компиляцию. NATTEN пока не поддерживает устройства под управлением Windows.
- В настоящее время поддерживается только размер патча 4.

## Ресурсы

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

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

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

## DinatConfig[[transformers.DinatConfig]]

#### transformers.DinatConfig[[transformers.DinatConfig]]

```python
transformers.DinatConfig(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, patch_size: int | list[int] | tuple[int, int] = 4, num_channels: int = 3, embed_dim: int = 64, depths: list[int] | tuple[int, ...] = (3, 4, 6, 5), num_heads: list[int] | tuple[int, ...] = (2, 4, 8, 16), kernel_size: int = 7, dilations: list | tuple | None = None, mlp_ratio: float = 3.0, qkv_bias: bool = True, hidden_dropout_prob: float | int = 0.0, attention_probs_dropout_prob: float | int = 0.0, drop_path_rate: float | int = 0.1, hidden_act: str = 'gelu', initializer_range: float = 0.02, layer_norm_eps: float = 1e-05, layer_scale_init_value: float = 0.0, _out_features: list[str] | None = None, _out_indices: list[int] | None = None)
```

[Источник](https://github.com/huggingface/transformers/blob/main/src/transformers/models/dinat/configuration_dinat.py#L25)

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

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

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

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

depths (`Union[list[int], tuple[int, ...]]`, *необязательный*, по умолчанию `(3, 4, 6, 5)`) : Глубина каждого слоя в Transformer.

num_heads (`Union[list[int], tuple[int, ...]]`, *необязательный*, по умолчанию `(2, 4, 8, 16)`) : Количество голов внимания для каждого слоя внимания в декодере Transformer.

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

dilations (`list[list[int]]`, *необязательный*, по умолчанию `[[1, 8, 1], [1, 4, 1, 4], [1, 2, 1, 2, 1, 2], [1, 1, 1, 1, 1]]`) : Значение дилатации для каждого NA-слоя в кодере Transformer.

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

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

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

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

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

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

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

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

layer_scale_init_value (`float`, *optional*, по умолчанию `0.0`) : Масштаб, используемый в слоях само-внимания. 0.1 для базовых моделей, 1e-6 для крупных. Установите 0, чтобы отключить масштабирование слоя.

Это класс конфигурации для хранения настроек модели DinatModel. Он используется для создания модели Dinat в соответствии с указанными аргументами, определяя архитектуру модели. Создание конфигурации с параметрами по умолчанию даст конфигурацию, аналогичную конфигурации [shi-labs/dinat-mini-in1k-224](https://huggingface.co/shi-labs/dinat-mini-in1k-224)

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

Пример:

```python
>>> from transformers import DinatConfig, DinatModel

>>> # Initializing a Dinat shi-labs/dinat-mini-in1k-224 style configuration
>>> configuration = DinatConfig()

>>> # Initializing a model (with random weights) from the shi-labs/dinat-mini-in1k-224 style configuration
>>> model = DinatModel(configuration)

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

## DinatModel[[transformers.DinatModel]]

#### transformers.DinatModel[[transformers.DinatModel]]

```python
transformers.DinatModel(config: DinatConfig, add_pooling_layer = True)
```

[Источник](https://github.com/huggingface/transformers/blob/main/src/transformers/models/dinat/modeling_dinat.py#L541)

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

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

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

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

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

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

#### forward[[transformers.DinatModel.forward]]

```python
forward(pixel_values: typing.Optional[torch.Tensor] = None, output_attentions: bool | None = None, output_hidden_states: bool | None = None, return_dict: bool | None = None, **kwargs)
```

[Источник](https://github.com/huggingface/transformers/blob/main/src/transformers/models/dinat/modeling_dinat.py#L567)

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

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

output_attentions (`bool`, *необязательный*) : Нужно ли возвращать тензоры внимания всех слоев внимания. Подробнее см. `attentions` в разделе возвращаемых тензоров.

output_hidden_states (`bool`, *необязательный*) : Нужно ли возвращать скрытые состояния всех слоёв. Подробнее о `hidden_states` в разделе возвращаемых тензоров.

return_dict (`bool`, *необязательный*) : Нужно ли возвращать [ModelOutput](/docs/transformers/main/ru/main_classes/output#transformers.utils.ModelOutput) вместо обычного кортежа.

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

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

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

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

- **last_hidden_state** (`torch.Tensor` формы `(batch_size, sequence_length, hidden_size)`, *необязательный*) -- Последовательность скрытых состояний на выходе последнего слоя модели.
- **pooler_output** (`torch.Tensor` формы `(batch_size, hidden_size)`, *необязательный*, возвращается при передаче `add_pooling_layer=True`) -- Средневзвешенное усреднение скрытых состояний последнего слоя.
- **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 в механизме внимания, используемые для вычисления взвешенного среднего в головах само-внимания.
- **reshaped_hidden_states** (`tuple(torch.Tensor)`, *необязательный*, возвращается, если передано `output_hidden_states=True` или если `config.output_hidden_states=True`) -- Кортеж `torch.Tensor` (один для вывода эмбеддингов + один для вывода каждого этапа) формы `(batch_size, hidden_size, height, width)`.

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

Пример:

```python
```

## DinatForImageClassification[[transformers.DinatForImageClassification]]

#### transformers.DinatForImageClassification[[transformers.DinatForImageClassification]]

```python
transformers.DinatForImageClassification(config: DinatConfig)
```

[Источник](https://github.com/huggingface/transformers/blob/main/src/transformers/models/dinat/modeling_dinat.py#L622)

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

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

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

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

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

#### forward[[transformers.DinatForImageClassification.forward]]

```python
forward(pixel_values: typing.Optional[torch.Tensor] = None, labels: typing.Optional[torch.LongTensor] = None, output_attentions: bool | None = None, output_hidden_states: bool | None = None, return_dict: bool | None = None, **kwargs)
```

[Источник](https://github.com/huggingface/transformers/blob/main/src/transformers/models/dinat/modeling_dinat.py#L639)

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

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

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

output_attentions (`bool`, *необязательный*) : Нужно ли возвращать тензоры внимания всех слоев внимания. Подробнее см. `attentions` в разделе возвращаемых тензоров.

output_hidden_states (`bool`, *необязательный*) : Нужно ли возвращать скрытые состояния всех слоёв. Подробнее о `hidden_states` в разделе возвращаемых тензоров.

return_dict (`bool`, *необязательный*) : Нужно ли возвращать [ModelOutput](/docs/transformers/main/ru/main_classes/output#transformers.utils.ModelOutput) вместо обычного кортежа.

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

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

Метод forward класса [DinatForImageClassification](/docs/transformers/main/ru/model_doc/dinat#transformers.DinatForImageClassification) переопределяет специальный метод `__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, sequence_length, sequence_length)`.

  Веса внимания после softmax в механизме внимания, используемые для вычисления взвешенного среднего в головах само-внимания.
- **reshaped_hidden_states** (`tuple(torch.Tensor)`, *необязательный*, возвращается, если передано `output_hidden_states=True` или если `config.output_hidden_states=True`) -- Кортеж `torch.Tensor` (один для вывода эмбеддингов + один для вывода каждого этапа) формы `(batch_size, hidden_size, height, width)`.

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

Пример:

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

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

>>> image_processor = AutoImageProcessor.from_pretrained("shi-labs/dinat-mini-in1k-224")
>>> model = DinatForImageClassification.from_pretrained("shi-labs/dinat-mini-in1k-224")

>>> 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])
...
```