# ResNet

## Visão geral

O modelo ResNet foi proposto em [Deep Residual Learning for Image Recognition](https://huggingface.co/papers/1512.03385) por Kaiming He, Xiangyu Zhang, Shaoqing Ren e Jian Sun. Nossa implementação segue as pequenas alterações feitas pela [Nvidia](https://catalog.ngc.nvidia.com/orgs/nvidia/resources/resnet_50_v1_5_for_pytorch): aplicamos `stride=2` para o downsampling na convolução `3x3` do bottleneck, e não na primeira `1x1`. Isso é geralmente conhecido como "ResNet v1.5".

O ResNet introduziu conexões residuais, que permitem treinar redes com um número inédito de camadas (até 1000). O ResNet venceu a competição ILSVRC & COCO de 2015, um marco importante na visão computacional profunda.

O resumo do artigo é o seguinte:

*Redes neurais mais profundas são mais difíceis de treinar. Apresentamos um framework de aprendizado residual para facilitar o treinamento de redes substancialmente mais profundas do que as usadas anteriormente. Reformulamos explicitamente as camadas para aprenderem funções residuais em relação às entradas da camada, em vez de aprender funções não referenciadas. Fornecemos evidência empírica abrangente mostrando que essas redes residuais são mais fáceis de otimizar e podem ganhar precisão a partir de um aumento considerável da profundidade. No conjunto de dados ImageNet, avaliamos redes residuais com profundidade de até 152 camadas — 8x mais profundas que as redes VGG, mas ainda com menor complexidade. Um ensemble dessas redes residuais atinge 3,57% de erro no conjunto de teste do ImageNet. Esse resultado conquistou o 1º lugar na tarefa de classificação do ILSVRC 2015. Também apresentamos análises no CIFAR-10 com 100 e 1000 camadas. A profundidade das representações é de importância central para muitas tarefas de reconhecimento visual. Devido exclusivamente às nossas representações extremamente profundas, obtemos uma melhoria relativa de 28% no conjunto de dados de detecção de objetos COCO. As redes residuais profundas são a base das nossas submissões para as competições ILSVRC & COCO 2015, onde também conquistamos os 1º lugares nas tarefas de detecção no ImageNet, localização no ImageNet, detecção no COCO e segmentação no COCO.*

A figura abaixo ilustra a arquitetura do ResNet. Retirada do [artigo original](https://huggingface.co/papers/1512.03385).

Este modelo foi contribuído por [Francesco](https://huggingface.co/Francesco). O código original pode ser encontrado [aqui](https://github.com/KaimingHe/deep-residual-networks).

## Recursos

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

- [ResNetForImageClassification](/docs/transformers/main/pt/model_doc/resnet#transformers.ResNetForImageClassification) é suportado por este [notebook](https://colab.research.google.com/github/huggingface/notebooks/blob/main/examples/image_classification.ipynb).
- Veja também: [Guia da tarefa de classificação de imagens](../tasks/image_classification)

Se você tiver interesse em enviar um recurso para ser incluído aqui, sinta-se à vontade para abrir um Pull Request e faremos a revisão! O recurso deve, idealmente, demonstrar algo novo, em vez de duplicar um recurso existente.

## ResNetConfig[[transformers.ResNetConfig]]

#### transformers.ResNetConfig[[transformers.ResNetConfig]]

```python
transformers.ResNetConfig(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, embedding_size: int = 64, hidden_sizes: list[int] | tuple[int, ...] | None = (256, 512, 1024, 2048), depths: list[int] | tuple[int, ...] | None = (3, 4, 6, 3), layer_type: str = 'bottleneck', hidden_act: str = 'relu', downsample_in_first_stage: bool = False, downsample_in_bottleneck: bool = False)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/resnet/configuration_resnet.py#L27)

**Parâmetros:**

num_channels (`int`, *opcional*, padrão `3`) : O número de canais de entrada.

embedding_size (`int`, *opcional*, padrão `64`) : Dimensionalidade dos embeddings e dos estados ocultos.

hidden_sizes (`Union[list[int], tuple[int, ...]]`, *opcional*, padrão `(256, 512, 1024, 2048)`) : Dimensionalidade (tamanho oculto) em cada etapa do modelo.

depths (`Union[list[int], tuple[int, ...]]`, *opcional*, padrão `(3, 4, 6, 3)`) : Profundidade de cada camada no Transformer.

layer_type (`str`, *opcional*, padrão `"bottleneck"`) : A camada a ser usada, pode ser `"basic"` (usada para modelos menores, como resnet-18 ou resnet-34) ou `"bottleneck"` (usada para modelos maiores, como resnet-50 e superiores).

hidden_act (`str`, *opcional*, padrão `relu`) : A função de ativação não linear (função ou string) no decodificador. Por exemplo, `"gelu"`, `"relu"`, `"silu"`, etc.

downsample_in_first_stage (`bool`, *opcional*, padrão `False`) : Se `True`, a primeira etapa reduzirá a resolução das entradas usando um `stride` de 2.

downsample_in_bottleneck (`bool`, *opcional*, padrão `False`) : Se `True`, a primeira conv 1x1 em ResNetBottleNeckLayer fará o downsampling das entradas usando um `stride` de 2.

Esta é a classe de configuração para armazenar a configuração de um ResNetModel. Ela é usada para instanciar um modelo Resnet 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 [microsoft/resnet-50](https://huggingface.co/microsoft/resnet-50)

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 ResNetConfig, ResNetModel

>>> # Initializing a ResNet resnet-50 style configuration
>>> configuration = ResNetConfig()

>>> # Initializing a model (with random weights) from the resnet-50 style configuration
>>> model = ResNetModel(configuration)

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

#### validate_layer_type[[transformers.ResNetConfig.validate_layer_type]]

```python
validate_layer_type()
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/resnet/configuration_resnet.py#L72)

Verifique se `layer_types` está definido corretamente.

## ResNetModel[[transformers.ResNetModel]]

#### transformers.ResNetModel[[transformers.ResNetModel]]

```python
transformers.ResNetModel(config: ResNetConfig)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/resnet/modeling_resnet.py#L291)

**Parâmetros:**

config ([ResNetConfig](/docs/transformers/main/pt/model_doc/resnet#transformers.ResNetConfig)) : Classe de configuração do modelo com todos os parâmetros do modelo. A inicialização com um arquivo de configuração não carrega os pesos associados ao modelo, apenas a configuração. Consulte o método [from_pretrained()](/docs/transformers/main/pt/main_classes/model#transformers.PreTrainedModel.from_pretrained) para carregar os pesos do modelo.

O modelo Resnet puro que produz estados ocultos brutos, sem nenhum cabeçalho específico no topo.

Este modelo herda de [PreTrainedModel](/docs/transformers/main/pt/main_classes/model#transformers.PreTrainedModel). Consulte a documentação da classe pai para os métodos genéricos que a biblioteca implementa para todos os seus modelos (como download ou salvamento, redimensionamento dos embeddings de entrada, poda de cabeças, etc.).

Este modelo também é uma subclasse de [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) do PyTorch. Use-o como um Módulo PyTorch regular e consulte a documentação do PyTorch para todos os assuntos relacionados ao uso e comportamento gerais.

#### forward[[transformers.ResNetModel.forward]]

```python
forward(pixel_values: Tensor, output_hidden_states: bool | None = None, return_dict: bool | None = None, **kwargs)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/resnet/modeling_resnet.py#L301)

**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 [ConvNextImageProcessor](/docs/transformers/main/pt/model_doc/convnext#transformers.ConvNextImageProcessor). Veja [ConvNextImageProcessor.__call__()](/docs/transformers/main/pt/model_doc/molmo2#transformers.Molmo2ImageProcessor.__call__) para detalhes (`processor_class` usa [ConvNextImageProcessor](/docs/transformers/main/pt/model_doc/convnext#transformers.ConvNextImageProcessor) para processar imagens).

output_hidden_states (`bool`, *opcional*) : Indica se os estados ocultos de todas as camadas devem ser retornados. Consulte `hidden_states` em tensores retornados para mais detalhes.

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.

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

Um `BaseModelOutputWithPoolingAndNoAttention` 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 ([ResNetConfig](/docs/transformers/main/pt/model_doc/resnet#transformers.ResNetConfig)) e das entradas.

O método forward do [ResNetModel](/docs/transformers/main/pt/model_doc/resnet#transformers.ResNetModel) 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.

- **last_hidden_state** (`torch.Tensor` de forma `(batch_size, num_channels, height, width)`) -- Sequência de estados ocultos na saída da última camada do modelo.
- **pooler_output** (`torch.Tensor` de forma `(batch_size, hidden_size)`) -- Estado oculto da última camada após uma operação de pooling nas dimensões espaciais.
- **hidden_states** (`tuple(torch.Tensor)`, *opcional*, retornado quando `output_hidden_states=True` é passado ou quando `config.output_hidden_states=True`) -- Tupla de `torch.Tensor` (um para a saída dos embeddings, se o modelo tiver uma camada de embedding, + um para a saída de cada camada) com a forma `(batch_size, num_channels, height, width)`.

  Estados ocultos do modelo na saída de cada camada, além das saídas opcionais do embedding inicial.

Exemplo:

```python
```

## ResNetForImageClassification[[transformers.ResNetForImageClassification]]

#### transformers.ResNetForImageClassification[[transformers.ResNetForImageClassification]]

```python
transformers.ResNetForImageClassification(config: ResNetConfig)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/resnet/modeling_resnet.py#L340)

**Parâmetros:**

config ([ResNetConfig](/docs/transformers/main/pt/model_doc/resnet#transformers.ResNetConfig)) : Classe de configuração do modelo com todos os parâmetros do modelo. A inicialização com um arquivo de configuração não carrega os pesos associados ao modelo, apenas a configuração. Consulte o método [from_pretrained()](/docs/transformers/main/pt/main_classes/model#transformers.PreTrainedModel.from_pretrained) para carregar os pesos do modelo.

Modelo ResNet com uma cabeça de classificação de imagem no topo (uma camada linear no topo dos recursos agregados), por exemplo, para o ImageNet.

Este modelo herda de [PreTrainedModel](/docs/transformers/main/pt/main_classes/model#transformers.PreTrainedModel). Consulte a documentação da classe pai para os métodos genéricos que a biblioteca implementa para todos os seus modelos (como download ou salvamento, redimensionamento dos embeddings de entrada, poda de cabeças, etc.).

Este modelo também é uma subclasse de [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) do PyTorch. Use-o como um Módulo PyTorch regular e consulte a documentação do PyTorch para todos os assuntos relacionados ao uso e comportamento gerais.

#### forward[[transformers.ResNetForImageClassification.forward]]

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

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/resnet/modeling_resnet.py#L353)

**Parâmetros:**

pixel_values (`torch.Tensor` de forma `(batch_size, num_channels, image_size, image_size)`, *opcional*) : Os tensores correspondentes às imagens de entrada. Os valores de pixels podem ser obtidos usando [ConvNextImageProcessor](/docs/transformers/main/pt/model_doc/convnext#transformers.ConvNextImageProcessor). Consulte [ConvNextImageProcessor.__call__()](/docs/transformers/main/pt/model_doc/molmo2#transformers.Molmo2ImageProcessor.__call__) para obter detalhes (`processor_class` usa [ConvNextImageProcessor](/docs/transformers/main/pt/model_doc/convnext#transformers.ConvNextImageProcessor) 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 classificação é calculada (Cross-Entropy).

output_hidden_states (`bool`, *opcional*) : Indica se os estados ocultos de todas as camadas devem ser retornados. Consulte `hidden_states` em tensores retornados para mais detalhes.

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.

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

Um [ImageClassifierOutputWithNoAttention](/docs/transformers/main/pt/main_classes/output#transformers.modeling_outputs.ImageClassifierOutputWithNoAttention) 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 ([ResNetConfig](/docs/transformers/main/pt/model_doc/resnet#transformers.ResNetConfig)) e das entradas.

O método forward de [ResNetForImageClassification](/docs/transformers/main/pt/model_doc/resnet#transformers.ResNetForImageClassification) 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` (um para a saída dos embeddings, se o modelo tiver uma camada de embedding, + um para a saída de cada estágio) de forma `(batch_size, num_channels, height, width)`. Estados ocultos (também chamados de mapas de características) do modelo na saída de cada estágio.

Exemplo:

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

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

>>> image_processor = AutoImageProcessor.from_pretrained("microsoft/resnet-50")
>>> model = ResNetForImageClassification.from_pretrained("microsoft/resnet-50")

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