# TimmWrapper

## Visão geral

Classe auxiliar para permitir o carregamento de modelos timm para uso com a biblioteca transformers e suas autoclasses.

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

## Recursos

Uma lista de recursos oficiais do Hugging Face e da comunidade (indicados por 🌎) para ajudar você a começar com o TimmWrapper.

- [Coleção de Notebooks de Exemplo](https://github.com/ariG23498/timm-wrapper-examples) 🌎

> [!TIP]
> Para uma visão mais detalhada, leia o [post oficial no blog](https://huggingface.co/blog/timm-transformers) sobre a integração com o 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)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/timm_wrapper/configuration_timm_wrapper.py#L31)

**Parâmetros:**

architecture (`str`, *opcional*, padrão `"resnet50"`) : A arquitetura do timm a ser carregada.

initializer_range (`float`, *opcional*, padrão `0.02`) : O desvio padrão do truncated_normal_initializer para inicializar todas as matrizes de pesos.

do_pooling (`bool`, *opcional*, padrão `True`) : Indica se deve ou não realizar pooling para o last_hidden_state em `TimmWrapperModel`.

model_args (`dict[str, Any]`, *opcional*) : Argumentos de palavra-chave adicionais para passar à função `timm.create_model`. Por exemplo, `model_args={"depth": 3}` para `timm/vit_base_patch32_clip_448.laion2b_ft_in12k_in1k` para criar um modelo com 3 blocos. O valor padrão é `None`.

Esta é a classe de configuração para armazenar a configuração de um TimmWrapperModel. Ela é usada para instanciar um modelo Timm Wrapper de acordo com os argumentos especificados, definindo a arquitetura do modelo. Instanciar uma configuração com os padrões resultará em uma configuração semelhante à do [resnet50](https://huggingface.co/resnet50)

Os objetos de configuração herdam de [PreTrainedConfig](/docs/transformers/main/pt/main_classes/configuration#transformers.PreTrainedConfig) e podem ser usados para controlar as saídas do modelo. Leia a documentação de [PreTrainedConfig](/docs/transformers/main/pt/main_classes/configuration#transformers.PreTrainedConfig) para mais informações.

Exemplo:
```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)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/timm_wrapper/image_processing_timm_wrapper.py#L38)

**Parâmetros:**

pretrained_cfg (`dict[str, Any]`) : A configuração do modelo pré-treinado usado para resolver as transformações de avaliação e treinamento.

architecture (`Optional[str]`, *opcional*) : Nome da arquitetura do modelo.

Classe de encapsulamento para modelos timm a serem usados dentro do 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')
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/timm_wrapper/image_processing_timm_wrapper.py#L96)

**Parâmetros:**

images (`ImageInput`) : Imagem para pré-processar. Espera uma única imagem ou um lote de imagens

return_tensors (`str` ou `TensorType`, *opcional*) : O tipo dos tensores a serem retornados.

Pré-processa uma imagem ou um lote de imagens.

## TimmWrapperModel[[transformers.TimmWrapperModel]]

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

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

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/timm_wrapper/modeling_timm_wrapper.py#L163)

Classe de wrapper para modelos timm a serem usados em 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)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/timm_wrapper/modeling_timm_wrapper.py#L177)

**Parâmetros:**

pixel_values (`torch.Tensor` de forma `(batch_size, num_channels, image_size, image_size)`) : Os tensores correspondentes às imagens de entrada. Os valores de pixels podem ser obtidos usando [TimmWrapperImageProcessor](/docs/transformers/main/pt/model_doc/timm_wrapper#transformers.TimmWrapperImageProcessor). Veja [TimmWrapperImageProcessor.__call__()](/docs/transformers/main/pt/model_doc/molmo2#transformers.Molmo2ImageProcessor.__call__) para detalhes (`processor_class` usa [TimmWrapperImageProcessor](/docs/transformers/main/pt/model_doc/timm_wrapper#transformers.TimmWrapperImageProcessor) para processar imagens).

output_attentions (`bool`, *opcional*) : Se deve ou não retornar os tensores de atenção de todas as camadas de atenção. Não compatível com modelos embrulhados pelo timm.

output_hidden_states (`bool`, *opcional*) : Se deve ou não retornar os estados ocultos de todas as camadas. Não compatível com modelos embrulhados pelo timm.

return_dict (`bool`, *opcional*) : Se deve ou não retornar um [ModelOutput](/docs/transformers/main/pt/main_classes/output#transformers.utils.ModelOutput) em vez de uma tupla simples.

do_pooling (`bool`, *opcional*) : Se deve ou não fazer pooling para o last_hidden_state em `TimmWrapperModel`. Se `None` for passado, o valor de `do_pooling` da config é usado.

use_cache (`bool`, *opcional*) : Se definido como `True`, os estados de chave-valor de `past_key_values` são retornados e podem ser usados para acelerar a decodificação (veja `past_key_values`).

**Retorna:** `TimmWrapperModelOutput` ou `tuple(torch.Tensor)`

Um `TimmWrapperModelOutput` ou uma tupla de `torch.Tensor` (se `return_dict=False` for passado ou quando `config.return_dict=False`) contendo vários elementos, dependendo da configuração ([TimmWrapperConfig](/docs/transformers/main/pt/model_doc/timm_wrapper#transformers.TimmWrapperConfig)) e das entradas.

O método forward do [TimmWrapperModel](/docs/transformers/main/pt/model_doc/timm_wrapper#transformers.TimmWrapperModel) substitui o método especial `__call__`.

Embora a receita para a passagem direta precise ser definida dentro desta função, deve-se chamar a instância de `Module` em seguida, em vez desta, pois a primeira cuida da execução das etapas de pré e pós-processamento, enquanto a segunda as ignora silenciosamente.

- **last_hidden_state** (`torch.Tensor`) -- O último estado oculto do modelo, saída antes da aplicação da cabeça de classificação.
- **pooler_output** (`torch.Tensor`, *opcional*) -- A saída agregada derivada do último estado oculto, se aplicável.
- **hidden_states** (`tuple(torch.Tensor)`, *opcional*, retornado se `output_hidden_states=True` estiver definido ou se `config.output_hidden_states=True`) -- Uma tupla contendo os estados ocultos intermediários do modelo na saída de cada camada ou das camadas especificadas.
- **attentions** (`tuple(torch.Tensor)`, *opcional*, retornado se `output_attentions=True` estiver definido ou se `config.output_attentions=True`.) -- Uma tupla contendo os pesos de atenção intermediários do modelo na saída de cada camada. Observação: Atualmente, os modelos Timm não suportam a saída de atenções.

Exemplos:
```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)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/timm_wrapper/modeling_timm_wrapper.py#L280)

Classe de wrapper para modelos timm a serem usados em transformers para classificação de imagem.

#### 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)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/timm_wrapper/modeling_timm_wrapper.py#L303)

**Parâmetros:**

pixel_values (`torch.Tensor` de forma `(batch_size, num_channels, image_size, image_size)`) : Os tensores correspondentes às imagens de entrada. Os valores de pixels podem ser obtidos usando [TimmWrapperImageProcessor](/docs/transformers/main/pt/model_doc/timm_wrapper#transformers.TimmWrapperImageProcessor). Veja [TimmWrapperImageProcessor.__call__()](/docs/transformers/main/pt/model_doc/molmo2#transformers.Molmo2ImageProcessor.__call__) para detalhes (`processor_class` usa [TimmWrapperImageProcessor](/docs/transformers/main/pt/model_doc/timm_wrapper#transformers.TimmWrapperImageProcessor) para processar imagens).

labels (`torch.LongTensor` de forma `(batch_size,)`, *opcional*) : Rótulos para o cálculo da perda de classificação/regressão de imagem. Os índices devem estar em `[0, ..., config.num_labels - 1]`. Se `config.num_labels == 1`, uma perda de regressão é calculada (perda de erro quadrático médio). Se `config.num_labels > 1`, uma perda de classificação é calculada (entropia cruzada).

output_attentions (`bool`, *opcional*) : Se deve ou não retornar os tensores de atenção de todas as camadas de atenção. Não compatível com modelos embrulhados pelo timm.

output_hidden_states (`bool`, *opcional*) : Se deve ou não retornar os estados ocultos de todas as camadas. Não compatível com modelos embrulhados pelo timm.

return_dict (`bool`, *opcional*) : Se deve ou não retornar um [ModelOutput](/docs/transformers/main/pt/main_classes/output#transformers.utils.ModelOutput) em vez de uma tupla simples. **kwargs: Argumentos de palavra-chave adicionais passados para o forward do modelo `timm`.

**Retorna:** [ImageClassifierOutput](/docs/transformers/main/pt/main_classes/output#transformers.modeling_outputs.ImageClassifierOutput) ou `tuple(torch.Tensor)`

Um [ImageClassifierOutput](/docs/transformers/main/pt/main_classes/output#transformers.modeling_outputs.ImageClassifierOutput) ou uma tupla de `torch.Tensor` (se `return_dict=False` for passado ou quando `config.return_dict=False`) contendo vários elementos, dependendo da configuração ([TimmWrapperConfig](/docs/transformers/main/pt/model_doc/timm_wrapper#transformers.TimmWrapperConfig)) e das entradas.

O método forward da [TimmWrapperForImageClassification](/docs/transformers/main/pt/model_doc/timm_wrapper#transformers.TimmWrapperForImageClassification) sobrescreve o método especial `__call__`.

Embora a receita para a passagem direta precise ser definida dentro desta função, deve-se chamar a instância de `Module` em seguida, em vez desta, pois a primeira cuida da execução das etapas de pré e pós-processamento, enquanto a segunda as ignora silenciosamente.

- **loss** (`torch.Tensor` de forma `(1,)`, *opcional*, retornado quando `labels` é fornecido) -- Perda de classificação (ou de regressão se config.num_labels==1).
- **logits** (`torch.Tensor` de forma `(batch_size, config.num_labels)`) -- Pontuações de classificação (ou regressão, se config.num_labels==1) (antes do SoftMax).
- **hidden_states** (`tuple(torch.Tensor)`, *opcional*, retornado quando `output_hidden_states=True` é passado ou quando `config.output_hidden_states=True`) -- Tupla de `torch.Tensor` (uma para a saída dos embeddings, se o modelo tiver uma camada de embedding, + uma para a saída de cada estágio) de forma `(batch_size, sequence_length, hidden_size)`. Hidden-states (também chamados de feature maps) do modelo na saída de cada estágio.
- **attentions** (`tuple(torch.Tensor)`, *opcional*, retornado quando `output_attentions=True` é passado ou quando `config.output_attentions=True`) -- Tupla de `torch.Tensor` (uma para cada camada) de forma `(batch_size, num_heads, patch_size, sequence_length)`.

  Pesos de atenção após o softmax de atenção, usados para calcular a média ponderada nas cabeças de autoatenção.

Exemplos:
```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)
```