# ColPali

[ColPali](https://huggingface.co/papers/2407.01449) est un modèle conçu pour récupérer des documents en analysant leurs caractéristiques visuelles. Contrairement aux systèmes traditionnels qui s’appuient fortement sur l’extraction de texte et l’OCR, ColPali traite chaque page comme une image. Il utilise [Paligemma-3B](./paligemma) pour capturer non seulement le texte, mais aussi la mise en page, les tableaux, les graphiques et autres éléments visuels, afin de créer des embeddings multi-vecteurs détaillés qui peuvent être utilisés pour la récupération en calculant des scores de similarité d’interaction tardive par paires. Cela offre une compréhension plus complète des documents et permet une récupération plus efficace et plus précise.

Ce modèle a été contribué par [@tonywu71](https://huggingface.co/tonywu71) (ILLUIN Technology) et [@yonigozlan](https://huggingface.co/yonigozlan) (HuggingFace).

Vous pouvez trouver tous les points de contrôle originaux de ColPali dans la collection [Hf-native ColVision Models](https://huggingface.co/collections/vidore/hf-native-colvision-models-6755d68fc60a8553acaa96f7) de Vidore.

> [!TIP]
> Cliquez sur les modèles ColPali dans la barre latérale droite pour plus d’exemples sur l’utilisation de ColPali pour la récupération d’images.

```python
import requests
import torch
from PIL import Image

from transformers import ColPaliForRetrieval, ColPaliProcessor

# Load the model and the processor
model_name = "vidore/colpali-v1.3-hf"

model = ColPaliForRetrieval.from_pretrained(
    model_name,
    device_map="auto",  # "cpu", "cuda", "xpu", or "mps" for Apple Silicon
)
processor = ColPaliProcessor.from_pretrained(model_name)

# The document page screenshots from your corpus
url1 = "https://upload.wikimedia.org/wikipedia/commons/8/89/US-original-Declaration-1776.jpg"
url2 = "https://upload.wikimedia.org/wikipedia/commons/thumb/4/4c/Romeoandjuliet1597.jpg/500px-Romeoandjuliet1597.jpg"

images = [
    Image.open(requests.get(url1, stream=True).raw),
    Image.open(requests.get(url2, stream=True).raw),
]

# The queries you want to retrieve documents for
queries = [
    "When was the United States Declaration of Independence proclaimed?",
    "Who printed the edition of Romeo and Juliet?",
]

# Process the inputs
inputs_images = processor(images=images).to(model.device)
inputs_text = processor(text=queries).to(model.device)

# Forward pass
with torch.no_grad():
    image_embeddings = model(**inputs_images).embeddings
    query_embeddings = model(**inputs_text).embeddings

# Score the queries against the images
scores = processor.score_retrieval(query_embeddings, image_embeddings)

print("Retrieval scores (query x image):")
print(scores)
```

Si vous rencontrez un problème lors du chargement des images avec PIL, vous pouvez utiliser le code suivant pour créer des images factices :

```python
images = [
    Image.new("RGB", (128, 128), color="white"),
    Image.new("RGB", (64, 32), color="black"),
]
```

La quantification réduit la charge mémoire des grands modèles en représentant les poids avec une précision inférieure. Reportez-vous à l'aperçu de la [Quantization](../quantization/overview) pour plus d'informations sur les backends de quantification disponibles.

L'exemple ci-dessous utilise [bitsandbytes](../quantization/bitsandbytes) pour quantiser les poids en int4.

```python
import requests
import torch
from PIL import Image

from transformers import BitsAndBytesConfig, ColPaliForRetrieval, ColPaliProcessor

model_name = "vidore/colpali-v1.3-hf"

# 4-bit quantization configuration
bnb_config = BitsAndBytesConfig(
    load_in_4bit=True,
    bnb_4bit_use_double_quant=True,
    bnb_4bit_quant_type="nf4",
    bnb_4bit_compute_dtype=torch.float16,
)

model = ColPaliForRetrieval.from_pretrained(
    model_name,
    quantization_config=bnb_config,
    device_map="auto",
)

processor = ColPaliProcessor.from_pretrained(model_name)

url1 = "https://upload.wikimedia.org/wikipedia/commons/8/89/US-original-Declaration-1776.jpg"
url2 = "https://upload.wikimedia.org/wikipedia/commons/thumb/4/4c/Romeoandjuliet1597.jpg/500px-Romeoandjuliet1597.jpg"

images = [
    Image.open(requests.get(url1, stream=True).raw),
    Image.open(requests.get(url2, stream=True).raw),
]

queries = [
    "When was the United States Declaration of Independence proclaimed?",
    "Who printed the edition of Romeo and Juliet?",
]

# Process the inputs
inputs_images = processor(images=images, return_tensors="pt").to(model.device)
inputs_text = processor(text=queries, return_tensors="pt").to(model.device)

# Forward pass
with torch.no_grad():
    image_embeddings = model(**inputs_images).embeddings
    query_embeddings = model(**inputs_text).embeddings

# Score the queries against the images
scores = processor.score_retrieval(query_embeddings, image_embeddings)

print("Retrieval scores (query x image):")
print(scores)
```

## Notes

- `score_retrieval()` renvoie un tenseur 2D dont la première dimension correspond au nombre de requêtes et la seconde au nombre d’images. Un score plus élevé indique une plus grande similarité entre la requête et l’image.

## ColPaliConfig[[transformers.ColPaliConfig]]

#### transformers.ColPaliConfig[[transformers.ColPaliConfig]]

```python
transformers.ColPaliConfig(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)
```

[Source](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/colpali/configuration_colpali.py#L28)

**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.

Il s'agit de la classe de configuration destinée à stocker la configuration d'un ColpaliModel. Elle est utilisée pour instancier un modèle Colpali 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 [vidore/colpali-v1.2](https://huggingface.co/vidore/colpali-v1.2)

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.models.colpali import ColPaliConfig, ColPaliForRetrieval

config = ColPaliConfig()
model = ColPaliForRetrieval(config)
```

## ColPaliProcessor[[transformers.ColPaliProcessor]]

#### transformers.ColPaliProcessor[[transformers.ColPaliProcessor]]

```python
transformers.ColPaliProcessor(image_processor = None, tokenizer = None, chat_template = None, visual_prompt_prefix: str = 'Describe the image.', query_prefix: str = 'Question: ')
```

[Source](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/colpali/processing_colpali.py#L42)

**Paramètres :**

image_processor (`SiglipImageProcessor`) : 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.

visual_prompt_prefix (`str`, *facultatif*, valeur par défaut `"Describe the image."`) : une chaîne de caractères qui est tokenisée et ajoutée avant les jetons de l'image.

query_prefix (`str`, *facultatif*, valeur par défaut `"Question : "`) : un préfixe à utiliser pour la requête.

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

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

#### __appel__[[transformers.ColPaliProcessor.__call__]]

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

[Source](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/colpali/processing_colpali.py#L90)

**Paramètres :**

images (`Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]]`, *facultatif*) : Image à prétraiter. Attend une image unique ou un lot d'images dont les valeurs de pixels sont comprises entre 0 et 255. Si vous transmettez des images dont les valeurs de pixels sont comprises entre 0 et 1, définissez `do_rescale=False`.

text (`Union[str, list[str], list[list[str]]]`, *facultatif*) : 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 (chaîne pré-tokenisée). Si vous transmettez une entrée pré-tokenisée, définissez `is_split_into_words=True` pour éviter toute ambiguïté avec les entrées en lot.

suffix (`str | list[str] | list[list[str]]`, *facultatif*) : Le suffixe ajouté à tous les textes d'entrée.

return_mm_token_type_ids (`bool`, *kwargs*) : Indique s'il faut retourner les identifiants de type de jeton multimodal indiquant les positions des jetons de substitution multimodaux.

return_text_replacement_offsets (`bool`, *kwargs*) : Indique s'il faut retourner les décalages de caractères pour chaque emplacement multimodal et son remplacement.

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.

- ****kwargs** ([ProcessingKwargs](/docs/transformers/v5.23.0/fr/main_classes/processors#transformers.ProcessingKwargs), *facultatif*) : Options de traitement supplémentaires pour chaque modalité (texte, images, vidéos, audio). Les paramètres spécifiques au modèle sont répertoriés ci-dessus ; consultez la classe TypedDict pour la liste complète des arguments pris en charge.

**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. Renvoyé lorsque `text` n'est pas `None`. Si `suffix` est fourni, les `input_ids` contiendront également les identifiants de jetons du suffixe.
- **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`.
- **labels** -- Étiquettes compatibles avec l'entraînement si `suffix` n'est pas None

## ColPaliForRetrieval[[transformers.ColPaliForRetrieval]]

#### transformers.ColPaliForRetrieval[[transformers.ColPaliForRetrieval]]

```python
transformers.ColPaliForRetrieval(config: ColPaliConfig)
```

[Source](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/colpali/modeling_colpali.py#L90)

**Paramètres :**

config ([ColPaliConfig](/docs/transformers/v5.23.0/fr/model_doc/colpali#transformers.ColPaliConfig)) : 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.

L’architecture ColPali 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 ColPali 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, etc.) d’un document.

ColPali fait partie de la famille de modèles ColVision, d'abord introduite 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.ColPaliForRetrieval.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/colpali/modeling_colpali.py#L104)

**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 (`processor_class` 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 :** `ColPaliForRetrievalOutput` ou `tuple(torch.Tensor)`

Un `ColPaliForRetrievalOutput` 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 (`None`) et les entrées.

La méthode forward de [ColPaliForRetrieval](/docs/transformers/v5.23.0/fr/model_doc/colpali#transformers.ColPaliForRetrieval) 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.
- **past_key_values** (`Cache`, *facultatif*, renvoyé lorsque `use_cache=True` est passé ou lorsque `config.use_cache=True`) -- Il s'agit d'une instance de [Cache](/docs/transformers/v5.23.0/fr/internal/generation_utils#transformers.Cache). Pour plus de détails, consultez notre [guide sur le cache kv](https://huggingface.co/docs/transformers/en/kv_cache).

  Contient des états cachés précalculés (clés et valeurs dans les blocs d'auto-attention) qui peuvent être utilisés (voir l'entrée `past_key_values`) pour accélérer le décodage séquentiel.
- **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.
- **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.
- **image_hidden_states** (`torch.Tensor`, *facultatif*) -- Un `torch.Tensor` de taille `(batch_size, num_images, sequence_length, hidden_size)`. image_hidden_states du modèle produit par l'encodeur visuel après projection de l'état caché final.