Hugging Face's logo

Transformers documentation

ColPali

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

该模型于 2024-06-27 在 HF papers 上发布，并于 2024-12-17 贡献至 Hugging Face Transformers。

ColPali

ColPali 是一种通过分析视觉特征来检索文档的模型。与严重依赖文本提取和 OCR 的传统系统不同，ColPali 将每一页视为一张图像。它使用 Paligemma-3B 来捕获文本以及布局、表格、图表和其他视觉元素，从而生成详细的多向量嵌入（multi-vector embeddings），并通过计算成对的后期交互（late interaction）相似度分数来实现检索。这提供了对文档更全面理解，并支持更高效、更准确的检索。

该模型由 @tonywu71（ILLUIN Technology）和 @yonigozlan（HuggingFace）贡献。

您可以在 Vidore 的 Hf-native ColVision Models 集合中找到所有原始的 ColPali 检查点。

点击右侧边栏中的 ColPali 模型，以查看更多使用 ColPali 进行图像检索的示例。

图像检索
import requests
import torch
from PIL import Image

from transformers import ColPaliForRetrieval, ColPaliProcessor


# Load the model and the processor
model_name = "vidore/colpali-v1.3-hf"

model = ColPaliForRetrieval.from_pretrained(
    model_name,
    device_map="auto",  # "cpu", "cuda", "xpu", or "mps" for Apple Silicon
)
processor = ColPaliProcessor.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)

如果在加载图像时遇到 PIL 问题，可以使用以下代码创建虚拟图像：

images = [
    Image.new("RGB", (128, 128), color="white"),
    Image.new("RGB", (64, 32), color="black"),
]

量化通过以较低精度表示权重来降低大模型的内存负担。有关更多可用的量化后端，请参阅 量化 概述。

以下示例使用 bitsandbytes 将权重量化为 int4。

import requests
import torch
from PIL import Image

from transformers import BitsAndBytesConfig, ColPaliForRetrieval, ColPaliProcessor


model_name = "vidore/colpali-v1.3-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 = ColPaliForRetrieval.from_pretrained(
    model_name,
    quantization_config=bnb_config,
    device_map="auto",
)

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

备注

  • score_retrieval() 返回一个二维张量，其中第一维表示查询的数量，第二维表示图像的数量。分数越高，表示查询与图像之间的相似度越高。

ColPaliConfig

class transformers.ColPaliConfig

< >

( 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 = 128 )

参数

  • vlm_config (Union[dict, ~configuration_utils.PreTrainedConfig], 可选) — 视觉-语言骨干网络的配置对象或字典。
  • embedding_dim (int，可选，默认为 128) — 嵌入和隐藏状态的维度。

这是用于存储 ColpaliModel 配置的类。它根据指定的参数实例化 Colpali 模型，并定义模型架构。使用默认值实例化配置将生成与 vidore/colpali-v1.2 类似的配置。

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

示例：

from transformers.models.colpali import ColPaliConfig, ColPaliForRetrieval

config = ColPaliConfig()
model = ColPaliForRetrieval(config)

ColPaliProcessor

class transformers.ColPaliProcessor

< >

( image_processor = Nonetokenizer = Nonechat_template = Nonevisual_prompt_prefix: str = 'Describe the image.'query_prefix: str = 'Question: ' )

参数

  • image_processor (SiglipImageProcessor) — 图像处理器是必需的输入。
  • tokenizer (tokenizer_class) — 分词器是必需的输入。
  • chat_template (str) — 一个 Jinja 模板，用于将聊天中的消息列表转换为可分词的字符串。
  • visual_prompt_prefix (str，可选，默认为 "Describe the image.") — 一个字符串，会被分词并前置到图像 token 之前。
  • query_prefix (str，可选，默认为 "Question -- ")： 用于查询的前缀。

构造一个 ColPaliProcessor，它将图像处理器和分词器封装为单一处理器。

ColPaliProcessor 提供了 SiglipImageProcessor 和 tokenizer_class 的所有功能。有关更多信息，请参阅 ~SiglipImageProcessor 和 ~tokenizer_class。

__call__

< >

( 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.colpali.processing_colpali.ColPaliProcessorKwargs'> ) → BatchFeature

参数

  • images (Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]], 可选) — 要预处理的图像。期望输入单张图像或一批图像，其像素值范围为 0 到 255。如果传入的图像像素值在 0 到 1 之间，请设置 do_rescale=False。
  • text (Union[str, list[str], list[list[str]]]，可选) — 要编码的序列或序列批次。每个序列可以是字符串或字符串列表（预分词字符串）。如果传入预分词输入，请设置 is_split_into_words=True，以避免与批量输入产生歧义。
  • return_tensors (str 或 TensorType, 可选) — 如果设置，将返回特定框架的张量。可接受的值为：
    • 'pt'：返回 PyTorch torch.Tensor 对象。
    • 'np'：返回 NumPy np.ndarray 对象。
  • **kwargs (ProcessingKwargs，可选) — 每种模态（文本、图像、视频、音频）的额外处理选项。模型特定参数已在上方列出；有关支持参数的完整列表，请参阅 TypedDict 类。

返回值

BatchFeature

