# ColQwen2

[ColQwen2](https://huggingface.co/papers/2407.01449) é uma variante do modelo [ColPali](./colpali) projetada para recuperar documentos analisando seus recursos visuais. Diferentemente dos sistemas tradicionais que dependem fortemente da extração de texto e do OCR, o ColQwen2 trata cada página como uma imagem. Ele utiliza o backbone [Qwen2-VL](./qwen2_vl) 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 ao calcular pontuações de similaridade de interação tardia em pares. 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 ColQwen2 na barra lateral à direita para ver mais exemplos de como usar o ColQwen2 para recuperação de imagens.

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

from transformers import ColQwen2ForRetrieval, ColQwen2Processor
from transformers.utils.import_utils import is_flash_attn_2_available

# Load the model and the processor
model_name = "vidore/colqwen2-v1.0-hf"

model = ColQwen2ForRetrieval.from_pretrained(
    model_name,
    device_map="auto",  # "cpu", "cuda", "xpu" or "mps" for Apple Silicon
    attn_implementation="flash_attention_2" if is_flash_attn_2_available() else "sdpa",
)
processor = ColQwen2Processor.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, ColQwen2ForRetrieval, ColQwen2Processor

model_name = "vidore/colqwen2-v1.0-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 = ColQwen2ForRetrieval.from_pretrained(
    model_name,
    quantization_config=bnb_config,
    device_map="auto",
).eval()

processor = ColQwen2Processor.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)
```

Você também pode usar checkpoints para `ColQwen2.5` que são **compatíveis com a arquitetura ColQwen2**. Esta versão do modelo usa [Qwen2_5_VL](./qwen2_5_vl) como backbone.

```python
from transformers import ColQwen2ForRetrieval, ColQwen2Processor
from transformers.utils.import_utils import is_flash_attn_2_available

model_name = "Sahil-Kabir/colqwen2.5-v0.2-hf" # An existing compatible checkpoint

model = ColQwen2ForRetrieval.from_pretrained(
    model_name,
    device_map="auto",
    attn_implementation="flash_attention_2" if is_flash_attn_2_available() else "sdpa"
)
processor = ColQwen2Processor.from_pretrained(model_name)
```

## 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.
- Diferentemente do ColPali, o ColQwen2 suporta resoluções e proporções de imagem arbitrárias, o que significa que as imagens não são redimensionadas para quadrados de tamanho fixo. Isso preserva mais do sinal de entrada original.
- Imagens de entrada maiores geram embeddings multivetoriais mais longos, permitindo que os usuários ajustem a resolução da imagem para equilibrar desempenho e uso de memória.

## ColQwen2Config[[transformers.ColQwen2Config]]

#### transformers.ColQwen2Config[[transformers.ColQwen2Config]]

```python
transformers.ColQwen2Config(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/colqwen2/configuration_colqwen2.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.

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 Colqwen2Model. Ela é usada para instanciar um modelo Colqwen2 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/colqwen2-v1.0-hf](https://huggingface.co/vidore/colqwen2-v1.0-hf)

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.colqwen2 import ColQwen2Config, ColQwen2ForRetrieval

config = ColQwen2Config()
model = ColQwen2ForRetrieval(config)
```

## ColQwen2Processor[[transformers.ColQwen2Processor]]

#### transformers.ColQwen2Processor[[transformers.ColQwen2Processor]]

```python
transformers.ColQwen2Processor(image_processor = None, tokenizer = None, chat_template = None, visual_prompt_prefix: str | None = None, query_prefix: str | None = None, **kwargs)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/colqwen2/processing_colqwen2.py#L51)

**Parâmetros:**

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

tokenizer (`Qwen2Tokenizer`) : 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 `"<|im_start|>user\n<|vision_start|><|image_pad|><|vision_end|>Describe the image.<|im_end|><|endoftext|>"`) : Uma string que é tokenizada e adicionada antes dos tokens da imagem.

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

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

[ColQwen2Processor](/docs/transformers/main/pt/model_doc/colqwen2#transformers.ColQwen2Processor) oferece todas as funcionalidades de [Qwen2VLImageProcessor](/docs/transformers/main/pt/model_doc/qwen2_vl#transformers.Qwen2VLImageProcessor) e [Qwen2Tokenizer](/docs/transformers/main/pt/model_doc/qwen2#transformers.Qwen2Tokenizer). Consulte [~Qwen2VLImageProcessor](/docs/transformers/main/pt/model_doc/qwen2_vl#transformers.Qwen2VLImageProcessor) e [~Qwen2Tokenizer](/docs/transformers/main/pt/model_doc/qwen2#transformers.Qwen2Tokenizer) para mais informações.

#### __call__[[transformers.ColQwen2Processor.__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.colqwen2.processing_colqwen2.ColQwen2ProcessorKwargs'>)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/colqwen2/processing_colqwen2.py#L77)

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

## ColQwen2ForRetrieval[[transformers.ColQwen2ForRetrieval]]

#### transformers.ColQwen2ForRetrieval[[transformers.ColQwen2ForRetrieval]]

```python
transformers.ColQwen2ForRetrieval(config: ColQwen2Config)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/colqwen2/modeling_colqwen2.py#L92)

**Parâmetros:**

config ([ColQwen2Config](/docs/transformers/main/pt/model_doc/colqwen2#transformers.ColQwen2Config)) : 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 ColQwen2 utiliza VLMs para construir embeddings multivetores 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 ColQwen2 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, ...) de um documento.

ColQwen2 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.ColQwen2ForRetrieval.forward]]

```python
forward(input_ids: typing.Optional[torch.LongTensor] = None, attention_mask: typing.Optional[torch.Tensor] = None, position_ids: typing.Optional[torch.LongTensor] = None, past_key_values: transformers.cache_utils.Cache | None = None, labels: typing.Optional[torch.LongTensor] = None, inputs_embeds: typing.Optional[torch.Tensor] = None, use_cache: bool | None = None, output_attentions: bool | None = None, output_hidden_states: bool | None = None, return_dict: bool | None = None, pixel_values: typing.Optional[torch.Tensor] = None, image_grid_thw: typing.Optional[torch.LongTensor] = None, **kwargs)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/colqwen2/modeling_colqwen2.py#L106)

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

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)

