Hugging Face's logo

Transformers documentation

ColModernVBert

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v5.22.1).
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Эта модель была опубликована в HF papers 01.10.2025 и добавлена в Hugging Face Transformers 23.02.2026.

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

класс 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

класс 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) — Длина последовательности изображения, то есть количество токенов на изображение во входных данных.
  • visual_prompt_prefix (str, необязательный) — Строка, которая токенизируется и добавляется перед токенами изображения.
  • 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.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': возвращает объекты torch.Tensor PyTorch.
    • 'np': возвращает объекты NumPy np.ndarray.

Возвращает

BatchFeature

Объект BatchFeature со следующими полями:

  • input_ids — список идентификаторов токенов, которые передаются в модель.
  • attention_mask — список индексов, указывающих, на какие токены модель должна обращать внимание (когда return_attention_mask=True или если “attention_mask” входит в self.model_input_names и если text не равно None).
  • pixel_values — Пиксельные значения, передаваемые в модель. Возвращается, если images не равно None.

Подготовка одного или нескольких изображений для модели. Обработка включает проверку входных данных, преобразование в RGB и добавление visual_prompt_prefix к каждому изображению. При наличии suffix в text_kwargs необязательно вычисляет метки из token_type_ids.

process_queries

< >

( 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': возвращает объекты torch.Tensor PyTorch.
    • 'np': возвращает объекты NumPy np.ndarray.

Возвращает

BatchFeature

Объект BatchFeature со следующими полями:

  • input_ids — список идентификаторов токенов, которые передаются в модель.
  • attention_mask — список индексов, указывающих, на какие токены модель должна обращать внимание (когда 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) — тип данных выходного тензора. Если None, используется тип данных входных эмбеддингов.
  • output_device (torch.device or str, необязательный, по умолчанию “cpu”) — Устройство выходного тензора.

Возвращает

torch.Tensor

Тензор формы (n_queries, n_passages), содержащий оценки. Тензор оценок сохраняется на устройстве «cpu».

Вычислите оценку late-interaction/MaxSim (по аналогии с ColBERT) для заданных многовекторных эмбеддингов запроса (qs) и эмбеддингов отрывков (ps). Для ColQwen2 отрывок представляет собой изображение страницы документа.

Поскольку тензоры эмбеддингов являются многовекторными и, следовательно, могут иметь различные формы, их следует передавать в виде: (1) списка тензоров, где i-й тензор имеет форму (sequence_length_i, embedding_dim) (2) одного тензора формы (n_passages, max_sequence_length, embedding_dim) -> обычно получается путем дополнения (padding) списка тензоров.

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. См. документацию родительского класса для общих методов, которые библиотека реализует для всех своих моделей (например, загрузка или сохранение, изменение размера входных эмбеддингов, обрезка голов и т. д.)

Эта модель также является подклассом torch.nn.Module в PyTorch. Используйте её как обычный модуль PyTorch и обращайтесь к документации PyTorch по всем вопросам, связанным с общим использованием и поведением.

forward

< >

( input_ids: typing.Optional[torch.LongTensor] = Nonepixel_values: typing.Optional[torch.FloatTensor] = Noneattention_mask: typing.Optional[torch.Tensor] = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → ColModernVBertForRetrievalOutput or tuple(torch.FloatTensor)

Параметры

  • input_ids (torch.LongTensor формы (batch_size, sequence_length), , необязательный) — Индексы токенов входной последовательности в словаре. По умолчанию токены отсечки (padding) игнорируются.

    Индексы можно получить с помощью AutoTokenizer. Подробности см. в PreTrainedTokenizer.encode() и PreTrainedTokenizer.call().

    Что такое входные идентификаторы?

  • pixel_values (torch.FloatTensor формы (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), , необязательный) — Маска для исключения токенов-заполнителей из внимания. Значения маски из диапазона [0, 1]:
    • 1 для токенов, которые не замаскированы,
    • 0 для токенов, которые замаскированы.

    Что такое маски внимания?

Возвращает

ColModernVBertForRetrievalOutput или tuple(torch.FloatTensor)

ColModernVBertForRetrievalOutput или кортеж из torch.FloatTensor (если передано return_dict=False или если config.return_dict=False), содержащий различные элементы в зависимости от конфигурации (ColModernVBertConfig) и входных данных.

Метод forward класса ColModernVBertForRetrieval переопределяет специальный метод __call__.

Хотя рецепт для прямого прохода должен быть определён внутри этой функции, после этого следует вызывать экземпляр Module, а не эту функцию, поскольку первый вариант обеспечивает выполнение шагов предварительной и последующей обработки, тогда как второй молча их игнорирует.

  • loss (torch.FloatTensor формы (1,), необязательный, возвращается, если задан labels) — Потери языковой модели (для предсказания следующего токена).

  • embeddings (torch.FloatTensor формы (batch_size, sequence_length, hidden_size)) — Векторные представления модели.

  • hidden_states (tuple[torch.FloatTensor], необязательный, возвращается, если передано output_hidden_states=True или если config.output_hidden_states=True) — Кортеж torch.FloatTensor (один для вывода слоя встраиваний, если модель имеет слой встраиваний, + один для вывода каждого слоя) формы (batch_size, sequence_length, hidden_size).

    Скрытые состояния модели на выходе каждого слоя, а также необязательные выходные значения начального слоя встраивания.

  • image_hidden_states (tuple(torch.FloatTensor), необязательный, возвращается при передаче output_hidden_states=True или когда config.output_hidden_states=True и предоставлены pixel_values) — Кортеж torch.FloatTensor (один для вывода проекции модальности изображения + один для вывода каждого слоя) формы (batch_size, num_channels, image_size, image_size). Скрытые состояния кодировщика изображения на выходе каждого слоя, а также начальные выводы проекции модальности.

  • attentions (tuple[torch.FloatTensor], необязательный, возвращается при передаче output_attentions=True или когда config.output_attentions=True) — Кортеж torch.FloatTensor (по одному для каждого слоя) формы (batch_size, num_heads, sequence_length, sequence_length).

    Веса внимания после softmax в механизме внимания, используемые для вычисления взвешенного среднего в головах само-внимания.

Пример:

Update on GitHub

←CohereCompass ColPali→