一个包含以下字段的 BatchFeature：

  • input_ids — 要输入模型的 token id 列表。当 text 不为 None 时返回。如果提供了 suffix，input_ids 还将包含后缀的输入 id。
  • attention_mask — 一个索引列表，指定模型应关注哪些 token（当 return_attention_mask=True，或当 “attention_mask” 位于 self.model_input_names 中且 text 不为 None 时）。
  • pixel_values — 输入模型的像素值。当 images 不为 None 时返回。
  • labels — 如果 suffix 不为 None，则与训练兼容的标签

ColPaliForRetrieval

class transformers.ColPaliForRetrieval

< >

( config: ColPaliConfig )

参数

  • config (ColPaliConfig) — 模型的配置类，包含模型的所有参数。使用配置文件进行初始化时，不会加载与模型关联的权重，仅加载配置。请查看 from_pretrained() 方法以加载模型权重。

ColPali 架构利用 VLM 直接从文档图像（“截图”）构建高效的多向量嵌入，用于文档检索。该模型采用 ColBERT 中提出的后期交互方法，通过最大化这些文档嵌入与相应查询嵌入之间的相似度来进行训练。

使用 ColPali 后，无需依赖可能复杂且脆弱的版面识别和 OCR 流水线，单个模型即可同时考虑文档的文本和视觉内容（如版面、图表等）。

ColPali 是 ColVision 模型家族的一部分，该家族首次在下述论文中提出：ColPali: Efficient Document Retrieval with Vision Language Models。

该模型继承自 PreTrainedModel。请查阅父类文档，了解该库为所有模型实现的通用方法（例如下载或保存、调整输入嵌入大小、剪枝头等）。

该模型也是 PyTorch torch.nn.Module 的子类。 请将其作为常规的 PyTorch Module 使用，有关通用用法和行为的所有事项，请参阅 PyTorch 文档。

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'> ) → ColPaliForRetrievalOutput or tuple(torch.Tensor)

参数

  • input_ids (torch.LongTensor 形状为 (batch_size, sequence_length), ，可选) — 输入序列中各 token 在词汇表中的索引。默认情况下，填充（padding）将被忽略。

    可以使用 AutoTokenizer 获取索引。有关详细信息，请参阅 PreTrainedTokenizer.encode() 和 PreTrainedTokenizer.call()。

    什么是输入 ID？

  • pixel_values（形状为 (batch_size, num_channels, image_size, image_size) 的 torch.Tensor，可选） — 与输入图像对应的张量。可以使用 image_processor_class 获取像素值。有关详细信息，请参阅 image_processor_class.__call__（processor_class 使用 image_processor_class 来处理图像）。
  • attention_mask (torch.Tensor 形状为 (batch_size, sequence_length), ，可选) — 用于避免对填充 token 索引执行注意力机制的掩码。掩码值取自 [0, 1]:
    • 1 表示未被屏蔽的 token，
    • 对于被掩码的 token，值为 0。

    什么是注意力掩码？

返回值

ColPaliForRetrievalOutput 或 tuple(torch.Tensor)

ColPaliForRetrievalOutput 或 torch.Tensor 元组（如果传入 return_dict=False 或 config.return_dict=False），包含根据配置（None）和输入而定的各种元素。

ColPaliForRetrieval 的 forward 方法重写了 __call__ 特殊方法。

尽管前向传播的实现需要在此函数中定义，但之后应调用 Module 实例，而不是直接调用此函数，因为前者会负责执行预处理和后处理步骤，而后者则会静默地忽略这些步骤。

  • loss (torch.Tensor，形状为 (1,)，可选，当提供 labels 时返回) — 语言建模损失（用于下一个 token 预测）。

  • 嵌入（形状为 (batch_size, sequence_length, hidden_size) 的 torch.Tensor）— 模型的嵌入。

  • past_key_values（Cache，可选，在传入 use_cache=True 或 config.use_cache=True 时返回）—— 它是一个 Cache 实例。更多详情，请参阅我们的 kv cache 指南。

    包含预计算的隐藏状态（自注意力块中的键和值），可用于（参见 past_key_values 输入）加速顺序解码。

  • hidden_states (tuple[torch.Tensor]，可选，当传入 output_hidden_states=True 或 config.output_hidden_states=True 时返回) — 一个 torch.Tensor 元组（如果模型具有嵌入层，则包含嵌入层输出的一个张量，以及每个层输出的一个张量），形状为 (batch_size, sequence_length, hidden_size)。

    模型在每一层输出处的隐藏状态，以及可选的初始嵌入输出。

  • attentions (tuple[torch.Tensor]，可选，当传入 output_attentions=True 或 config.output_attentions=True 时返回) — 一个 torch.Tensor 元组（每层一个），形状为 (batch_size, num_heads, sequence_length, sequence_length)。

    注意力权重，即经过注意力 softmax 之后的权重，用于在自注意力头中计算加权平均值。

  • image_hidden_states (torch.Tensor，可选) — 大小为 (batch_size, num_images, sequence_length, hidden_size) 的 torch.Tensor。 由视觉编码器生成的模型 image_hidden_states，即对最后一个隐藏状态进行投影后的结果。

Update on GitHub

←ColModernVBert ColQwen2→