position_ids (`torch.LongTensor` de forma `(batch_size, sequence_length)`, *opcional*) : Índices das posições dos tokens de cada sequência de entrada nos embeddings de posição. Selecionados no intervalo `[0, config.n_positions - 1]`.  [O que são IDs de posição?](../glossary#position-ids)

past_key_values (`~cache_utils.Cache`, *opcional*) : hidden-states pré-computados (chaves e valores nos blocos de autoatenção e nos blocos de atenção cruzada) que podem ser usados para acelerar a decodificação sequencial. Isso geralmente consiste nos `past_key_values` retornados pelo modelo em uma etapa anterior da decodificação, quando `use_cache=True` ou `config.use_cache=True`.  Apenas uma instância de [Cache](/docs/transformers/main/pt/internal/generation_utils#transformers.Cache) é permitida como entrada, consulte nosso [guia de kv cache](https://huggingface.co/docs/transformers/en/kv_cache). Se nenhum `past_key_values` for passado, [DynamicCache](/docs/transformers/main/pt/internal/generation_utils#transformers.DynamicCache) será inicializado por padrão.  O modelo sairá no mesmo formato de cache que foi fornecido como entrada.  Se `past_key_values` forem usados, espera-se que o usuário insira apenas `input_ids` não processados (aqueles que não têm seus estados de chave e valor passados para este modelo) com a forma `(batch_size, unprocessed_length)` em vez de todos os `input_ids` com a forma `(batch_size, sequence_length)`.

labels (`torch.LongTensor` de forma `(batch_size, sequence_length)`, *opcional*) : Rótulos para calcular a perda de modelagem de linguagem mascarada. Os índices devem estar em `[0, ..., config.vocab_size]` ou ser -100 (veja a docstring de `input_ids`). Tokens com índices definidos como `-100` são ignorados (mascarados); a perda é calculada apenas para os tokens com rótulos em `[0, ..., config.vocab_size]`.

inputs_embeds (`torch.Tensor` de forma `(batch_size, sequence_length, hidden_size)`, *opcional*) : Opcionalmente, em vez de passar `input_ids`, você pode escolher passar diretamente uma representação incorporada. Isso é útil se você quiser ter mais controle sobre como converter os índices de `input_ids` nos vetores associados do que a matriz de busca de incorporação interna do modelo.

use_cache (`bool`, *opcional*) : Se definido como `True`, os estados de chave-valor de `past_key_values` são retornados e podem ser usados para acelerar a decodificação (veja `past_key_values`).

output_attentions (`bool`, *opcional*) : Indica se os tensores de atenção de todas as camadas de atenção devem ser retornados. Consulte `attentions` nos tensores retornados para mais detalhes.

output_hidden_states (`bool`, *opcional*) : Indica se os estados ocultos de todas as camadas devem ser retornados. Consulte `hidden_states` em tensores retornados para mais detalhes.

return_dict (`bool`, *opcional*) : Se deve ou não retornar um [ModelOutput](/docs/transformers/main/pt/main_classes/output#transformers.utils.ModelOutput) em vez de uma tupla simples.

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 [Qwen2VLImageProcessor](/docs/transformers/main/pt/model_doc/qwen2_vl#transformers.Qwen2VLImageProcessor). Consulte [Qwen2VLImageProcessor.__call__()](/docs/transformers/main/pt/model_doc/molmo2#transformers.Molmo2ImageProcessor.__call__) para obter detalhes ([ColQwen2Processor](/docs/transformers/main/pt/model_doc/colqwen2#transformers.ColQwen2Processor) usa [Qwen2VLImageProcessor](/docs/transformers/main/pt/model_doc/qwen2_vl#transformers.Qwen2VLImageProcessor) para processar imagens).

image_grid_thw (`torch.LongTensor` de forma `(num_images, 3)`, *opcional*) : O tempo, a altura e a largura da forma dos recursos de cada imagem no LLM.

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

Um `ColQwen2ForRetrievalOutput` 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 ([ColQwen2Config](/docs/transformers/main/pt/model_doc/colqwen2#transformers.ColQwen2Config)) e das entradas.

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

Exemplo:

```python
```