Transformers documentation
ColModernVBert
该模型于 2025-10-01 在 HF papers 上发布，并于 2026-02-23 贡献至 Hugging Face Transformers。
ColModernVBert
概述
ColModernVBert 是一个用于高效视觉文档检索的模型。它利用 ModernVBert 直接从文档图像构建多向量嵌入，遵循 ColPali 的方法。
该模型在 ModernVBERT: Towards Smaller Visual Document Retrievers 中提出。
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
< source >( 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 )
这是用于存储 ColmodernvbertModel 配置的类。它根据指定的参数实例化 Colmodernvbert 模型，并定义模型架构。使用默认值实例化配置将得到与 ModernVBERT/colmodernvbert-merged 类似的配置。
配置对象继承自 PreTrainedConfig，可用于控制模型输出。有关更多信息，请参阅 PreTrainedConfig 的文档。
ColModernVBertProcessor
class transformers.ColModernVBertProcessor
< source >( 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) — 图像序列的长度，即输入中每张图像的token 数量。 - visual_prompt_prefix (
str, 可选) — 一个字符串，会被分词并前置到图像 token 之前。 - query_prefix (
str, 可选) — 用于查询的前缀。
构建一个 ColModernVBertProcessor，它将图像处理器和分词器封装为单个处理器。
ColModernVBertProcessor 提供了 image_processor_class 和 tokenizer_class 的所有功能。有关更多信息，请参阅 ~image_processor_class 和 ~tokenizer_class。
process_images
< source >( 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.models.colmodernvbert.processing_colmodernvbert.ColModernVBertProcessorKwargs'> ) → 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'：返回 PyTorchtorch.Tensor对象。'np'：返回 NumPynp.ndarray对象。
返回值
一个包含以下字段的 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
< source >( text: str | list[str]**kwargs: *<class 'transformers.models.colmodernvbert.processing_colmodernvbert.ColModernVBertProcessorKwargs'> ) → BatchFeature
参数
- text (
str,list[str],list[list[str]]) — 要编码的序列或序列批次。每个序列可以是字符串或字符串列表（预分词字符串）。如果序列以字符串列表（预分词）形式提供，则必须设置is_split_into_words=True（以消除与序列批次的歧义）。 - return_tensors (
str或 TensorType, 可选) — 如果设置，将返回特定框架的张量。可接受的值为：'pt'：返回 PyTorchtorch.Tensor对象。'np'：返回 NumPynp.ndarray对象。
返回值
一个包含以下字段的 BatchFeature：
- input_ids — 要输入模型的 token id 列表。
- attention_mask — 一个索引列表，指定模型应关注哪些 token（当
return_attention_mask=True，或当 “attention_mask” 位于self.model_input_names中且text不为None时）。
为模型准备一个或多个文本查询。处理输入验证，在开头添加 query_prefix，并在末尾追加查询增强标记（用于填充查询嵌入，以提升后期交互检索的性能）。
score_retrieval
< source >( 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
< source >( 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
< source >( 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()。
- 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 之后的权重，用于在自注意力头中计算加权平均值。