Transformers documentation
EoMT-DINOv3
该模型于 2025-03-24 在 HF papers 上发布，并于 2026-02-02 贡献至 Hugging Face Transformers。
EoMT-DINOv3
概述
EoMT-DINOv3 系列在 Encoder-only Mask Transformer 架构的基础上，引入了使用 DINOv3 进行预训练的 Vision Transformers。此次更新在 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 检查点。
提示：
- 该配置暴露了 DINOv3 特有的参数，例如
rope_theta和use_gated_mlp。大型 DINOv3 骨干网络，例如dinov3-vitg14，要求设置use_gated_mlp=True。 - 得益于旋转位置嵌入，DINOv3 模型可以处理更广泛的分辨率范围。图像处理器仍然默认使用方形裁剪，但可以通过
AutoImageProcessor提供自定义尺寸。 - TU/e 移动感知系统实验室托管的预训练检查点提供的是增量权重，需要与上游的 DINOv3 主干网络进行合并。官方仓库中的转换工具详细描述了这一工作流程。
使用示例
以下是一个最小示例，展示了如何使用基于 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
class 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) — 嵌入层、编码器和池化层中所有全连接层的 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 fusion 的 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的值，并且如果希望使用 RoPE 处理更长的max_position_embeddings，则可选地包含用于缩放的参数。 - query_bias (
bool，可选，默认为True) — 是否在查询投影中使用偏置。 - key_bias (
bool，可选，默认为False) — 是否在键投影中使用偏置。 - value_bias (
bool，可选，默认为True) — 是否在 value 投影中使用偏置。 - 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.Tensor)
参数
- 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]，可选) — 一个元组列表，指示用于语义分割的图像索引以及 patch 的起始和结束位置。
返回值
EomtDinov3ForUniversalSegmentationOutput 或 tuple(torch.Tensor)
EomtDinov3ForUniversalSegmentationOutput 或 torch.Tensor 元组（当传入 return_dict=False 或 config.return_dict=False 时），其包含的元素取决于配置（EomtDinov3Config）和输入。
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]，可选) — 一个元组列表，指示用于语义分割的图像索引以及 patch 的起始和结束位置。