# 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]`, *optional*) : ビジョン・言語バックボーンの config オブジェクトまたは辞書。

embedding_dim (`int`、*optional*、デフォルトは`128`) : 埋め込みおよび隠れ状態の次元数。

initializer_range (`float`、*任意*、デフォルトは`0.02`) : すべての重み行列を初期化するためのtruncated_normal_initializerの標準偏差です。

これはColmodernvbertModelの設定を保存するための設定クラスです。指定された引数に従ってColmodernvbertモデルをインスタンス化し、モデルのアーキテクチャを定義するために使用されます。デフォルト値で設定をインスタンス化すると、[ModernVBERT/colmodernvbert-merged](https://huggingface.co/ModernVBERT/colmodernvbert-merged)と類似した設定が得られます。

設定オブジェクトは [PreTrainedConfig](/docs/transformers/main/ja/main_classes/configuration#transformers.PreTrainedConfig) を継承し、モデルの出力を制御するために使用できます。詳細については、[PreTrainedConfig](/docs/transformers/main/ja/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) : 画像シーケンスの長さ、すなわち入力における 1 画像あたりのトークン数。

visual_prompt_prefix (`str`, *任意*) : トークン化され、画像トークンの前に付加される文字列。

query_prefix (`str`, *任意*) : クエリに使用するプレフィックス。

画像プロセッサとトークナイザーを単一のプロセッサにラップするColModernVBertProcessorを構築します。

[ColModernVBertProcessor](/docs/transformers/main/ja/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/ja/internal/file_utils#transformers.TensorType)、*optional*) : 設定されている場合、特定のフレームワークのテンソルを返します。受け入れ可能な値は以下の通りです:  - `'pt'`: PyTorch の `torch.Tensor` オブジェクトを返します。 - `'np'`: NumPy の `np.ndarray` オブジェクトを返します。

**戻り値:** [BatchFeature](/docs/transformers/main/ja/main_classes/feature_extractor#transformers.BatchFeature)

以下のフィールドを持つ[BatchFeature](/docs/transformers/main/ja/main_classes/feature_extractor#transformers.BatchFeature):

- **input_ids** -- モデルに渡すトークンIDのリスト。
- **attention_mask** -- モデルが注意すべきトークンを指定するインデックスのリスト（`return_attention_mask=True`の場合、または`self.model_input_names`に*"attention_mask"*が含まれており`text`が`None`でない場合）。
- **pixel_values** -- モデルに渡すピクセル値。`images` が `None` でない場合に返されます。

モデル用に1枚または複数枚の画像を準備します。入力検証、RGB変換、および各画像への`visual_prompt_prefix`の前置きを行います。`text_kwargs`に`suffix`が指定されている場合、`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/ja/internal/file_utils#transformers.TensorType)、*optional*) : 設定されている場合、特定のフレームワークのテンソルを返します。受け入れ可能な値は以下の通りです:  - `'pt'`: PyTorch の `torch.Tensor` オブジェクトを返します。 - `'np'`: NumPy の `np.ndarray` オブジェクトを返します。

**戻り値:** [BatchFeature](/docs/transformers/main/ja/main_classes/feature_extractor#transformers.BatchFeature)

以下のフィールドを持つ[BatchFeature](/docs/transformers/main/ja/main_classes/feature_extractor#transformers.BatchFeature):

- **input_ids** -- モデルに渡すトークンIDのリスト。
- **attention_mask** -- モデルが注意すべきトークンを指定するインデックスのリスト（`return_attention_mask=True`の場合、または`self.model_input_names`に*"attention_mask"*が含まれており`text`が`None`でない場合）。

モデル用の1つまたは複数のテキストクエリを準備します。入力検証を行い、`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`、*optional*、デフォルトは 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ページに対応します。

埋め込みテンソルはマルチベクトルであり、そのため形状が異なる可能性があるため、以下のように入力する必要があります: (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/ja/model_doc/colmodernvbert#transformers.ColModernVBertConfig)) : モデルのパラメータをすべて含むモデル設定クラスです。設定ファイルで初期化しても、モデルに関連する重みは読み込まれず、設定のみが読み込まれます。モデルの重みをロードするには、[from_pretrained()](/docs/transformers/main/ja/main_classes/model#transformers.PreTrainedModel.from_pretrained) メソッドを確認してください。

ColPaliのアプローチに従い、ColModernVBertはVLM（視覚言語モデル）を活用して、文書検索のために文書画像（「スクリーンショット」）から効率的なマルチベクトル埋め込みを構築します。このモデルは、ColBERTで導入された遅延相互作用（late interaction）手法を用いて、これらの文書埋め込みと対応するクエリ埋め込みの類似度を最大化するように学習されます。

ColModernVBertを使用することで、テキストとビジュアル（レイアウト、チャートなど）の両方の内容を考慮できる単一のモデルにより、複雑で脆弱になりがちなレイアウト認識やOCRのパイプラインの必要性を排除できます。

ColModernVBert は ModernVBert をベースに学習されており、以下の論文で提案されました: [*ModernVBERT: Towards Smaller Visual Document Retrievers*](https://arxiv.org/abs/2510.01149)。

ColModernVBertは、ColPaliとともに以下の論文で発表されたColVisionモデルファミリーの一部です: [*ColPali: Efficient Document Retrieval with Vision Language Models*](https://huggingface.co/papers/2407.01449)。

このモデルは [PreTrainedModel](/docs/transformers/main/ja/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.FloatTensor] = 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`、shape `(batch_size, sequence_length)`、*任意*) : 語彙における入力シーケンスのトークンインデックスです。デフォルトでは、パディングは無視されます。インデックスは [AutoTokenizer](/docs/transformers/main/ja/model_doc/auto#transformers.AutoTokenizer) を使用して取得できます。詳細については、[PreTrainedTokenizer.encode()](/docs/transformers/main/ja/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) および [PreTrainedTokenizer.__call__()](/docs/transformers/main/ja/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__) を参照してください。 [入力IDとは何ですか？](../glossary#input-ids)

pixel_values (`torch.FloatTensor`、shape `(batch_size, num_channels, image_size, image_size)`、*任意*) : 入力画像に対応するテンソルです。ピクセル値は `image_processor_class` を使用して取得できます。詳細は `image_processor_class.__call__` を参照してください（[ColModernVBertProcessor](/docs/transformers/main/ja/model_doc/colmodernvbert#transformers.ColModernVBertProcessor) は画像の処理に `image_processor_class` を使用します）。

attention_mask (`torch.Tensor`、shape `(batch_size, sequence_length)`、*任意*) : padding トークンのインデックスに対する attention を回避するためのマスクです。マスクの値は `[0, 1]` から選択されます:  - **マスクされない**トークンは 1、- **マスクされる**トークンは 0。  [attention マスクとは?](../glossary#attention-mask)

**戻り値:** `ColModernVBertForRetrievalOutput` または `tuple(torch.FloatTensor)`

`ColModernVBertForRetrievalOutput`、または`torch.FloatTensor`のタプル（`return_dict=False`が渡された場合、または`config.return_dict=False`の場合）。設定（[ColModernVBertConfig](/docs/transformers/main/ja/model_doc/colmodernvbert#transformers.ColModernVBertConfig)）と入力に応じて、さまざまな要素で構成されます。

[ColModernVBertForRetrieval](/docs/transformers/main/ja/model_doc/colmodernvbert#transformers.ColModernVBertForRetrieval)のforwardメソッドは、`__call__`特殊メソッドをオーバーライドします。

この関数内でフォワードパスの手順を定義する必要がありますが、その後、この関数ではなく`Module`インスタンスを呼び出すべきです。前者は前処理と後処理の実行を適切に処理するのに対し、後者はそれらを無視してしまいます。

- **loss** (`torch.FloatTensor`、shape `(1,)`、*optional*、`labels` が指定された場合に返されます) -- 言語モデリングの損失(次のトークンの予測用)。
- **embeddings** (`torch.FloatTensor`、形状 `(batch_size, sequence_length, hidden_size)`) -- モデルの埋め込み。
- **hidden_states** (`tuple[torch.FloatTensor]`、*optional*、`output_hidden_states=True` が渡された場合または `config.output_hidden_states=True` の場合に返されます) -- `torch.FloatTensor` のタプル（モデルに埋め込み層がある場合はその出力用 + 各層の出力用）で、形状は `(batch_size, sequence_length, hidden_size)` です。

  各層の出力におけるモデルのHidden-states、および任意の初期埋め込み出力。
- **image_hidden_states** (`tuple(torch.FloatTensor)`、*optional*、`output_hidden_states=True` が渡された場合、または `config.output_hidden_states=True` かつ `pixel_values` が提供された場合に返されます) -- `torch.FloatTensor` のタプル（画像モダリティ投影の出力用 1 つ + 各層の出力用 1 つ）、形状は `(batch_size, num_channels, image_size, image_size)`。各層の出力における画像エンコーダーの隠れ状態、および初期モダリティ投影の出力。
- **attentions** (`tuple[torch.FloatTensor]`、*optional*、`output_attentions=True` が渡された場合または `config.output_attentions=True` の場合に返されます) -- `torch.FloatTensor` のタプル（各レイヤーごとに1つ）、形状は `(batch_size, num_heads, sequence_length, sequence_length)`。

  アテンションのsoftmax後のアテンション重み。自己アテンションヘッド内で加重平均を計算するために使用されます。

例:

```python
```