# ColModernVBert

## Aperçu

ColModernVBert est un modèle pour la récupération efficace de documents visuels. Il exploite [ModernVBert](modernvbert) pour construire des embeddings multi-vecteurs directement à partir d'images de documents, en suivant l'approche ColPali.

Le modèle a été introduit dans [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)
```

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

**Paramètres :**

vlm_config (`Union[dict, ~configuration_utils.PreTrainedConfig]`, *facultatif*) : L'objet de configuration ou le dictionnaire du backbone vision-langage.

embedding_dim (`int`, *facultatif*, par défaut `128`) : Dimension des embeddings et des états cachés.

initializer_range (`float`, *facultatif*, valeur par défaut `0.02`) : L'écart-type de la truncated_normal_initializer utilisé pour l'initialisation de toutes les matrices de poids.

Il s'agit de la classe de configuration destinée à stocker la configuration d'un ColmodernvbertModel. Elle est utilisée pour instancier un modèle Colmodernvbert en fonction des arguments spécifiés, en définissant l'architecture du modèle. L'instanciation d'une configuration avec les valeurs par défaut produira une configuration similaire à celle de [ModernVBERT/colmodernvbert-merged](https://huggingface.co/ModernVBERT/colmodernvbert-merged)

Les objets de configuration héritent de [PreTrainedConfig](/docs/transformers/v5.23.0/fr/main_classes/configuration#transformers.PreTrainedConfig) et peuvent être utilisés pour contrôler les sorties du modèle. Consultez la documentation de [PreTrainedConfig](/docs/transformers/v5.23.0/fr/main_classes/configuration#transformers.PreTrainedConfig) pour plus d’informations.

Exemple :

```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)
```

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

**Paramètres :**

image_processor (`image_processor_class`) : le processeur d'images est une entrée obligatoire.

tokenizer (`tokenizer_class`) : Le tokenizer est une entrée obligatoire.

chat_template (`str`) : Un modèle Jinja pour convertir des listes de messages d'une conversation en une chaîne tokenisable.

image_seq_len (`int`, *facultatif*, valeur par défaut : 64) : La longueur de la séquence d'image, c'est-à-dire le nombre de jetons par image dans l'entrée.

visual_prompt_prefix (`str`, *facultatif*) : Une chaîne de caractères qui est tokenisée et ajoutée avant les jetons d'image.

query_prefix (`str`, *facultatif*) : Un préfixe à utiliser pour la requête.

Construit un ColModernVBertProcessor qui encapsule un processeur d’images et un tokenizer en un seul processeur.

[ColModernVBertProcessor](/docs/transformers/v5.23.0/fr/model_doc/colmodernvbert#transformers.ColModernVBertProcessor) offre toutes les fonctionnalités de `image_processor_class` et de `tokenizer_class`. Consultez `~image_processor_class` et `~tokenizer_class` pour plus d’informations.

#### 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'>)
```

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

**Paramètres :**

images (`PIL.Image.Image`, `np.ndarray`, `torch.Tensor`, `list[PIL.Image.Image]`, `list[np.ndarray]`, `list[torch.Tensor]`) : L'image ou le lot d'images à préparer. Chaque image peut être une image PIL, un tableau NumPy ou un tenseur PyTorch. Dans le cas d'un tableau NumPy/d'un tenseur PyTorch, chaque image doit avoir la forme (C, H, W), où C est le nombre de canaux, et H et W sont la hauteur et la largeur de l'image.

