# ColModernVBert

## Resumen

ColModernVBert es un modelo para la recuperación eficiente de documentos visuales. Utiliza [ModernVBert](modernvbert) para construir embeddings multivector directamente a partir de imágenes de documentos, siguiendo el enfoque de ColPali.

El modelo fue introducido en [ModernVBERT: Towards Smaller Visual Document Retrievers](https://huggingface.co/papers/2510.01149).

```python
import torch
from huggingface_hub import hf_hub_download
from PIL import Image

from transformers import ColModernVBertForRetrieval, ColModernVBertProcessor

processor = ColModernVBertProcessor.from_pretrained("ModernVBERT/colmodernvbert-hf")
model = ColModernVBertForRetrieval.from_pretrained("ModernVBERT/colmodernvbert-hf", device_map="auto")

# Load the test dataset
queries = [
    "A paint on the wall",
    "ColModernVBERT matches the performance of models nearly 10x larger on visual document benchmarks."
]

images = [
    Image.open(hf_hub_download("HuggingFaceTB/SmolVLM", "example_images/rococo.jpg", repo_type="space")),
    Image.open(hf_hub_download("ModernVBERT/colmodernvbert", "table.png", repo_type="model"))
]

# Preprocess the examples
batch_images = processor(images=images).to(model.device)
batch_queries = processor(text=queries).to(model.device)

# Run inference
with torch.inference_mode():
    image_embeddings = model(**batch_images).embeddings
    query_embeddings = model(**batch_queries).embeddings

# Compute retrieval scores
scores = processor.score_retrieval(
    query_embeddings=query_embeddings,
    passage_embeddings=image_embeddings,
)

scores = torch.softmax(scores, dim=-1)

print(scores)    # [[0.9350, 0.0650], [0.0015, 0.9985]]
```

## ColModernVBertConfig[[transformers.ColModernVBertConfig]]

#### transformers.ColModernVBertConfig[[transformers.ColModernVBertConfig]]

```python
transformers.ColModernVBertConfig(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, vlm_config: dict | transformers.configuration_utils.PreTrainedConfig | None = None, embedding_dim: int = 128, initializer_range: float = 0.02)
```

[Fuente](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/colmodernvbert/configuration_colmodernvbert.py#L31)

**Parámetros:**

vlm_config (`Union[dict, ~configuration_utils.PreTrainedConfig]`, *opcional*) : El objeto de configuración o el diccionario del backbone de visión-lenguaje.

embedding_dim (`int`, *opcional*, valor predeterminado `128`) : Dimensionalidad de los embeddings y los estados ocultos.

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

Esta es la clase de configuración para almacenar la configuración de un ColmodernvbertModel. Se utiliza para instanciar un modelo Colmodernvbert 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 [ModernVBERT/colmodernvbert-merged](https://huggingface.co/ModernVBERT/colmodernvbert-merged)

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 ColModernVBertConfig, ColModernVBertForRetrieval

config = ColModernVBertConfig()
model = ColModernVBertForRetrieval(config)
```

## ColModernVBertProcessor[[transformers.ColModernVBertProcessor]]

#### transformers.ColModernVBertProcessor[[transformers.ColModernVBertProcessor]]

```python
transformers.ColModernVBertProcessor(image_processor, tokenizer = None, chat_template = None, image_seq_len: int = 64, visual_prompt_prefix: str | None = None, query_prefix: str | None = None, **kwargs)
```

[Fuente](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/colmodernvbert/processing_colmodernvbert.py#L54)

**Parámetros:**

image_processor (`image_processor_class`): el procesador de imágenes es un parámetro de entrada obligatorio.

tokenizer (`tokenizer_class`): El tokenizador es una entrada obligatoria.

chat_template (`str`) : Una plantilla de Jinja para convertir listas de mensajes de un chat en una cadena tokenizable.

image_seq_len (`int`, *opcional*, valor predeterminado: 64) : La longitud de la secuencia de imagen, es decir, el número de tokens por imagen en la entrada.

visual_prompt_prefix (`str`, *opcional*) : Una cadena que se tokeniza y se antepone a los tokens de imagen.

query_prefix (`str`, *opcional*) : Un prefijo que se usará para la consulta.

Construye un ColModernVBertProcessor que envuelve un procesador de imágenes y un tokenizador en un único procesador.

[ColModernVBertProcessor](/docs/transformers/v5.23.0/es/model_doc/colmodernvbert#transformers.ColModernVBertProcessor) ofrece todas las funcionalidades de `image_processor_class` y `tokenizer_class`. Consulte `~image_processor_class` y `~tokenizer_class` para obtener más información.

#### process_images[[transformers.ColModernVBertProcessor.process_images]]

```python
process_images(images: typing.Union[ForwardRef('PIL.Image.Image'), numpy.ndarray, ForwardRef('torch.Tensor'), list['PIL.Image.Image'], list[numpy.ndarray], list['torch.Tensor'], NoneType] = None, **kwargs: *<class 'transformers.processing_utils.ProcessingKwargs'>)
```

[Fuente](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/colmodernvbert/processing_colmodernvbert.py#L330)

**Parámetros:**

images (`PIL.Image.Image`, `np.ndarray`, `torch.Tensor`, `list[PIL.Image.Image]`, `list[np.ndarray]`, `list[torch.Tensor]`) : La imagen o el lote de imágenes que se van a preparar. Cada imagen puede ser una imagen PIL, un array de NumPy o un tensor de PyTorch. En el caso de un array de NumPy o un tensor de PyTorch, cada imagen debe tener la forma (C, H, W), donde C es el número de canales, y H y W son la altura y el ancho de la imagen, respectivamente.

return_tensors (`str` o [TensorType](/docs/transformers/v5.23.0/es/internal/file_utils#transformers.TensorType), *opcional*) : Si se establece, devolverá tensores de un marco de trabajo específico. Los valores aceptables son:  - `'pt'`: Devuelve objetos `torch.Tensor` de PyTorch. - `'np'`: Devuelve objetos `np.ndarray` de NumPy.

**Devuelve:** [BatchFeature](/docs/transformers/v5.23.0/es/main_classes/feature_extractor#transformers.BatchFeature)

Un [BatchFeature](/docs/transformers/v5.23.0/es/main_classes/feature_extractor#transformers.BatchFeature) con los siguientes campos:

- **input_ids** -- Lista de ids de tokens que se enviarán a un modelo.
- **attention_mask** -- Lista de índices que especifica qué tokens deben ser atendidos por el modelo (cuando `return_attention_mask=True` o si *"attention_mask"* está en `self.model_input_names` y si `text` no es `None`).
- **pixel_values** -- Valores de píxeles que se enviarán a un modelo. Se devuelve cuando `images` no es `None`.

Prepara una o varias imágenes para el modelo. Gestiona la validación de la entrada, la conversión a RGB y antepone `visual_prompt_prefix` a cada imagen. Opcionalmente, calcula las etiquetas a partir de `token_type_ids` cuando se proporciona un `suffix` en `text_kwargs`.

#### process_queries[[transformers.ColModernVBertProcessor.process_queries]]

```python
process_queries(text: str | list[str], suffix: str | None = None, **kwargs: *<class 'transformers.processing_utils.ProcessingKwargs'>)
```

[Fuente](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/colmodernvbert/processing_colmodernvbert.py#L390)

**Parámetros:**

text (`str`, `list[str]`, `list[list[str]]`) : La secuencia o el lote de secuencias que se van a codificar. Cada secuencia puede ser una cadena de caracteres o una lista de cadenas de caracteres (cadenas pretokenizadas). Si las secuencias se proporcionan como lista de cadenas de caracteres (pretokenizadas), debe establecer `is_split_into_words=True` (para eliminar la ambigüedad con un lote de secuencias).

suffix (`str`, *opcional*) : Sufijo añadido a las consultas.

return_tensors (`str` o [TensorType](/docs/transformers/v5.23.0/es/internal/file_utils#transformers.TensorType), *opcional*) : Si se establece, devolverá tensores de un marco de trabajo específico. Los valores aceptables son:  - `'pt'`: Devuelve objetos `torch.Tensor` de PyTorch. - `'np'`: Devuelve objetos `np.ndarray` de NumPy.

**Devuelve:** [BatchFeature](/docs/transformers/v5.23.0/es/main_classes/feature_extractor#transformers.BatchFeature)

Un [BatchFeature](/docs/transformers/v5.23.0/es/main_classes/feature_extractor#transformers.BatchFeature) con los siguientes campos:

- **input_ids** -- Lista de ids de tokens que se enviarán a un modelo.
- **attention_mask** -- Lista de índices que especifica qué tokens deben ser atendidos por el modelo (cuando `return_attention_mask=True` o si *"attention_mask"* está en `self.model_input_names` y si `text` no es `None`).

Prepara una o varias consultas de texto para el modelo. Maneja la validación de la entrada, antepone `query_prefix` y añade tokens de aumento de consulta (utilizados para rellenar los embeddings de consulta y mejorar el rendimiento de la recuperación de interacción tardía).

#### score_retrieval[[transformers.ColModernVBertProcessor.score_retrieval]]

```python
score_retrieval(query_embeddings: typing.Union[ForwardRef('torch.Tensor'), list['torch.Tensor']], passage_embeddings: typing.Union[ForwardRef('torch.Tensor'), list['torch.Tensor']], batch_size: int = 128, output_dtype: typing.Optional[ForwardRef('torch.dtype')] = None, output_device: typing.Union[ForwardRef('torch.device'), str] = 'cpu')
```

[Fuente](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/colmodernvbert/processing_colmodernvbert.py#L454)

**Parámetros:**

query_embeddings (`Union[torch.Tensor, list[torch.Tensor]`) : Embeddings de consulta.

passage_embeddings (`Union[torch.Tensor, list[torch.Tensor]`) : Embeddings de pasajes.

batch_size (`int`, *opcional*, valor predeterminado 128) : Tamaño del lote para el cálculo de las puntuaciones.

output_dtype (`torch.dtype`, *opcional*, valor predeterminado `torch.float32`) : El dtype del tensor de salida. Si es `None`, se utiliza el dtype de las incrustaciones de entrada.

output_device (`torch.device` o `str`, *opcional*, valor predeterminado "cpu") : El dispositivo del tensor de salida.

**Devuelve:** `torch.Tensor`

Un tensor de forma `(n_queries, n_passages)` que contiene las puntuaciones. El tensor de puntuaciones se guarda en el dispositivo "cpu".

Calcule la puntuación de interacción tardía/MaxSim (similar a ColBERT) para los embeddings de consulta multivector (`qs`) y los embeddings de pasaje (`ps`) dados. En ColQwen2, un pasaje es la imagen de una página de documento.

Dado que los tensores de incrustación son de multivector y, por lo tanto, pueden tener formas diferentes, deben proporcionarse como: (1) una lista de tensores, donde el i-ésimo tensor tiene la forma (sequence_length_i, embedding_dim) (2) un único tensor de forma (n_passages, max_sequence_length, embedding_dim) -> generalmente obtenido mediante el relleno (padding) de la lista de tensores.

## ColModernVBertForRetrieval[[transformers.ColModernVBertForRetrieval]]

#### transformers.ColModernVBertForRetrieval[[transformers.ColModernVBertForRetrieval]]

```python
transformers.ColModernVBertForRetrieval(config: ColModernVBertConfig)
```

[Fuente](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/colmodernvbert/modeling_colmodernvbert.py#L91)

**Parámetros:**

config ([ColModernVBertConfig](/docs/transformers/v5.23.0/es/model_doc/colmodernvbert#transformers.ColModernVBertConfig)) : 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.

Siguiendo el enfoque de ColPali, ColModernVBert aprovecha los VLM para construir embeddings multivectoriales eficientes directamente a partir de imágenes de documentos (“capturas de pantalla”) para la recuperación de documentos. El modelo se entrena para maximizar la similitud entre estos embeddings de documentos y los embeddings de consulta correspondientes, utilizando el método de interacción tardía introducido en ColBERT.

El uso de ColModernVBert elimina la necesidad de pipelines de reconocimiento de diseño y OCR que pueden ser complejos y frágiles, mediante un único modelo que puede tener en cuenta tanto el contenido textual como el visual (diseño, gráficos, ...) de un documento.

ColModernVBert se entrena sobre ModernVBert y fue introducido en el siguiente artículo: [*ModernVBERT: Towards Smaller Visual Document Retrievers*](https://arxiv.org/abs/2510.01149).

ColModernVBert forma parte de la familia de modelos ColVision, que se presentó con ColPali en el siguiente artículo: [*ColPali: Efficient Document Retrieval with Vision Language Models*](https://huggingface.co/papers/2407.01449).

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.ColModernVBertForRetrieval.forward]]

```python
forward(input_ids: typing.Optional[torch.LongTensor] = None, pixel_values: 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/colmodernvbert/modeling_colmodernvbert.py#L105)

**Parámetros:**

input_ids (`torch.LongTensor` de forma `(batch_size, sequence_length)`, *opcional*) : Índices de los tokens de la secuencia de entrada en el vocabulario. El relleno se ignorará de forma predeterminada. Los índices se pueden obtener mediante [AutoTokenizer](/docs/transformers/v5.23.0/es/model_doc/auto#transformers.AutoTokenizer). Consulte [PreTrainedTokenizer.encode()](/docs/transformers/v5.23.0/es/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) y [PreTrainedTokenizer.__call__()](/docs/transformers/v5.23.0/es/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__) para obtener más detalles. [¿Qué son los IDs de entrada?](../glossary#input-ids)

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 usando `image_processor_class`. Consulte `image_processor_class.__call__` para más detalles ([ColModernVBertProcessor](/docs/transformers/v5.23.0/es/model_doc/colmodernvbert#transformers.ColModernVBertProcessor) usa `image_processor_class` para procesar las imágenes).

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:** `ColModernVBertForRetrievalOutput` o `tuple(torch.Tensor)`

Un `ColModernVBertForRetrievalOutput` 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 ([ColModernVBertConfig](/docs/transformers/v5.23.0/es/model_doc/colmodernvbert#transformers.ColModernVBertConfig)) y las entradas.

El método forward de [ColModernVBertForRetrieval](/docs/transformers/v5.23.0/es/model_doc/colmodernvbert#transformers.ColModernVBertForRetrieval) 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 modelado de lenguaje (para la predicción del siguiente token).
- **embeddings** (`torch.Tensor` de forma `(batch_size, sequence_length, hidden_size)`) -- Las embeddings del modelo.
- **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 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.
- **image_hidden_states** (`tuple(torch.Tensor)`, *opcional*, se devuelve cuando se pasa `output_hidden_states=True` o cuando `config.output_hidden_states=True` y se proporcionan `pixel_values`) -- Tupla de `torch.Tensor` (una para la salida de la proyección de la modalidad de imagen + una para la salida de cada capa) de forma `(batch_size, num_channels, image_size, image_size)`. Estados ocultos del codificador de imagen en la salida de cada capa más las salidas iniciales de la proyección de modalidad.
- **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
```