Transformers documentation
带寄存器（Registers）的 DINOv2
该模型于 2023-09-28 在 HF papers 上发布，并于 2024-12-24 贡献至 Hugging Face Transformers。
带寄存器（Registers）的 DINOv2
概述
带有 Registers 的 DINOv2 模型由 Timothée Darcet、Maxime Oquab、Julien Mairal 和 Piotr Bojanowski 在 Vision Transformers Need Registers 中提出。
Vision Transformer（ViT）是一种 Transformer 编码器模型（类似于 BERT），最初被提出用于在 ImageNet 上进行有监督图像分类。
接下来，人们找到了让 ViT 在无标签图像上出色完成自监督图像特征提取（即学习有意义的特征，也称为嵌入）的方法。相关论文示例包括 DINOv2 和 MAE。
DINOv2 的作者们注意到，ViT 的注意力图中存在伪影。这是由于模型将某些图像块用作“寄存器”所致。作者们提出了一种修复方法：只需添加一些新的 token（称为“寄存器” token），这些 token 仅在预训练阶段使用（之后即丢弃）。这样做会带来以下结果：
- 无伪影
- 可解释的注意力图
- 并提升了性能。
该论文的摘要如下：
Transformer 最近已成为学习视觉表示的强大工具。在本文中，我们识别并刻画了监督式与自监督 ViT 网络特征图中的伪影。这些伪影对应于推理过程中出现的高范数 token，它们主要位于图像中信息量较低的背景区域，并被重新用于内部计算。我们提出了一种简单而有效的解决方案：向 Vision Transformer 的输入序列中提供额外的 token，以承担该角色。我们证明，该方案能够完全解决监督式与自监督模型中的这一问题，在密集视觉预测任务上为自监督视觉模型树立了新的最先进水平，使对象发现方法能够使用更大的模型，并且最重要的是，为下游视觉处理带来了更平滑的特征图和注意力图。
Visualization of attention maps of various models trained with vs. without registers. Taken from the original paper. 提示：
- 使用带 Registers 的 DINOv2 与不带 Registers 的 DINOv2 用法完全相同，只是性能会更好。
Dinov2WithRegistersConfig
class transformers.Dinov2WithRegistersConfig
< 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 = 768num_hidden_layers: int = 12num_attention_heads: int = 12mlp_ratio: int = 4hidden_act: str = 'gelu'hidden_dropout_prob: float | int = 0.0attention_probs_dropout_prob: float | int = 0.0initializer_range: float = 0.02layer_norm_eps: float = 1e-06image_size: int | list[int] | tuple[int, int] = 224patch_size: int | list[int] | tuple[int, int] = 16num_channels: int = 3qkv_bias: bool = Truelayerscale_value: float = 1.0drop_path_rate: float | int = 0.0use_swiglu_ffn: bool = Falsenum_register_tokens: int = 4_out_features: list[str] | None = None_out_indices: list[int] | None = Noneapply_layernorm: bool = Truereshape_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) — 嵌入层、编码器和池化层中所有全连接层的 dropout 概率。 - attention_probs_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]]，可选，默认为224) — 每张图片的尺寸（分辨率）。 - patch_size (
Union[int, list[int], tuple[int, int]]，可选，默认为16) — 每个 patch 的大小（分辨率）。 - num_channels (
int，可选，默认为3) — 输入通道的数量。 - qkv_bias (
bool，可选，默认为True) — 是否向查询、键和值添加偏置。 - 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) — 要使用的 register token 数量。 - apply_layernorm (
bool，可选，默认为True) — 当模型用作 backbone 时，是否对特征图应用层归一化。 - reshape_hidden_states (
bool，可选，默认为True) — 当模型用作骨干网络时，是否将特征图重塑为形状为(batch_size, hidden_size, height, width)的 4D 张量。如果为False，则特征图将是形状为(batch_size, seq_len, hidden_size)的 3D 张量。
This is the configuration class to store the configuration of a Dinov2WithRegistersModel. It is used to instantiate a Dinov2 With Registers model according to the specified arguments, defining the model architecture. Instantiating a configuration with the defaults will yield a similar configuration to that of the 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
< source >( config: Dinov2WithRegistersConfig )
参数
- config (Dinov2WithRegistersConfig) — 模型的配置类，包含模型的所有参数。使用配置文件进行初始化时，不会加载与模型关联的权重，仅加载配置。请查看 from_pretrained() 方法以加载模型权重。
输出原始隐藏状态、顶部未附加任何特定头部的裸 Dinov2 With Registers 模型。
该模型继承自 PreTrainedModel。请查阅父类文档，了解该库为所有模型实现的通用方法（例如下载或保存、调整输入嵌入大小、剪枝头等）。
该模型也是 PyTorch torch.nn.Module 的子类。 请将其作为常规的 PyTorch Module 使用，有关通用用法和行为的所有事项，请参阅 PyTorch 文档。
forward
< source >( pixel_values: typing.Optional[torch.Tensor] = Nonebool_masked_pos: typing.Optional[torch.Tensor] = Noneattention_mask: typing.Optional[torch.Tensor] = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → BaseModelOutputWithPooling or tuple(torch.Tensor)
参数
- 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）。仅与预训练相关。 - attention_mask (
torch.Tensor形状为(batch_size, sequence_length), ，可选) — 用于避免对填充 token 索引执行注意力机制的掩码。掩码值取自[0, 1]:- 1 表示未被屏蔽的 token，
- 对于被掩码的 token，值为 0。
返回值
BaseModelOutputWithPooling 或 tuple(torch.Tensor)
一个 BaseModelOutputWithPooling 或 torch.Tensor 元组（如果传入了 return_dict=False 或 config.return_dict=False），其包含的元素取决于配置（Dinov2WithRegistersConfig）和输入。
Dinov2WithRegistersModel 的 forward 方法重写了 __call__ 特殊方法。
尽管前向传播的实现需要在此函数中定义，但之后应调用
Module实例，而不是直接调用此函数，因为前者会负责执行预处理和后处理步骤，而后者则会静默地忽略这些步骤。
last_hidden_state（形状为
(batch_size, sequence_length, hidden_size)的torch.Tensor）— 模型最后一层输出的隐藏状态序列。pooler_output (
torch.Tensor，形状为(batch_size, hidden_size)) — 序列中第一个 token（分类 token）的最后一层隐藏状态，经过用于辅助预训练任务的层进一步处理后得到。例如，对于 BERT 系列模型，这返回的是分类 token 经过线性层和 tanh 激活函数处理后的结果。线性层的权重在预训练期间通过下一句预测（分类）目标进行训练。hidden_states (
tuple(torch.Tensor)，可选，当传入output_hidden_states=True或config.output_hidden_states=True时返回) — 一个torch.Tensor元组（如果模型具有嵌入层，则包含嵌入层的输出，以及每一层的输出），形状为(batch_size, sequence_length, hidden_size)。模型在每一层输出处的隐藏状态，以及可选的初始嵌入输出。
attentions (
tuple(torch.Tensor)，可选，当传入output_attentions=True或config.output_attentions=True时返回) — 一个torch.Tensor元组（每层一个），形状为(batch_size, num_heads, sequence_length, sequence_length)。注意力权重，即经过注意力 softmax 之后的权重，用于在自注意力头中计算加权平均值。
Dinov2WithRegistersForImageClassification
class transformers.Dinov2WithRegistersForImageClassification
< source >( config: Dinov2WithRegistersConfig )
参数
- config (Dinov2WithRegistersConfig) — 模型的配置类，包含模型的所有参数。使用配置文件进行初始化时，不会加载与模型关联的权重，仅加载配置。请查看 from_pretrained() 方法以加载模型权重。
Dinov2WithRegisters 模型，在顶部添加了一个图像分类头（即在 [CLS] token 的最终隐藏状态之上添加了一个线性层），例如用于 ImageNet。
该模型继承自 PreTrainedModel。请查阅父类文档，了解该库为所有模型实现的通用方法（例如下载或保存、调整输入嵌入大小、剪枝头等）。
该模型也是 PyTorch torch.nn.Module 的子类。 请将其作为常规的 PyTorch Module 使用，有关通用用法和行为的所有事项，请参阅 PyTorch 文档。
forward
< source >( pixel_values: typing.Optional[torch.Tensor] = Nonelabels: typing.Optional[torch.Tensor] = Noneattention_mask: typing.Optional[torch.Tensor] = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → ImageClassifierOutput or tuple(torch.Tensor)
参数
- 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，则计算分类损失（交叉熵）。 - attention_mask (
torch.Tensor形状为(batch_size, sequence_length), ，可选) — 用于避免对填充 token 索引执行注意力机制的掩码。掩码值取自[0, 1]:- 1 表示未被屏蔽的 token，
- 对于被掩码的 token，值为 0。
返回值
ImageClassifierOutput 或 tuple(torch.Tensor)
一个 ImageClassifierOutput 或 torch.Tensor 元组（当传入 return_dict=False 或 config.return_dict=False 时），其包含的元素取决于配置（Dinov2WithRegistersConfig）和输入。
Dinov2WithRegistersForImageClassification 的 forward 方法重写了 __call__ 特殊方法。
尽管前向传播的实现需要在此函数中定义，但之后应调用
Module实例，而不是直接调用此函数，因为前者会负责执行预处理和后处理步骤，而后者则会静默地忽略这些步骤。
loss (
torch.Tensor，形状为(1,)，可选，当提供labels时返回) — 分类损失（如果 config.num_labels==1，则为回归损失）。logits（形状为
(batch_size, config.num_labels)的torch.Tensor）— 分类（或当 config.num_labels==1 时为回归）得分（SoftMax 之前）。hidden_states (
tuple(torch.Tensor)，可选，在传入output_hidden_states=True或config.output_hidden_states=True时返回) — 一个torch.Tensor元组（如果模型具有嵌入层，则包含嵌入层输出的一个张量，以及每个阶段输出的一个张量），形状为(batch_size, sequence_length, hidden_size)。模型在每个阶段输出处的隐藏状态（也称为特征图）。attentions (
tuple(torch.Tensor)，可选，当传入output_attentions=True或config.output_attentions=True时返回) — 一个torch.Tensor元组（每层一个），形状为(batch_size, num_heads, patch_size, sequence_length)。注意力权重，即经过注意力 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])
...