return_tensors (`str` ou [TensorType](/docs/transformers/v5.23.0/fr/internal/file_utils#transformers.TensorType), *facultatif*) : Si défini, renverra des tenseurs d'un framework particulier. Les valeurs acceptables sont :  - `'pt'` : Renvoie des objets `torch.Tensor` de PyTorch. - `'np'` : Renvoie des objets `np.ndarray` de NumPy.

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

Un [BatchFeature](/docs/transformers/v5.23.0/fr/main_classes/feature_extractor#transformers.BatchFeature) avec les champs suivants :

- **input_ids** -- Liste des identifiants de jetons à fournir au modèle.
- **attention_mask** -- Liste d'indices spécifiant les jetons auxquels le modèle doit prêter attention (lorsque `return_attention_mask=True` ou si *"attention_mask"* est présent dans `self.model_input_names` et si `text` n'est pas `None`).
- **pixel_values** -- Valeurs des pixels à fournir à un modèle. Renvoyé lorsque `images` n'est pas `None`.

Prépare une ou plusieurs image(s) pour le modèle. Gère la validation des entrées, la conversion en RGB et préfixe chaque image avec `visual_prompt_prefix`. Calcule éventuellement les étiquettes à partir de `token_type_ids` lorsqu'un `suffix` est fourni dans `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'>)
```

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

**Paramètres :**

text (`str`, `list[str]`, `list[list[str]]`) : La séquence ou le lot de séquences à encoder. Chaque séquence peut être une chaîne de caractères ou une liste de chaînes de caractères (chaîne pré-tokenisée). Si les séquences sont fournies sous forme de liste de chaînes de caractères (pré-tokenisées), vous devez définir `is_split_into_words=True` (pour lever l'ambiguïté avec un lot de séquences).

suffix (`str`, *facultatif*) : Suffixe ajouté aux requêtes.

return_tensors (`str` ou [TensorType](/docs/transformers/v5.23.0/fr/internal/file_utils#transformers.TensorType), *facultatif*) : Si défini, renverra des tenseurs d'un framework particulier. Les valeurs acceptables sont :  - `'pt'` : Renvoie des objets `torch.Tensor` de PyTorch. - `'np'` : Renvoie des objets `np.ndarray` de NumPy.

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

Un [BatchFeature](/docs/transformers/v5.23.0/fr/main_classes/feature_extractor#transformers.BatchFeature) avec les champs suivants :

- **input_ids** -- Liste des identifiants de jetons à fournir au modèle.
- **attention_mask** -- Liste d'indices spécifiant les jetons auxquels le modèle doit prêter attention (lorsque `return_attention_mask=True` ou si *"attention_mask"* est présent dans `self.model_input_names` et si `text` n'est pas `None`).

Prépare une ou plusieurs requêtes textuelles pour le modèle. Gère la validation des entrées, préfixe le `query_prefix` et ajoute les jetons d'augmentation de requête (utilisés pour rembourrer les embeddings de requête afin d'améliorer les performances de la récupération par interaction tardive).

#### 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')
```

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

**Paramètres :**

query_embeddings (`Union[torch.Tensor, list[torch.Tensor]`) : Embeddings de requête.

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

batch_size (`int`, *facultatif*, valeur par défaut 128) : Taille du lot pour le calcul des scores.

output_dtype (`torch.dtype`, *facultatif*, par défaut `torch.float32`) : Le dtype du tenseur de sortie. Si `None`, le dtype des embeddings d'entrée est utilisé.

output_device (`torch.device` ou `str`, *facultatif*, par défaut "cpu") : L'appareil du tenseur de sortie.

**Retourne :** `torch.Tensor`

Un tenseur de forme `(n_queries, n_passages)` contenant les scores. Le tenseur de scores est enregistré sur l'appareil « cpu ».

Calcule le score late-interaction/MaxSim (de type ColBERT) pour les embeddings de requête multi-vecteurs (`qs`) et les embeddings de passages (`ps`) donnés. Pour ColQwen2, un passage correspond à l'image d'une page de document.

Comme les tenseurs d'embedding sont multi-vecteurs et peuvent donc avoir des formes différentes, ils doivent être fournis sous la forme : (1) une liste de tenseurs, où le i-ème tenseur a la forme (sequence_length_i, embedding_dim) (2) un tenseur unique de forme (n_passages, max_sequence_length, embedding_dim) -> généralement obtenu en appliquant un padding à la liste de tenseurs.

## ColModernVBertForRetrieval[[transformers.ColModernVBertForRetrieval]]

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

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

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

**Paramètres :**

config ([ColModernVBertConfig](/docs/transformers/v5.23.0/fr/model_doc/colmodernvbert#transformers.ColModernVBertConfig)) : Classe de configuration du modèle contenant tous les paramètres du modèle. L'initialisation à partir d'un fichier de configuration ne charge pas les poids associés au modèle, uniquement la configuration. Consultez la méthode [from_pretrained()](/docs/transformers/v5.23.0/fr/main_classes/model#transformers.PreTrainedModel.from_pretrained) pour charger les poids du modèle.

Dans la lignée de l’approche ColPali, ColModernVBert exploite les VLM pour construire des embeddings multi-vecteurs efficaces directement à partir d’images de documents (« captures d’écran ») en vue de la récupération de documents. Le modèle est entraîné pour maximiser la similarité entre ces embeddings de documents et les embeddings de requêtes correspondants, en utilisant la méthode d’interaction tardive introduite dans ColBERT.

L'utilisation de ColModernVBert supprime le besoin de pipelines de reconnaissance de mise en page et d'OCR potentiellement complexes et fragiles, grâce à un modèle unique capable de prendre en compte à la fois le contenu textuel et visuel (mise en page, graphiques, ...) d'un document.

ColModernVBert est entraîné à partir de ModernVBert et a été introduit dans l'article suivant : [*ModernVBERT: Towards Smaller Visual Document Retrievers*](https://arxiv.org/abs/2510.01149).

ColModernVBert fait partie de la famille de modèles ColVision, qui a été introduite avec ColPali dans l'article suivant : [*ColPali: Efficient Document Retrieval with Vision Language Models*](https://huggingface.co/papers/2407.01449).

Ce modèle hérite de [PreTrainedModel](/docs/transformers/v5.23.0/fr/main_classes/model#transformers.PreTrainedModel). Consultez la documentation de la classe parente pour les méthodes génériques que la bibliothèque implémente pour tous ses modèles (tels que le téléchargement ou l'enregistrement, le redimensionnement des embeddings d'entrée, l'élagage des têtes, etc.).

Ce modèle est également une sous-classe de [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) de PyTorch. Utilisez-le comme un module PyTorch standard et consultez la documentation de PyTorch pour tout ce qui concerne l’utilisation et le comportement généraux.

#### 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'>)
```

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

**Paramètres :**

input_ids (`torch.LongTensor` de forme `(batch_size, sequence_length)`, *facultatif*) : Indices des jetons de la séquence d'entrée dans le vocabulaire. Le bourrage (padding) sera ignoré par défaut. Les indices peuvent être obtenus à l'aide de [AutoTokenizer](/docs/transformers/v5.23.0/fr/model_doc/auto#transformers.AutoTokenizer). Consultez [PreTrainedTokenizer.encode()](/docs/transformers/v5.23.0/fr/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) et [PreTrainedTokenizer.__call__()](/docs/transformers/v5.23.0/fr/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__) pour plus de détails. [Que sont les identifiants d'entrée ?](../glossary#input-ids)

pixel_values (`torch.Tensor` de forme `(batch_size, num_channels, image_size, image_size)`, *facultatif*) : Les tenseurs correspondant aux images d'entrée. Les valeurs des pixels peuvent être obtenues à l'aide de `image_processor_class`. Voir `image_processor_class.__call__` pour plus de détails ([ColModernVBertProcessor](/docs/transformers/v5.23.0/fr/model_doc/colmodernvbert#transformers.ColModernVBertProcessor) utilise `image_processor_class` pour le traitement des images).

attention_mask (`torch.Tensor` de forme `(batch_size, sequence_length)`, *facultatif*) : Masque pour éviter d'appliquer l'attention aux indices des jetons de bourrage. Les valeurs du masque sont choisies dans `[0, 1]` : - 1 pour les jetons qui ne sont **pas masqués**, - 0 pour les jetons qui sont **masqués**. [Qu'est-ce qu'un masque d'attention ?](../glossary#attention-mask)

**Retourne :** `ColModernVBertForRetrievalOutput` ou `tuple(torch.Tensor)`

Un `ColModernVBertForRetrievalOutput` ou un tuple de `torch.Tensor` (si `return_dict=False` est passé ou lorsque `config.return_dict=False`) comprenant divers éléments selon la configuration ([ColModernVBertConfig](/docs/transformers/v5.23.0/fr/model_doc/colmodernvbert#transformers.ColModernVBertConfig)) et les entrées.

La méthode forward de [ColModernVBertForRetrieval](/docs/transformers/v5.23.0/fr/model_doc/colmodernvbert#transformers.ColModernVBertForRetrieval) redéfinit la méthode spéciale `__call__`.

Bien que la recette de la passe avant doive être définie dans cette fonction, il faut ensuite appeler l'instance `Module` plutôt que celle-ci, car la première gère l'exécution des étapes de prétraitement et de post-traitement, tandis que la seconde les ignore silencieusement.

- **loss** (`torch.Tensor` de forme `(1,)`, *facultatif*, renvoyé lorsque `labels` est fourni) -- Perte de modélisation du langage (pour la prédiction du jeton suivant).
- **embeddings** (`torch.Tensor` de forme `(batch_size, sequence_length, hidden_size)`) -- Les embeddings du modèle.
- **hidden_states** (`tuple[torch.Tensor]`, *facultatif*, renvoyé lorsque `output_hidden_states=True` est passé ou lorsque `config.output_hidden_states=True`) -- Tuple de `torch.Tensor` (un pour la sortie des embeddings, si le modèle possède une couche d'embedding, + un pour la sortie de chaque couche) de forme `(batch_size, sequence_length, hidden_size)`.

  États cachés du modèle à la sortie de chaque couche, ainsi que les sorties d'incorporation initiales facultatives.
- **image_hidden_states** (`tuple(torch.Tensor)`, *facultatif*, renvoyé lorsque `output_hidden_states=True` est passé ou lorsque `config.output_hidden_states=True` et que `pixel_values` sont fournis) -- Tuple de `torch.Tensor` (un pour la sortie de la projection de la modalité image + un pour la sortie de chaque couche) de forme `(batch_size, num_channels, image_size, image_size)`. États cachés de l'encodeur d'images à la sortie de chaque couche, ainsi que les sorties initiales de la projection de la modalité.
- **attentions** (`tuple[torch.Tensor]`, *facultatif*, renvoyé lorsque `output_attentions=True` est passé ou lorsque `config.output_attentions=True`) -- Tuple de `torch.Tensor` (un par couche) de forme `(batch_size, num_heads, sequence_length, sequence_length)`.

  Pondérations des attentions après le softmax d'attention, utilisées pour calculer la moyenne pondérée dans les têtes d'auto-attention.

Exemple :

```python
```

