Transformers documentation

Registers付きDINOv2

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v5.22.1).
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

このモデルは2023年9月28日にHF papersで公開され、2024年12月24日にHugging Face Transformersに貢献されました。

Registers付きDINOv2

FlashAttention SDPA

概要

Registers付きDINOv2モデルは、Timothée Darcet、Maxime Oquab、Julien Mairal、Piotr BojanowskiによるVision Transformers Need Registersで提案されました。

Vision Transformer(ViT)は、ImageNet での教師あり画像分類のために最初に提案された、Transformer エンコーダーモデル(BERT 類似)です。

次に、ラベルなしの画像から意味のある特徴(埋め込みとも呼ばれる)を学習する、自己教師あり画像特徴抽出において ViT を非常に効果的に機能させる方法が次々と考案されました。関連する論文の例としては、DINOv2やMAEなどが挙げられます。

DINOv2の著者たちは、ViTの注意マップにアーティファクトが発生することを確認しました。これは、モデルが一部の画像パッチを「レジスタ」として使用しているためです。著者たちは修正策を提案しています。それは、新しいトークン(「レジスタ」トークンと呼ばれます)を追加し、事前学習の段階でのみ使用して、その後は破棄するというものです。これにより、以下のような結果が得られます:

  • アーティファクトなし
  • 解釈可能なアテンションマップ
  • そして、パフォーマンスの向上。

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

Transformers は、視覚表現の学習において強力なツールとして近年登場しました。本論文では、教師あり ViT ネットワークと自己教師あり ViT ネットワークの両方の特徴マップにおけるアーティファクトを特定し、その特性を明らかにします。これらのアーティファクトは、推論時に主に画像の低情報量な背景領域に現れる高ノルムトークンに対応しており、内部計算のために転用されています。私たちは、Vision Transformer の入力シーケンスに追加のトークンを提供してその役割を担わせるという、シンプルかつ効果的な解決策を提案します。この解決策が、教師ありモデルと自己教師ありモデルの両方において当該問題を完全に解消し、密な視覚予測タスクにおける自己教師あり視覚モデルの新たな最良性能を達成し、より大きなモデルを用いたオブジェクト発見手法を可能にし、最も重要なのは、下流の視覚処理においてより滑らかな特徴マップとアテンションマップをもたらすことを示します。

drawing Visualization of attention maps of various models trained with vs. without registers. Taken from the original paper.

ヒント:

  • Registers付きDINOv2の使用方法は、Registersなしの場合と同一であり、パフォーマンスが向上するだけです。

このモデルはnielsrによって提供されました。 元のコードはこちらで確認できます。

Dinov2WithRegistersConfig

class transformers.Dinov2WithRegistersConfig

< >

( transformers_version: str | None = Nonearchitectures: list[str] | None = Noneoutput_hidden_states: bool | None = Falsereturn_dict: bool | None = Truedtype: str | torch.dtype | None = Nonechunk_size_feed_forward: int = 0is_encoder_decoder: bool = Falseid2label: dict[int, str] | dict[str, str] | None = Nonelabel2id: dict[str, int] | dict[str, str] | None = Noneproblem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = Nonehidden_size: int = 768num_hidden_layers: int = 12num_attention_heads: int = 12mlp_ratio: int = 4hidden_act: str = 'gelu'hidden_dropout_prob: float | int = 0.0attention_probs_dropout_prob: float | int = 0.0initializer_range: float = 0.02layer_norm_eps: float = 1e-06image_size: int | list[int] | tuple[int, int] = 224patch_size: int | list[int] | tuple[int, int] = 16num_channels: int = 3qkv_bias: bool = Truelayerscale_value: float = 1.0drop_path_rate: float | int = 0.0use_swiglu_ffn: bool = Falsenum_register_tokens: int = 4_out_features: list[str] | None = None_out_indices: list[int] | None = Noneapply_layernorm: bool = Truereshape_hidden_states: bool = True )

パラメータ

  • hidden_size (int、任意、デフォルトは 768) — 隠れ表現の次元数。
  • num_hidden_layers (int、任意、デフォルトは 12) — Transformer デコーダーの隠れ層の数。
  • num_attention_heads (int、任意、デフォルトは12) — Transformerデコーダーの各アテンション層におけるアテンションヘッドの数。
  • mlp_ratio (int、任意、デフォルトは 4) — 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) — レイヤーノーマル層で使用する 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) — クエリ、キー、バリューにバイアスを追加するかどうか。
  • layerscale_value (float、任意、デフォルトは 1.0) — Layer scale に使用する初期値。
  • drop_path_rate (Union[float, int]、任意、デフォルトは 0.0) — パッチ融合におけるドロップパスの率。
  • use_swiglu_ffn (bool、任意、デフォルトは False) — SwiGLUフィードフォワードニューラルネットワークを使用するかどうかを指定します。
  • num_register_tokens (int、任意、デフォルトは 4)— 使用する register token の数。
  • apply_layernorm (bool、任意、デフォルトはTrue) — モデルがバックボーンとして使用される場合、特徴量マップにレイヤノルムを適用するかどうかを指定します。
  • reshape_hidden_states (bool、任意、デフォルトは True) — モデルがバックボーンとして使用される場合、特徴マップを (batch_size, hidden_size, height, width) の形状の 4 次元テンソルにリサイズするかどうか。False の場合、特徴マップは (batch_size, seq_len, hidden_size) の形状の 3 次元テンソルになります。

