# ColModernVBert

## Visão geral

ColModernVBert é um modelo para recuperação visual eficiente de documentos. Ele utiliza o [ModernVBert](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](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)
```

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

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

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](https://huggingface.co/ModernVBERT/colmodernvbert-merged)

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

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/colmodernvbert/processing_colmodernvbert.py#L55)

**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](/docs/transformers/main/pt/model_doc/colmodernvbert#transformers.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[[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.models.colmodernvbert.processing_colmodernvbert.ColModernVBertProcessorKwargs'>)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/colmodernvbert/processing_colmodernvbert.py#L319)

**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 preparada. 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](/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.

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

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

#### process_queries[[transformers.ColModernVBertProcessor.process_queries]]

```python
process_queries(text: str | list[str], **kwargs: *<class 'transformers.models.colmodernvbert.processing_colmodernvbert.ColModernVBertProcessorKwargs'>)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/colmodernvbert/processing_colmodernvbert.py#L385)

**Parâmetros:**

text (`str`, `list[str]`, `list[list[str]]`) : A sequência ou lote de sequências a serem codificadas. Cada sequência pode ser uma string ou uma lista de strings (string pretokenizada). Se as sequências forem fornecidas como lista de strings (pretokenizadas), você deve definir `is_split_into_words=True` (para eliminar a ambiguidade com um lote de sequências).

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.

**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.
- **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, antecede o `query_prefix` 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[[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')
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/colmodernvbert/processing_colmodernvbert.py#L442)

**Parâmetros:**

query_embeddings (`Union[torch.Tensor, list[torch.Tensor]`) : Embeddings de consulta.

passage_embeddings (`Union[torch.Tensor, list[torch.Tensor]`) : Embebimentos de 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 multivetor (`qs`) e os embeddings 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[[transformers.ColModernVBertForRetrieval]]

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

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

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

**Parâmetros:**

config ([ColModernVBertConfig](/docs/transformers/main/pt/model_doc/colmodernvbert#transformers.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()](/docs/transformers/main/pt/main_classes/model#transformers.PreTrainedModel.from_pretrained) para carregar os pesos do modelo.

Seguindo a abordagem do ColPali, o ColModernVBert utiliza VLMs para construir embeddings multivetor 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 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 consideração 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*](https://arxiv.org/abs/2510.01149).

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*](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.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'>)
```

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

**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 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](/docs/transformers/main/pt/model_doc/colmodernvbert#transformers.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?](../glossary#attention-mask)

**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](/docs/transformers/main/pt/model_doc/colmodernvbert#transformers.ColModernVBertConfig)) e das entradas.

O método forward de [ColModernVBertForRetrieval](/docs/transformers/main/pt/model_doc/colmodernvbert#transformers.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 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.

Exemplo:

```python
```