# DINOv2

[DINOv2](https://huggingface.co/papers/2304.07193) es un modelo de visión de base que utiliza [ViT](./vit) como extractor de características para múltiples tareas posteriores, como la clasificación de imágenes y la estimación de profundidad. Se centra en estabilizar y acelerar el entrenamiento mediante técnicas como una atención más rápida y eficiente en memoria, empaquetado de secuencias, profundidad estocástica mejorada, Fully Sharded Data Parallel (FSDP) y destilación de modelos.

Puedes encontrar todos los puntos de control originales de DINOv2 en la colección [Dinov2](https://huggingface.co/collections/facebook/dinov2-6526c98554b3d2576e071ce3).

> [!TIP]
> Haz clic en los modelos DINOv2 en la barra lateral derecha para ver más ejemplos de cómo aplicar DINOv2 a diferentes tareas de visión.

El siguiente ejemplo demuestra cómo obtener un embedding de imagen con [Pipeline](/docs/transformers/v5.23.0/es/main_classes/pipelines#transformers.Pipeline) o la clase [AutoModel](/docs/transformers/v5.23.0/es/model_doc/auto#transformers.AutoModel).

```python
from transformers import pipeline

pipe = pipeline(
    task="image-classification",
    model="facebook/dinov2-small-imagenet1k-1-layer",
    device=0
)

pipe("https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/pipeline-cat-chonk.jpeg")
```

```python
import requests
from PIL import Image

from transformers import AutoImageProcessor, AutoModelForImageClassification

url = "http://images.cocodataset.org/val2017/000000039769.jpg"
image = Image.open(requests.get(url, stream=True).raw)

processor = AutoImageProcessor.from_pretrained("facebook/dinov2-small-imagenet1k-1-layer")
model = AutoModelForImageClassification.from_pretrained(
    "facebook/dinov2-small-imagenet1k-1-layer",
    device_map="auto",
    attn_implementation="sdpa"
)

inputs = processor(images=image, return_tensors="pt").to(model.device)
logits = model(**inputs).logits
predicted_class_idx = logits.argmax(-1).item()
print("Predicted class:", model.config.id2label[predicted_class_idx])
```

La cuantización reduce la carga de memoria de los modelos grandes al representar los pesos con una precisión inferior. Consulte el resumen de [Cuantización](../quantization/overview) para conocer más backends de cuantización disponibles.

El ejemplo siguiente utiliza [torchao](../quantization/torchao) para cuantizar únicamente los pesos a int4.

```python
# pip install torchao
import requests
from PIL import Image
from torchao.quantization import Int4WeightOnlyConfig

from transformers import AutoImageProcessor, AutoModelForImageClassification, TorchAoConfig

url = 'http://images.cocodataset.org/val2017/000000039769.jpg'
image = Image.open(requests.get(url, stream=True).raw)

processor = AutoImageProcessor.from_pretrained('facebook/dinov2-giant-imagenet1k-1-layer')

quant_config = Int4WeightOnlyConfig(group_size=128)
quantization_config = TorchAoConfig(quant_type=quant_config)

model = AutoModelForImageClassification.from_pretrained(
    'facebook/dinov2-giant-imagenet1k-1-layer',
    device_map="auto",
    quantization_config=quantization_config
)

inputs = processor(images=image, return_tensors="pt").to(model.device)
outputs = model(**inputs)
logits = outputs.logits
predicted_class_idx = logits.argmax(-1).item()
print("Predicted class:", model.config.id2label[predicted_class_idx])
```

## Notas

- El siguiente ejemplo muestra cómo dividir el tensor de salida en:
  - una única representación para la imagen completa, comúnmente referida como un token `CLS`, útil para clasificación y recuperación
  - un conjunto de embeddings locales, uno para cada parche de `14x14` de la imagen de entrada, útil para tareas densas, como la segmentación semántica

  ```py
  from transformers import AutoImageProcessor, AutoModel
  from PIL import Image
  import requests

  url = 'http://images.cocodataset.org/val2017/000000039769.jpg'
  image = Image.open(requests.get(url, stream=True).raw)
  print(image.height, image.width)  # [480, 640]

  processor = AutoImageProcessor.from_pretrained('facebook/dinov2-base')
  model = AutoModel.from_pretrained('facebook/dinov2-base', device_map="auto")
  patch_size = model.config.patch_size

  inputs = processor(images=image, return_tensors="pt").to(model.device)
  print(inputs.pixel_values.shape)  # [1, 3, 224, 224]
  batch_size, rgb, img_height, img_width = inputs.pixel_values.shape
  num_patches_height, num_patches_width = img_height // patch_size, img_width // patch_size
  num_patches_flat = num_patches_height * num_patches_width

  outputs = model(**inputs)
  last_hidden_states = outputs[0]
  print(last_hidden_states.shape)  # [1, 1 + 256, 768]
  assert last_hidden_states.shape == (batch_size, 1 + num_patches_flat, model.config.hidden_size)

  cls_token = last_hidden_states[:, 0, :]
  patch_features = last_hidden_states[:, 1:, :].unflatten(1, (num_patches_height, num_patches_width))
  ```

- Use [torch.jit.trace](https://pytorch.org/docs/stable/generated/torch.jit.trace.html) para acelerar la inferencia. Sin embargo, generará algunos elementos no coincidentes. La diferencia entre el modelo original y el modelo trazado es de 1e-4.

  ```py
  import torch
  from transformers import AutoImageProcessor, AutoModel
  from PIL import Image
  import requests

  url = 'http://images.cocodataset.org/val2017/000000039769.jpg'
  image = Image.open(requests.get(url, stream=True).raw)

  processor = AutoImageProcessor.from_pretrained('facebook/dinov2-base')
  model = AutoModel.from_pretrained('facebook/dinov2-base', device_map="auto")

  inputs = processor(images=image, return_tensors="pt").to(model.device)
  outputs = model(**inputs)
  last_hidden_states = outputs[0]

  # We have to force return_dict=False for tracing
  model.config.return_dict = False

  with torch.no_grad():
      traced_model = torch.jit.trace(model, [inputs.pixel_values])
      traced_outputs = traced_model(inputs.pixel_values)

  print((last_hidden_states - traced_outputs[0]).abs().max())
  ```

## Dinov2Config[[transformers.Dinov2Config]]

#### transformers.Dinov2Config[[transformers.Dinov2Config]]

```python
transformers.Dinov2Config(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 = 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] = 14, 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, _out_features: list[str] | None = None, _out_indices: list[int] | None = None, apply_layernorm: bool = True, reshape_hidden_states: bool = True, use_mask_token: bool = True)
```

[Fuente](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/dinov2/configuration_dinov2.py#L25)

**Parámetros:**

hidden_size (`int`, *opcional*, valor predeterminado `768`) : Dimensión de las representaciones ocultas.

num_hidden_layers (`int`, *opcional*, valor predeterminado `12`) : Número de capas ocultas en el decodificador del Transformer.

num_attention_heads (`int`, *opcional*, valor predeterminado `12`) : Número de cabezas de atención para cada capa de atención en el decodificador Transformer.

mlp_ratio (`int`, *opcional*, valor predeterminado `4`) : Proporción entre la dimensión oculta del MLP y la dimensión de incrustación.

hidden_act (`str`, *opcional*, valor predeterminado `gelu`) : 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 predeterminado `0.0`) : La probabilidad de dropout para todas las capas completamente conectadas en los embeddings, el codificador y el pooler.

attention_probs_dropout_prob (`Union[float, int]`, *opcional*, valor predeterminado `0.0`) : La proporción de dropout para las probabilidades de atención.

initializer_range (`float`, *opcional*, valor predeterminado `0.02`) : La desviación estándar de truncated_normal_initializer para inicializar todas las matrices de pesos.

layer_norm_eps (`float`, *opcional*, valor predeterminado `1e-06`) : El epsilon utilizado por las capas de normalización de capas.

image_size (`Union[int, list[int], tuple[int, int]]`, *opcional*, valor predeterminado `224`) : El tamaño (resolución) de cada imagen.

patch_size (`Union[int, list[int], tuple[int, int]]`, *opcional*, valor predeterminado `14`) : El tamaño (resolución) de cada parche.

num_channels (`int`, *opcional*, valor predeterminado `3`) : El número de canales de entrada.

qkv_bias (`bool`, *opcional*, valor predeterminado `True`) : Indica 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 la capa.

drop_path_rate (`Union[float, int]`, *opcional*, valor predeterminado `0.0`) : Tasa de drop path para la fusión de parches.

use_swiglu_ffn (`bool`, *opcional*, por defecto `False`) : Si se debe usar la red neuronal de avance SwiGLU.

apply_layernorm (`bool`, *opcional*, valor predeterminado `True`) : Indica si se debe aplicar 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 predeterminado `True`) : Indica 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 es `False`, los mapas de características serán tensores 3D de forma `(batch_size, seq_len, hidden_size)`.

use_mask_token (`bool`, *opcional*, valor predeterminado `True`) : Si se debe usar mask_token en los embeddings.

Esta es la clase de configuración para almacenar la configuración de un Dinov2Model. Se utiliza para instanciar un modelo Dinov2 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-base](https://huggingface.co/facebook/dinov2-base)

Los objetos de configuración heredan de [PreTrainedConfig](/docs/transformers/v5.23.0/es/main_classes/configuration#transformers.PreTrainedConfig) y se pueden utilizar para controlar las salidas del modelo. Consulte la documentación de [PreTrainedConfig](/docs/transformers/v5.23.0/es/main_classes/configuration#transformers.PreTrainedConfig) para obtener más información.

Ejemplo:

```python
>>> from transformers import Dinov2Config, Dinov2Model

>>> # Initializing a Dinov2 dinov2-base style configuration
>>> configuration = Dinov2Config()

>>> # Initializing a model (with random weights) from the dinov2-base style configuration
>>> model = Dinov2Model(configuration)

>>> # Accessing the model configuration
>>> configuration = model.config
```

## Dinov2Model[[transformers.Dinov2Model]]

#### transformers.Dinov2Model[[transformers.Dinov2Model]]

```python
transformers.Dinov2Model(config: Dinov2Config)
```

[Fuente](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/dinov2/modeling_dinov2.py#L386)

**Parámetros:**

config ([Dinov2Config](/docs/transformers/v5.23.0/es/model_doc/dinov2#transformers.Dinov2Config)) : 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()](/docs/transformers/v5.23.0/es/main_classes/model#transformers.PreTrainedModel.from_pretrained) para cargar los pesos del modelo.

El modelo Dinov2 básico que genera estados ocultos sin ningún cabezal específico en la parte superior.

Este modelo hereda de [PreTrainedModel](/docs/transformers/v5.23.0/es/main_classes/model#transformers.PreTrainedModel). Consulte 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](https://pytorch.org/docs/stable/nn.html#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[[transformers.Dinov2Model.forward]]

```python
forward(pixel_values: typing.Optional[torch.Tensor] = None, bool_masked_pos: typing.Optional[torch.Tensor] = None, attention_mask: typing.Optional[torch.Tensor] = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[Fuente](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/dinov2/modeling_dinov2.py#L395)

**Parámetros:**

pixel_values (`torch.Tensor` de 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 mediante [BitImageProcessor](/docs/transformers/v5.23.0/es/model_doc/bit#transformers.BitImageProcessor). Consulte [BitImageProcessor.__call__()](/docs/transformers/v5.23.0/es/model_doc/molmo2#transformers.Molmo2ImageProcessor.__call__) para obtener más detalles (`processor_class` utiliza [BitImageProcessor](/docs/transformers/v5.23.0/es/model_doc/bit#transformers.BitImageProcessor) para procesar las imágenes).

bool_masked_pos (`torch.BoolTensor` de 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.Tensor` de forma `(batch_size, sequence_length)`, *opcional*) : Máscara para evitar realizar atención en los índices de tokens de relleno. Valores de la máscara seleccionados en `[0, 1]`:  - 1 para tokens que **no están enmascarados**, - 0 para tokens que **están enmascarados**.  [¿Qué son las máscaras de atención?](../glossary#attention-mask)

**Devuelve:** [BaseModelOutputWithPooling](/docs/transformers/v5.23.0/es/main_classes/output#transformers.modeling_outputs.BaseModelOutputWithPooling) o `tuple(torch.Tensor)`

Un [BaseModelOutputWithPooling](/docs/transformers/v5.23.0/es/main_classes/output#transformers.modeling_outputs.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 ([Dinov2Config](/docs/transformers/v5.23.0/es/model_doc/dinov2#transformers.Dinov2Config)) y las entradas.

El método forward de [Dinov2Model](/docs/transformers/v5.23.0/es/model_doc/dinov2#transformers.Dinov2Model) reemplaza 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 `Module` después, en lugar de a esta, ya que la primera se encarga de ejecutar los pasos de preprocesamiento y posprocesamiento, mientras que la segunda los ignora silenciosamente.

- **last_hidden_state** (`torch.Tensor` de forma `(batch_size, sequence_length, hidden_size)`) -- Secuencia de estados ocultos en la salida de la última capa del modelo.
- **pooler_output** (`torch.Tensor` de 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*, se devuelve cuando se pasa `output_hidden_states=True` o cuando `config.output_hidden_states=True`) -- Tupla de `torch.Tensor` (una para la salida de los embeddings, si el modelo tiene una capa de embedding, + 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 pasa `output_attentions=True` o cuando `config.output_attentions=True`) -- Tupla de `torch.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.

Ejemplo:

```python
```

## Dinov2ForImageClassification[[transformers.Dinov2ForImageClassification]]

#### transformers.Dinov2ForImageClassification[[transformers.Dinov2ForImageClassification]]

```python
transformers.Dinov2ForImageClassification(config: Dinov2Config)
```

[Fuente](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/dinov2/modeling_dinov2.py#L432)

**Parámetros:**

config ([Dinov2Config](/docs/transformers/v5.23.0/es/model_doc/dinov2#transformers.Dinov2Config)) : 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()](/docs/transformers/v5.23.0/es/main_classes/model#transformers.PreTrainedModel.from_pretrained) para cargar los pesos del modelo.

Transformador del modelo Dinov2 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](/docs/transformers/v5.23.0/es/main_classes/model#transformers.PreTrainedModel). Consulte 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](https://pytorch.org/docs/stable/nn.html#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[[transformers.Dinov2ForImageClassification.forward]]

```python
forward(pixel_values: typing.Optional[torch.Tensor] = None, labels: typing.Optional[torch.Tensor] = None, attention_mask: typing.Optional[torch.Tensor] = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[Fuente](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/dinov2/modeling_dinov2.py#L445)

**Parámetros:**

pixel_values (`torch.Tensor` de 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 mediante [BitImageProcessor](/docs/transformers/v5.23.0/es/model_doc/bit#transformers.BitImageProcessor). Consulte [BitImageProcessor.__call__()](/docs/transformers/v5.23.0/es/model_doc/molmo2#transformers.Molmo2ImageProcessor.__call__) para obtener más detalles (`processor_class` utiliza [BitImageProcessor](/docs/transformers/v5.23.0/es/model_doc/bit#transformers.BitImageProcessor) para procesar las imágenes).

labels (`torch.LongTensor` de forma `(batch_size,)`, *opcional*) : Etiquetas para calcular la pérdida de clasificación/regresión de imagen. Los índices deben estar en `[0, ..., config.num_labels - 1]`. Si `config.num_labels == 1` se calcula una pérdida de regresión (pérdida de error cuadrático medio), si `config.num_labels > 1` se calcula una pérdida de clasificación (entropía cruzada).

attention_mask (`torch.Tensor` de forma `(batch_size, sequence_length)`, *opcional*) : Máscara para evitar realizar atención en los índices de tokens de relleno. Valores de la máscara seleccionados en `[0, 1]`:  - 1 para tokens que **no están enmascarados**, - 0 para tokens que **están enmascarados**.  [¿Qué son las máscaras de atención?](../glossary#attention-mask)

**Devuelve:** [ImageClassifierOutput](/docs/transformers/v5.23.0/es/main_classes/output#transformers.modeling_outputs.ImageClassifierOutput) o `tuple(torch.Tensor)`

Un [ImageClassifierOutput](/docs/transformers/v5.23.0/es/main_classes/output#transformers.modeling_outputs.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 ([Dinov2Config](/docs/transformers/v5.23.0/es/model_doc/dinov2#transformers.Dinov2Config)) y las entradas.

El método forward de [Dinov2ForImageClassification](/docs/transformers/v5.23.0/es/model_doc/dinov2#transformers.Dinov2ForImageClassification) 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 `Module` después, en lugar de a esta, ya que la primera se encarga de ejecutar los pasos de preprocesamiento y posprocesamiento, mientras que la segunda los ignora silenciosamente.

- **loss** (`torch.Tensor` de forma `(1,)`, *opcional*, se devuelve cuando se proporciona `labels`) -- Pérdida de clasificación (o de regresión si config.num_labels==1).
- **logits** (`torch.Tensor` de 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 pasa `output_hidden_states=True` o cuando `config.output_hidden_states=True`) -- Tupla de `torch.Tensor` (una para la salida de los embeddings, si el modelo tiene una capa de embedding, + una para la salida de cada etapa) de forma `(batch_size, sequence_length, hidden_size)`. Hidden-states (también llamados feature maps) del modelo en la salida de cada etapa.
- **attentions** (`tuple(torch.Tensor)`, *opcional*, se devuelve cuando se pasa `output_attentions=True` o cuando `config.output_attentions=True`) -- Tupla de `torch.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:

```python
>>> from transformers import AutoImageProcessor, Dinov2ForImageClassification
>>> 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-base")
>>> model = Dinov2ForImageClassification.from_pretrained("facebook/dinov2-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])
...
```