This is the configuration class to store the configuration of a Dinov2WithRegistersModel. It is used to instantiate a Dinov2 With Registers model according to the specified arguments, defining the model architecture. Instantiating a configuration with the defaults will yield a similar configuration to that of the facebook/dinov2-with-registers-base

設定オブジェクトはPreTrainedConfigを継承し、モデルの出力を制御するために使用できます。詳細については、PreTrainedConfigのドキュメントを参照してください。

例:

>>> from transformers import Dinov2WithRegistersConfig, Dinov2WithRegistersModel

>>> # Initializing a Dinov2WithRegisters base style configuration
>>> configuration = Dinov2WithRegistersConfig()

>>> # Initializing a model (with random weights) from the base style configuration
>>> model = Dinov2WithRegistersModel(configuration)

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

Dinov2WithRegistersModel

クラス transformers.Dinov2WithRegistersModel

< >

( config: Dinov2WithRegistersConfig )

パラメータ

  • config (Dinov2WithRegistersConfig) — モデルのパラメータをすべて含むモデル設定クラスです。設定ファイルで初期化しても、モデルに関連する重みは読み込まれず、設定のみが読み込まれます。モデルの重みをロードするには、from_pretrained() メソッドを参照してください。

裸のDinov2 With Registers Modelは、特定のヘッドを付加せずに生のhidden-statesを出力します。

このモデルは PreTrainedModel を継承しています。すべてのモデルに実装されている汎用的なメソッド(ダウンロードや保存、入力埋め込みのリサイズ、ヘッドのプルーニングなど)については、スーパークラスのドキュメントを参照してください。

このモデルは、PyTorchのtorch.nn.Moduleのサブクラスでもあります。 通常のPyTorch Moduleとして使用し、一般的な使用方法や動作に関する詳細については、PyTorchのドキュメントを参照してください。

forward

< >

