# ViTMSN

## 概要

ViTMSNモデルは、Mahmoud Assran、Mathilde Caron、Ishan Misra、Piotr Bojanowski、Florian Bordes、Pascal Vincent、Armand Joulin、Michael Rabbat、Nicolas Ballas による論文 [Masked Siamese Networks for Label-Efficient Learning](https://huggingface.co/papers/2204.07141) で提案されました。この論文では、マスクされたパッチのプロトタイプをマスクされていないパッチのプロトタイプと一致させるためのジョイントエンベディングアーキテクチャが紹介されています。この構成により、低ショットおよび極低ショットの環境で優れたパフォーマンスを発揮します。

論文の抄録は以下の通りです。

*画像表現を学習するための自己教師あり学習フレームワークである Masked Siamese Networks (MSN) を提案します。当社のアプローチでは、ランダムにマスクされたパッチを含む画像ビューの表現と、元のマスクされていない画像の表現を一致させます。この自己教師あり事前学習戦略は、Vision Transformers に適用する場合に特にスケーラビリティが高く、ネットワークが処理するのはマスクされていないパッチのみだからです。その結果、MSN は joint-embedding アーキテクチャのスケーラビリティを向上させると同時に、低ショット画像分類で競争力のある性能を発揮する高セマンティックレベルの表現を生成します。例えば、ImageNet-1K において、アノテーション付き画像をわずか 5,000 枚のみ使用しても、ベースの MSN モデルは 72.4% の top-1 精度を達成し、ImageNet-1K のラベルの 1% を使用すると 75.7% の top-1 精度を達成し、このベンチマークにおける自己教師あり学習の新たな state-of-the-art を樹立しました。*

 MSNアーキテクチャ。元の論文から引用。

このモデルは [sayakpaul](https://huggingface.co/sayakpaul) によって提供されました。元のコードは [こちら](https://github.com/facebookresearch/msn) で確認できます。

## 使用のコツ

- MSN (masked siamese networks)は、Vision Transformers（ViTs）の自己教師あり事前学習を行う手法です。事前学習
目的は、画像のマスキングされていないビューに割り当てられたプロトタイプを、同じ画像のマスキングされたビューのプロトタイプと一致させることです。
- 著者らは、バックボーン（ImageNet-1k事前学習）の事前学習済み重みのみを公開しています。したがって、ご自身の画像分類データセットでそれを使用するには、
[ViTMSNForImageClassification](/docs/transformers/main/ja/model_doc/vit_msn#transformers.ViTMSNForImageClassification) クラスは [ViTMSNModel](/docs/transformers/main/ja/model_doc/vit_msn#transformers.ViTMSNModel) から初期化されます。ファインチューニングの詳細なチュートリアルについては、[このノートブック](https://github.com/huggingface/notebooks/blob/main/examples/image_classification.ipynb)を参照してください。
- MSNは、低ショットおよび極低ショットの環境で特に有用です。特に、ImageNet-1Kのわずか1%
ファインチューニング時のラベル。

### Scaled Dot Product Attention (SDPA) の使用

PyTorchには、`torch.nn.functional`の一部として、ネイティブなスケーリングドットプロダクトアテンション（SDPA）オペレーターが含まれています。この関数は、入力や使用しているハードウェアに応じて適用できる複数の実装を備えています。詳細については、[公式ドキュメント](https://pytorch.org/docs/stable/generated/torch.nn.functional.scaled_dot_product_attention.html)または[GPU推論](https://huggingface.co/docs/transformers/main/en/perf_infer_gpu_one#pytorch-scaled-dot-product-attention)ページを参照してください。

`torch>=2.1.1` の場合、実装が利用可能な場合はデフォルトで SDPA が使用されますが、`from_pretrained()` で `attn_implementation="sdpa"` を設定することで、SDPA の使用を明示的に指定することもできます。

```python
from transformers import ViTMSNForImageClassification

model = ViTMSNForImageClassification.from_pretrained("facebook/vit-msn-base", attn_implementation="sdpa", device_map="auto")
...
```

最大限の高速化を実現するには、モデルを半精度（例: `torch.float16` または `torch.bfloat16`）で読み込むことをお勧めします。

ローカルベンチマーク（A100-40GB、PyTorch 2.3.0、OS Ubuntu 22.04）において、`float32` と `facebook/vit-msn-base` モデルを使用した場合、推論時に以下の速度向上を確認しました。

|   バッチサイズ |   平均推論時間 (ms)、eager モード |   平均推論時間 (ms)、sdpa モデル |   Speed up, Sdpa / Eager (x) |
|--------------|-------------------------------------------|-------------------------------------------|------------------------------|
|            1 |                                         7 |                                         6 |                      1.17 |
|            2 |                                         8 |                                         6 |                      1.33 |
|            4 |                                         8 |                                         6 |                      1.33 |
|            8 |                                         8 |                                         6 |                      1.33 |

## リソース

ViT MSNの入門を支援するための、Hugging Face公式およびコミュニティ（🌎で示されます）のリソースのリストです。

- [ViTMSNForImageClassification](/docs/transformers/main/ja/model_doc/vit_msn#transformers.ViTMSNForImageClassification) は、この [ノートブック](https://colab.research.google.com/github/huggingface/notebooks/blob/main/examples/image_classification.ipynb) でサポートされています。
- 関連項目: [画像分類タスクガイド](../tasks/image_classification)

ここにリソースを掲載していただくことを希望される場合は、Pull Request を開いてください。レビューいたします。リソースは、既存のリソースと重複するのではなく、新しいものを示すことが望ましいです。

## ViTMSNConfig[[transformers.ViTMSNConfig]]

#### transformers.ViTMSNConfig[[transformers.ViTMSNConfig]]

```python
transformers.ViTMSNConfig(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, hidden_size: int = 768, num_hidden_layers: int = 12, num_attention_heads: int = 12, intermediate_size: int = 3072, hidden_act: str = 'gelu', hidden_dropout_prob: float | int = 0.0, attention_probs_dropout_prob: float | int = 0.0, initializer_range: float = 0.02, layer_norm_eps: float = 1e-06, image_size: int | list[int] | tuple[int, int] = 224, patch_size: int | list[int] | tuple[int, int] = 16, num_channels: int = 3, qkv_bias: bool = True)
```

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/models/vit_msn/configuration_vit_msn.py#L24)

**パラメータ:**

hidden_size (`int`、*任意*、デフォルトは`768`) : 隠れ表現の次元数。

num_hidden_layers (`int`, *任意*, デフォルトは `12`) : Transformer デコーダーの隠れ層の数。

num_attention_heads (`int`、*任意*、デフォルトは `12`) : Transformer デコーダーの各アテンション層におけるアテンションヘッドの数。

intermediate_size (`int`、*任意*、デフォルトは `3072`) : MLP 表現の次元数。

hidden_act (`str`、*任意*、デフォルトは`gelu`) : デコーダーで使用する非線形活性化関数（関数または文字列）。例えば、`"gelu"`、`"relu"`、`"silu"`など。

hidden_dropout_prob (`Union[float, int]`、*任意*、デフォルトは`0.0`) : embeddings、encoder、pooler 内のすべての全結合層における dropout 確率。

attention_probs_dropout_prob (`Union[float, int]`、*任意*、デフォルトは`0.0`) : 注意確率のドロップアウト率。

initializer_range (`float`、*任意*、デフォルトは`0.02`) : すべての重み行列を初期化するためのtruncated_normal_initializerの標準偏差です。

layer_norm_eps (`float`、*任意*、デフォルトは`1e-06`) : Layer Normalization 層で使用する epsilon です。

image_size (`Union[int, list[int], tuple[int, int]]`、*任意*、デフォルトは`224`) : 各画像のサイズ（解像度）。

patch_size (`Union[int, list[int], tuple[int, int]]`、*任意*、デフォルトは`16`) : 各パッチのサイズ（解像度）。

num_channels (`int`、*任意*、デフォルトは`3`) : 入力チャネル数。

qkv_bias (`bool`, *任意*, デフォルトは `True`) : クエリ、キー、バリューにバイアスを追加するかどうか。

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

設定オブジェクトは [PreTrainedConfig](/docs/transformers/main/ja/main_classes/configuration#transformers.PreTrainedConfig) を継承し、モデルの出力を制御するために使用できます。詳細については、[PreTrainedConfig](/docs/transformers/main/ja/main_classes/configuration#transformers.PreTrainedConfig) のドキュメントを参照してください。

例:

```python
>>> from transformers import ViTMSNModel, ViTMSNConfig

>>> # Initializing a ViT MSN vit-msn-base style configuration
>>> configuration = ViTConfig()

>>> # Initializing a model from the vit-msn-base style configuration
>>> model = ViTMSNModel(configuration)

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

## ViTMSNModel[[transformers.ViTMSNModel]]

#### transformers.ViTMSNModel[[transformers.ViTMSNModel]]

```python
transformers.ViTMSNModel(config: ViTMSNConfig, use_mask_token: bool = False)
```

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/models/vit_msn/modeling_vit_msn.py#L317)

**パラメータ:**

config ([ViTMSNConfig](/docs/transformers/main/ja/model_doc/vit_msn#transformers.ViTMSNConfig)) : モデルのパラメータをすべて含むモデル設定クラスです。設定ファイルで初期化しても、モデルに関連する重みは読み込まれず、設定のみが読み込まれます。モデルの重みをロードするには、[from_pretrained()](/docs/transformers/main/ja/main_classes/model#transformers.PreTrainedModel.from_pretrained) メソッドを確認してください。

use_mask_token (`bool`、*任意*、デフォルトは`False`) : マスクドイメージモデリングにマスクトークンを使用するかどうか。

特定のヘッドを付加せず、生のhidden-statesを出力する素のVit Msn Modelです。

このモデルは [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.ViTMSNModel.forward]]

```python
forward(pixel_values: typing.Optional[torch.Tensor] = None, bool_masked_pos: typing.Optional[torch.BoolTensor] = None, interpolate_pos_encoding: bool | None = None, attention_mask: typing.Optional[torch.Tensor] = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/models/vit_msn/modeling_vit_msn.py#L331)

**パラメータ:**

pixel_values (`torch.Tensor`、shape `(batch_size, num_channels, image_size, image_size)`、*任意*) : 入力画像に対応するテンソルです。ピクセル値は [ViTImageProcessor](/docs/transformers/main/ja/model_doc/vit#transformers.ViTImageProcessor) を使用して取得できます。詳細は [ViTImageProcessor.__call__()](/docs/transformers/main/ja/model_doc/molmo2#transformers.Molmo2ImageProcessor.__call__) を参照してください（`processor_class` は画像の処理に [ViTImageProcessor](/docs/transformers/main/ja/model_doc/vit#transformers.ViTImageProcessor) を使用します）。

bool_masked_pos (`torch.BoolTensor`、shape `(batch_size, num_patches)`、*optional*) : ブール型のマスク位置。どのパッチがマスクされているか（1）、されていないか（0）を示します。

interpolate_pos_encoding (`bool`, *任意*) : 事前学習済みの位置エンコーディングを補間するかどうか。

attention_mask (`torch.Tensor`、shape `(batch_size, sequence_length)`、*任意*) : padding トークンのインデックスに対する attention を回避するためのマスクです。マスクの値は `[0, 1]` から選択されます:  - **マスクされない**トークンは 1、- **マスクされる**トークンは 0。  [attention マスクとは?](../glossary#attention-mask)

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

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

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

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

- **last_hidden_state** (`torch.Tensor`、形状 `(batch_size, sequence_length, hidden_size)`) -- モデルの最終層の出力における隠れ状態のシーケンス。
- **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)` です。

  各層の出力におけるモデルのHidden-states、および任意の初期埋め込み出力。
- **attentions** (`tuple(torch.Tensor)`、*optional*、`output_attentions=True` が渡された場合または `config.output_attentions=True` の場合に返されます) -- `torch.Tensor` のタプル（各レイヤーごとに1つ）、形状は `(batch_size, num_heads, sequence_length, sequence_length)`。

  アテンションのsoftmax後のアテンション重み。自己アテンションヘッド内で加重平均を計算するために使用されます。

例:

```python
>>> from transformers import AutoImageProcessor, ViTMSNModel
>>> import torch
>>> from PIL import Image
>>> from huggingface_hub.utils import httpx
>>> from io import BytesIO

>>> url = "http://images.cocodataset.org/val2017/000000039769.jpg"
>>> with httpx.stream("GET", url) as response:
...     image = Image.open(BytesIO(response.read()))

>>> image_processor = AutoImageProcessor.from_pretrained("facebook/vit-msn-small")
>>> model = ViTMSNModel.from_pretrained("facebook/vit-msn-small")
>>> inputs = image_processor(images=image, return_tensors="pt")
>>> with torch.no_grad():
...     outputs = model(**inputs)
>>> last_hidden_states = outputs.last_hidden_state
```

## ViTMSNForImageClassification[[transformers.ViTMSNForImageClassification]]

#### transformers.ViTMSNForImageClassification[[transformers.ViTMSNForImageClassification]]

```python
transformers.ViTMSNForImageClassification(config: ViTMSNConfig)
```

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/models/vit_msn/modeling_vit_msn.py#L387)

**パラメータ:**

config ([ViTMSNConfig](/docs/transformers/main/ja/model_doc/vit_msn#transformers.ViTMSNConfig)) : モデルのパラメータをすべて含むモデル設定クラスです。設定ファイルで初期化しても、モデルに関連する重みは読み込まれず、設定のみが読み込まれます。モデルの重みをロードするには、[from_pretrained()](/docs/transformers/main/ja/main_classes/model#transformers.PreTrainedModel.from_pretrained) メソッドを確認してください。

ImageNet などのタスクに使用される、画像分類ヘッドを上部に備えた Vit Msn Model です。

このモデルは [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.ViTMSNForImageClassification.forward]]

```python
forward(pixel_values: typing.Optional[torch.Tensor] = None, labels: typing.Optional[torch.Tensor] = None, interpolate_pos_encoding: bool | None = None, attention_mask: typing.Optional[torch.Tensor] = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/models/vit_msn/modeling_vit_msn.py#L395)

**パラメータ:**

pixel_values (`torch.Tensor`、shape `(batch_size, num_channels, image_size, image_size)`、*任意*) : 入力画像に対応するテンソルです。ピクセル値は [ViTImageProcessor](/docs/transformers/main/ja/model_doc/vit#transformers.ViTImageProcessor) を使用して取得できます。詳細は [ViTImageProcessor.__call__()](/docs/transformers/main/ja/model_doc/molmo2#transformers.Molmo2ImageProcessor.__call__) を参照してください（`processor_class` は画像の処理に [ViTImageProcessor](/docs/transformers/main/ja/model_doc/vit#transformers.ViTImageProcessor) を使用します）。

labels (`torch.LongTensor`、形状 `(batch_size,)`、*任意*) : 画像分類/回帰の損失を計算するためのラベル。

interpolate_pos_encoding (`bool`, *任意*) : 事前学習済みの位置エンコーディングを補間するかどうか。

attention_mask (`torch.Tensor`、shape `(batch_size, sequence_length)`、*任意*) : padding トークンのインデックスに対する attention を回避するためのマスクです。マスクの値は `[0, 1]` から選択されます:  - **マスクされない**トークンは 1、- **マスクされる**トークンは 0。  [attention マスクとは?](../glossary#attention-mask)

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

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

[ViTMSNForImageClassification](/docs/transformers/main/ja/model_doc/vit_msn#transformers.ViTMSNForImageClassification)の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
>>> from transformers import AutoImageProcessor, ViTMSNForImageClassification
>>> import torch
>>> from PIL import Image
>>> from huggingface_hub.utils import httpx
>>> from io import BytesIO

>>> torch.manual_seed(2)
>>> url = "http://images.cocodataset.org/val2017/000000039769.jpg"
>>> with httpx.stream("GET", url) as response:
...     image = Image.open(BytesIO(response.read())).convert("RGB")

>>> image_processor = AutoImageProcessor.from_pretrained("facebook/vit-msn-small")
>>> model = ViTMSNForImageClassification.from_pretrained("facebook/vit-msn-small")

>>> inputs = image_processor(images=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])
tusker
```