ColPali

概述

ColPali 模型在 ColPali: Efficient Document Retrieval with Vision Language Models 中提出，作者包括 Manuel Faysse*、 Hugues Sibille*、 Tony Wu*、 Bilel Omrani、 Gautier Viaud、 Céline Hudelot、 Pierre Colombo (* 表示同等贡献)。由 ILLUIN Technology 领导完成。

在我们提出的 ColPali 方法中，我们利用 VLM 直接从文档图像（“屏幕截图”）构建高效的多向量嵌入，用于文档检索。我们训练模型以最大化这些文档嵌入和相应的查询嵌入之间的相似性，使用 ColBERT 中引入的后期交互方法。

使用 ColPali 消除了对可能复杂且脆弱的布局识别和 OCR 管道的需求，只需一个模型即可考虑文档的文本和视觉内容（布局、图表等）。

资源

ColPali arXiv 论文可以在这里找到。 📄
详细介绍 ColPali 的官方博客文章可以在这里找到。 📝
ColPali 模型和 colpali-engine 包的原始模型实现代码可以在这里找到。 🌎
学习使用 ColPali 的 transformers 原生版本、微调和相似度图生成的 Cookbook 可以在这里找到。 📚

此模型由 @tonywu71 和 @yonigozlan 贡献。

用法

此示例演示了如何使用 ColPali 嵌入查询和图像，计算它们的相似度得分，并识别最相关的匹配项。对于特定查询，您可以通过选择相似度得分最高的图像来检索前 k 个最相似的图像。

import torch
from PIL import Image

from transformers import ColPaliForRetrieval, ColPaliProcessor

model_name = "vidore/colpali-v1.2-hf"

model = ColPaliForRetrieval.from_pretrained(
    model_name,
    torch_dtype=torch.bfloat16,
    device_map="cuda:0",  # or "mps" if on Apple Silicon
).eval()

processor = ColPaliProcessor.from_pretrained(model_name)

# Your inputs (replace dummy images with screenshots of your documents)
images = [
    Image.new("RGB", (32, 32), color="white"),
    Image.new("RGB", (16, 16), color="black"),
]
queries = [
    "What is the organizational structure for our R&D department?",
    "Can you provide a breakdown of last year’s financial performance?",
]

# Process the inputs
batch_images = processor(images=images).to(model.device)
batch_queries = processor(text=queries).to(model.device)

# Forward pass
with torch.no_grad():
    image_embeddings = model(**batch_images).embeddings
    query_embeddings = model(**batch_queries).embeddings

# Score the queries against the images
scores = processor.score_retrieval(query_embeddings, image_embeddings)

ColPaliConfig

class transformers.ColPaliConfig

< source >

( vlm_config = None text_config = None embedding_dim: int = 128 **kwargs )

参数

vlm_config (PretrainedConfig, 可选) — VLM 主干模型的配置。
text_config (PretrainedConfig, 可选) — 文本主干模型的配置。如果提供，则覆盖 vlm_config 的 text_config 属性。
embedding_dim (int, 可选, 默认为 128) — 模型生成的多向量嵌入的维度。

用于存储 ColPaliForRetrieval 配置的配置类。它用于根据指定的参数实例化 ColPaliForRetrieval 的实例，定义模型架构，遵循 “ColPali: Efficient Document Retrieval with Vision Language Models” 论文中的方法。

使用默认设置创建配置将生成一个配置，其中 VLM 主干设置为默认的 PaliGemma 配置，即来自 vidore/colpali-v1.2 的配置。

ColPali 配置与 PaligemmaConfig 非常相似，但增加了一个定义嵌入维度的属性。

请注意，与类名暗示的相反（实际上，该名称指的是 ColPali 方法），您可以通过将相应的 VLM 配置传递给类构造函数来使用与 PaliGemma 不同的 VLM 主干模型。

配置对象继承自 PretrainedConfig，可用于控制模型输出。有关更多信息，请阅读 PretrainedConfig 的文档。

示例

from transformers.models.colpali import ColPaliConfig, ColPaliForRetrieval

config = ColPaliConfig()
model = ColPaliForRetrieval(config)

