Hugging Face's logo

Transformers documentation

ColPali

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]] = Nonesuffix: str | None = None**kwargs: *<class 'transformers.processing_utils.ProcessingKwargs'> ) → 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，以避免与批量输入产生歧义。
  • suffix (str | list[str] | list[list[str]], 可选) — 附加到所有输入文本末尾的后缀。
  • return_mm_token_type_ids (bool, kwargs) — 是否返回多模态 token 类型 id，用于指示多模态占位符 token 的位置。
  • return_text_replacement_offsets (bool, kwargs) — 是否返回每个多模态占位符及其替换内容的字符偏移量。
  • 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→