Transformers 文档
DINOv2 with Registers
并获得增强的文档体验
开始使用
该模型于 2023 年 9 月 28 日发布在 HF 论文库中，并于 2024 年 12 月 24 日贡献给 Hugging Face Transformers。
带寄存器的 DINOv2
概述
带寄存器的 DINOv2 模型由 Timothée Darcet、Maxime Oquab、Julien Mairal 和 Piotr Bojanowski 在论文《Vision Transformers Need Registers》中提出。
视觉转换器 (ViT) 是一种转换器编码器模型（类似 BERT），最初被引入用于在 ImageNet 上进行有监督的图像分类。
随后，人们发现了使 ViT 在自监督图像特征提取（即学习有意义的特征，也称为嵌入）方面表现优异的方法，且无需任何标签。相关论文示例包括 DINOv2 和 MAE。
DINOv2 的作者注意到，ViT 的注意力图中存在伪影。这是由于模型将部分图像补丁（patches）用作了“寄存器”。作者提出了一个解决方案：添加一些新的标记（称为“寄存器”标记），这些标记仅在预训练期间使用（之后即被丢弃）。这带来了：
- 消除了伪影
- 具有可解释性的注意力图
- 以及性能的提升。
论文摘要如下：
Transformers 最近已成为学习视觉表示的强大工具。在本文中，我们识别并表征了监督和自监督 ViT 网络特征图中的伪影。这些伪影对应于推理过程中出现在图像低信息背景区域的高范数（high-norm）标记，这些区域被重新用于内部计算。我们提出了一种简单且有效的解决方案，即在视觉转换器的输入序列中提供额外的标记来填补该角色。我们证明，该解决方案彻底解决了监督和自监督模型中的这一问题，为密集视觉预测任务中的自监督视觉模型设定了新的最先进水平，利用更大模型实现了目标发现方法，最重要的是，为后续的视觉处理带来了更平滑的特征图和注意力图。
使用与不使用寄存器训练的各种模型的注意力图可视化。取自原始论文。技巧
- 带寄存器的 DINOv2 的用法与不带寄存器的 DINOv2 完全相同，你只需获得更好的性能即可。
Dinov2WithRegistersConfig
class transformers.Dinov2WithRegistersConfig
< 源代码 >( transformers_version: str | None = None architectures: list[str] | None = None output_hidden_states: bool | None = False return_dict: bool | None = True dtype: typing.Union[str, ForwardRef('torch.dtype'), NoneType] = 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: typing.Optional[typing.Literal['regression', 'single_label_classification', 'multi_label_classification']] = None hidden_size: int = 768 num_hidden_layers: int = 12 num_attention_heads: int = 12 mlp_ratio: int = 4 hidden_act: str = 'gelu' hidden_dropout_prob: float | int = 0.0 attention_probs_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] = 224 patch_size: int | list[int] | tuple[int, int] = 16 num_channels: int = 3 qkv_bias: bool = True layerscale_value: float = 1.0 drop_path_rate: float | int = 0.0 use_swiglu_ffn: bool = False num_register_tokens: int = 4 _out_features: list[str] | None = None _out_indices: list[int] | None = None apply_layernorm: bool = True reshape_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) — 嵌入、编码器和池化层中所有全连接层的丢弃概率。 - 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) — 每个补丁（patch）的大小（分辨率）。 - num_channels (
int, 可选, 默认为3) — 输入通道的数量。 - qkv_bias (
bool, 可选, 默认为True) — 是否为查询（queries）、键（keys）和值（values）添加偏置项。 - layerscale_value (
float, 可选, 默认为 1.0) — 层缩放（layer scale）使用的初始值。 - drop_path_rate (
Union[float, int], 可选, 默认为0.0) — 补丁融合（patch fusion）的 drop path 比率。 - use_swiglu_ffn (
bool, 可选, 默认为False) — 是否使用 SwiGLU 前馈神经网络。 - num_register_tokens (
int, 可选, 默认为 4) — 使用的寄存器标记数量。 - apply_layernorm (
bool, 可选, 默认为True) — 在模型作为骨干网络（backbone）使用时，是否对特征图应用层归一化。 - reshape_hidden_states (
bool, 可选, 默认为True) — 若模型作为骨干网络（backbone）使用，是否将特征图重塑为(batch_size, hidden_size, height, width)形状的 4D 张量。如果为False，特征图将保持为(batch_size, seq_len, hidden_size)形状的 3D 张量。
这是用于存储 Dinov2WithRegistersModel 配置的配置类。它根据指定的参数实例化 Dinov2 With Registers 模型，定义模型架构。使用默认值实例化配置将产生与 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.configDinov2WithRegistersModel
class transformers.Dinov2WithRegistersModel
< 源码 >( config: Dinov2WithRegistersConfig )
参数
- config (Dinov2WithRegistersConfig) — 模型配置类，包含模型的所有参数。使用配置文件进行初始化不会加载与模型相关的权重，仅加载配置。请查看 from_pretrained() 方法以加载模型权重。
裸 Dinov2 With Registers 模型，输出原始隐藏状态，顶部没有任何特定的头部（head）。
该模型继承自 PreTrainedModel。请查看超类文档以了解该库为所有模型实现的通用方法（例如下载或保存、调整输入嵌入大小、剪枝头部等）。
此模型也是一个 PyTorch torch.nn.Module 子类。像普通的 PyTorch Module 一样使用它，并参考 PyTorch 文档了解一般用法和行为的所有相关信息。
forward
< 源码 >( pixel_values: torch.Tensor | None = None bool_masked_pos: torch.Tensor | None = None **kwargs: typing_extensions.Unpack[transformers.utils.generic.TransformersKwargs] ) → BaseModelOutputWithPooling 或 tuple(torch.FloatTensor)
参数
- pixel_values (形状为
(batch_size, num_channels, image_size, image_size)的torch.Tensor, 可选) — 对应于输入图像的张量。像素值可以使用image_processor_class获取。详情请见image_processor_class.__call__（processor_class使用image_processor_class处理图像）。 - bool_masked_pos (形状为
(batch_size, sequence_length)的torch.BoolTensor) — 布尔掩码位置。指示哪些分块（patch）被掩盖（1），哪些未被掩盖（0）。仅对预训练有意义。
返回
BaseModelOutputWithPooling or tuple(torch.FloatTensor)
BaseModelOutputWithPooling 或 torch.FloatTensor 元组（如果传递了 return_dict=False 或 config.return_dict=False 时），根据配置（Dinov2WithRegistersConfig）和输入的不同，包含各种元素。
Dinov2WithRegistersModel 的 forward 方法，重写了 __call__ 特殊方法。
虽然 forward pass 的实现需要在此函数中定义，但你应该在之后调用
Module实例而不是这个，因为前者负责运行预处理和后处理步骤，而后者会静默地忽略它们。
last_hidden_state (
torch.FloatTensor, 形状为(batch_size, sequence_length, hidden_size)) — 模型最后一层输出的隐藏状态序列。pooler_output (
torch.FloatTensor，形状为(batch_size, hidden_size)) — 序列第一个 token（分类 token）在进一步通过用于辅助预训练任务的层后的最后一个隐藏状态。例如，对于 BERT 系列模型，这会返回经过线性层和 tanh 激活函数处理后的分类 token。线性层的权重是通过预训练期间的下一句预测（分类）目标来训练的。hidden_states (
tuple(torch.FloatTensor), optional, 当传递output_hidden_states=True或当config.output_hidden_states=True时返回) —torch.FloatTensor的元组（一个用于嵌入层的输出，如果模型有嵌入层；+一个用于每个层的输出），形状为(batch_size, sequence_length, hidden_size)。模型在每个层输出的隐藏状态以及可选的初始嵌入输出。
attentions (
tuple(torch.FloatTensor), optional, 当传递output_attentions=True或当config.output_attentions=True时返回) —torch.FloatTensor的元组（每个层一个），形状为(batch_size, num_heads, sequence_length, sequence_length)。注意力 softmax 后的注意力权重，用于计算自注意力头中的加权平均值。
Dinov2WithRegistersForImageClassification
class transformers.Dinov2WithRegistersForImageClassification
< 源码 >( config: Dinov2WithRegistersConfig )
参数
- config (Dinov2WithRegistersConfig) — 模型配置类，包含模型的所有参数。使用配置文件进行初始化不会加载与模型相关的权重，仅加载配置。请查看 from_pretrained() 方法以加载模型权重。
Dinov2WithRegisters 模型 transformer，顶部带有图像分类头（[CLS] token 的最终隐藏状态之上的线性层），例如用于 ImageNet。
该模型继承自 PreTrainedModel。请查看超类文档以了解该库为所有模型实现的通用方法（例如下载或保存、调整输入嵌入大小、剪枝头部等）。
此模型也是一个 PyTorch torch.nn.Module 子类。像普通的 PyTorch Module 一样使用它，并参考 PyTorch 文档了解一般用法和行为的所有相关信息。
forward
< 源码 >( pixel_values: torch.Tensor | None = None labels: torch.Tensor | None = None **kwargs: typing_extensions.Unpack[transformers.utils.generic.TransformersKwargs] ) → ImageClassifierOutput 或 tuple(torch.FloatTensor)
参数
- pixel_values (形状为
(batch_size, num_channels, image_size, image_size)的torch.Tensor, 可选) — 对应于输入图像的张量。像素值可以使用image_processor_class获取。详情请见image_processor_class.__call__（processor_class使用image_processor_class处理图像）。 - labels (形状为
(batch_size,)的torch.LongTensor, 可选) — 用于计算图像分类/回归损失的标签。索引应在[0, ..., config.num_labels - 1]范围内。如果config.num_labels == 1，则计算回归损失（均方误差损失）；如果config.num_labels > 1，则计算分类损失（交叉熵损失）。
返回
ImageClassifierOutput 或 tuple(torch.FloatTensor)
ImageClassifierOutput 或 torch.FloatTensor 元组（如果传递了 return_dict=False 或 config.return_dict=False 时），根据配置（Dinov2WithRegistersConfig）和输入的不同，包含各种元素。
Dinov2WithRegistersForImageClassification 的 forward 方法，重写了 __call__ 特殊方法。
虽然 forward pass 的实现需要在此函数中定义，但你应该在之后调用
Module实例而不是这个，因为前者负责运行预处理和后处理步骤，而后者会静默地忽略它们。
loss (形状为
(1,)的torch.FloatTensor，可选，当提供labels时返回) — 分类损失（如果 config.num_labels==1，则为回归损失）。logits (形状为
(batch_size, config.num_labels)的torch.FloatTensor) — 分类（如果 config.num_labels==1，则为回归）分数（SoftMax 之前）。hidden_states (
tuple(torch.FloatTensor), optional, 当传入output_hidden_states=True或当config.output_hidden_states=True时返回) — 形状为(batch_size, sequence_length, hidden_size)的torch.FloatTensor元组（一个用于嵌入层的输出，如果模型有嵌入层，+ 每个阶段的输出）。模型在每个阶段输出的隐藏状态（也称为特征图）。attentions (
tuple(torch.FloatTensor), optional, 当传入output_attentions=True或当config.output_attentions=True时返回) — 形状为(batch_size, num_heads, patch_size, sequence_length)的torch.FloatTensor元组（每个层一个）。注意力 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])
...