# ColPali

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

该模型由 [@tonywu71](https://huggingface.co/tonywu71)（ILLUIN Technology）和 [@yonigozlan](https://huggingface.co/yonigozlan)（HuggingFace）贡献。

您可以在 Vidore 的 [Hf-native ColVision Models](https://huggingface.co/collections/vidore/hf-native-colvision-models-6755d68fc60a8553acaa96f7) 集合中找到所有原始的 ColPali 检查点。

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

```python
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 问题，可以使用以下代码创建虚拟图像：

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

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

以下示例使用 [bitsandbytes](../quantization/bitsandbytes) 将权重量化为 int4。

```python
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[[transformers.ColPaliConfig]]

#### transformers.ColPaliConfig[[transformers.ColPaliConfig]]

```python
transformers.ColPaliConfig(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)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/colpali/configuration_colpali.py#L28)

**参数：**

vlm_config (`Union[dict, ~configuration_utils.PreTrainedConfig]`, *可选*) : 视觉-语言骨干网络的配置对象或字典。

embedding_dim (`int`，*可选*，默认为 `128`)：嵌入和隐藏状态的维度。

这是用于存储 ColpaliModel 配置的类。它根据指定的参数实例化 Colpali 模型，并定义模型架构。使用默认值实例化配置将得到与 [vidore/colpali-v1.2](https://huggingface.co/vidore/colpali-v1.2) 类似的配置。

配置对象继承自 [PreTrainedConfig](/docs/transformers/v5.23.0/zh/main_classes/configuration#transformers.PreTrainedConfig)，可用于控制模型输出。有关更多信息，请参阅 [PreTrainedConfig](/docs/transformers/v5.23.0/zh/main_classes/configuration#transformers.PreTrainedConfig) 的文档。

示例：

```python
from transformers.models.colpali import ColPaliConfig, ColPaliForRetrieval

config = ColPaliConfig()
model = ColPaliForRetrieval(config)
```

## ColPaliProcessor[[transformers.ColPaliProcessor]]

#### transformers.ColPaliProcessor[[transformers.ColPaliProcessor]]

```python
transformers.ColPaliProcessor(image_processor = None, tokenizer = None, chat_template = None, visual_prompt_prefix: str = 'Describe the image.', query_prefix: str = 'Question: ')
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/colpali/processing_colpali.py#L42)

**参数：**

image_processor (`SiglipImageProcessor`)：图像处理器是必需的输入。

tokenizer (`tokenizer_class`)：分词器是必需的输入。

chat_template (`str`) : 一个 Jinja 模板，用于将聊天中的消息列表转换为可分词的字符串。

visual_prompt_prefix (`str`，*可选*，默认为 `"Describe the image."`)：一个字符串，会被分词并前置到图像 token 之前。

query_prefix (`str`，*可选*，默认为 `"Question : "`)：用于查询的前缀。

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

[ColPaliProcessor](/docs/transformers/v5.23.0/zh/model_doc/colpali#transformers.ColPaliProcessor) 提供了 [SiglipImageProcessor](/docs/transformers/v5.23.0/zh/model_doc/siglip#transformers.SiglipImageProcessor) 和 `tokenizer_class` 的所有功能。有关更多信息，请参阅 [~SiglipImageProcessor](/docs/transformers/v5.23.0/zh/model_doc/siglip#transformers.SiglipImageProcessor) 和 `~tokenizer_class`。

#### __调用__[[transformers.ColPaliProcessor.__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, suffix: str | None = None, **kwargs: *<class 'transformers.processing_utils.ProcessingKwargs'>)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/colpali/processing_colpali.py#L90)

**参数：**

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](/docs/transformers/v5.23.0/zh/internal/file_utils#transformers.TensorType)，*可选*)：如果设置，将返回特定框架的张量。可接受的值为： - `'pt'`：返回 PyTorch `torch.Tensor` 对象。 - `'np'`：返回 NumPy `np.ndarray` 对象。

- ****kwargs** ([ProcessingKwargs](/docs/transformers/v5.23.0/zh/main_classes/processors#transformers.ProcessingKwargs), *可选*) : 针对每种模态（文本、图像、视频、音频）的额外处理选项。模型特定参数已在上方列出；有关支持参数的完整列表，请参阅 TypedDict 类。

**返回：** [BatchFeature](/docs/transformers/v5.23.0/zh/main_classes/feature_extractor#transformers.BatchFeature)

一个包含以下字段的 [BatchFeature](/docs/transformers/v5.23.0/zh/main_classes/feature_extractor#transformers.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[[transformers.ColPaliForRetrieval]]

#### transformers.ColPaliForRetrieval[[transformers.ColPaliForRetrieval]]

```python
transformers.ColPaliForRetrieval(config: ColPaliConfig)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/colpali/modeling_colpali.py#L90)

**参数：**

config ([ColPaliConfig](/docs/transformers/v5.23.0/zh/model_doc/colpali#transformers.ColPaliConfig))：模型配置类，包含模型的所有参数。通过配置文件进行初始化时，不会加载与模型关联的权重，仅加载配置。请查看 [from_pretrained()](/docs/transformers/v5.23.0/zh/main_classes/model#transformers.PreTrainedModel.from_pretrained) 方法以加载模型权重。

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

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

ColPali 是 ColVision 模型家族的一部分，该家族首次在下述论文中提出：[*ColPali: Efficient Document Retrieval with Vision Language Models*](https://huggingface.co/papers/2407.01449)。

该模型继承自 [PreTrainedModel](/docs/transformers/v5.23.0/zh/main_classes/model#transformers.PreTrainedModel)。请查阅父类文档，了解该库为所有模型实现的通用方法（例如下载或保存、调整输入嵌入大小、剪枝头等）。

该模型也是 PyTorch [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) 的子类。请将其作为常规的 PyTorch Module 使用，有关通用用法和行为的所有事项，请参阅 PyTorch 文档。

#### forward[[transformers.ColPaliForRetrieval.forward]]

```python
forward(input_ids: typing.Optional[torch.LongTensor] = None, pixel_values: typing.Optional[torch.Tensor] = None, attention_mask: typing.Optional[torch.Tensor] = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/colpali/modeling_colpali.py#L104)

**参数：**

input_ids (`torch.LongTensor`，形状为 `(batch_size, sequence_length)`，*可选*)：输入序列中 token 在词汇表中的索引。默认情况下，填充（padding）将被忽略。可以使用 [AutoTokenizer](/docs/transformers/v5.23.0/zh/model_doc/auto#transformers.AutoTokenizer) 获取索引。有关详细信息，请参阅 [PreTrainedTokenizer.encode()](/docs/transformers/v5.23.0/zh/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) 和 [PreTrainedTokenizer.__call__()](/docs/transformers/v5.23.0/zh/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__)。[什么是输入 ID？](../glossary#input-ids)

pixel_values (`torch.Tensor`，形状为 `(batch_size, num_channels, image_size, image_size)`，*可选*) : 与输入图像对应的张量。可以使用 `image_processor_class` 获取像素值。有关详细信息，请参阅 `image_processor_class.__call__`（`processor_class` 使用 `image_processor_class` 处理图像）。

attention_mask (`torch.Tensor`，形状为 `(batch_size, sequence_length)`，*可选*)：用于避免对填充（padding）标记索引执行注意力机制的掩码。掩码值取自 `[0, 1]`： - 1 表示**未掩码**的标记， - 0 表示**已掩码**的标记。 [什么是注意力掩码？](../glossary#attention-mask)

**返回：** `ColPaliForRetrievalOutput` 或 `tuple(torch.Tensor)`

`ColPaliForRetrievalOutput` 或 `torch.Tensor` 元组（如果传入 `return_dict=False` 或 `config.return_dict=False`），其包含的元素取决于配置（`None`）和输入。

[ColPaliForRetrieval](/docs/transformers/v5.23.0/zh/model_doc/colpali#transformers.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](/docs/transformers/v5.23.0/zh/internal/generation_utils#transformers.Cache) 实例。更多详情，请参阅我们的 [kv cache 指南](https://huggingface.co/docs/transformers/en/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，即投影后的最后一个隐藏状态。

