# ColPali

[ColPali](https://huggingface.co/papers/2407.01449) é um modelo projetado para recuperar documentos analisando seus recursos visuais. Diferentemente dos sistemas tradicionais, que dependem fortemente da extração de texto e do OCR, o ColPali trata cada página como uma imagem. Ele utiliza o [Paligemma-3B](./paligemma) para capturar não apenas o texto, mas também o layout, tabelas, gráficos e outros elementos visuais, criando embeddings multivetoriais detalhados que podem ser usados para recuperação por meio do cálculo de pontuações de similaridade de interação tardia par a par. Isso oferece uma compreensão mais abrangente dos documentos e permite uma recuperação mais eficiente e precisa.

Este modelo foi contribuído por [@tonywu71](https://huggingface.co/tonywu71) (ILLUIN Technology) e [@yonigozlan](https://huggingface.co/yonigozlan) (HuggingFace).

Você pode encontrar todos os checkpoints originais do ColPali na coleção [Hf-native ColVision Models](https://huggingface.co/collections/vidore/hf-native-colvision-models-6755d68fc60a8553acaa96f7) do Vidore.

> [!TIP]
> Clique nos modelos ColPali na barra lateral à direita para ver mais exemplos de como usar o ColPali para recuperação de imagens.

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

Se você tiver problemas ao carregar as imagens com PIL, pode usar o código a seguir para criar imagens fictícias:

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

A quantização reduz a carga de memória de modelos grandes ao representar os pesos em uma precisão menor. Consulte a visão geral de [Quantização](../quantization/overview) para mais backends de quantização disponíveis.

O exemplo abaixo usa [bitsandbytes](../quantization/bitsandbytes) para quantizar os pesos para 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)
```

## Observações

- `score_retrieval()` retorna um tensor 2D em que a primeira dimensão corresponde ao número de consultas e a segunda dimensão ao número de imagens. Uma pontuação mais alta indica maior similaridade entre a consulta e a imagem.

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

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

**Parâmetros:**

vlm_config (`Union[dict, ~configuration_utils.PreTrainedConfig]`, *opcional*) : O objeto de configuração ou dicionário do backbone de visão-linguagem.

embedding_dim (`int`, *opcional*, padrão `128`) : Dimensionalidade dos embeddings e dos estados ocultos.

Esta é a classe de configuração para armazenar a configuração de um ColpaliModel. Ela é usada para instanciar um modelo Colpali de acordo com os argumentos especificados, definindo a arquitetura do modelo. Instanciar uma configuração com os padrões resultará em uma configuração semelhante à do [vidore/colpali-v1.2](https://huggingface.co/vidore/colpali-v1.2)

Os objetos de configuração herdam de [PreTrainedConfig](/docs/transformers/main/pt/main_classes/configuration#transformers.PreTrainedConfig) e podem ser usados para controlar as saídas do modelo. Leia a documentação de [PreTrainedConfig](/docs/transformers/main/pt/main_classes/configuration#transformers.PreTrainedConfig) para mais informações.

Exemplo:

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

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/colpali/processing_colpali.py#L54)

**Parâmetros:**

image_processor (`SiglipImageProcessor`) : O processador de imagem é uma entrada obrigatória.

tokenizer (`tokenizer_class`) : O tokenizer é uma entrada obrigatória.

chat_template (`str`) : Um modelo Jinja para converter listas de mensagens em um chat em uma string tokenizável.

visual_prompt_prefix (`str`, *opcional*, padrão `"Describe the image."`) : Uma string que é tokenizada e adicionada antes dos tokens da imagem.

query_prefix (`str`, *opcional*, padrão `"Question : "`): Um prefixo a ser usado para a consulta.

Constrói um ColPaliProcessor que encapsula um processador de imagem e um tokenizer em um único processador.

[ColPaliProcessor](/docs/transformers/main/pt/model_doc/colpali#transformers.ColPaliProcessor) oferece todas as funcionalidades de [SiglipImageProcessor](/docs/transformers/main/pt/model_doc/siglip#transformers.SiglipImageProcessor) e `tokenizer_class`. Consulte [~SiglipImageProcessor](/docs/transformers/main/pt/model_doc/siglip#transformers.SiglipImageProcessor) e `~tokenizer_class` para mais informações.

#### __call__[[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, **kwargs: *<class 'transformers.models.colpali.processing_colpali.ColPaliProcessorKwargs'>)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/colpali/processing_colpali.py#L94)

**Parâmetros:**

images (`Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]]`, *opcional*) : Imagem a ser pré-processada. Espera uma única imagem ou um lote de imagens com valores de pixel variando de 0 a 255. Se estiver passando imagens com valores de pixel entre 0 e 1, defina `do_rescale=False`.

text (`Union[str, list[str], list[list[str]]]`, *opcional*) : A sequência ou lote de sequências a ser codificada. Cada sequência pode ser uma string ou uma lista de strings (string pretokenizada). Se você passar uma entrada pretokenizada, defina `is_split_into_words=True` para evitar ambiguidade com entradas em lote.

return_tensors (`str` ou [TensorType](/docs/transformers/main/pt/internal/file_utils#transformers.TensorType), *opcional*) : Se definido, retornará tensores de um framework específico. Os valores aceitos são:  - `'pt'`: Retorna objetos `torch.Tensor` do PyTorch. - `'np'`: Retorna objetos `np.ndarray` do NumPy.

- ****kwargs** ([ProcessingKwargs](/docs/transformers/main/pt/main_classes/processors#transformers.ProcessingKwargs), *opcional*) : Opções de processamento adicionais para cada modalidade (texto, imagens, vídeos, áudio). Os parâmetros específicos do modelo estão listados acima; consulte a classe TypedDict para a lista completa de argumentos suportados.

**Retorna:** [BatchFeature](/docs/transformers/main/pt/main_classes/feature_extractor#transformers.BatchFeature)

Um [BatchFeature](/docs/transformers/main/pt/main_classes/feature_extractor#transformers.BatchFeature) com os seguintes campos:

- **input_ids** -- Lista de ids de tokens a serem fornecidos a um modelo. Retornado quando `text` não é `None`. Se `suffix` for fornecido, os `input_ids` também conterão os ids de entrada do sufixo.
- **attention_mask** -- Lista de índices que especifica quais tokens devem ser considerados pelo modelo (quando `return_attention_mask=True` ou se *"attention_mask"* estiver em `self.model_input_names` e se `text` não for `None`).
- **pixel_values** -- Valores de pixel a serem fornecidos a um modelo. Retornado quando `images` não é `None`.
- **labels** -- Rótulos compatíveis com o treinamento se `suffix` não for None

## ColPaliForRetrieval[[transformers.ColPaliForRetrieval]]

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

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

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

**Parâmetros:**

config ([ColPaliConfig](/docs/transformers/main/pt/model_doc/colpali#transformers.ColPaliConfig)) : Classe de configuração do modelo com todos os parâmetros do modelo. A inicialização com um arquivo de configuração não carrega os pesos associados ao modelo, apenas a configuração. Consulte o método [from_pretrained()](/docs/transformers/main/pt/main_classes/model#transformers.PreTrainedModel.from_pretrained) para carregar os pesos do modelo.

A arquitetura ColPali utiliza VLMs para construir embeddings multivetores eficientes diretamente de imagens de documentos (“capturas de tela”) para recuperação de documentos. O modelo é treinado para maximizar a similaridade entre esses embeddings de documentos e os embeddings de consulta correspondentes, utilizando o método de interação tardia introduzido no ColBERT.

O uso do ColPali elimina a necessidade de pipelines de reconhecimento de layout e OCR potencialmente complexos e frágeis, com um único modelo que pode levar em consideração tanto o conteúdo textual quanto o visual (layout, gráficos, etc.) de um documento.

ColPali faz parte da família de modelos ColVision, que foi introduzida pela primeira vez no seguinte artigo: [*ColPali: Efficient Document Retrieval with Vision Language Models*](https://huggingface.co/papers/2407.01449).

Este modelo herda de [PreTrainedModel](/docs/transformers/main/pt/main_classes/model#transformers.PreTrainedModel). Consulte a documentação da classe pai para os métodos genéricos que a biblioteca implementa para todos os seus modelos (como download ou salvamento, redimensionamento dos embeddings de entrada, poda de cabeças, etc.).

Este modelo também é uma subclasse de [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) do PyTorch. Use-o como um Módulo PyTorch regular e consulte a documentação do PyTorch para todos os assuntos relacionados ao uso e comportamento gerais.

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

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/colpali/modeling_colpali.py#L104)

**Parâmetros:**

input_ids (`torch.LongTensor` de forma `(batch_size, sequence_length)`, *opcional*) : Índices dos tokens da sequência de entrada no vocabulário. O preenchimento (padding) será ignorado por padrão. Os índices podem ser obtidos usando [AutoTokenizer](/docs/transformers/main/pt/model_doc/auto#transformers.AutoTokenizer). Consulte [PreTrainedTokenizer.encode()](/docs/transformers/main/pt/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) e [PreTrainedTokenizer.__call__()](/docs/transformers/main/pt/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__) para mais detalhes. [O que são IDs de entrada?](../glossary#input-ids)

pixel_values (`torch.Tensor` de forma `(batch_size, num_channels, image_size, image_size)`, *opcional*) : Os tensors correspondentes às imagens de entrada. Os valores de pixels podem ser obtidos usando `image_processor_class`. Consulte `image_processor_class.__call__` para mais detalhes (`processor_class` usa `image_processor_class` para processar as imagens).

attention_mask (`torch.Tensor` de forma `(batch_size, sequence_length)`, *opcional*) : Máscara para evitar a execução de atenção nos índices de tokens de preenchimento. Valores de máscara selecionados em `[0, 1]`:  - 1 para tokens que **não estão mascarados**, - 0 para tokens que **estão mascarados**.  [O que são máscaras de atenção?](../glossary#attention-mask)

**Retorna:** `ColPaliForRetrievalOutput` ou `tuple(torch.Tensor)`

Um `ColPaliForRetrievalOutput` ou uma tupla de `torch.Tensor` (se `return_dict=False` for passado ou quando `config.return_dict=False`) contendo vários elementos dependendo da configuração (`None`) e das entradas.

O método forward de [ColPaliForRetrieval](/docs/transformers/main/pt/model_doc/colpali#transformers.ColPaliForRetrieval) substitui o método especial `__call__`.

Embora a receita para a passagem direta precise ser definida dentro desta função, deve-se chamar a instância de `Module` em seguida, em vez desta, pois a primeira cuida da execução das etapas de pré e pós-processamento, enquanto a segunda as ignora silenciosamente.

- **loss** (`torch.Tensor` de forma `(1,)`, *opcional*, retornado quando `labels` é fornecido) -- Perda de modelagem de linguagem (para previsão do próximo token).
- **embeddings** (`torch.Tensor` de forma `(batch_size, sequence_length, hidden_size)`) -- Os embeddings do modelo.
- **past_key_values** (`Cache`, *opcional*, retornado quando `use_cache=True` é passado ou quando `config.use_cache=True`) -- Trata-se de uma instância de [Cache](/docs/transformers/main/pt/internal/generation_utils#transformers.Cache). Para mais detalhes, consulte nosso [guia de cache kv](https://huggingface.co/docs/transformers/en/kv_cache).

  Contém estados ocultos pré-computados (chaves e valores nos blocos de autoatenção) que podem ser usados (veja a entrada `past_key_values`) para acelerar a decodificação sequencial.
- **hidden_states** (`tuple[torch.Tensor]`, *opcional*, retornado quando `output_hidden_states=True` é passado ou quando `config.output_hidden_states=True`) -- Tupla de `torch.Tensor` (um para a saída dos embeddings, se o modelo tiver uma camada de embedding, + um para a saída de cada camada) de forma `(batch_size, sequence_length, hidden_size)`.

  Estados ocultos do modelo na saída de cada camada, além das saídas opcionais do embedding inicial.
- **attentions** (`tuple[torch.Tensor]`, *opcional*, retornado quando `output_attentions=True` é passado ou quando `config.output_attentions=True`) -- Tupla de `torch.Tensor` (um para cada camada) com a forma `(batch_size, num_heads, sequence_length, sequence_length)`.

  Pesos de atenção após o softmax de atenção, usados para calcular a média ponderada nas cabeças de autoatenção.
- **image_hidden_states** (`torch.Tensor`, *opcional*) -- Um `torch.Tensor` de tamanho `(batch_size, num_images, sequence_length, hidden_size)`. image_hidden_states do modelo produzido pelo codificador de visão após projetar o último estado oculto.