# EoMT-DINOv3

  

## 概述

**EoMT-DINOv3** 系列在 [Encoder-only Mask Transformer](eomt) 架构的基础上，引入了使用 [DINOv3](dinov3) 进行预训练的 Vision Transformers。此次更新在 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 检查点。

提示：

* 该配置暴露了 DINOv3 特有的参数，例如 `rope_theta` 和 `use_gated_mlp`。大型 DINOv3 骨干网络（如 `dinov3-vitg14`）要求设置 `use_gated_mlp=True`。
* 得益于旋转位置嵌入，DINOv3 模型能够处理更广泛的分辨率范围。图像处理器默认仍使用方形裁剪，但可以通过 `AutoImageProcessor` 提供自定义尺寸。
* 由 TU/e 移动感知系统实验室托管的预训练检查点提供增量权重，这些权重应与上游 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`，*可选*，默认为 `24`)：Transformer 解码器中的隐藏层数。

num_attention_heads (`int`，*可选*，默认为 `16`)：Transformer 解码器中每个注意力层的注意力头数量。

hidden_act (`str`，*可选*，默认为 `gelu`)：解码器中的非线性激活函数（函数或字符串）。例如，`"gelu"`、`"relu"`、`"silu"` 等。

hidden_dropout_prob (`Union[float, int]`，*可选*，默认值为 `0.0`)：嵌入层、编码器和池化器中所有全连接层的 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`)：每个 patch 的大小（分辨率）。

num_channels (`int`，*可选*，默认为 `3`)：输入通道数。

layerscale_value (`float`, *可选*，默认为 1.0) : LayerScale 参数的初始值。

drop_path_rate (`Union[float, int]`，*可选*，默认为 `0.0`)：用于 patch 融合的 drop path 比率。

num_upscale_blocks (`int`, *可选*，默认为 2)：解码器或分割头中使用的上采样块数量。

attention_dropout (`Union[float, int]`，*可选*，默认值为 `0.0`)：注意力概率的 dropout 比率。

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`) : 全景分割损失中 dice 损失的相对权重。

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 输入中的可学习寄存器 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`) : 是否在值投影中使用偏置。

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/zh/main_classes/configuration#transformers.PreTrainedConfig)，可用于控制模型输出。有关更多信息，请参阅 [PreTrainedConfig](/docs/transformers/main/zh/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/zh/main_classes/configuration#transformers.PreTrainedConfig))：模型配置类，包含模型的所有参数。通过配置文件进行初始化时，不会加载与模型关联的权重，仅加载配置。请查看 [from_pretrained()](/docs/transformers/main/zh/main_classes/model#transformers.PreTrainedModel.from_pretrained) 方法以加载模型权重。

该模型继承自 [PreTrainedModel](/docs/transformers/main/zh/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/zh/model_doc/eomt_dinov3#transformers.EomtDinov3Config))：模型配置类，包含模型的所有参数。通过配置文件进行初始化时，不会加载与模型关联的权重，仅加载配置。请查看 [from_pretrained()](/docs/transformers/main/zh/main_classes/model#transformers.PreTrainedModel.from_pretrained) 方法以加载模型权重。

带有顶部头部的 EoMT-DINOv3 模型，用于实例/语义/全景分割。

该模型继承自 [PreTrainedModel](/docs/transformers/main/zh/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`，形状为 `(batch_size, num_channels, image_size, image_size)`)：与输入图像对应的张量。可以使用 [EomtImageProcessor](/docs/transformers/main/zh/model_doc/eomt#transformers.EomtImageProcessor) 获取像素值。有关详细信息，请参阅 [EomtImageProcessor.__call__()](/docs/transformers/main/zh/model_doc/molmo2#transformers.Molmo2ImageProcessor.__call__)（`processor_class` 使用 [EomtImageProcessor](/docs/transformers/main/zh/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.Tensor)`

`EomtDinov3ForUniversalSegmentationOutput` 或 `torch.Tensor` 元组（如果传入 `return_dict=False` 或 `config.return_dict=False`），其包含的元素取决于配置（[EomtDinov3Config](/docs/transformers/main/zh/model_doc/eomt_dinov3#transformers.EomtDinov3Config)）和输入。

[EomtDinov3ForUniversalSegmentation](/docs/transformers/main/zh/model_doc/eomt_dinov3#transformers.EomtDinov3ForUniversalSegmentation) 的 forward 方法重写了 `__call__` 特殊方法。

尽管前向传播的实现需要在此函数中定义，但之后应调用 `Module` 实例，而不是直接调用此函数，因为前者会负责执行预处理和后处理步骤，而后者会静默地忽略这些步骤。

- **loss** (`torch.Tensor`, *可选*) -- 计算得到的损失，当存在标签时返回。
- **class_queries_logits** (`torch.Tensor`, *可选*) -- 形状为 `(batch_size, num_queries, num_labels + 1)` 的张量，表示每个查询所提议的类别。请注意，`+ 1` 是必需的，因为我们纳入了空类别。
- **masks_queries_logits** (`torch.Tensor`, *可选*) -- 形状为 `(batch_size, num_queries, height, width)` 的张量，表示每个查询对应的预测掩码。
- **last_hidden_state**（形状为 `(batch_size, num_channels, height, width)` 的 `torch.Tensor`）-- 最后一层的最后隐藏状态（最终特征图）。
- **hidden_states** (`tuple(torch.Tensor)`，*可选*，在传入 `output_hidden_states=True` 或 `config.output_hidden_states=True` 时返回) -- 一个 `torch.Tensor` 元组（包含嵌入层的输出以及每个阶段的输出），形状为 `(batch_size, sequence_length, hidden_size)`。模型所有层的隐藏状态。
- **attentions** (`tuple(tuple(torch.Tensor))`，*可选*，当传入 `output_attentions=True` 或 `config.output_attentions=True` 时返回) -- 一个 `tuple(torch.Tensor)` 元组（每层一个），形状为 `(batch_size, num_heads, sequence_length, sequence_length)`。来自 transformer 解码器的自注意力和交叉注意力权重。
- **patch_offsets** (`list[torch.Tensor]`，*可选*) -- 一个元组列表，指示用于语义分割的图像索引以及补丁的起始和结束位置。