# EoMT-DINOv3

  

## 概要

**EoMT-DINOv3** ファミリーは、[DINOv3](dinov3) を用いて事前学習された Vision Transformer を備えた [Encoder-only Mask Transformer](eomt) アーキテクチャを拡張したものです。今回の更新により、ADE20K と COCO のベンチマークにおけるセグメンテーション品質が向上し、リアルタイムアプリケーション向けに EoMT を魅力的なものにしたエンコーダー専用設計は維持されています。

DINOv2ベースのモデルと比較して、DINOv3の各バリアントは、回転位置埋め込み、任意のゲート付きMLPブロック、およびMeta AIの最新の事前学習レシピを活用しています。これらの変更により、セマンティックセグメンテーション、インスタンスセグメンテーション、パノプティックセグメンテーションの各タスクにおいて、[DINOv3モデルズー](https://github.com/tue-mps/eomt/blob/master/model_zoo/dinov3.md)に示されているように、測定可能な性能向上が得られます。

元の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](https://huggingface.co/papers/2503.19108)* で提案されました。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 バックボーンと組み合わせるべきデルタ重みを提供します。[公式リポジトリ](https://github.com/tue-mps/eomt)の変換ユーティリティでは、このワークフローが詳細に説明されています。

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

## 使用例

以下は、DINOv3をベースにしたEoMTモデルでパノプティックセグメンテーションを実行する方法を示す最小限の例です。チェックポイントを切り替えるだけで、同じイメージプロセッサをセマンティックセグメンテーションやインスタンスセグメンテーションにも再利用できます。

```python
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]]

#### transformers.EomtDinov3Config[[transformers.EomtDinov3Config]]

```python
transformers.EomtDinov3Config(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 = 1024, num_hidden_layers: int = 24, num_attention_heads: int = 16, hidden_act: str = 'gelu', hidden_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] = 640, patch_size: int | list[int] | tuple[int, int] = 16, num_channels: int = 3, layerscale_value: float = 1.0, drop_path_rate: float | int = 0.0, num_upscale_blocks: int = 2, attention_dropout: float | int = 0.0, num_blocks: int = 4, no_object_weight: float = 0.1, class_weight: float = 2.0, mask_weight: float = 5.0, dice_weight: float = 5.0, train_num_points: int = 12544, oversample_ratio: float = 3.0, importance_sample_ratio: float = 0.75, num_queries: int = 200, num_register_tokens: int = 4, intermediate_size: int = 4096, rope_parameters: transformers.modeling_rope_utils.RopeParameters | dict | None = None, query_bias: bool = True, key_bias: bool = False, value_bias: bool = True, proj_bias: bool = True, mlp_bias: bool = True, use_gated_mlp: bool = False, pos_embed_shift: float | None = None, pos_embed_jitter: float | None = None, pos_embed_rescale: float | None = 2.0)
```

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/models/eomt_dinov3/configuration_eomt_dinov3.py#L29)

**パラメータ:**

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

num_hidden_layers (`int`、*optional*、デフォルトは `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`) : Layer Normalization 層で使用する 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`、*optional*、デフォルトは 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`) : パノプティックセグメンテーション損失におけるフォーカル損失の相対的な重み。

dice_weight (`float`、*任意*、デフォルトは `5.0`) : パノプティックセグメンテーション損失における dice loss の相対的な重み。

train_num_points (`int`、*optional*、デフォルトは 12544) : 学習中のマスク損失の計算のためにサンプリングする点の数。

oversample_ratio (`float`、*任意*、デフォルト値は 3.0) : マスク学習におけるポイントサンプリングで使用するオーバーサンプリング比率。

importance_sample_ratio (`float`、*任意*、デフォルトは 0.75) : 学習中に重要度に基づいてサンプリングするポイントの比率。

num_queries (`int`、*任意*、デフォルトは 200) : Transformer におけるオブジェクトクエリの数。

num_register_tokens (`int`、*任意*、デフォルトは 4) : Transformer の入力に追加される学習可能なレジスタトークンの数。

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

rope_parameters (`Union[~modeling_rope_utils.RopeParameters, dict]`, *optional*) : 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](https://huggingface.co/tue-mps/coco_panoptic_eomt_large_640_dinov3) と同様の設定が得られます。

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

## EomtDinov3PreTrainedModel[[transformers.EomtDinov3PreTrainedModel]]

#### transformers.EomtDinov3PreTrainedModel[[transformers.EomtDinov3PreTrainedModel]]

```python
transformers.EomtDinov3PreTrainedModel(config: PreTrainedConfig, *inputs, **kwargs)
```

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/models/eomt_dinov3/modeling_eomt_dinov3.py#L1061)

**パラメータ:**

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

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

```python
forward(*args, **kwargs)
```

ドット区切りパス（例: `torch.float32`）に対するモック値: 属性アクセスのチェーン、呼び出しはパススルーデコレータとして動作し、`repr` はドット区切りパスを返し、ベースクラスとして使用するとプレーンな `type` ベースに置き換えられます（PEP 560 の `__mro_entries__`）。これにより、実際のサブクラスは通常のメタクラスを保持し、`inspect.signature` はモックのものではなく実際の `__init__` を読み取ります。

## EomtDinov3ForUniversalSegmentation[[transformers.EomtDinov3ForUniversalSegmentation]]

#### transformers.EomtDinov3ForUniversalSegmentation[[transformers.EomtDinov3ForUniversalSegmentation]]

```python
transformers.EomtDinov3ForUniversalSegmentation(config: EomtDinov3Config)
```

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/models/eomt_dinov3/modeling_eomt_dinov3.py#L1167)

**パラメータ:**

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

インスタンスセグメンテーション、セマンティックセグメンテーション、パノプティックセグメンテーション用のヘッドを上部に備えたEoMT-DINOv3モデル。

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

```python
forward(pixel_values: Tensor, mask_labels: list[torch.Tensor] | None = None, class_labels: list[torch.Tensor] | None = None, patch_offsets: list[torch.Tensor] | None = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/models/eomt_dinov3/modeling_eomt_dinov3.py#L1231)

**パラメータ:**

pixel_values (`torch.Tensor`、shape `(batch_size, num_channels, image_size, image_size)`) : 入力画像に対応するテンソルです。ピクセル値は [EomtImageProcessor](/docs/transformers/main/ja/model_doc/eomt#transformers.EomtImageProcessor) を使用して取得できます。詳細については [EomtImageProcessor.__call__()](/docs/transformers/main/ja/model_doc/molmo2#transformers.Molmo2ImageProcessor.__call__) を参照してください（`processor_class` は画像の処理に [EomtImageProcessor](/docs/transformers/main/ja/model_doc/eomt#transformers.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](/docs/transformers/main/ja/model_doc/eomt_dinov3#transformers.EomtDinov3Config)）や入力に応じて、さまざまな要素で構成されます。

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

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

- **loss** (`torch.Tensor`, *optional*) -- ラベルが存在する場合に返される、計算された損失。
- **class_queries_logits** (`torch.FloatTensor`, *optional*) -- 各クエリに対して提案されるクラスを表す、形状が `(batch_size, num_queries, num_labels + 1)` のテンソルです。`+ 1` が必要なのは、null クラスを含めるためです。
- **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 つ）、形状は `(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]`、*省略可*) -- セマンティックセグメンテーションにおけるパッチの画像インデックスおよび開始・終了位置を示すタプルのリスト。