( pixel_values: typing.Optional[torch.Tensor] = Nonebool_masked_pos: typing.Optional[torch.Tensor] = Noneattention_mask: typing.Optional[torch.Tensor] = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → BaseModelOutputWithPooling or tuple(torch.FloatTensor)

パラメータ

  • pixel_values (torch.Tensor、形状 (batch_size, num_channels, image_size, image_size)、任意) — 入力画像に対応するテンソルです。ピクセル値は image_processor_class を使用して取得できます。詳細は image_processor_class.__call__ を参照してください(processor_class は画像の処理に image_processor_class を使用します)。
  • bool_masked_pos (torch.BoolTensor、shape (batch_size, sequence_length)) — Boolean 形式のマスク位置。どのパッチがマスクされているか(1)、されていないか(0)を示します。事前学習でのみ関連します。
  • attention_mask (torch.Tensor の形状 (batch_size, sequence_length), 、任意) — パディングトークンのインデックスに対するアテンションを回避するためのマスク。 [0, 1]:
    • マスクされていないトークンに対して1
    • マスクされたトークンに対しては 0 です。

    アテンションマスクとは?

戻り値

BaseModelOutputWithPooling または tuple(torch.FloatTensor)

torch.FloatTensor のタプル(return_dict=False が渡された場合、または config.return_dict=False の場合)、または BaseModelOutputWithPooling。設定(Dinov2WithRegistersConfig)や入力に応じて、さまざまな要素で構成されます。

Dinov2WithRegistersModel の forward メソッドは、__call__ という特殊メソッドをオーバーライドします。

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

  • last_hidden_state (torch.FloatTensor、shape (batch_size, sequence_length, hidden_size)) — モデルの最終層の出力における隠れ状態のシーケンス。

  • pooler_output (torch.FloatTensor、shape (batch_size, hidden_size)) — 補助事前学習タスクに使用される層をさらに通して処理された後、シーケンスの最初のトークン(分類トークン)の最終層の隠れ状態。例えば、BERT 系のモデルでは、線形層と tanh 活性化関数を経て処理された後の分類トークンを返します。この線形層の重みは、事前学習中の次文予測(分類)目的から学習されます。

  • hidden_states (tuple(torch.FloatTensor)、optional、output_hidden_states=True が渡された場合または config.output_hidden_states=True の場合に返されます)— torch.FloatTensor のタプル(埋め込み層を持つモデルの場合、埋め込みの出力が 1 つ、各層の出力がそれぞれ 1 つずつ)で、形状は (batch_size, sequence_length, hidden_size) です。

    各層の出力におけるモデルのHidden-states、および任意の初期埋め込み出力。

  • attentions (tuple(torch.FloatTensor)、optional、output_attentions=True が渡された場合または config.output_attentions=True の場合に返されます)— torch.FloatTensor のタプル(各レイヤーごとに1つ)、形状は (batch_size, num_heads, sequence_length, sequence_length)。

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

例:

Dinov2WithRegistersForImageClassification

class transformers.Dinov2WithRegistersForImageClassification

< >

( config: Dinov2WithRegistersConfig )

パラメータ

  • config (Dinov2WithRegistersConfig) — モデルのパラメータをすべて含むモデル設定クラスです。設定ファイルで初期化しても、モデルに関連付けられた重みは読み込まれず、設定のみが読み込まれます。モデルの重みをロードするには、from_pretrained() メソッドを参照してください。

Dinov2WithRegisters Model [CLS]トークンの最終隠れ状態の上に線形層を載せた画像分類ヘッドを備えたtransformerモデル(ImageNetなど)。

このモデルは PreTrainedModel を継承しています。すべてのモデルに実装されている汎用的なメソッド(ダウンロードや保存、入力埋め込みのリサイズ、ヘッドのプルーニングなど)については、スーパークラスのドキュメントを参照してください。

このモデルは、PyTorchのtorch.nn.Moduleのサブクラスでもあります。 通常のPyTorch Moduleとして使用し、一般的な使用方法や動作に関する詳細については、PyTorchのドキュメントを参照してください。

forward

< >

( pixel_values: typing.Optional[torch.Tensor] = Nonelabels: typing.Optional[torch.Tensor] = Noneattention_mask: typing.Optional[torch.Tensor] = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → ImageClassifierOutput or tuple(torch.FloatTensor)

パラメータ

  • pixel_values (torch.Tensor、形状 (batch_size, num_channels, image_size, image_size)、任意) — 入力画像に対応するテンソルです。ピクセル値は image_processor_class を使用して取得できます。詳細は image_processor_class.__call__ を参照してください(processor_class は画像の処理に image_processor_class を使用します)。
  • labels (torch.LongTensor、shape (batch_size,)、任意) — 画像分類/回帰の損失を計算するためのラベル。インデックスは [0, ..., config.num_labels - 1] の範囲である必要があります。config.num_labels == 1 の場合は回帰損失(平均二乗誤差)が計算され、config.num_labels > 1 の場合は分類損失(クロスエントロピー)が計算されます。
  • attention_mask (torch.Tensor の形状 (batch_size, sequence_length), 、任意) — パディングトークンのインデックスに対するアテンションを回避するためのマスク。 [0, 1]:
    • マスクされていないトークンに対して1
    • マスクされたトークンに対しては 0 です。

    アテンションマスクとは?

戻り値

ImageClassifierOutput または tuple(torch.FloatTensor)

torch.FloatTensor のタプル、または ImageClassifierOutput(return_dict=False が渡された場合、または config.return_dict=False の場合)。設定(Dinov2WithRegistersConfig)や入力に応じて、さまざまな要素で構成されます。

Dinov2WithRegistersForImageClassification の forward メソッドは、__call__ という特殊メソッドをオーバーライドします。

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

  • loss (torch.FloatTensor、shape (1,)、optional、labels が指定された場合に返されます) — 分類損失(config.num_labels==1 の場合は回帰損失)。

  • logits (torch.FloatTensor、shape (batch_size, config.num_labels)) — SoftMax 適用前の分類スコア(config.num_labels==1 の場合は回帰スコア)。

  • hidden_states (tuple(torch.FloatTensor)、optional、output_hidden_states=True が渡された場合または config.output_hidden_states=True の場合に返されます) — torch.FloatTensor のタプル(埋め込み層を持つモデルの場合、埋め込みの出力用が 1 つ、各ステージの出力用がそれぞれ 1 つずつ)で、形状は (batch_size, sequence_length, hidden_size) です。各ステージの出力におけるモデルの隠れ状態(特徴マップとも呼ばれます)。

  • attentions (tuple(torch.FloatTensor)、optional、output_attentions=True が渡された場合または config.output_attentions=True の場合に返されます)— torch.FloatTensor のタプル(各レイヤーごとに1つ)、形状は (batch_size, num_heads, patch_size, sequence_length)。

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

例:

>>> from transformers import AutoImageProcessor, Dinov2WithRegistersForImageClassification
>>> import torch
>>> from datasets import load_dataset

>>> dataset = load_dataset("huggingface/cats-image")
>>> image = dataset["test"]["image"][0]

>>> image_processor = AutoImageProcessor.from_pretrained("facebook/dinov2-with-registers-base")
>>> model = Dinov2WithRegistersForImageClassification.from_pretrained("facebook/dinov2-with-registers-base")

>>> 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])
...
Update on GitHub