Transformers documentation
DINOv2 con registros
Este modelo se publicó en HF papers el 28-09-2023 y se contribuyó a Hugging Face Transformers el 24-12-2024.
DINOv2 con registros
Resumen
El modelo DINOv2 with Registers fue propuesto en Vision Transformers Need Registers por Timothée Darcet, Maxime Oquab, Julien Mairal, Piotr Bojanowski.
El Vision Transformer (ViT) es un modelo de codificador de transformadores (similar a BERT) introducido originalmente para realizar clasificación de imágenes supervisada en ImageNet.
A continuación, se encontraron formas de hacer que ViT funcione muy bien en la extracción de características de imágenes auto-supervisada (es decir, el aprendizaje de características significativas, también llamadas embeddings) en imágenes sin necesidad de etiquetas. Algunos ejemplos de artículos al respecto son DINOv2 y MAE.
Los autores de DINOv2 notaron que los ViT presentan artefactos en los mapas de atención. Esto se debe a que el modelo utiliza algunos parches de imagen como “registros”. Los autores proponen una solución: simplemente añadir algunos tokens nuevos (llamados tokens de “registro”), que solo se utilizan durante el preentrenamiento (y se descartan después). Esto da como resultado:
- sin artefactos
- mapas de atención interpretables
- y rendimientos mejorados.
El resumen del artículo es el siguiente:
Los Transformers han surgido recientemente como una herramienta poderosa para el aprendizaje de representaciones visuales. En este artículo, identificamos y caracterizamos artefactos en los mapas de características de redes ViT tanto supervisadas como auto-supervisadas. Los artefactos corresponden a tokens de alta norma que aparecen durante la inferencia, principalmente en áreas de fondo de baja información de las imágenes, que se reutilizan para cálculos internos. Proponemos una solución simple pero efectiva basada en proporcionar tokens adicionales a la secuencia de entrada del Vision Transformer para cumplir ese rol. Demostramos que esta solución corrige por completo ese problema tanto para modelos supervisados como auto-supervisados, establece un nuevo estado del arte para los modelos visuales auto-supervisados en tareas de predicción visual densa, permite métodos de descubrimiento de objetos con modelos más grandes y, lo más importante, conduce a mapas de características y mapas de atención más suaves para el procesamiento visual posterior.
Visualization of attention maps of various models trained with vs. without registers. Taken from the original paper. Consejos:
- El uso de DINOv2 con Registers es idéntico al de DINOv2 sin ellos; simplemente obtendrás un mejor rendimiento.
Este modelo fue aportado por nielsr. El código original se puede encontrar aquí.
Dinov2WithRegistersConfig
clase 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 )
Parámetros
- hidden_size (
int, opcional, valor predeterminado768) — Dimensión de las representaciones ocultas. - num_hidden_layers (
int, opcional, valor predeterminado12) — Número de capas ocultas en el decodificador del Transformer. - num_attention_heads (
int, opcional, valor predeterminado12) — Número de cabezas de atención para cada capa de atención en el decodificador Transformer. - mlp_ratio (
int, opcional, valor predeterminado4) — Relación entre la dimensión oculta del MLP y la dimensión de la incrustación. - hidden_act (
str, opcional, valor predeterminadogelu) — La función de activación no lineal (función o cadena) en el decodificador. Por ejemplo,"gelu","relu","silu", etc. - hidden_dropout_prob (
Union[float, int], opcional, valor predeterminado0.0) — La probabilidad de dropout para todas las capas totalmente conectadas en las incrustaciones, el codificador y el pooler. - attention_probs_dropout_prob (
Union[float, int], opcional, valor predeterminado0.0) — La proporción de dropout para las probabilidades de atención. - initializer_range (
float, opcional, valor predeterminado0.02) — La desviación estándar del truncated_normal_initializer para inicializar todas las matrices de pesos. - layer_norm_eps (
float, opcional, valor predeterminado1e-06) — La epsilon utilizada por las capas de normalización de capa. - image_size (
Union[int, list[int], tuple[int, int]], opcional, valor predeterminado224) — El tamaño (resolución) de cada imagen. - patch_size (
Union[int, list[int], tuple[int, int]], opcional, valor predeterminado16) — El tamaño (resolución) de cada parche. - num_channels (
int, opcional, valor predeterminado3) — El número de canales de entrada. - qkv_bias (
bool, opcional, valor predeterminadoTrue) — Si se debe añadir un sesgo a las consultas, claves y valores. - layerscale_value (
float, opcional, valor predeterminado 1.0) — Valor inicial para la escala de capa. - drop_path_rate (
Union[float, int], opcional, valor predeterminado0.0) — Tasa de drop path para la fusión de parches. - use_swiglu_ffn (
bool, opcional, valor predeterminadoFalse) — Si se debe usar la red neuronal feedforward SwiGLU. - num_register_tokens (
int, opcional, valor predeterminado 4) — Número de tokens de registro a utilizar. - apply_layernorm (
bool, opcional, valor predeterminadoTrue) — Si se aplica la normalización de capas a los mapas de características en caso de que el modelo se utilice como backbone. - reshape_hidden_states (
bool, opcional, valor predeterminadoTrue) — Si se deben redimensionar los mapas de características a tensores 4D de forma(batch_size, hidden_size, height, width)en caso de que el modelo se utilice como backbone. Si esFalse, los mapas de características serán tensores 3D de forma(batch_size, seq_len, hidden_size).
Esta es la clase de configuración para almacenar la configuración de un Dinov2WithRegistersModel. Se utiliza para instanciar un modelo Dinov2 With Registers según los argumentos especificados, definiendo la arquitectura del modelo. Instanciar una configuración con los valores predeterminados producirá una configuración similar a la de facebook/dinov2-with-registers-base
Los objetos de configuración heredan de PreTrainedConfig y se pueden usar para controlar las salidas del modelo. Lea la documentación de PreTrainedConfig para obtener más información.
Ejemplo:
>>> 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
clase transformers.Dinov2WithRegistersModel
< source >( config: Dinov2WithRegistersConfig )
Parámetros
- config (Dinov2WithRegistersConfig) — Clase de configuración del modelo con todos los parámetros del modelo. Inicializar con un archivo de configuración no carga los pesos asociados con el modelo, solo la configuración. Consulte el método from_pretrained() para cargar los pesos del modelo.
El modelo Dinov2 With Registers sin procesar, que emite estados ocultos crudos sin ninguna cabeza específica en la parte superior.
Este modelo hereda de PreTrainedModel. Consulta la documentación de la clase superior para los métodos genéricos que la biblioteca implementa para todos sus modelos (como la descarga o el guardado, el redimensionamiento de las incrustaciones de entrada, la poda de cabezas, etc.).
Este modelo también es una subclase de torch.nn.Module de PyTorch. Úsalo como un módulo de PyTorch regular y consulta la documentación de PyTorch para todo lo relacionado con el uso y el comportamiento generales.
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)
Parámetros
- pixel_values (
torch.Tensorde forma(batch_size, num_channels, image_size, image_size), opcional) — Los tensores correspondientes a las imágenes de entrada. Los valores de píxeles se pueden obtener utilizandoimage_processor_class. Consulteimage_processor_class.__call__para más detalles (processor_classutilizaimage_processor_classpara procesar las imágenes). - bool_masked_pos (
torch.BoolTensorde forma(batch_size, sequence_length)) — Posiciones enmascaradas booleanas. Indica qué parches están enmascarados (1) y cuáles no (0). Solo es relevante para el preentrenamiento. - attention_mask (
torch.Tensorde forma(batch_size, sequence_length), opcional) — Máscara para evitar realizar atención en los índices de tokens de relleno. Valores de máscara seleccionados en[0, 1]:- 1 para los tokens que no están enmascarados,
- 0 para los tokens que están enmascarados.
Devuelve
BaseModelOutputWithPooling o tuple(torch.Tensor)
Un BaseModelOutputWithPooling o una tupla de
torch.Tensor (si se pasa return_dict=False o cuando config.return_dict=False) que comprende varios
elementos según la configuración (Dinov2WithRegistersConfig) y las entradas.
El método forward de Dinov2WithRegistersModel sobrescribe el método especial __call__.
Aunque la receta para la pasada hacia adelante debe definirse dentro de esta función, se debe llamar a la instancia de
Moduledespués en lugar de a esta, ya que la primera se encarga de ejecutar los pasos de pre y postprocesamiento, mientras que la segunda los ignora silenciosamente.
last_hidden_state (
torch.Tensorde forma(batch_size, sequence_length, hidden_size)) — Secuencia de estados ocultos en la salida de la última capa del modelo.pooler_output (
torch.Tensorde forma(batch_size, hidden_size)) — Estado oculto de la última capa del primer token de la secuencia (token de clasificación) después de un procesamiento adicional a través de las capas utilizadas para la tarea de preentrenamiento auxiliar. Por ejemplo, para la familia de modelos BERT, esto devuelve el token de clasificación después de procesarlo a través de una capa lineal y una función de activación tanh. Los pesos de la capa lineal se entrenan a partir del objetivo de predicción de la siguiente oración (clasificación) durante el preentrenamiento.hidden_states (
tuple(torch.Tensor), opcional, devuelto cuando se pasaoutput_hidden_states=Trueo cuandoconfig.output_hidden_states=True) — Tupla detorch.Tensor(una para la salida de las incrustaciones, si el modelo tiene una capa de incrustaciones, + una para la salida de cada capa) de forma(batch_size, sequence_length, hidden_size).Estados ocultos del modelo en la salida de cada capa más las salidas opcionales de la incrustación inicial.
attentions (
tuple(torch.Tensor), opcional, se devuelve cuando se pasaoutput_attentions=Trueo cuandoconfig.output_attentions=True) — Tupla detorch.Tensor(una por cada capa) de forma(batch_size, num_heads, sequence_length, sequence_length).Pesos de atención tras el softmax de atención, utilizados para calcular la media ponderada en las cabezas de autoatención.
Dinov2WithRegistersForImageClassification
clase transformers.Dinov2WithRegistersForImageClassification
< source >( config: Dinov2WithRegistersConfig )
Parámetros
- config (Dinov2WithRegistersConfig) — Clase de configuración del modelo con todos los parámetros del modelo. Inicializar con un archivo de configuración no carga los pesos asociados con el modelo, solo la configuración. Consulte el método from_pretrained() para cargar los pesos del modelo.
Modelo Dinov2WithRegisters: transformer con una cabeza de clasificación de imágenes en la parte superior (una capa lineal sobre el estado oculto final del token [CLS]), por ejemplo, para ImageNet.
Este modelo hereda de PreTrainedModel. Consulta la documentación de la clase superior para los métodos genéricos que la biblioteca implementa para todos sus modelos (como la descarga o el guardado, el redimensionamiento de las incrustaciones de entrada, la poda de cabezas, etc.).
Este modelo también es una subclase de torch.nn.Module de PyTorch. Úsalo como un módulo de PyTorch regular y consulta la documentación de PyTorch para todo lo relacionado con el uso y el comportamiento generales.
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)
Parámetros
- pixel_values (
torch.Tensorde forma(batch_size, num_channels, image_size, image_size), opcional) — Los tensores correspondientes a las imágenes de entrada. Los valores de píxeles se pueden obtener utilizandoimage_processor_class. Consulteimage_processor_class.__call__para más detalles (processor_classutilizaimage_processor_classpara procesar las imágenes). - labels (
torch.LongTensorde forma(batch_size,), opcional) — Etiquetas para calcular la pérdida de clasificación/regresión de imágenes. Los índices deben estar en[0, ..., config.num_labels - 1]. Siconfig.num_labels == 1se calcula una pérdida de regresión (pérdida de error cuadrático medio), siconfig.num_labels > 1se calcula una pérdida de clasificación (entropía cruzada). - attention_mask (
torch.Tensorde forma(batch_size, sequence_length), opcional) — Máscara para evitar realizar atención en los índices de tokens de relleno. Valores de máscara seleccionados en[0, 1]:- 1 para los tokens que no están enmascarados,
- 0 para los tokens que están enmascarados.
Devuelve
ImageClassifierOutput o tuple(torch.Tensor)
Un ImageClassifierOutput o una tupla de
torch.Tensor (si se pasa return_dict=False o cuando config.return_dict=False) que comprende varios
elementos según la configuración (Dinov2WithRegistersConfig) y las entradas.
El método forward de Dinov2WithRegistersForImageClassification sobrescribe el método especial __call__.
Aunque la receta para la pasada hacia adelante debe definirse dentro de esta función, se debe llamar a la instancia de
Moduledespués en lugar de a esta, ya que la primera se encarga de ejecutar los pasos de pre y postprocesamiento, mientras que la segunda los ignora silenciosamente.
loss (
torch.Tensorde forma(1,), opcional, se devuelve cuando se proporcionalabels) — Pérdida de clasificación (o de regresión si config.num_labels==1).logits (
torch.Tensorde forma(batch_size, config.num_labels)) — Puntuaciones de clasificación (o de regresión si config.num_labels==1) (antes de SoftMax).hidden_states (
tuple(torch.Tensor), opcional, devuelto cuando se pasaoutput_hidden_states=Trueo cuandoconfig.output_hidden_states=True) — Tupla detorch.Tensor(una para la salida de las incrustaciones, si el modelo tiene una capa de incrustación, + una para la salida de cada etapa) de forma(batch_size, sequence_length, hidden_size). Estados ocultos (también llamados mapas de características) del modelo en la salida de cada etapa.attentions (
tuple(torch.Tensor), opcional, se devuelve cuando se pasaoutput_attentions=Trueo cuandoconfig.output_attentions=True) — Tupla detorch.Tensor(una por cada capa) de forma(batch_size, num_heads, patch_size, sequence_length).Pesos de atención tras el softmax de atención, utilizados para calcular la media ponderada en las cabezas de autoatención.
Ejemplo:
>>> 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])
...