Transformers documentation
EoMT-DINOv3
このモデルは2025年3月24日にHF papersで公開され、2026年2月2日にHugging Face Transformersに貢献されました。
EoMT-DINOv3
概要
EoMT-DINOv3 ファミリーは、DINOv3 を用いて事前学習された Vision Transformer を備えた Encoder-only Mask Transformer アーキテクチャを拡張したものです。今回の更新により、ADE20K と COCO のベンチマークにおけるセグメンテーション品質が向上し、リアルタイムアプリケーション向けに EoMT を魅力的なものにしたエンコーダー専用設計は維持されています。
DINOv2ベースのモデルと比較して、DINOv3の各バリアントは、回転位置埋め込み、任意のゲート付きMLPブロック、およびMeta AIの最新の事前学習レシピを活用しています。これらの変更により、セマンティックセグメンテーション、インスタンスセグメンテーション、パノプティックセグメンテーションの各タスクにおいて、DINOv3モデルズーに示されているように、測定可能な性能向上が得られます。
元のEoMTアーキテクチャは、Tommie Kerssies、Niccolò Cavagnero、Alexander Hermans、Narges Norouzi、Giuseppe Averta、Bastian Leibe、Gijs Dubbelman、Daan de Geus による CVPR 2025 Highlight 論文 Your ViT is Secretly an Image Segmentation Model で紹介されました。DINOv3 へのアップグレードでは、同じ軽量なセグメンテーションヘッドとクエリベースの推論戦略を維持したまま、エンコーダーを DINOv3 ViT チェックポイントに置き換えます。
ヒント:
- 設定には、
rope_thetaやuse_gated_mlpといった DINOv3 固有のパラメータが公開されています。dinov3-vitg14のような大規模な DINOv3 バックボーンでは、use_gated_mlp=Trueが期待されます。 - DINOv3モデルは、回転位置埋め込み（rotary position embeddings）のおかげで、より幅広い解像度で動作できます。画像プロセッサは引き続き正方形のクロップをデフォルトとしていますが、
AutoImageProcessorを通じてカスタムサイズを指定できます。 - TU/e Mobile Perception Systems Lab がホストする事前学習済みチェックポイントは、アップストリームの DINOv3 バックボーンと組み合わせるべきデルタ重みを提供します。公式リポジトリの変換ユーティリティでは、このワークフローが詳細に説明されています。
このモデルはnielsrによって提供されました。 元のコードはこちらで確認できます。
使用例
以下は、DINOv3をベースにしたEoMTモデルでパノプティックセグメンテーションを実行する方法を示す最小限の例です。チェックポイントを切り替えるだけで、同じイメージプロセッサをセマンティックセグメンテーションやインスタンスセグメンテーションにも再利用できます。
import requests
import torch
from PIL import Image
from transformers import AutoImageProcessor, AutoModelForUniversalSegmentation
model_id = "tue-mps/eomt-dinov3-coco-panoptic-base-640"
processor = AutoImageProcessor.from_pretrained(model_id)
model = AutoModelForUniversalSegmentation.from_pretrained(model_id, device_map="auto")
image = Image.open(requests.get("http://images.cocodataset.org/val2017/000000039769.jpg", stream=True).raw)
inputs = processor(images=image, return_tensors="pt").to(model.device)
with torch.inference_mode():
outputs = model(**inputs)
segmentation = processor.post_process_panoptic_segmentation(outputs, target_sizes=[image.size[::-1]])[0]
list(segmentation.keys())
['segmentation', 'segments_info']EomtDinov3Config
クラス transformers.EomtDinov3Config
< source >( 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 = 1024num_hidden_layers: int = 24num_attention_heads: int = 16hidden_act: str = 'gelu'hidden_dropout_prob: float | int = 0.0initializer_range: float = 0.02layer_norm_eps: float = 1e-06image_size: int | list[int] | tuple[int, int] = 640patch_size: int | list[int] | tuple[int, int] = 16num_channels: int = 3layerscale_value: float = 1.0drop_path_rate: float | int = 0.0num_upscale_blocks: int = 2attention_dropout: float | int = 0.0num_blocks: int = 4no_object_weight: float = 0.1class_weight: float = 2.0mask_weight: float = 5.0dice_weight: float = 5.0train_num_points: int = 12544oversample_ratio: float = 3.0importance_sample_ratio: float = 0.75num_queries: int = 200num_register_tokens: int = 4intermediate_size: int = 4096rope_parameters: transformers.modeling_rope_utils.RopeParameters | dict | None = Nonequery_bias: bool = Truekey_bias: bool = Falsevalue_bias: bool = Trueproj_bias: bool = Truemlp_bias: bool = Trueuse_gated_mlp: bool = Falsepos_embed_shift: float | None = Nonepos_embed_jitter: float | None = Nonepos_embed_rescale: float | None = 2.0 )
パラメータ
- hidden_size (
int、任意、デフォルトは1024) — 隠れ表現の次元数。 - num_hidden_layers (
int、任意、デフォルトは24) — Transformer デコーダーの隠れ層の数。 - num_attention_heads (
int、任意、デフォルトは16) — Transformer デコーダーの各アテンション層におけるアテンションヘッドの数。 - hidden_act (
str、任意、デフォルトはgelu) — デコーダーで使用する非線形活性化関数（関数または文字列）。例えば、"gelu"、"relu"、"silu"など。 - hidden_dropout_prob (
Union[float, int]、任意、デフォルト値は0.0) — embeddings、encoder、pooler 内のすべての全結合層における dropout 確率です。 - initializer_range (
float、任意、デフォルトは0.02) — すべての重み行列を初期化するための truncated_normal_initializer の標準偏差です。 - layer_norm_eps (
float、任意、デフォルトは1e-06) — レイヤーノーマル層で使用する epsilon です。 - image_size (
Union[int, list[int], tuple[int, int]]、任意、デフォルトは640) — 各画像のサイズ（解像度）です。 - patch_size (
Union[int, list[int], tuple[int, int]]、任意、デフォルトは16) — 各パッチのサイズ（解像度）です。 - num_channels (
int、任意、デフォルトは3) — 入力チャネル数。 - layerscale_value (
float、任意、デフォルト値は 1.0) — LayerScale パラメータの初期値です。 - drop_path_rate (
Union[float, int]、任意、デフォルトは0.0) — パッチ融合におけるドロップパスの率。 - num_upscale_blocks (
int、任意、デフォルト値は 2)— デコーダーまたはセグメンテーションヘッドで使用するアップサンプリングブロックの数。 - attention_dropout (
Union[float, int]、任意、デフォルトは0.0) — アテンション確率のドロップアウト率です。 - num_blocks (
int、任意、デフォルトは 4) — アーキテクチャにおける特徴量ブロックまたはステージの数。 - no_object_weight (
float、任意、デフォルト値は 0.1) — パノラミック/インスタンスセグメンテーションにおける「no object」クラスの損失重みです。 - class_weight (
float、任意、デフォルトは2.0) — ハンガリー法によるマッチングコストにおける、分類誤差の相対的な重み。 - mask_weight (
float、任意、デフォルトは5.0) — パノプティックセグメンテーション損失における、focal loss の相対的な重み。 - dice_weight (
float、任意、デフォルトは5.0) — パノラミックセグメンテーション損失における dice loss の相対的な重み。 - train_num_points (
int、任意、デフォルト値は 12544)— 学習中にマスク損失の計算のためにサンプリングする点の数。 - oversample_ratio (
float、任意、デフォルトは 3.0) — マスク学習におけるポイントサンプリングで使用するオーバーサンプリング比率。 - importance_sample_ratio (
float、任意、デフォルト値: 0.75) — 学習中に重要度に基づいてサンプリングするポイントの比率。 - num_queries (
int、任意、デフォルトは 200) — Transformer におけるオブジェクトクエリの数。 - num_register_tokens (
int、省略可、デフォルト値は 4) — Transformer の入力に追加される、学習可能な register token の数です。 - intermediate_size (
int、任意、デフォルトは4096) — MLP 表現の次元数。 - rope_parameters (
Union[~modeling_rope_utils.RopeParameters, dict], 省略可) — RoPE 埋め込みの設定パラメータを含む辞書です。この辞書にはrope_thetaの値が含まれており、より長いmax_position_embeddingsで RoPE を使用する場合にスケーリングに使用されるパラメータが任意で含まれます。 - query_bias (
bool、任意、デフォルトはTrue) — クエリ投影にバイアスを使用するかどうか。 - key_bias (
bool、任意、デフォルトはFalse) — キー投影にバイアスを使用するかどうか。 - value_bias (
bool、任意、デフォルトはTrue) — value projection に bias を使用するか否かを指定します。 - proj_bias (
bool、任意、デフォルトはTrue) — 出力プロジェクションにバイアスを使用するかどうか。 - mlp_bias (
bool、任意、デフォルトはTrue) — MLP層の up_proj、down_proj、gate_proj 層でバイアスを使用するかどうか。 - use_gated_mlp (
bool、任意、デフォルトはFalse) — ゲート付き MLP レイヤーを使用するかどうか。 - pos_embed_shift (
float, 任意) — 位置埋め込みのシフト値。 - pos_embed_jitter (
float, 任意) — 位置埋め込み用のジッター値。 - pos_embed_rescale (
float、任意、デフォルトは 2.0) — 位置埋め込みの再スケーリング値。
これは、Eomt Dinov3Model の設定を保存するための設定クラスです。指定された引数に基づいて Eomt Dinov3 モデルをインスタンス化し、モデルのアーキテクチャを定義するために使用されます。デフォルト値で設定をインスタンス化すると、tue-mps/coco_panoptic_eomt_large_640_dinov3 と同様の設定が得られます。
設定オブジェクトはPreTrainedConfigを継承し、モデルの出力を制御するために使用できます。詳細については、PreTrainedConfigのドキュメントを参照してください。
EomtDinov3PreTrainedModel
クラス transformers.EomtDinov3PreTrainedModel
< source >( config: PreTrainedConfig*inputs**kwargs )
パラメータ
- config (PreTrainedConfig) — モデルのパラメータをすべて含むモデル設定クラスです。設定ファイルで初期化しても、モデルに関連する重みは読み込まれず、設定のみが読み込まれます。モデルの重みをロードするには、from_pretrained() メソッドを参照してください。
このモデルは PreTrainedModel を継承しています。すべてのモデルに実装されている汎用的なメソッド（ダウンロードや保存、入力埋め込みのリサイズ、ヘッドのプルーニングなど）については、スーパークラスのドキュメントを参照してください。
このモデルは、PyTorchのtorch.nn.Moduleのサブクラスでもあります。 通常のPyTorch Moduleとして使用し、一般的な使用方法や動作に関する詳細については、PyTorchのドキュメントを参照してください。
EomtDinov3ForUniversalSegmentation
class transformers.EomtDinov3ForUniversalSegmentation
< source >( config: EomtDinov3Config )
パラメータ
- config (EomtDinov3Config) — モデルのすべてのパラメータを含むモデル設定クラスです。設定ファイルで初期化しても、モデルに関連する重みは読み込まれず、設定のみが読み込まれます。モデルの重みをロードするには、from_pretrained() メソッドを参照してください。
インスタンスセグメンテーション、セマンティックセグメンテーション、パノプティックセグメンテーション用のヘッドを上部に備えたEoMT-DINOv3モデル。
このモデルは PreTrainedModel を継承しています。すべてのモデルに実装されている汎用的なメソッド（ダウンロードや保存、入力埋め込みのリサイズ、ヘッドのプルーニングなど）については、スーパークラスのドキュメントを参照してください。
このモデルは、PyTorchのtorch.nn.Moduleのサブクラスでもあります。 通常のPyTorch Moduleとして使用し、一般的な使用方法や動作に関する詳細については、PyTorchのドキュメントを参照してください。
forward
< source >( pixel_values: Tensormask_labels: list[torch.Tensor] | None = Noneclass_labels: list[torch.Tensor] | None = Nonepatch_offsets: list[torch.Tensor] | None = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → EomtDinov3ForUniversalSegmentationOutput or tuple(torch.FloatTensor)
パラメータ
- pixel_values (
torch.Tensor、形状(batch_size, num_channels, image_size, image_size)) — 入力画像に対応するテンソルです。ピクセル値は EomtImageProcessor を使用して取得できます。詳細については EomtImageProcessor.call() を参照してください（processor_classは画像の処理に EomtImageProcessor を使用します）。 - mask_labels (
list[torch.Tensor]、任意) —(num_labels, height, width)の形状を持つマスクラベルのリストで、モデルに渡すものです - class_labels (
list[torch.LongTensor]、任意) — モデルに渡す、(num_labels, height, width)の形状を持つターゲットクラスラベルのリストです。mask_labelsのラベルを識別します。例えば、class_labels[i][j]が真の場合、mask_labels[i][j]のラベルを示します。 - patch_offsets (
list[torch.Tensor], 任意) — セマンティックセグメンテーションにおけるパッチの画像インデックスおよび開始・終了位置を示すタプルのリスト。
戻り値
EomtDinov3ForUniversalSegmentationOutput または tuple(torch.FloatTensor)
EomtDinov3ForUniversalSegmentationOutput、または torch.FloatTensor のタプル（return_dict=False が渡された場合、または config.return_dict=False の場合）。設定（EomtDinov3Config）や入力に応じて、さまざまな要素で構成されます。
EomtDinov3ForUniversalSegmentation の forward メソッドは、__call__ という特殊メソッドをオーバーライドします。
この関数内でフォワードパスの手順を定義する必要がありますが、その後、この関数ではなく
Moduleインスタンスを呼び出すべきです。前者は前処理と後処理の実行を適切に処理するのに対し、後者はそれらを黙って無視するためです。
- loss (
torch.Tensor, optional) — ラベルが存在する場合に返される、計算された損失。 - class_queries_logits (
torch.FloatTensor, optional) — 各クエリに対して提案されるクラスを表す、形状が(batch_size, num_queries, num_labels + 1)のテンソル。nullクラスを組み込む必要があるため、+ 1が必要です。 - masks_queries_logits (
torch.FloatTensor, オプション) — 各クエリに対する提案マスクを表す、形状が(batch_size, num_queries, height, width)のテンソル。 - last_hidden_state (
torch.FloatTensor、shape(batch_size, num_channels, height, width)) — 最終層の最後の隠れ状態（最終的な特徴マップ）。 - hidden_states (
tuple(torch.FloatTensor)、optional、output_hidden_states=Trueが渡された場合またはconfig.output_hidden_states=Trueの場合に返されます)—torch.FloatTensorのタプル（埋め込みの出力用 1 つ + 各ステージの出力用 1 つ）、shape は(batch_size, sequence_length, hidden_size)。モデルの全レイヤーの隠れ状態です。 - attentions (
tuple(tuple(torch.FloatTensor))、optional、output_attentions=Trueが渡された場合またはconfig.output_attentions=Trueの場合に返されます) —tuple(torch.FloatTensor)のタプル(レイヤーごとに1つ)、形状は(batch_size, num_heads, sequence_length, sequence_length)。Transformer デコーダーからの Self Attention と Cross Attention の重み。 - patch_offsets (
list[torch.Tensor]、任意) — セマンティックセグメンテーションにおけるパッチの画像インデックスおよび開始・終了位置を示すタプルのリスト。