ColPaliProcessor

class transformers.ColPaliProcessor

< source >

（ image_processor = None tokenizer = None chat_template = None **kwargs ）

参数

image_processor (SiglipImageProcessor, 可选) — 图像处理器是必需的输入。
tokenizer (LlamaTokenizerFast, 可选) — 分词器是必需的输入。
chat_template (str, 可选) — Jinja 模板，用于将聊天中的消息列表转换为可分词的字符串。

构建一个 ColPali 处理器，它包装了 PaliGemmaProcessor 和特殊方法来处理图像和查询，以及计算晚期交互检索分数。

ColPaliProcessor 提供了 PaliGemmaProcessor 的所有功能。有关更多信息，请参阅 __call__() 。

batch_decode

< source >

（ *args **kwargs ）

此方法将其所有参数转发到 GemmaTokenizerFast 的 batch_decode()。有关更多信息，请参阅此方法的文档字符串。

decode

< source >

（ *args **kwargs ）

此方法将其所有参数转发到 GemmaTokenizerFast 的 decode()。有关更多信息，请参阅此方法的文档字符串。

process_images

< source >

（ images: typing.Union[ForwardRef('PIL.Image.Image'), numpy.ndarray, ForwardRef('torch.Tensor'), list['PIL.Image.Image'], list[numpy.ndarray], list['torch.Tensor']] = None **kwargs: typing_extensions.Unpack[transformers.models.colpali.processing_colpali.ColPaliProcessorKwargs] ） → BatchFeature

参数

images (PIL.Image.Image, np.ndarray, torch.Tensor, List[PIL.Image.Image], List[np.ndarray], List[torch.Tensor]) — 要准备的图像或批量图像。每个图像可以是 PIL 图像、NumPy 数组或 PyTorch 张量。如果是 NumPy 数组/PyTorch 张量，则每个图像应具有形状 (C, H, W)，其中 C 是通道数，H 和 W 是图像的高度和宽度。
return_tensors (str 或 TensorType, 可选) — 如果设置，将返回特定框架的张量。可接受的值为：
- 'tf': 返回 TensorFlow tf.constant 对象。
- 'pt': 返回 PyTorch torch.Tensor 对象。
- 'np': 返回 NumPy np.ndarray 对象。
- 'jax': 返回 JAX jnp.ndarray 对象。

BatchFeature

一个 BatchFeature，包含以下字段

input_ids — 要馈送到模型的令牌 ID 列表。
attention_mask — 指示模型应关注哪些令牌的索引列表（当 return_attention_mask=True 或如果 “attention_mask” 在 self.model_input_names 中并且 text 不是 None 时）。
pixel_values — 要馈送到模型的像素值。当 images 不是 None 时返回。

为模型准备一个或多个图像。此方法是 ColPaliProcessor 的 __call__ 方法 ColPaliProcessor.__call__() 的包装器。

此方法将 images 和 kwargs 参数转发到 SiglipImageProcessor 的 call()。

process_queries

< source >

（ text: typing.Union[str, typing.List[str]] **kwargs: typing_extensions.Unpack[transformers.models.colpali.processing_colpali.ColPaliProcessorKwargs] ） → BatchFeature

参数

text (str, List[str], List[List[str]]) — 要编码的序列或批量序列。每个序列可以是字符串或字符串列表（预分词字符串）。如果序列以字符串列表（预分词）的形式提供，则必须设置 is_split_into_words=True （以消除批量序列的歧义）。
return_tensors (str 或 TensorType, 可选) — 如果设置，将返回特定框架的张量。可接受的值为：
- 'tf': 返回 TensorFlow tf.constant 对象。
- 'pt': 返回 PyTorch torch.Tensor 对象。
- 'np': 返回 NumPy np.ndarray 对象。
- 'jax': 返回 JAX jnp.ndarray 对象。

BatchFeature

一个 BatchFeature，包含以下字段

input_ids — 要馈送到模型的令牌 ID 列表。
attention_mask — 指示模型应关注哪些令牌的索引列表（当 return_attention_mask=True 或如果 “attention_mask” 在 self.model_input_names 中并且 text 不是 None 时）。

