Hugging Face's logo

Transformers documentation

ColModernVBert

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

该模型于 2025-10-01 在 HF papers 上发布，并于 2026-02-23 贡献至 Hugging Face Transformers。

ColModernVBert

FlashAttention SDPA

概述

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

该模型在 ModernVBERT: Towards Smaller Visual Document Retrievers 中提出。

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

class transformers.ColModernVBertConfig

< >

( 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 = 128initializer_range: float = 0.02 )

参数

  • vlm_config (Union[dict, ~configuration_utils.PreTrainedConfig], 可选) — 视觉-语言骨干网络的配置对象或字典。
  • embedding_dim (int，可选，默认为 128) — 嵌入和隐藏状态的维度。
  • initializer_range (float，可选，默认为 0.02) — 用于初始化所有权重矩阵的 truncated_normal_initializer 的标准差。

这是用于存储 ColmodernvbertModel 配置的类。它根据指定的参数实例化 Colmodernvbert 模型，并定义模型架构。使用默认值实例化配置将得到与 ModernVBERT/colmodernvbert-merged 类似的配置。

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

示例：

from transformers import ColModernVBertConfig, ColModernVBertForRetrieval

config = ColModernVBertConfig()
model = ColModernVBertForRetrieval(config)

ColModernVBertProcessor

class transformers.ColModernVBertProcessor

< >

( image_processortokenizer = Nonechat_template = Noneimage_seq_len: int = 64visual_prompt_prefix: str | None = Nonequery_prefix: str | None = None**kwargs )

参数

  • image_processor (image_processor_class) — 图像处理器是必需的输入。
  • tokenizer (tokenizer_class) — 分词器是必需的输入。
  • chat_template (str) — 一个 Jinja 模板，用于将聊天中的消息列表转换为可分词的字符串。
  • image_seq_len (int，可选，默认为 64) — 图像序列的长度，即输入中每张图像的 <image> token 数量。
  • visual_prompt_prefix (str, 可选) — 一个字符串，会被分词并前置到图像 token 之前。
  • query_prefix (str, 可选) — 用于查询的前缀。

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

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

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'> ) → 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, 可选) — 如果设置，将返回特定框架的张量。可接受的值为：
    • 'pt'：返回 PyTorch torch.Tensor 对象。
    • 'np'：返回 NumPy np.ndarray 对象。

返回值

BatchFeature

一个包含以下字段的 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

< >

( text: str | list[str]suffix: str | None = None**kwargs: *<class 'transformers.processing_utils.ProcessingKwargs'> ) → BatchFeature

参数

  • text (str, list[str], list[list[str]]) — 要编码的序列或序列批次。每个序列可以是字符串或字符串列表（预分词字符串）。如果序列以字符串列表（预分词）形式提供，则必须设置 is_split_into_words=True（以消除与序列批次的歧义）。
  • suffix (str, 可选) — 附加到查询末尾的后缀。
  • return_tensors (str 或 TensorType, 可选) — 如果设置，将返回特定框架的张量。可接受的值为：
    • 'pt'：返回 PyTorch torch.Tensor 对象。
    • 'np'：返回 NumPy np.ndarray 对象。

返回值

BatchFeature

一个包含以下字段的 BatchFeature：

  • input_ids — 要输入模型的 token id 列表。
  • attention_mask — 一个索引列表，指定模型应关注哪些 token（当 return_attention_mask=True，或当 “attention_mask” 位于 self.model_input_names 中且 text 不为 None 时）。

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

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 = 128output_dtype: typing.Optional[ForwardRef('torch.dtype')] = Noneoutput_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]) — 段落嵌入。
  • 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

< >

( config: ColModernVBertConfig )

参数

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

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

使用 ColModernVBert 可以借助单个模型同时考虑文档的文本内容和视觉内容（布局、图表等），从而省去可能复杂且脆弱的版面识别和 OCR 流程。

ColModernVBert 是在 ModernVBert 的基础上进行训练的，并在以下论文中提出：ModernVBERT: Towards Smaller Visual Document Retrievers。

ColModernVBert 属于 ColVision 模型系列，该系列在以下论文中随 ColPali 一同推出：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'> ) → ColModernVBertForRetrievalOutput or tuple(torch.Tensor)

参数

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

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

    什么是输入 ID？

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

    什么是注意力掩码？

返回值

ColModernVBertForRetrievalOutput 或 tuple(torch.Tensor)

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

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 之后的权重，用于在自注意力头中计算加权平均值。

示例：

Update on GitHub

←CohereCompass ColPali→