# Свёрточный Vision Transformer (CvT)

[Convolutional Vision Transformer (CvT)](https://huggingface.co/papers/2103.15808) — это модель, сочетающая преимущества свёрточных нейронных сетей (CNN) и Vision Transformers для задач компьютерного зрения. Она вводит свёрточные слои в архитектуру Vision Transformer, что позволяет улавливать локальные паттерны на изображениях, сохраняя при этом глобальный контекст, обеспечиваемый механизмами self-attention.

Все контрольные точки CvT можно найти в организации [Microsoft](https://huggingface.co/microsoft?search_models=cvt).

> [!TIP]
> Эта модель была предоставлена пользователем [anujunj](https://huggingface.co/anugunj).
>
> Щёлкните по моделям CvT в боковой панели справа, чтобы увидеть больше примеров применения CvT к различным задачам компьютерного зрения.

Пример ниже демонстрирует, как классифицировать изображение с помощью [Pipeline](/docs/transformers/main/ru/main_classes/pipelines#transformers.Pipeline) или класса [AutoModel](/docs/transformers/main/ru/model_doc/auto#transformers.AutoModel).

```python
from transformers import pipeline

pipeline = pipeline(
    task="image-classification",
    model="microsoft/cvt-13",
    device=0
)
pipeline("https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/pipeline-cat-chonk.jpeg")
```

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

from transformers import AutoImageProcessor, AutoModelForImageClassification

image_processor = AutoImageProcessor.from_pretrained("microsoft/cvt-13")
model = AutoModelForImageClassification.from_pretrained(
    "microsoft/cvt-13",
    device_map="auto"
)

url = "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/pipeline-cat-chonk.jpeg"
image = Image.open(requests.get(url, stream=True).raw)
inputs = image_processor(image, return_tensors="pt").to(model.device)

with torch.no_grad():
  logits = model(**inputs).logits
predicted_class_id = logits.argmax(dim=-1).item()

class_labels = model.config.id2label
predicted_class_label = class_labels[predicted_class_id]
print(f"The predicted class label is: {predicted_class_label}")
```

## Ресурсы

Обратитесь к этому набору [ноутбуков](https://github.com/NielsRogge/Transformers-Tutorials/tree/master/VisionTransformer) ViT, чтобы посмотреть примеры инференса и дообучения на собственных наборах данных. Замените в этих ноутбуках `ViTFeatureExtractor` и [ViTForImageClassification](/docs/transformers/main/ru/model_doc/vit#transformers.ViTForImageClassification) на [AutoImageProcessor](/docs/transformers/main/ru/model_doc/auto#transformers.AutoImageProcessor) и [CvtForImageClassification](/docs/transformers/main/ru/model_doc/cvt#transformers.CvtForImageClassification).

## CvtConfig[[transformers.CvtConfig]]

#### transformers.CvtConfig[[transformers.CvtConfig]]

```python
transformers.CvtConfig(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, num_channels: int = 3, patch_sizes: list[int] | tuple[int, ...] = (7, 3, 3), patch_stride: list[int] | tuple[int, ...] = (4, 2, 2), patch_padding: list[int] | tuple[int, ...] = (2, 1, 1), embed_dim: list[int] | tuple[int, ...] = (64, 192, 384), num_heads: list[int] | tuple[int, ...] = (1, 3, 6), depth: list[int] | tuple[int, ...] = (1, 2, 10), mlp_ratio: list[float] | tuple[float, ...] = (4.0, 4.0, 4.0), attention_drop_rate: list[float] | tuple[float, ...] = (0.0, 0.0, 0.0), drop_rate: list[float] | tuple[float, ...] = (0.0, 0.0, 0.0), drop_path_rate: list[float] | tuple[float, ...] = (0.0, 0.0, 0.1), qkv_bias: list[bool] | tuple[bool, ...] = (True, True, True), cls_token: list[bool] | tuple[bool, ...] = (False, False, True), qkv_projection_method: list[str] | tuple[str, ...] = ('dw_bn', 'dw_bn', 'dw_bn'), kernel_qkv: list[int] | tuple[int, ...] = (3, 3, 3), padding_kv: list[int] | tuple[int, ...] = (1, 1, 1), stride_kv: list[int] | tuple[int, ...] = (2, 2, 2), padding_q: list[int] | tuple[int, ...] = (1, 1, 1), stride_q: list[int] | tuple[int, ...] = (1, 1, 1), initializer_range: float = 0.02, layer_norm_eps: float = 1e-12)
```

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

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

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

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

patch_stride (`list[int]`, *optional*, по умолчанию `[4, 2, 2]`) : Размер шага (stride) для каждого patch embedding в энкодере.

patch_padding (`list[int]`, *optional*, по умолчанию `[2, 1, 1]`) : Размер отступов для каждого встраивания патчей энкодера.

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

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

depth (`list[int]`, *необязательный*, по умолчанию `[1, 2, 10]`) : Количество слоев в каждом блоке кодировщика.

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

attention_drop_rate (`list[float]`, *необязательный*, по умолчанию `[0.0, 0.0, 0.0]`) : Доля dropout для вероятностей внимания.

drop_rate (`list[float]`, *необязательный*, по умолчанию `[0.0, 0.0, 0.0]`) : Доля dropout для вероятностей эмбеддингов патчей.

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

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

cls_token (`list[bool]`, *необязательный*, по умолчанию `[False, False, True]`) : Добавлять или нет токен классификации к выходу каждого из последних трёх этапов.

qkv_projection_method (`list[string]`, *optional*, по умолчанию ["dw_bn", "dw_bn", "dw_bn"]`) : Метод проекции для query, key и value. По умолчанию используются depth-wise свёртки с batch norm. Для линейной проекции используйте "avg".

kernel_qkv (`list[int]`, *необязательный*, по умолчанию `[3, 3, 3]`) : Размер ядра для query, key и value в слое внимания

padding_kv (`list[int]`, *необязательный*, по умолчанию `[1, 1, 1]`) : Размер отступов для ключей и значений в слое внимания

stride_kv (`list[int]`, *необязательный*, по умолчанию `[2, 2, 2]`) : Размер шага для ключей и значений в слое внимания

padding_q (`list[int]`, *необязательный*, по умолчанию `[1, 1, 1]`) : Размер отступов для запроса в слое внимания

stride_q (`list[int]`, *необязательный*, по умолчанию `[1, 1, 1]`) : Размер шага для query в слое внимания

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

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

Это класс конфигурации для хранения настроек модели CvtModel. Он используется для создания модели Cvt в соответствии с указанными аргументами, определяя архитектуру модели. Создание конфигурации с параметрами по умолчанию даст конфигурацию, аналогичную конфигурации [microsoft/cvt-13](https://huggingface.co/microsoft/cvt-13)

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

Пример:

```python
>>> from transformers import CvtConfig, CvtModel

>>> # Initializing a Cvt msft/cvt style configuration
>>> configuration = CvtConfig()

>>> # Initializing a model (with random weights) from the msft/cvt style configuration
>>> model = CvtModel(configuration)

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

## CvtModel[[transformers.CvtModel]]

#### transformers.CvtModel[[transformers.CvtModel]]

```python
transformers.CvtModel(config: CvtConfig, add_pooling_layer = True)
```

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

- **last_hidden_state** (`torch.Tensor` формы `(batch_size, sequence_length, hidden_size)`, *необязательный*) -- Последовательность скрытых состояний на выходе последнего слоя модели.
- **cls_token_value** (`torch.Tensor` формы `(batch_size, 1, hidden_size)`) -- Токен классификации на выходе последнего слоя модели.
- **hidden_states** (`tuple[torch.Tensor, ...]`, *необязательный*, возвращается, если передано `output_hidden_states=True` или если `config.output_hidden_states=True`) -- Кортеж `torch.Tensor` (один для вывода слоя встраиваний, если модель имеет слой встраиваний, + один для вывода каждого слоя) формы `(batch_size, sequence_length, hidden_size)`.

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

## CvtForImageClassification[[transformers.CvtForImageClassification]]

#### transformers.CvtForImageClassification[[transformers.CvtForImageClassification]]

```python
transformers.CvtForImageClassification(config: CvtConfig)
```

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

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

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

Модель-трансформер Cvt с головной частью для классификации изображений (линейный слой поверх финального скрытого состояния токена [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.CvtForImageClassification.forward]]

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

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

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

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

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

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

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

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

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

Метод [CvtForImageClassification](/docs/transformers/main/ru/model_doc/cvt#transformers.CvtForImageClassification) forward переопределяет специальный метод `__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, num_channels, height, width)`. Скрытые состояния (также называемые картами признаков) модели на выходе каждого этапа.

Пример:

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

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

>>> image_processor = AutoImageProcessor.from_pretrained("microsoft/cvt-13")
>>> model = CvtForImageClassification.from_pretrained("microsoft/cvt-13")

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