# TimmWrapper

## Обзор

Вспомогательный класс, позволяющий загружать модели timm для использования с библиотекой transformers и её автоклассами.

```python
from urllib.request import urlopen

import torch
from PIL import Image

from transformers import AutoImageProcessor, AutoModelForImageClassification

# Load image
image = Image.open(urlopen(
    'https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/beignets-task-guide.png'
))

# Load model and image processor
checkpoint = "timm/resnet50.a1_in1k"
image_processor = AutoImageProcessor.from_pretrained(checkpoint)
model = AutoModelForImageClassification.from_pretrained(checkpoint).eval( device_map="auto")

# Preprocess image
inputs = image_processor(image)

# Forward pass
with torch.no_grad():
    logits = model(**inputs).logits

# Get top 5 predictions
top5_probabilities, top5_class_indices = torch.topk(logits.softmax(dim=1) * 100, k=5)
```

## Ресурсы

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

- [Коллекция примеров в Notebook](https://github.com/ariG23498/timm-wrapper-examples) 🌎

> [!TIP]
> Для более подробного обзора прочитайте [официальный пост в блоге](https://huggingface.co/blog/timm-transformers) об интеграции с timm.

## TimmWrapperConfig[[transformers.TimmWrapperConfig]]

#### transformers.TimmWrapperConfig[[transformers.TimmWrapperConfig]]

```python
transformers.TimmWrapperConfig(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, architecture: str = 'resnet50', initializer_range: float = 0.02, do_pooling: bool = True, model_args: dict[str, typing.Any] | None = None)
```

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

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

architecture (`str`, *необязательный*, по умолчанию `"resnet50"`) : Архитектура timm для загрузки.

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

do_pooling (`bool`, *необязательный*, по умолчанию `True`) : Выполнять ли пулинг для last_hidden_state в `TimmWrapperModel`.

model_args (`dict[str, Any]`, *необязательный*) : Дополнительные именованные аргументы для передачи в функцию `timm.create_model`. Например, `model_args={"depth": 3}` для `timm/vit_base_patch32_clip_448.laion2b_ft_in12k_in1k`, чтобы создать модель с 3 блоками. По умолчанию `None`.

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

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

Пример:
```python
>>> from transformers import TimmWrapperModel

>>> # Initializing a timm model
>>> model = TimmWrapperModel.from_pretrained("timm/resnet18.a1_in1k")

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

## TimmWrapperImageProcessor[[transformers.TimmWrapperImageProcessor]]

#### transformers.TimmWrapperImageProcessor[[transformers.TimmWrapperImageProcessor]]

```python
transformers.TimmWrapperImageProcessor(pretrained_cfg: dict, architecture: str | None = None, **kwargs)
```

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

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

pretrained_cfg (`dict[str, Any]`) : Конфигурация предобученной модели, используемая для разрешения трансформаций оценки и обучения.

architecture (`Optional[str]`, *необязательный*) : Название архитектуры модели.

Обёртка для моделей timm, предназначенная для использования в transformers.

#### preprocess[[transformers.TimmWrapperImageProcessor.preprocess]]

```python
preprocess(images: typing.Union[ForwardRef('PIL.Image.Image'), numpy.ndarray, ForwardRef('torch.Tensor'), list['PIL.Image.Image'], list[numpy.ndarray], list['torch.Tensor']], return_tensors: str | transformers.utils.generic.TensorType | None = 'pt')
```

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

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

images (`ImageInput`) : изображение для предобработки. Ожидается одно изображение или батч изображений

return_tensors (`str` или `TensorType`, *необязательный*) : Тип тензоров, которые будут возвращены.

Предобработка изображения или пакета изображений.

## TimmWrapperModel[[transformers.TimmWrapperModel]]

#### transformers.TimmWrapperModel[[transformers.TimmWrapperModel]]

```python
transformers.TimmWrapperModel(config: TimmWrapperConfig)
```

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

Обёртка для моделей timm, используемая в transformers.

#### forward[[transformers.TimmWrapperModel.forward]]

```python
forward(pixel_values: Tensor, output_attentions: bool | None = None, output_hidden_states: bool | list[int] | None = None, return_dict: bool | None = None, do_pooling: bool | None = None, use_cache: bool | None = None, **kwargs)
```

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

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

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

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

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

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

do_pooling (`bool`, *необязательный*) : Выполнять ли пулинг для last_hidden_state в `TimmWrapperModel`. Если передано `None`, используется значение `do_pooling` из конфигурации.

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

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

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

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

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

- **last_hidden_state** (`torch.Tensor`) -- Последнее скрытое состояние модели, выводимое до применения классификационной головы.
- **pooler_output** (`torch.Tensor`, *необязательный*) -- Пул-вывод, полученный из последнего скрытого состояния, если применимо.
- **hidden_states** (`tuple(torch.Tensor)`, *необязательный*, возвращается, если установлено `output_hidden_states=True` или `config.output_hidden_states=True`) — кортеж, содержащий промежуточные скрытые состояния модели на выходе каждого слоя или указанных слоёв.
- **attentions** (`tuple(torch.Tensor)`, *optional*, возвращается, если задано `output_attentions=True` или `config.output_attentions=True`.) — Кортеж, содержащий промежуточные веса внимания модели на выходе каждого слоя. Примечание: в настоящее время модели Timm не поддерживают вывод весов внимания.

Примеры:
```python
>>> import torch
>>> from PIL import Image
>>> from urllib.request import urlopen
>>> from transformers import AutoModel, AutoImageProcessor

>>> # Load image
>>> image = Image.open(urlopen(
...     'https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/beignets-task-guide.png'
... ))

>>> # Load model and image processor
>>> checkpoint = "timm/resnet50.a1_in1k"
>>> image_processor = AutoImageProcessor.from_pretrained(checkpoint)
>>> model = AutoModel.from_pretrained(checkpoint).eval()

>>> # Preprocess image
>>> inputs = image_processor(image)

>>> # Forward pass
>>> with torch.no_grad():
...     outputs = model(**inputs)

>>> # Get pooled output
>>> pooled_output = outputs.pooler_output

>>> # Get last hidden state
>>> last_hidden_state = outputs.last_hidden_state
```

## TimmWrapperForImageClassification[[transformers.TimmWrapperForImageClassification]]

#### transformers.TimmWrapperForImageClassification[[transformers.TimmWrapperForImageClassification]]

```python
transformers.TimmWrapperForImageClassification(config: TimmWrapperConfig)
```

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

Обёртка для моделей timm, используемая в transformers для классификации изображений.

#### forward[[transformers.TimmWrapperForImageClassification.forward]]

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

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

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

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

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

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

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

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

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

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

Метод forward класса [TimmWrapperForImageClassification](/docs/transformers/main/ru/model_doc/timm_wrapper#transformers.TimmWrapperForImageClassification) переопределяет специальный метод `__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
>>> import torch
>>> from PIL import Image
>>> from urllib.request import urlopen
>>> from transformers import AutoModelForImageClassification, AutoImageProcessor

>>> # Load image
>>> image = Image.open(urlopen(
...     'https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/beignets-task-guide.png'
... ))

>>> # Load model and image processor
>>> checkpoint = "timm/resnet50.a1_in1k"
>>> image_processor = AutoImageProcessor.from_pretrained(checkpoint)
>>> model = AutoModelForImageClassification.from_pretrained(checkpoint).eval()

>>> # Preprocess image
>>> inputs = image_processor(image)

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

>>> # Get top 5 predictions
>>> top5_probabilities, top5_class_indices = torch.topk(logits.softmax(dim=1) * 100, k=5)
```