# ResNet

## 개요

ResNet 모델은 Kaiming He, Xiangyu Zhang, Shaoqing Ren, Jian Sun이 [Deep Residual Learning for Image Recognition](https://huggingface.co/papers/1512.03385)에서 제안했습니다. 저희 구현은 [Nvidia](https://catalog.ngc.nvidia.com/orgs/nvidia/resources/resnet_50_v1_5_for_pytorch)가 적용한 작은 변경 사항을 따르며, bottleneck의 `3x3` conv에서 `stride=2`를 다운샘플링에 사용하고 첫 번째 `1x1`에서는 사용하지 않습니다. 이는 일반적으로 "ResNet v1.5"로 알려져 있습니다.

ResNet은 잔차 연결을 도입하여, 이전에 볼 수 없었던 층 수(최대 1000개)까지의 네트워크를 학습할 수 있게 했습니다. ResNet은 2015년 ILSVRC & COCO 경연에서 우승하여, 딥 컴퓨터 비전의 중요한 이정표를 세웠습니다.

해당 논문의 초록은 다음과 같습니다:

*더 깊은 신경망은 학습이 더 어렵습니다. 이전에 사용되었던 것보다 훨씬 더 깊은 네트워크의 학습을 용이하게 하기 위해 잔차 학습 프레임워크를 제시합니다. 레이어를 참조되지 않는 함수를 학습하는 대신 레이어 입력을 기준으로 잔차 함수를 학습하도록 명시적으로 재구성합니다. 이러한 잔차 네트워크가 최적화하기가 더 쉽고, 상당한 깊이 증가로 정확도를 향상시킬 수 있음을 보여주는 포괄적인 실증적 증거를 제공합니다. ImageNet 데이터셋에서 최대 152층 깊이의 잔차 네트워크를 평가했는데, 이는 VGG 네트워크보다 8배 더 깊지만 여전히 복잡도가 더 낮습니다. 이러한 잔차 네트워크의 앙상블은 ImageNet 테스트 세트에서 3.57%의 오류를 달성했습니다. 이 결과는 ILSVRC 2015 분류 작업에서 1위를 차지했습니다. 또한 100층과 1000층에 대한 CIFAR-10 분석을 제시합니다. 표현의 깊이는 많은 시각 인식 작업에서 핵심적인 중요성을 가집니다. 극도로 깊은 표현 덕분에 COCO 객체 감지 데이터셋에서 28%의 상대적 개선을 얻었습니다. 깊은 잔차 네트워크는 ILSVRC & COCO 2015 대회에 제출한 기반이 되었으며, ImageNet 감지, ImageNet 위치 파악, COCO 감지, COCO 분할 작업에서도 1위를 차지했습니다.*

아래 그림은 ResNet의 아키텍처를 보여줍니다. [원 논문](https://huggingface.co/papers/1512.03385)에서 가져왔습니다.

이 모델은 [Francesco](https://huggingface.co/Francesco)가 기여했습니다. 원본 코드는 [여기](https://github.com/KaimingHe/deep-residual-networks)에서 찾을 수 있습니다.

## 리소스

ResNet을 시작하는 데 도움이 되는 공식 Hugging Face 및 커뮤니티(🌎로 표시) 리소스 목록입니다.

- [ResNetForImageClassification](/docs/transformers/main/ko/model_doc/resnet#transformers.ResNetForImageClassification)은 이 [노트북](https://colab.research.google.com/github/huggingface/notebooks/blob/main/examples/image_classification.ipynb)에서 지원됩니다.
- 참고: [이미지 분류 작업 가이드](../tasks/image_classification)

여기에 포함할 리소스를 제출하고 싶으시면 Pull Request를 열어 주시면 검토하겠습니다! 기존 리소스와 중복되지 않고 새로운 것을 보여주는 것이 이상적입니다.

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

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

**매개변수:**

num_channels (`int`, *선택 사항*, 기본값 `3`) : 입력 채널의 수입니다.

embedding_size (`int`, *선택 사항*, 기본값 `64`) : 임베딩 및 숨겨진 상태의 차원.

hidden_sizes (`Union[list[int], tuple[int, ...]]`, *선택 사항*, 기본값 `(256, 512, 1024, 2048)`) : 모델의 각 단계별 차원(숨겨진 크기).

depths (`Union[list[int], tuple[int, ...]]`, *선택 사항*, 기본값 `(3, 4, 6, 3)`) : Transformer의 각 레이어 깊이.

layer_type (`str`, *선택 사항*, 기본값 `"bottleneck"`) : 사용할 레이어입니다. `"basic"`(resnet-18 또는 resnet-34와 같은 작은 모델에 사용) 또는 `"bottleneck"`(resnet-50 이상의 큰 모델에 사용) 중 하나를 지정할 수 있습니다.

hidden_act (`str`, *선택 사항*, 기본값 `relu`) : 디코더의 비선형 활성화 함수(함수 또는 문자열). 예를 들어, `"gelu"`, `"relu"`, `"silu"` 등.

downsample_in_first_stage (`bool`, *선택 사항*, 기본값 `False`) : `True`인 경우, 첫 번째 단계에서 `stride` 2를 사용하여 입력을 다운샘플링합니다.

downsample_in_bottleneck (`bool`, *선택 사항*, 기본값 `False`) : `True`인 경우, ResNetBottleNeckLayer의 첫 번째 conv 1x1이 `stride` 2를 사용하여 입력을 다운샘플링합니다.

이것은 ResNetModel의 구성을 저장하기 위한 구성 클래스입니다. 지정된 인자에 따라 Resnet 모델을 인스턴스화하여 모델 아키텍처를 정의하는 데 사용됩니다. 기본값으로 구성을 인스턴스화하면 [microsoft/resnet-50](https://huggingface.co/microsoft/resnet-50)의 구성과 유사한 구성이 생성됩니다.

Configuration 객체는 [PreTrainedConfig](/docs/transformers/main/ko/main_classes/configuration#transformers.PreTrainedConfig)를 상속하며, 모델 출력을 제어하는 데 사용할 수 있습니다. 자세한 내용은 [PreTrainedConfig](/docs/transformers/main/ko/main_classes/configuration#transformers.PreTrainedConfig)의 문서를 참고하세요.

예:
```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()
```

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

`layer_types`가 올바르게 정의되어 있는지 확인하세요.

## ResNetModel[[transformers.ResNetModel]]

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

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

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

**매개변수:**

config ([ResNetConfig](/docs/transformers/main/ko/model_doc/resnet#transformers.ResNetConfig)) : 모델의 모든 매개변수를 포함하는 모델 구성 클래스입니다. 구성 파일로 초기화하는 것은 모델과 관련된 가중치를 로드하지 않으며, 구성 정보만 로드합니다. 모델 가중치를 로드하려면 [from_pretrained()](/docs/transformers/main/ko/main_classes/model#transformers.PreTrainedModel.from_pretrained) 메서드를 확인하세요.

특정 헤드가 위에 없는 상태에서 원시 hidden-states를 출력하는 기본 Resnet 모델입니다.

이 모델은 [PreTrainedModel](/docs/transformers/main/ko/main_classes/model#transformers.PreTrainedModel)에서 상속됩니다. 라이브러리가 모든 모델에 대해 구현하는 일반적 메서드(다운로드 또는 저장, 입력 임베딩 크기 조정, 헤드 프루닝 등)에 대해서는 상위 클래스 문서를 확인하세요.

이 모델은 또한 PyTorch [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module)의 하위 클래스입니다. 일반적인 PyTorch Module처럼 사용하며, 일반적인 사용법과 동작에 관한 모든 사항은 PyTorch 문서를 참조하세요.

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

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

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

**매개변수:**

pixel_values (`torch.Tensor`, shape `(batch_size, num_channels, image_size, image_size)`) : 입력 이미지에 해당하는 텐서입니다. 픽셀 값은 [ConvNextImageProcessor](/docs/transformers/main/ko/model_doc/convnext#transformers.ConvNextImageProcessor)를 사용하여 얻을 수 있습니다. 자세한 내용은 [ConvNextImageProcessor.__call__()](/docs/transformers/main/ko/model_doc/molmo2#transformers.Molmo2ImageProcessor.__call__)를 참조하세요 (`processor_class`는 이미지 처리에 [ConvNextImageProcessor](/docs/transformers/main/ko/model_doc/convnext#transformers.ConvNextImageProcessor)를 사용합니다).

output_hidden_states (`bool`, *선택 사항*) : 모든 레이어의 hidden states를 반환할지 여부. 자세한 내용은 반환되는 텐서 중 `hidden_states` 항목을 참조하세요.

return_dict (`bool`, *선택 사항*) : 일반 튜플 대신 [ModelOutput](/docs/transformers/main/ko/main_classes/output#transformers.utils.ModelOutput)를 반환할지 여부.

**반환값:** `BaseModelOutputWithPoolingAndNoAttention` 또는 `tuple(torch.Tensor)`

`BaseModelOutputWithPoolingAndNoAttention` 또는 `torch.Tensor`의 튜플(`return_dict=False`가 전달되거나 `config.return_dict=False`인 경우)로, 구성([ResNetConfig](/docs/transformers/main/ko/model_doc/resnet#transformers.ResNetConfig)) 및 입력에 따라 다양한 요소를 포함합니다.

[ResNetModel](/docs/transformers/main/ko/model_doc/resnet#transformers.ResNetModel)의 forward 메서드는 `__call__` 특수 메서드를 오버라이드합니다.

`Module` 인스턴스는 전처리 및 후처리 단계를 실행하는 것을 처리하지만, 이 함수는 해당 단계를 조용히 무시하므로, 순전파(forward pass) 레시피를 이 함수 내에서 정의해야 하더라도 이후에는 이 함수 대신 `Module` 인스턴스를 호출해야 합니다.

- **last_hidden_state** (`torch.Tensor`, shape `(batch_size, num_channels, height, width)`) -- 모델의 마지막 레이어 출력에서 생성된 hidden-state 시퀀스입니다.
- **pooler_output** (`torch.Tensor`, shape `(batch_size, hidden_size)`) -- 공간 차원에 대해 풀링 연산을 수행한 후의 마지막 레이어 hidden-state입니다.
- **hidden_states** (`tuple(torch.Tensor)`, *선택 사항*, `output_hidden_states=True`가 전달되었거나 `config.output_hidden_states=True`인 경우 반환됨) -- `torch.Tensor`의 튜플(모델에 임베딩 레이어가 있는 경우 임베딩 출력 1개 + 각 레이어의 출력 1개)로, 모양은 `(batch_size, num_channels, height, width)`입니다.

  각 레이어의 출력에서 모델의 Hidden-states와 선택적 초기 임베딩 출력을 포함합니다.

예:

```python
```

## ResNetForImageClassification[[transformers.ResNetForImageClassification]]

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

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

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

**매개변수:**

config ([ResNetConfig](/docs/transformers/main/ko/model_doc/resnet#transformers.ResNetConfig)) : 모델의 모든 매개변수를 포함하는 모델 구성 클래스입니다. 구성 파일로 초기화하는 것은 모델과 관련된 가중치를 로드하지 않으며, 구성 정보만 로드합니다. 모델 가중치를 로드하려면 [from_pretrained()](/docs/transformers/main/ko/main_classes/model#transformers.PreTrainedModel.from_pretrained) 메서드를 확인하세요.

ResNet 모델 위에 이미지 분류 헤드를 추가한 구조(풀링된 특징 위에 선형 레이어를 배치), 예: ImageNet

이 모델은 [PreTrainedModel](/docs/transformers/main/ko/main_classes/model#transformers.PreTrainedModel)에서 상속됩니다. 라이브러리가 모든 모델에 대해 구현하는 일반적 메서드(다운로드 또는 저장, 입력 임베딩 크기 조정, 헤드 프루닝 등)에 대해서는 상위 클래스 문서를 확인하세요.

이 모델은 또한 PyTorch [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module)의 하위 클래스입니다. 일반적인 PyTorch Module처럼 사용하며, 일반적인 사용법과 동작에 관한 모든 사항은 PyTorch 문서를 참조하세요.

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

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

**매개변수:**

pixel_values (`torch.Tensor`, shape `(batch_size, num_channels, image_size, image_size)`, *선택 사항*) : 입력 이미지에 해당하는 텐서입니다. 픽셀 값은 [ConvNextImageProcessor](/docs/transformers/main/ko/model_doc/convnext#transformers.ConvNextImageProcessor)를 사용하여 얻을 수 있습니다. 자세한 내용은 [ConvNextImageProcessor.__call__()](/docs/transformers/main/ko/model_doc/molmo2#transformers.Molmo2ImageProcessor.__call__)를 참조하세요 (`processor_class`는 이미지 처리에 [ConvNextImageProcessor](/docs/transformers/main/ko/model_doc/convnext#transformers.ConvNextImageProcessor)를 사용합니다).

labels (`torch.LongTensor`, shape `(batch_size,)`, *선택 사항*) : 이미지 분류/회귀 손실을 계산하는 데 사용되는 라벨. 인덱스는 `[0, ..., config.num_labels - 1]` 범위에 있어야 합니다. `config.num_labels > 1`인 경우 분류 손실(Cross-Entropy)이 계산됩니다.

output_hidden_states (`bool`, *선택 사항*) : 모든 레이어의 hidden states를 반환할지 여부. 자세한 내용은 반환되는 텐서 중 `hidden_states` 항목을 참조하세요.

return_dict (`bool`, *선택 사항*) : 일반 튜플 대신 [ModelOutput](/docs/transformers/main/ko/main_classes/output#transformers.utils.ModelOutput)를 반환할지 여부.

**반환값:** [ImageClassifierOutputWithNoAttention](/docs/transformers/main/ko/main_classes/output#transformers.modeling_outputs.ImageClassifierOutputWithNoAttention) 또는 `tuple(torch.Tensor)`

구성([ResNetConfig](/docs/transformers/main/ko/model_doc/resnet#transformers.ResNetConfig))과 입력에 따라 다양한 요소를 포함하는 [ImageClassifierOutputWithNoAttention](/docs/transformers/main/ko/main_classes/output#transformers.modeling_outputs.ImageClassifierOutputWithNoAttention) 또는 `torch.Tensor`의 튜플(`return_dict=False`가 전달되거나 `config.return_dict=False`인 경우).

[ResNetForImageClassification](/docs/transformers/main/ko/model_doc/resnet#transformers.ResNetForImageClassification)의 forward 메서드는 `__call__` 특수 메서드를 오버라이드합니다.

`Module` 인스턴스는 전처리 및 후처리 단계를 실행하는 것을 처리하지만, 이 함수는 해당 단계를 조용히 무시하므로, 순전파(forward pass) 레시피를 이 함수 내에서 정의해야 하더라도 이후에는 이 함수 대신 `Module` 인스턴스를 호출해야 합니다.

- **loss** (`torch.Tensor`, shape `(1,)`, *선택*, `labels`이 제공될 때 반환됨) -- 분류(또는 config.num_labels==1인 경우 회귀) 손실.
- **logits** (`torch.Tensor`, shape `(batch_size, config.num_labels)`) -- SoftMax 적용 전 분류(또는 config.num_labels==1인 경우 회귀) 점수.
- **hidden_states** (`tuple(torch.Tensor)`, *선택*, `output_hidden_states=True`가 전달되거나 `config.output_hidden_states=True`인 경우 반환) -- `torch.Tensor`의 튜플(모델에 임베딩 레이어가 있는 경우 임베딩 출력용 1개 + 각 단계 출력용 1개)로, shape은 `(batch_size, num_channels, height, width)`입니다. 각 단계 출력 시점의 모델 hidden-states(또는 feature maps)입니다.

예:

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