# 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` 畳み込みで `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/ja/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の最初の1x1畳み込みが`stride` 2を使用して入力をダウンサンプリングします。

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

設定オブジェクトは [PreTrainedConfig](/docs/transformers/main/ja/main_classes/configuration#transformers.PreTrainedConfig) を継承し、モデルの出力を制御するために使用できます。詳細については、[PreTrainedConfig](/docs/transformers/main/ja/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/ja/model_doc/resnet#transformers.ResNetConfig)) : モデルのパラメータをすべて含むモデル設定クラスです。設定ファイルで初期化しても、モデルに関連する重みは読み込まれず、設定のみが読み込まれます。モデルの重みをロードするには、[from_pretrained()](/docs/transformers/main/ja/main_classes/model#transformers.PreTrainedModel.from_pretrained) メソッドを確認してください。

特定のヘッドを付加せず、生のhidden-statesを出力する素のResnetモデル。

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

output_hidden_states (`bool`, *任意*) : 全レイヤーの hidden states を返すかどうかを指定します。詳細は、返されるテンソルの `hidden_states` を参照してください。

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

**戻り値:** `BaseModelOutputWithPoolingAndNoAttention` または `tuple(torch.Tensor)`

`BaseModelOutputWithPoolingAndNoAttention`、または`torch.Tensor`のタプル（`return_dict=False`が渡された場合、または`config.return_dict=False`の場合）。設定（[ResNetConfig](/docs/transformers/main/ja/model_doc/resnet#transformers.ResNetConfig)）と入力に応じて、さまざまな要素で構成されます。

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

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

- **last_hidden_state** (`torch.Tensor`、形状 `(batch_size, num_channels, height, width)`) -- モデルの最終層の出力における隠れ状態のシーケンス。
- **pooler_output** (`torch.Tensor`、形状 `(batch_size, hidden_size)`) -- 空間次元に対するプーリング操作を行った後の最終層の隠れ状態。
- **hidden_states** (`tuple(torch.Tensor)`、*optional*、`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/ja/model_doc/resnet#transformers.ResNetConfig)) : モデルのパラメータをすべて含むモデル設定クラスです。設定ファイルで初期化しても、モデルに関連する重みは読み込まれず、設定のみが読み込まれます。モデルの重みをロードするには、[from_pretrained()](/docs/transformers/main/ja/main_classes/model#transformers.PreTrainedModel.from_pretrained) メソッドを確認してください。

画像分類ヘッド（プーリングされた特徴量の上に配置された線形層）を備えたResNetモデル。ImageNetなどでの使用例。

このモデルは [PreTrainedModel](/docs/transformers/main/ja/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`、形状 `(batch_size, num_channels, image_size, image_size)`、*任意*) : 入力画像に対応するテンソルです。ピクセル値は [ConvNextImageProcessor](/docs/transformers/main/ja/model_doc/convnext#transformers.ConvNextImageProcessor) を使用して取得できます。詳細については [ConvNextImageProcessor.__call__()](/docs/transformers/main/ja/model_doc/molmo2#transformers.Molmo2ImageProcessor.__call__) を参照してください（`processor_class` は画像の処理に [ConvNextImageProcessor](/docs/transformers/main/ja/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/ja/main_classes/output#transformers.utils.ModelOutput) を返すかどうか。

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

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

[ResNetForImageClassification](/docs/transformers/main/ja/model_doc/resnet#transformers.ResNetForImageClassification) の 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, num_channels, height, width)` です。各ステージの出力におけるモデルの隠れ状態（特徴マップとも呼ばれます）。

例:

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