为模型准备一个或多个文本。此方法是 ColPaliProcessor 的 __call__ 方法 ColPaliProcessor.__call__() 的包装器。

此方法将 text 和 kwargs 参数转发到 LlamaTokenizerFast 的 call()。

score_retrieval

< source >

（ query_embeddings: typing.Union[ForwardRef('torch.Tensor'), typing.List[ForwardRef('torch.Tensor')]] passage_embeddings: typing.Union[ForwardRef('torch.Tensor'), typing.List[ForwardRef('torch.Tensor')]] batch_size: int = 128 output_dtype: typing.Optional[ForwardRef('torch.dtype')] = None output_device: typing.Union[ForwardRef('torch.device'), str] = 'cpu' ） → torch.Tensor

参数

query_embeddings (Union[torch.Tensor, List[torch.Tensor]) — 查询嵌入。
passage_embeddings (Union[torch.Tensor, List[torch.Tensor]) — Passage 嵌入。
batch_size (int, 可选, 默认为 128) — 用于计算分数的批次大小。
output_dtype (torch.dtype, 可选, 默认为 torch.float32) — 输出张量的数据类型。如果为 None，则使用输入嵌入的数据类型。
output_device (torch.device 或 str, 可选, 默认为 “cpu”) — 输出张量的设备。

torch.Tensor

形状为 (n_queries, n_passages) 的张量，其中包含分数。分数张量保存在 “cpu” 设备上。

计算给定多向量查询嵌入 ( qs ) 和 passage 嵌入 ( ps ) 的晚期交互/MaxSim 分数（类似 ColBERT）。对于 ColPali，passage 是文档页面的图像。

由于嵌入张量是多向量的，因此可能具有不同的形状，因此应按以下方式馈送：（1）张量列表，其中第 i 个张量的形状为（sequence_length_i，embedding_dim）（2）形状为（n_passages，max_sequence_length，embedding_dim）的单个张量 -> 通常通过填充张量列表获得。

ColPaliForRetrieval

class transformers.ColPaliForRetrieval

< source >

（ config: ColPaliConfig ）

在我们提出的 ColPali 方法中，我们利用 VLM 直接从文档图像（“屏幕截图”）构建高效的多向量嵌入，用于文档检索。我们训练模型以最大化这些文档嵌入和相应的查询嵌入之间的相似性，使用 ColBERT 中引入的晚期交互方法。

使用 ColPali，无需潜在的复杂且脆弱的布局识别和 OCR 管道，只需一个模型即可考虑文档的文本和视觉内容（布局、图表等）。

forward

< source >

( input_ids: LongTensor = None pixel_values: FloatTensor = None attention_mask: typing.Optional[torch.Tensor] = None output_attentions: typing.Optional[bool] = None output_hidden_states: typing.Optional[bool] = None return_dict: typing.Optional[bool] = None **kwargs ) → transformers.models.colpali.modeling_colpali.ColPaliForRetrievalOutput or tuple(torch.FloatTensor)

参数

input_ids (torch.LongTensor, 形状为 (batch_size, sequence_length)) — 词汇表中输入序列 tokens 的索引。如果您提供 padding，默认情况下将被忽略。索引可以使用 AutoTokenizer 获得。参见 PreTrainedTokenizer.encode() 和 PreTrainedTokenizer.call() 以了解详细信息。什么是输入 IDs？
pixel_values (torch.FloatTensor, 形状为 (batch_size, num_channels, image_size, image_size)) — 对应于输入图像的 tensors。像素值可以使用 [AutoImageProcessor](/docs/transformers/v4.50.0/en/model_doc/auto#transformers.AutoImageProcessor) 获得。参见 [SiglipImageProcessor.__call__()](/docs/transformers/v4.50.0/en/model_doc/vilt#transformers.ViltFeatureExtractor.__call__) 以了解详细信息（[`PaliGemmaProcessor`] 使用 SiglipImageProcessor 处理图像）。如果为 None，ColPali 将仅处理文本（查询 embeddings）。
attention_mask (torch.Tensor, 形状为 (batch_size, sequence_length), 可选) — Mask，用于避免在 padding token 索引上执行 attention。 Mask 值在 [0, 1] 中选择：
- 1 表示 tokens 未被 masked，
- 0 表示 tokens 已被 masked。什么是 attention masks？索引可以使用 AutoTokenizer 获得。参见 PreTrainedTokenizer.encode() 和 PreTrainedTokenizer.call() 以了解详细信息。如果使用了 past_key_values，则可以选择只输入最后的 decoder_input_ids（参见 past_key_values）。如果您想更改 padding 行为，您应该阅读 modeling_opt._prepare_decoder_attention_mask 并根据您的需要进行修改。有关默认策略的更多信息，请参见论文中的图 1。
- 1 表示 head 未被 masked，
- 0 表示 head 已被 masked。
output_attentions (bool, 可选) — 是否返回所有 attention 层的 attentions tensors。有关更多详细信息，请参见返回 tensors 下的 attentions。
output_hidden_states (bool, 可选) — 是否返回所有层的 hidden states。有关更多详细信息，请参见返回 tensors 下的 hidden_states。
return_dict (bool, 可选) — 是否返回一个 ModelOutput 对象而不是一个普通 tuple。
kwargs (Dict[str, Any], 可选) — 传递给 vlm backbone 模型的其他关键字参数。

transformers.models.colpali.modeling_colpali.ColPaliForRetrievalOutput 或 tuple(torch.FloatTensor)

一个 transformers.models.colpali.modeling_colpali.ColPaliForRetrievalOutput 或一个 torch.FloatTensor 的 tuple （如果传递了 return_dict=False 或当 config.return_dict=False 时），包含各种元素，具体取决于配置 (ColPaliConfig) 和输入。

loss (torch.FloatTensor, 形状为 (1,), 可选, 当提供 labels 时返回) — 语言建模 loss（用于 next-token prediction）。
embeddings (torch.FloatTensor, 形状为 (batch_size, sequence_length, hidden_size)) — 模型的 embeddings。
past_key_values (tuple(tuple(torch.FloatTensor)), 可选, 当传递了 use_cache=True 或当 config.use_cache=True 时返回) — 长度为 config.n_layers 的 tuple(tuple(torch.FloatTensor)), 其中每个 tuple 具有 2 个形状为 (batch_size, num_heads, sequence_length, embed_size_per_head) 的 tensors)

包含预先计算的 hidden-states （self-attention blocks 中的 key 和 values），可以用于（参见 past_key_values 输入）加速顺序解码。
hidden_states (tuple(torch.FloatTensor), 可选, 当传递了 output_hidden_states=True 或当 config.output_hidden_states=True 时返回) — torch.FloatTensor 的 tuple（如果模型具有 embedding layer，则为 embeddings 的输出 + 每层的输出一个），形状为 (batch_size, sequence_length, hidden_size)。

模型在每一层输出的 Hidden-states 加上可选的初始 embedding 输出。
attentions (tuple(torch.FloatTensor), 可选, 当传递了 output_attentions=True 或当 config.output_attentions=True 时返回) — torch.FloatTensor 的 tuple（每层一个），形状为 (batch_size, num_heads, sequence_length, sequence_length)。

attention softmax 之后的 Attentions 权重，用于计算 self-attention heads 中的加权平均值。
image_hidden_states (torch.FloatTensor, 可选) — 一个 torch.FloatTensor，大小为 (batch_size, num_images, sequence_length, hidden_size)。由 vision encoder 在投影最后一个 hidden state 之后生成的模型的 image_hidden_states。

ColPaliForRetrieval 的 forward 方法，覆盖了 __call__ 特殊方法。

虽然 forward pass 的配方需要在该函数内定义，但应该在之后调用 Module 实例而不是此函数，因为前者负责运行预处理和后处理步骤，而后者会静默地忽略它们。

< > 在 GitHub 上更新

Transformers

ColPali

概述

资源

用法

ColPaliConfig

class transformers.ColPaliConfig

ColPaliProcessor

class transformers.ColPaliProcessor

batch_decode

decode

process_images

process_queries

score_retrieval

ColPaliForRetrieval

class transformers.ColPaliForRetrieval

forward