# TimmWrapper

## 概要

transformers ライブラリとそのオートクラスで利用できるように、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公式およびコミュニティ（🌎で示されます）のリソースのリストです。

- [サンプルノートブックのコレクション](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` で 3 ブロックのモデルを作成するには `model_args={"depth": 3}` を指定します。デフォルトは `None` です。

これは、TimmWrapperModel の設定を保存するための設定クラスです。指定された引数に基づいて Timm Wrapper モデルをインスタンス化し、モデルのアーキテクチャを定義するために使用されます。デフォルト値で設定をインスタンス化すると、[resnet50](https://huggingface.co/resnet50) と同様の設定が得られます。

設定オブジェクトは [PreTrainedConfig](/docs/transformers/main/ja/main_classes/configuration#transformers.PreTrainedConfig) を継承し、モデルの出力を制御するために使用できます。詳細については、[PreTrainedConfig](/docs/transformers/main/ja/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[str, typing.Any], 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#L95)

**パラメータ:**

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)

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`、形状 `(batch_size, num_channels, image_size, image_size)`) : 入力画像に対応するテンソルです。ピクセル値は [TimmWrapperImageProcessor](/docs/transformers/main/ja/model_doc/timm_wrapper#transformers.TimmWrapperImageProcessor) を使用して取得できます。詳細は [TimmWrapperImageProcessor.__call__()](/docs/transformers/main/ja/model_doc/molmo2#transformers.Molmo2ImageProcessor.__call__) を参照してください（`processor_class` は画像の処理に [TimmWrapperImageProcessor](/docs/transformers/main/ja/model_doc/timm_wrapper#transformers.TimmWrapperImageProcessor) を使用します）。

output_attentions (`bool`, *任意*) : 全アテンション層のアテンションテンソルを返すかどうか。timmでラップされたモデルとは互換性がありません。

output_hidden_states (`bool`, *任意*) : 全レイヤーの隠れ状態を返すかどうか。timmでラップされたモデルとは互換性がありません。

return_dict (`bool`, *任意*) : プレーンなタプルではなく [ModelOutput](/docs/transformers/main/ja/main_classes/output#transformers.utils.ModelOutput) を返すかどうか。

do_pooling (`bool`, *optional*) : Whether to do pooling for the last_hidden_state in `TimmWrapperModel` or not. If `None` is passed, the `do_pooling` value from the config is used.

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/ja/model_doc/timm_wrapper#transformers.TimmWrapperConfig)および入力に応じて、さまざまな要素で構成されます。

[TimmWrapperModel](/docs/transformers/main/ja/model_doc/timm_wrapper#transformers.TimmWrapperModel)のforwardメソッドは、`__call__`特殊メソッドをオーバーライドします。

この関数内でフォワードパスの手順を定義する必要がありますが、その後、この関数ではなく`Module`インスタンスを呼び出すべきです。前者は前処理と後処理の実行を適切に処理するのに対し、後者はそれらを無視してしまいます。

- **last_hidden_state** (`torch.Tensor`) -- 分類ヘッドを適用する前のモデルの最後の隠れ状態です。
- **pooler_output** (`torch.Tensor`, *optional*) -- 適用可能な場合、最後の隠れ状態から導出されたプーリング済み出力です。
- **hidden_states** (`tuple(torch.Tensor)`、*optional*、`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)

画像分類用の 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`、形状 `(batch_size, num_channels, image_size, image_size)`) : 入力画像に対応するテンソルです。ピクセル値は [TimmWrapperImageProcessor](/docs/transformers/main/ja/model_doc/timm_wrapper#transformers.TimmWrapperImageProcessor) を使用して取得できます。詳細は [TimmWrapperImageProcessor.__call__()](/docs/transformers/main/ja/model_doc/molmo2#transformers.Molmo2ImageProcessor.__call__) を参照してください（`processor_class` は画像の処理に [TimmWrapperImageProcessor](/docs/transformers/main/ja/model_doc/timm_wrapper#transformers.TimmWrapperImageProcessor) を使用します）。

labels (`torch.LongTensor`、shape `(batch_size,)`、*任意*) : 画像分類/回帰の損失を計算するためのラベル。インデックスは `[0, ..., config.num_labels - 1]` の範囲である必要があります。`config.num_labels == 1` の場合は回帰損失（Mean-Square loss）が計算され、`config.num_labels > 1` の場合は分類損失（Cross-Entropy）が計算されます。

output_attentions (`bool`, *任意*) : 全アテンション層のアテンションテンソルを返すかどうか。timmでラップされたモデルとは互換性がありません。

output_hidden_states (`bool`, *任意*) : 全レイヤーの隠れ状態を返すかどうか。timmでラップされたモデルとは互換性がありません。

return_dict (`bool`, *任意*) : プレーンなタプルではなく [ModelOutput](/docs/transformers/main/ja/main_classes/output#transformers.utils.ModelOutput) を返すかどうか。`timm` モデルの forward に渡される追加のキーワード引数。

**戻り値:** [ImageClassifierOutput](/docs/transformers/main/ja/main_classes/output#transformers.modeling_outputs.ImageClassifierOutput) または `tuple(torch.Tensor)`

設定（[TimmWrapperConfig](/docs/transformers/main/ja/model_doc/timm_wrapper#transformers.TimmWrapperConfig)）や入力に応じて、さまざまな要素で構成される [ImageClassifierOutput](/docs/transformers/main/ja/main_classes/output#transformers.modeling_outputs.ImageClassifierOutput)、または `torch.Tensor` のタプル（`return_dict=False` が渡された場合、または `config.return_dict=False` の場合）。

[TimmWrapperForImageClassification](/docs/transformers/main/ja/model_doc/timm_wrapper#transformers.TimmWrapperForImageClassification)のforwardメソッドは、`__call__`特殊メソッドをオーバーライドします。

この関数内でフォワードパスの手順を定義する必要がありますが、その後、この関数ではなく`Module`インスタンスを呼び出すべきです。前者は前処理と後処理の実行を適切に処理するのに対し、後者はそれらを無視してしまいます。

- **loss** (`torch.Tensor`、shape `(1,)`、*optional*、`labels` が指定された場合に返されます) -- 分類損失（config.num_labels==1 の場合は回帰損失）。
- **logits** (`torch.Tensor`、形状 `(batch_size, config.num_labels)`) -- SoftMax 適用前の分類（または config.num_labels==1 の場合は回帰）スコア。
- **hidden_states** (`tuple(torch.Tensor)`、*optional*、`output_hidden_states=True` が渡された場合または `config.output_hidden_states=True` の場合に返されます) -- `torch.Tensor` のタプル（モデルに埋め込み層がある場合はその出力用 1 つ、各ステージの出力用 1 つずつ）で、形状は `(batch_size, sequence_length, hidden_size)` です。各ステージの出力におけるモデルの隠れ状態（特徴マップとも呼ばれます）。
- **attentions** (`tuple(torch.Tensor)`、*optional*、`output_attentions=True` が渡された場合または `config.output_attentions=True` の場合に返されます) -- `torch.Tensor` のタプル（各レイヤーごとに1つ）、形状は `(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)
```