Hugging Face's logo

Transformers documentation

ColPali

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v5.22.1).
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Este modelo foi publicado no HF papers em 2024-06-27 e contribuído para o Hugging Face Transformers em 2024-12-17.

ColPali

ColPali é 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 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 (ILLUIN Technology) e @yonigozlan (HuggingFace).

Você pode encontrar todos os checkpoints originais do ColPali na coleção Hf-native ColVision Models do Vidore.

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

recuperação de imagens
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:

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 para mais backends de quantização disponíveis.

O exemplo abaixo usa bitsandbytes para quantizar os pesos para int4.

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

classe transformers.ColPaliConfig

< >

( transformers_version: str | None = Nonearchitectures: list[str] | None = Noneoutput_hidden_states: bool | None = Falsereturn_dict: bool | None = Truedtype: str | torch.dtype | None = Nonechunk_size_feed_forward: int = 0is_encoder_decoder: bool = Falseid2label: dict[int, str] | dict[str, str] | None = Nonelabel2id: dict[str, int] | dict[str, str] | None = Noneproblem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = Nonevlm_config: dict | transformers.configuration_utils.PreTrainedConfig | None = Noneembedding_dim: int = 128 )

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) — Dimensão 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

Os objetos de configuração herdam de PreTrainedConfig e podem ser usados para controlar as saídas do modelo. Consulte a documentação de PreTrainedConfig para mais informações.

Exemplo:

from transformers.models.colpali import ColPaliConfig, ColPaliForRetrieval

config = ColPaliConfig()
model = ColPaliForRetrieval(config)

ColPaliProcessor

classe transformers.ColPaliProcessor

< >

( image_processor = Nonetokenizer = Nonechat_template = Nonevisual_prompt_prefix: str = 'Describe the image.'query_prefix: str = 'Question: ' )

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 oferece todas as funcionalidades de SiglipImageProcessor e tokenizer_class. Consulte ~SiglipImageProcessor e ~tokenizer_class para mais informações.

__call__

< >

( images: typing.Union[ForwardRef('PIL.Image.Image'), numpy.ndarray, ForwardRef('torch.Tensor'), list['PIL.Image.Image'], list[numpy.ndarray], list['torch.Tensor'], NoneType] = Nonetext: str | list[str] | list[list[str]] = None**kwargs: *<class 'transformers.models.colpali.processing_colpali.ColPaliProcessorKwargs'> ) → BatchFeature

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 passar 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 pré-tokenizada). Se você passar uma entrada pré-tokenizada, defina is_split_into_words=True para evitar ambiguidade com entradas em lote.
  • return_tensors (str ou TensorType, opcional) — Se definido, retornará tensors 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, 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

Um 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 pixels 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

classe transformers.ColPaliForRetrieval

< >

( config: ColPaliConfig )

Parâmetros

  • config (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() para carregar os pesos do modelo.

A arquitetura ColPali utiliza VLMs para construir embeddings multivetor eficientes diretamente a partir de imagens de documentos (“screenshots”) 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 conta 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.

Este modelo herda de 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 do PyTorch. Use-o como um Módulo PyTorch regular e consulte a documentação do PyTorch para todos os assuntos relacionados ao uso geral e ao comportamento.

forward

< >

( input_ids: typing.Optional[torch.LongTensor] = Nonepixel_values: typing.Optional[torch.FloatTensor] = Noneattention_mask: typing.Optional[torch.Tensor] = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → ColPaliForRetrievalOutput or tuple(torch.FloatTensor)

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 padding será ignorado por padrão.

    Os índices podem ser obtidos usando AutoTokenizer. Consulte PreTrainedTokenizer.encode() e PreTrainedTokenizer.call() para mais detalhes.

    O que são IDs de entrada?

  • pixel_values (torch.FloatTensor de forma (batch_size, num_channels, image_size, image_size), opcional) — Os tensores 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?

Retorna

ColPaliForRetrievalOutput ou tuple(torch.FloatTensor)

Um ColPaliForRetrievalOutput ou uma tupla de torch.FloatTensor (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 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.FloatTensor de forma (1,), opcional, retornado quando labels é fornecido) — Perda de modelagem de linguagem (para previsão do próximo token).

  • embeddings (torch.FloatTensor 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) — É uma instância de Cache. Para mais detalhes, consulte nosso guia de cache kv.

    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.FloatTensor], opcional, retornado quando output_hidden_states=True é passado ou quando config.output_hidden_states=True) — Tupla de torch.FloatTensor (uma para a saída dos embeddings, se o modelo tiver uma camada de embedding, + uma 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.FloatTensor], opcional, retornado quando output_attentions=True é passado ou quando config.output_attentions=True) — Tupla de torch.FloatTensor (uma para cada camada) com 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 nos cabeçalhos de autoatenção.

  • image_hidden_states (torch.FloatTensor, opcional) — Um torch.FloatTensor 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.

Update on GitHub

←ColModernVBert ColQwen2→