# ColModernVBert

## 概述

ColModernVBert 是一个用于高效视觉文档检索的模型。它利用 [ModernVBert](modernvbert) 直接从文档图像构建多向量嵌入，遵循 ColPali 的方法。

该模型在 [ModernVBERT: Towards Smaller Visual Document Retrievers](https://huggingface.co/papers/2510.01149) 中提出。

```python
import torch
from huggingface_hub import hf_hub_download
from PIL import Image

from transformers import ColModernVBertForRetrieval, ColModernVBertProcessor

processor = ColModernVBertProcessor.from_pretrained("ModernVBERT/colmodernvbert-hf")
model = ColModernVBertForRetrieval.from_pretrained("ModernVBERT/colmodernvbert-hf", device_map="auto")

# Load the test dataset
queries = [
    "A paint on the wall",
    "ColModernVBERT matches the performance of models nearly 10x larger on visual document benchmarks."
]

images = [
    Image.open(hf_hub_download("HuggingFaceTB/SmolVLM", "example_images/rococo.jpg", repo_type="space")),
    Image.open(hf_hub_download("ModernVBERT/colmodernvbert", "table.png", repo_type="model"))
]

# Preprocess the examples
batch_images = processor(images=images).to(model.device)
batch_queries = processor(text=queries).to(model.device)

# Run inference
with torch.inference_mode():
    image_embeddings = model(**batch_images).embeddings
    query_embeddings = model(**batch_queries).embeddings

# Compute retrieval scores
scores = processor.score_retrieval(
    query_embeddings=query_embeddings,
    passage_embeddings=image_embeddings,
)

scores = torch.softmax(scores, dim=-1)

print(scores)    # [[0.9350, 0.0650], [0.0015, 0.9985]]
```

## ColModernVBertConfig[[transformers.ColModernVBertConfig]]

#### transformers.ColModernVBertConfig[[transformers.ColModernVBertConfig]]

```python
transformers.ColModernVBertConfig(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, initializer_range: float = 0.02)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/colmodernvbert/configuration_colmodernvbert.py#L31)

**参数：**

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

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

initializer_range (`float`，*可选*，默认值为 `0.02`)：用于初始化所有权重矩阵的 truncated_normal_initializer 的标准差。

这是用于存储 ColmodernvbertModel 配置的类。它根据指定的参数实例化 Colmodernvbert 模型，并定义模型架构。使用默认值实例化配置将生成与 [ModernVBERT/colmodernvbert-merged](https://huggingface.co/ModernVBERT/colmodernvbert-merged) 类似的配置。

配置对象继承自 [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 import ColModernVBertConfig, ColModernVBertForRetrieval

config = ColModernVBertConfig()
model = ColModernVBertForRetrieval(config)
```

## ColModernVBertProcessor[[transformers.ColModernVBertProcessor]]

#### transformers.ColModernVBertProcessor[[transformers.ColModernVBertProcessor]]

```python
transformers.ColModernVBertProcessor(image_processor, tokenizer = None, chat_template = None, image_seq_len: int = 64, visual_prompt_prefix: str | None = None, query_prefix: str | None = None, **kwargs)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/colmodernvbert/processing_colmodernvbert.py#L54)

**参数：**

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

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

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

image_seq_len (`int`，*可选*，默认为 64)：图像序列的长度，即输入中每张图像的 token 数量。

visual_prompt_prefix (`str`, *可选*) : 一个字符串，会被分词并前置到图像标记之前。

query_prefix (`str`, *可选*) : 用于查询的前缀。

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

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

#### process_images[[transformers.ColModernVBertProcessor.process_images]]

```python
process_images(images: typing.Union[ForwardRef('PIL.Image.Image'), numpy.ndarray, ForwardRef('torch.Tensor'), list['PIL.Image.Image'], list[numpy.ndarray], list['torch.Tensor'], NoneType] = None, **kwargs: *<class 'transformers.processing_utils.ProcessingKwargs'>)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/colmodernvbert/processing_colmodernvbert.py#L330)

**参数：**

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

**返回：** [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 列表。
- **attention_mask** -- 指定模型应关注哪些 token 的索引列表（当 `return_attention_mask=True` 时，或当 *"attention_mask"* 位于 `self.model_input_names` 中且 `text` 不为 `None` 时）。
- **pixel_values** -- 输入模型的像素值。当 `images` 不为 `None` 时返回。

为模型准备一张或多张图像。处理输入验证、RGB 转换，并在每张图像前添加 `visual_prompt_prefix`。如果 `text_kwargs` 中提供了 `suffix`，则可选地从 `token_type_ids` 计算标签。

#### process_queries[[transformers.ColModernVBertProcessor.process_queries]]

```python
process_queries(text: str | list[str], suffix: str | None = None, **kwargs: *<class 'transformers.processing_utils.ProcessingKwargs'>)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/colmodernvbert/processing_colmodernvbert.py#L390)

**参数：**

text (`str`, `list[str]`, `list[list[str]]`) : 要编码的序列或序列批次。每个序列可以是字符串或字符串列表（预分词字符串）。如果序列以字符串列表（预分词）形式提供，则必须设置 `is_split_into_words=True`（以消除与序列批次的歧义）。

suffix (`str`, *可选*) : 附加到查询末尾的后缀。

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

**返回：** [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 列表。
- **attention_mask** -- 指定模型应关注哪些 token 的索引列表（当 `return_attention_mask=True` 时，或当 *"attention_mask"* 位于 `self.model_input_names` 中且 `text` 不为 `None` 时）。

为模型准备一个或多个文本查询。处理输入验证，在开头添加`query_prefix`，并在末尾添加查询增强标记（用于填充查询嵌入，以提升后期交互检索的性能）。

#### score_retrieval[[transformers.ColModernVBertProcessor.score_retrieval]]

```python
score_retrieval(query_embeddings: typing.Union[ForwardRef('torch.Tensor'), list['torch.Tensor']], passage_embeddings: typing.Union[ForwardRef('torch.Tensor'), list['torch.Tensor']], batch_size: int = 128, output_dtype: typing.Optional[ForwardRef('torch.dtype')] = None, output_device: typing.Union[ForwardRef('torch.device'), str] = 'cpu')
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/colmodernvbert/processing_colmodernvbert.py#L454)

**参数：**

query_embeddings (`Union[torch.Tensor, list[torch.Tensor]`) : 查询嵌入。

passage_embeddings (`Union[torch.Tensor, list[torch.Tensor]`) : 段落嵌入。

batch_size (`int`，*可选*，默认为 128)：用于计算分数的批大小。

output_dtype (`torch.dtype`，*可选*，默认为 `torch.float32`)：输出张量的 dtype。如果为 `None`，则使用输入嵌入的 dtype。

output_device (`torch.device` 或 `str`，*可选*，默认为 "cpu")：输出张量的设备。

**返回：** `torch.Tensor`

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

计算给定多向量查询嵌入（`qs`）和段落嵌入（`ps`）的后期交互/MaxSim 分数（类似 ColBERT）。对于 ColQwen2，一个段落对应文档的一页。

由于嵌入张量是多向量的，因此可能具有不同的形状，它们应作为以下形式输入：(1) 一个张量列表，其中第 i 个张量的形状为 (sequence_length_i, embedding_dim)；(2) 一个形状为 (n_passages, max_sequence_length, embedding_dim) 的单个张量 -> 通常通过对张量列表进行填充获得。

## ColModernVBertForRetrieval[[transformers.ColModernVBertForRetrieval]]

#### transformers.ColModernVBertForRetrieval[[transformers.ColModernVBertForRetrieval]]

```python
transformers.ColModernVBertForRetrieval(config: ColModernVBertConfig)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/colmodernvbert/modeling_colmodernvbert.py#L91)

**参数：**

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

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

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

ColModernVBert 是在 ModernVBert 的基础上进行训练的，并在以下论文中提出：[*ModernVBERT: Towards Smaller Visual Document Retrievers*](https://arxiv.org/abs/2510.01149)。

ColModernVBert 属于 ColVision 模型系列，该系列在以下论文中随 ColPali 一同推出：[*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.ColModernVBertForRetrieval.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/colmodernvbert/modeling_colmodernvbert.py#L105)

**参数：**

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__`（[ColModernVBertProcessor](/docs/transformers/v5.23.0/zh/model_doc/colmodernvbert#transformers.ColModernVBertProcessor) 使用 `image_processor_class` 处理图像）。

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

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

`ColModernVBertForRetrievalOutput` 或 `torch.Tensor` 元组（如果传入 `return_dict=False` 或 `config.return_dict=False`），其包含的元素取决于配置（[ColModernVBertConfig](/docs/transformers/v5.23.0/zh/model_doc/colmodernvbert#transformers.ColModernVBertConfig)）和输入。

[ColModernVBertForRetrieval](/docs/transformers/v5.23.0/zh/model_doc/colmodernvbert#transformers.ColModernVBertForRetrieval) 的 forward 方法重写了 `__call__` 特殊方法。

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

- **loss** (`torch.Tensor`，形状为 `(1,)`，*可选*，当提供 `labels` 时返回) -- 语言建模损失（用于下一个 token 预测）。
- **嵌入**（形状为 `(batch_size, sequence_length, hidden_size)` 的 `torch.Tensor`）-- 模型的嵌入。
- **hidden_states** (`tuple[torch.Tensor]`，*可选*，在传入 `output_hidden_states=True` 或 `config.output_hidden_states=True` 时返回) -- 一个 `torch.Tensor` 元组（如果模型具有嵌入层，则包含嵌入层输出的一个张量，以及每个层输出的一个张量），形状为 `(batch_size, sequence_length, hidden_size)`。

  模型在每一层输出处的隐藏状态，以及可选的初始嵌入输出。
- **image_hidden_states** (`tuple(torch.Tensor)`，*可选*，当传入 `output_hidden_states=True` 或当 `config.output_hidden_states=True` 且提供了 `pixel_values` 时返回) -- 一个 `torch.Tensor` 元组（包含一个图像模态投影的输出，以及每一层的输出），形状为 `(batch_size, num_channels, image_size, image_size)`。图像编码器在每一层输出处的隐藏状态，以及初始模态投影的输出。
- **attentions** (`tuple[torch.Tensor]`，*可选*，当传入 `output_attentions=True` 或 `config.output_attentions=True` 时返回) -- 一个 `torch.Tensor` 元组（每层一个），形状为 `(batch_size, num_heads, sequence_length, sequence_length)`。

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

示例：

```python
```

