# 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/main/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/main/ru/main_classes/configuration#transformers.PreTrainedConfig) и могут использоваться для управления выводами модели. Подробнее см. в документации [PreTrainedConfig](/docs/transformers/main/ru/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/main/src/transformers/models/colmodernvbert/processing_colmodernvbert.py#L55)

**Параметры:**

image_processor (`image_processor_class`) : Процессор изображений является обязательным входным параметром.

tokenizer (`tokenizer_class`) : Токенизатор является обязательным входным параметром.

chat_template (`str`) : Шаблон Jinja для преобразования списков сообщений в чате в строку, готовую к токенизации.

image_seq_len (`int`, *optional*, по умолчанию 64) : Длина последовательности изображений, то есть количество токенов на изображение во входных данных.

visual_prompt_prefix (`str`, *необязательный*) : строка, которая токенизируется и добавляется перед токенами изображения.

query_prefix (`str`, *необязательный*) : Префикс, используемый для запроса.

Создаёт ColModernVBertProcessor, который объединяет процессор изображений и токенизатор в единый процессор.

[ColModernVBertProcessor](/docs/transformers/main/ru/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.models.colmodernvbert.processing_colmodernvbert.ColModernVBertProcessorKwargs'>)
```

[Источник](https://github.com/huggingface/transformers/blob/main/src/transformers/models/colmodernvbert/processing_colmodernvbert.py#L324)

**Параметры:**

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/main/ru/internal/file_utils#transformers.TensorType), *optional*) : Если задано, возвращает тензоры конкретного фреймворка. Допустимые значения:  - `'pt'`: возвращает объекты `torch.Tensor` PyTorch. - `'np'`: возвращает объекты `np.ndarray` NumPy.

**Возвращает:** [BatchFeature](/docs/transformers/main/ru/main_classes/feature_extractor#transformers.BatchFeature)

Объект [BatchFeature](/docs/transformers/main/ru/main_classes/feature_extractor#transformers.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[[transformers.ColModernVBertProcessor.process_queries]]

```python
process_queries(text: str | list[str], **kwargs: *<class 'transformers.models.colmodernvbert.processing_colmodernvbert.ColModernVBertProcessorKwargs'>)
```

[Источник](https://github.com/huggingface/transformers/blob/main/src/transformers/models/colmodernvbert/processing_colmodernvbert.py#L390)

**Параметры:**

text (`str`, `list[str]`, `list[list[str]]`) : Последовательность или батч последовательностей для кодирования. Каждая последовательность может быть строкой или списком строк (предтокенизированная строка). Если последовательности предоставлены в виде списка строк (предтокенизированных), необходимо установить `is_split_into_words=True` (чтобы устранить неоднозначность с батчем последовательностей).

return_tensors (`str` или [TensorType](/docs/transformers/main/ru/internal/file_utils#transformers.TensorType), *optional*) : Если задано, возвращает тензоры конкретного фреймворка. Допустимые значения:  - `'pt'`: возвращает объекты `torch.Tensor` PyTorch. - `'np'`: возвращает объекты `np.ndarray` NumPy.

**Возвращает:** [BatchFeature](/docs/transformers/main/ru/main_classes/feature_extractor#transformers.BatchFeature)

Объект [BatchFeature](/docs/transformers/main/ru/main_classes/feature_extractor#transformers.BatchFeature) со следующими полями:

- **input_ids** -- Список идентификаторов токенов, которые подаются в модель.
- **attention_mask** -- Список индексов, указывающих, на какие токены модель должна обращать внимание (когда `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/main/src/transformers/models/colmodernvbert/processing_colmodernvbert.py#L447)

**Параметры:**

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` или `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) -> обычно полученного путем дополнения списка тензоров.

## ColModernVBertForRetrieval[[transformers.ColModernVBertForRetrieval]]

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

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

[Источник](https://github.com/huggingface/transformers/blob/main/src/transformers/models/colmodernvbert/modeling_colmodernvbert.py#L91)

**Параметры:**

config ([ColModernVBertConfig](/docs/transformers/main/ru/model_doc/colmodernvbert#transformers.ColModernVBertConfig)) : Класс конфигурации модели со всеми параметрами модели. Инициализация с файлом конфигурации не загружает веса, связанные с моделью, только конфигурацию. Используйте метод [from_pretrained()](/docs/transformers/main/ru/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/main/ru/main_classes/model#transformers.PreTrainedModel). Общие методы, которые библиотека реализует для всех своих моделей (например, загрузка или сохранение, изменение размера входных эмбеддингов, обрезка головок и т. д.), описаны в документации родительского класса.

Эта модель также является подклассом [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) в PyTorch. Используйте её как обычный модуль PyTorch и обращайтесь к документации 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/main/src/transformers/models/colmodernvbert/modeling_colmodernvbert.py#L105)

**Параметры:**

input_ids (`torch.LongTensor` формы `(batch_size, sequence_length)`, *необязательно*) : Индексы токенов входной последовательности в словаре. По умолчанию заполнение (padding) игнорируется. Индексы можно получить с помощью [AutoTokenizer](/docs/transformers/main/ru/model_doc/auto#transformers.AutoTokenizer). Подробности см. в [PreTrainedTokenizer.encode()](/docs/transformers/main/ru/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) и [PreTrainedTokenizer.__call__()](/docs/transformers/main/ru/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__). [Что такое входные идентификаторы?](../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/main/ru/model_doc/colmodernvbert#transformers.ColModernVBertProcessor) использует `image_processor_class` для обработки изображений).

attention_mask (`torch.Tensor` формы `(batch_size, sequence_length)`, *необязательный*) : Маска для предотвращения применения внимания к индексам токенов отсечки. Значения маски выбираются из `[0, 1]`:  - 1 для токенов, которые **не замаскированы**, - 0 для токенов, которые **замаскированы**.  [Что такое маски внимания?](../glossary#attention-mask)

**Возвращает:** `ColModernVBertForRetrievalOutput` или `tuple(torch.Tensor)`

Объект `ColModernVBertForRetrievalOutput` или кортеж из `torch.Tensor` (если передано `return_dict=False` или если `config.return_dict=False`), содержащий различные элементы в зависимости от конфигурации ([ColModernVBertConfig](/docs/transformers/main/ru/model_doc/colmodernvbert#transformers.ColModernVBertConfig)) и входных данных.

Метод forward класса [ColModernVBertForRetrieval](/docs/transformers/main/ru/model_doc/colmodernvbert#transformers.ColModernVBertForRetrieval) переопределяет специальный метод `__call__`.

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

- **loss** (`torch.Tensor` формы `(1,)`, *необязательный*, возвращается, если задан `labels`) -- Потеря языковой модели (для предсказания следующего токена).
- **embeddings** (`torch.Tensor` формы `(batch_size, sequence_length, hidden_size)`) -- Векторные представления модели.
- **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
```