Transformers documentation
ColModernVBert
このモデルは2025年10月1日にHF papersで公開され、2026年2月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) — 画像シーケンスの長さ、すなわち入力における 1 画像あたりのトークン数 。 - visual_prompt_prefix (
str、省略可) — トークン化されて画像トークンの前に付加される文字列です。 - 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': PyTorchのtorch.Tensorオブジェクトを返します。'np': NumPyのnp.ndarrayオブジェクトを返します。
戻り値
以下のフィールドを持つ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
< 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': PyTorchのtorch.Tensorオブジェクトを返します。'np': NumPyのnp.ndarrayオブジェクトを返します。
戻り値
以下のフィールドを持つBatchFeature:
- input_ids — モデルに与えるトークン ID のリスト。
- attention_mask — モデルがどのトークンに注意を払うべきかを指定するインデックスのリスト（
return_attention_mask=Trueの場合、またはself.model_input_namesに“attention_mask”が含まれておりtextがNoneでない場合）。
モデルに対して1つまたは複数のテキストクエリを準備します。入力検証を行い、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ページに対応します。
埋め込みテンソルはマルチベクトルであり、そのため形状が異なる可能性があるため、以下のように渡す必要があります。 (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で導入された遅延相互作用（late interaction）手法を用いて、これらのドキュメント埋め込みと対応するクエリ埋め込みの類似度を最大化するように学習されます。
ColModernVBertを使用することで、文書のテキストと視覚的な内容（レイアウト、チャートなど）の両方を考慮できる単一のモデルにより、複雑で脆弱になりがちなレイアウト認識やOCRのパイプラインの必要性を排除できます。
ColModernVBert は ModernVBert をベースに学習されており、以下の論文で提案されました: ModernVBERT: Towards Smaller Visual Document Retrievers。
ColModernVBertは、ColPaliとともに以下の論文で発表されたColVisionモデルファミリーの一部です: 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.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), 、省略可) — 語彙における入力シーケンスのトークンインデックスです。デフォルトではパディングは無視されます。インデックスは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）と入力に応じて、さまざまな要素で構成されます。
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のタプル（埋め込み層を持つモデルの場合、埋め込みの出力用が 1 つ、各層の出力用が 1 つずつ）で、形状は(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後のアテンション重み。自己アテンションヘッド内で加重平均を計算するために使用されます。