Transformers documentation

ColQwen2

Transformers

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

Join the Hugging Face community

and get access to the augmented documentation experience

Collaborate on models, datasets and Spaces

Faster examples with accelerated inference

Switch between documentation themes

to get started

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

ColQwen2

ColQwen2 é uma variante do modelo 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 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 (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 ColQwen2 na barra lateral à direita para ver mais exemplos de como usar o ColQwen2 para recuperação de imagens.

recuperação de imagens

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, 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 como backbone.

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

classe transformers.ColQwen2Config

< source >

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

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

config = ColQwen2Config()
model = ColQwen2ForRetrieval(config)

ColQwen2Processor

classe transformers.ColQwen2Processor

< source >

( image_processor = Nonetokenizer = Nonechat_template = Nonevisual_prompt_prefix: str | None = Nonequery_prefix: str | None = None**kwargs )

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

call

< source >

( 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.colqwen2.processing_colqwen2.ColQwen2ProcessorKwargs'> ) → 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

ColQwen2ForRetrieval

classe transformers.ColQwen2ForRetrieval

< source >

( config: ColQwen2Config )

Parâmetros

config (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() 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 conteúdo 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.

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

< source >

( input_ids: typing.Optional[torch.LongTensor] = Noneattention_mask: typing.Optional[torch.Tensor] = Noneposition_ids: typing.Optional[torch.LongTensor] = Nonepast_key_values: transformers.cache_utils.Cache | None = Nonelabels: typing.Optional[torch.LongTensor] = Noneinputs_embeds: typing.Optional[torch.Tensor] = Noneuse_cache: bool | None = Noneoutput_attentions: bool | None = Noneoutput_hidden_states: bool | None = Nonereturn_dict: bool | None = Nonepixel_values: typing.Optional[torch.Tensor] = Noneimage_grid_thw: typing.Optional[torch.LongTensor] = None**kwargs ) → ColQwen2ForRetrievalOutput 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?
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?
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?
past_key_values (~cache_utils.Cache, opcional) — Estados ocultos 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 no past_key_values retornado pelo modelo em uma etapa anterior da decodificação, quando use_cache=True ou config.use_cache=True.
Apenas uma instância de Cache é permitida como entrada, consulte nosso guia de cache de kv. Se nenhum past_key_values for passado, DynamicCache será inicializado por padrão.

O modelo sairá no mesmo formato de cache que é fornecido como entrada.

Se past_key_values forem usados, espera-se que o usuário insira apenas os input_ids não processados (aqueles que não têm seus estados de chave e valor passados fornecidos a 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 o cálculo da 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 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 as hidden states de todas as camadas devem ser retornadas. Consulte hidden_states em tensors retornados para mais detalhes.
return_dict (bool, opcional) — Indica se deve retornar um 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. Consulte Qwen2VLImageProcessor.call() para mais detalhes (ColQwen2Processor usa Qwen2VLImageProcessor para processar imagens).
image_grid_thw (torch.LongTensor de forma (num_images, 3), opcional) — A dimensão temporal, 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) e das entradas.

O método forward de 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) — É 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.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 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

←ColPali Cosmos3 Edge→