Hugging Face's logo

Transformers documentation

ColModernVBert

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 2025-10-01 e contribuído para o Hugging Face Transformers em 2026-02-23.

ColModernVBert

FlashAttention SDPA

Visão geral

ColModernVBert é um modelo para recuperação visual eficiente de documentos. Ele utiliza o ModernVBert para construir embeddings multivetoriais diretamente a partir de imagens de documentos, seguindo a abordagem ColPali.

O modelo foi introduzido em ModernVBERT: Towards Smaller Visual Document Retrievers.

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

classe transformers.ColModernVBertConfig

< >

( 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 = 128initializer_range: float = 0.02 )

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.
  • initializer_range (float, opcional, padrão 0.02) — O desvio padrão do truncated_normal_initializer para inicializar todas as matrizes de pesos.

Esta é a classe de configuração para armazenar a configuração de um ColmodernvbertModel. Ela é usada para instanciar um modelo Colmodernvbert 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 ModernVBERT/colmodernvbert-merged

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

config = ColModernVBertConfig()
model = ColModernVBertForRetrieval(config)

ColModernVBertProcessor

classe transformers.ColModernVBertProcessor

< >

( image_processortokenizer = Nonechat_template = Noneimage_seq_len: int = 64visual_prompt_prefix: str | None = Nonequery_prefix: str | None = None**kwargs )

Parâmetros

  • image_processor (image_processor_class) — 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.
  • image_seq_len (int, opcional, padrão 64) — O comprimento da sequência de imagem, ou seja, o número de tokens por imagem na entrada.
  • visual_prompt_prefix (str, opcional) — Uma string que é tokenizada e adicionada antes dos tokens da imagem.
  • query_prefix (str, opcional) — Um prefixo a ser usado para a consulta.

Constrói um ColModernVBertProcessor que encapsula um processador de imagem e um tokenizador em um único processador.

ColModernVBertProcessor oferece todas as funcionalidades de image_processor_class e tokenizer_class. Consulte ~image_processor_class e ~tokenizer_class para mais informações.

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.models.colmodernvbert.processing_colmodernvbert.ColModernVBertProcessorKwargs'> ) → BatchFeature

Parâmetros

  • images (PIL.Image.Image, np.ndarray, torch.Tensor, list[PIL.Image.Image], list[np.ndarray], list[torch.Tensor]) — A imagem ou lote de imagens a ser preparado. Cada imagem pode ser uma imagem PIL, um array NumPy ou um tensor PyTorch. No caso de um array NumPy/tensor PyTorch, cada imagem deve ter a forma (C, H, W), onde C é o número de canais, e H e W são a altura e a largura da imagem, respectivamente.
  • 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.

Retorna

BatchFeature

Um BatchFeature com os seguintes campos:

  • input_ids — Lista de ids de tokens a serem fornecidos a um modelo.
  • 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.

Prepara uma ou várias imagens para o modelo. Trata a validação da entrada, a conversão para RGB e antepõe o visual_prompt_prefix a cada imagem. Opcionalmente, calcula os rótulos a partir de token_type_ids quando um suffix é fornecido em text_kwargs.

process_queries

< >

( text: str | list[str]**kwargs: *<class 'transformers.models.colmodernvbert.processing_colmodernvbert.ColModernVBertProcessorKwargs'> ) → BatchFeature

Parâmetros

  • text (str, list[str], list[list[str]]) — 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 as sequências forem fornecidas como lista de strings (pré-tokenizadas), você deve definir is_split_into_words=True (para eliminar a ambiguidade com um lote de sequências).
  • 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.

Retorna

BatchFeature

Um BatchFeature com os seguintes campos:

  • input_ids — Lista de ids de tokens a serem fornecidos a um modelo.
  • 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).

Prepare uma ou várias consultas de texto para o modelo. Trata da validação da entrada, adiciona o query_prefix no início e acrescenta tokens de aumento de consulta (usados para preencher os embeddings de consulta para um melhor desempenho de recuperação de interação tardia).

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 = 128output_dtype: typing.Optional[ForwardRef('torch.dtype')] = Noneoutput_device: typing.Union[ForwardRef('torch.device'), str] = 'cpu' ) → torch.Tensor

Parâmetros

  • query_embeddings (Union[torch.Tensor, list[torch.Tensor]) — Embeddings de consulta.
  • passage_embeddings (Union[torch.Tensor, list[torch.Tensor]) — Embeddings das passagens.
  • batch_size (int, opcional, padrão 128) — Tamanho do lote para o cálculo das pontuações.
  • output_dtype (torch.dtype, opcional, padrão torch.float32) — O dtype do tensor de saída. Se None, o dtype dos embeddings de entrada é utilizado.
  • output_device (torch.device ou str, opcional, padrão “cpu”) — O dispositivo do tensor de saída.

Retorna

torch.Tensor

Um tensor de forma (n_queries, n_passages) contendo as pontuações. O tensor de pontuações é salvo no dispositivo “cpu”.

Calcule a pontuação de interação tardia/MaxSim (estilo ColBERT) para os embeddings de consulta multi-vetor (qs) e de passagem (ps) fornecidos. No ColQwen2, uma passagem é a imagem de uma página de documento.

Como os tensores de incorporação são multivetoriais e, portanto, podem ter formas diferentes, eles devem ser fornecidos como: (1) uma lista de tensores, em que o i-ésimo tensor tem a forma (sequence_length_i, embedding_dim) (2) um único tensor com a forma (n_passages, max_sequence_length, embedding_dim) -> geralmente obtido ao aplicar padding na lista de tensores.

ColModernVBertForRetrieval

classe transformers.ColModernVBertForRetrieval

< >

( config: ColModernVBertConfig )

Parâmetros

  • config (ColModernVBertConfig) — 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.

Seguindo a abordagem do ColPali, o ColModernVBert utiliza VLMs para construir embeddings multi-vetores 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 ColModernVBert 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 conteúdo visual (layout, gráficos, …) de um documento.

ColModernVBert é treinado sobre o ModernVBert e foi introduzido no seguinte artigo: ModernVBERT: Towards Smaller Visual Document Retrievers.

ColModernVBert faz parte da família de modelos ColVision, que foi introduzida com o ColPali 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.Tensor] = Noneattention_mask: typing.Optional[torch.Tensor] = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → ColModernVBertForRetrievalOutput or tuple(torch.Tensor)

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.Tensor 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 detalhes (ColModernVBertProcessor usa image_processor_class para processar 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

ColModernVBertForRetrievalOutput ou tuple(torch.Tensor)

Um ColModernVBertForRetrievalOutput 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 (ColModernVBertConfig) e das entradas.

O método forward de ColModernVBertForRetrieval sobrescreve 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.

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

  • image_hidden_states (tuple(torch.Tensor), opcional, retornado quando output_hidden_states=True é passado ou quando config.output_hidden_states=True e pixel_values são fornecidos) — Tupla de torch.Tensor (um para a saída da projeção da modalidade de imagem + um para a saída de cada camada) com forma (batch_size, num_channels, image_size, image_size). Estados ocultos do codificador de imagem na saída de cada camada, além das saídas iniciais da projeção de modalidade.

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

Exemplo:

Update on GitHub

←CohereCompass ColPali→