# TimmWrapper

## 개요

transformers 라이브러리 및 그 autoclasses와 함께 timm 모델을 로드할 수 있도록 하는 헬퍼 클래스입니다.

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

## 리소스

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

- [예제 Notebook 모음](https://github.com/ariG23498/timm-wrapper-examples) 🌎

> [!TIP]
> timm 통합에 대한 보다 자세한 개요는 [공식 블로그 게시물](https://huggingface.co/blog/timm-transformers)을 참고하세요.

## 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`) : `TimmWrapperModel`의 last_hidden_state에 대해 풀링을 수행할지 여부.

model_args (`dict[str, Any]`, *선택 사항*) : `timm.create_model` 함수에 전달할 추가 키워드 인수입니다. 예를 들어 `timm/vit_base_patch32_clip_448.laion2b_ft_in12k_in1k`의 경우 `model_args={"depth": 3}`을 사용하여 3개의 블록을 가진 모델을 생성할 수 있습니다. 기본값은 `None`입니다.

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

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 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]`, *선택 사항*) : 모델의 아키텍처 이름.

transformers 내에서 timm 모델을 사용하기 위한 래퍼 클래스입니다.

#### 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`) : 전처리할 이미지. 단일 이미지 또는 이미지 배치(batch)를 기대합니다

return_tensors (`str` 또는 `TensorType`, *선택 사항*) : 반환할 텐서의 유형입니다.

이미지 또는 이미지 배치(batch)를 전처리합니다.

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

transformers에서 사용할 timm 모델을 위한 래퍼 클래스

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

output_attentions (`bool`, *선택 사항*) : 모든 attention 레이어의 attentions 텐서를 반환할지 여부. timm 래핑된 모델과 호환되지 않습니다.

output_hidden_states (`bool`, *선택 사항*) : 모든 레이어의 hidden states를 반환할지 여부. timm 래핑된 모델과 호환되지 않습니다.

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

do_pooling (`bool`, *선택 사항*) : `TimmWrapperModel`의 last_hidden_state에 대해 풀링을 수행할지 여부입니다. `None`이 전달되면 config의 `do_pooling` 값이 사용됩니다.

use_cache (`bool`, *선택 사항*) : `True`로 설정하면 `past_key_values` 키 값 상태가 반환되며, 디코딩 속도를 높이는 데 사용할 수 있습니다(`past_key_values` 참조).

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

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

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

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

- **last_hidden_state** (`torch.Tensor`) -- 분류 헤드를 적용하기 전에 출력되는 모델의 마지막 히든 상태입니다.
- **pooler_output** (`torch.Tensor`, *선택 사항*) -- 적용 가능한 경우, 마지막 숨겨진 상태(last hidden state)에서 파생된 풀링된 출력입니다.
- **hidden_states** (`tuple(torch.Tensor)`, *선택 사항*, `output_hidden_states=True`가 설정되었거나 `config.output_hidden_states=True`인 경우 반환됨) -- 각 레이어 또는 지정된 레이어의 출력에서 모델의 중간 hidden states를 포함하는 튜플입니다.
- **attentions** (`tuple(torch.Tensor)`, *선택 사항*, `output_attentions=True`가 설정되었거나 `config.output_attentions=True`인 경우 반환됨) -- 각 레이어 출력에서 모델의 중간 어텐션 가중치를 포함하는 튜플입니다. 참고: 현재 Timm 모델은 attentions 출력을 지원하지 않습니다.

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

이미지 분류를 위해 transformers에서 timm 모델을 사용할 때 사용하는 래퍼 클래스입니다.

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

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

output_attentions (`bool`, *선택 사항*) : 모든 attention 레이어의 attentions 텐서를 반환할지 여부. timm 래핑된 모델과 호환되지 않습니다.

output_hidden_states (`bool`, *선택 사항*) : 모든 레이어의 hidden states를 반환할지 여부. timm 래핑된 모델과 호환되지 않습니다.

return_dict (`bool`, *선택 사항*) : 일반 튜플 대신 [ModelOutput](/docs/transformers/main/ko/main_classes/output#transformers.utils.ModelOutput)를 반환할지 여부. **kwargs: `timm` 모델의 forward에 전달되는 추가 키워드 인자.

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

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

[TimmWrapperForImageClassification](/docs/transformers/main/ko/model_doc/timm_wrapper#transformers.TimmWrapperForImageClassification)의 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, sequence_length, hidden_size)`입니다. 각 단계 출력 시점의 모델 hidden-states(또는 feature maps)입니다.
- **attentions** (`tuple(torch.Tensor)`, *선택 사항*, `output_attentions=True`가 전달되었거나 `config.output_attentions=True`인 경우 반환) -- 각 레이어당 하나씩, shape가 `(batch_size, num_heads, patch_size, sequence_length)`인 `torch.Tensor`의 튜플.

  self-attention 헤드에서 가중 평균을 계산하는 데 사용되는 attention softmax 이후의 attention 가중치입니다.

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