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

Model ini dipublikasikan di HF papers pada 2025-10-01 dan disumbangkan ke Hugging Face Transformers pada 2026-02-23.

ColModernVBert

FlashAttention SDPA

Ikhtisar

ColModernVBert adalah model untuk pengambilan dokumen visual yang efisien. Model ini memanfaatkan ModernVBert untuk membangun embedding multi-vektor langsung dari gambar dokumen, mengikuti pendekatan ColPali.

Model ini diperkenalkan dalam 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

kelas 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 )

Parameter

  • vlm_config (Union[dict, ~configuration_utils.PreTrainedConfig], opsional) — Objek config atau dictionary dari backbone vision-language.
  • embedding_dim (int, opsional, default 128) — Dimensi dari embedding dan hidden states.
  • initializer_range (float, opsional, defaultnya 0.02) — Standar deviasi dari truncated_normal_initializer untuk menginisialisasi semua matriks bobot.

Ini adalah kelas konfigurasi untuk menyimpan konfigurasi dari ColmodernvbertModel. Kelas ini digunakan untuk membuat model Colmodernvbert berdasarkan argumen yang ditentukan, yang mendefinisikan arsitektur model. Membuat konfigurasi dengan nilai bawaan akan menghasilkan konfigurasi yang serupa dengan konfigurasi dari ModernVBERT/colmodernvbert-merged

Objek konfigurasi mewarisi dari PreTrainedConfig dan dapat digunakan untuk mengontrol output model. Baca dokumentasi dari PreTrainedConfig untuk informasi lebih lanjut.

Contoh:

from transformers import ColModernVBertConfig, ColModernVBertForRetrieval

config = ColModernVBertConfig()
model = ColModernVBertForRetrieval(config)

ColModernVBertProcessor

kelas transformers.ColModernVBertProcessor

< >

( image_processortokenizer = Nonechat_template = Noneimage_seq_len: int = 64visual_prompt_prefix: str | None = Nonequery_prefix: str | None = None**kwargs )

Parameter

  • image_processor (image_processor_class) — Image processor adalah input yang wajib.
  • tokenizer (tokenizer_class) — Tokenizer adalah input yang wajib.
  • chat_template (str) — Template Jinja untuk mengubah daftar pesan dalam chat menjadi string yang dapat ditokenisasi.
  • image_seq_len (int, opsional, default 64) — Panjang urutan gambar, yaitu jumlah token per gambar dalam input.
  • visual_prompt_prefix (str, opsional) — String yang ditokenisasi dan ditambahkan di depan token gambar.
  • query_prefix (str, opsional) — Awalan yang akan digunakan untuk query.

Membangun ColModernVBertProcessor yang membungkus image processor dan tokenizer menjadi satu processor.

ColModernVBertProcessor menyediakan semua fungsionalitas dari image_processor_class dan tokenizer_class. Lihat ~image_processor_class dan ~tokenizer_class untuk informasi lebih lanjut.

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

Parameter

  • images (PIL.Image.Image, np.ndarray, torch.Tensor, list[PIL.Image.Image], list[np.ndarray], list[torch.Tensor]) — Gambar atau batch gambar yang akan disiapkan. Setiap gambar dapat berupa gambar PIL, array NumPy, atau tensor PyTorch. Jika berupa array NumPy/tensor PyTorch, setiap gambar harus memiliki bentuk (C, H, W), di mana C adalah jumlah channel, dan H serta W adalah tinggi dan lebar gambar.
  • return_tensors (str atau TensorType, opsional) — Jika diset, akan mengembalikan tensor dari framework tertentu. Nilai yang dapat diterima adalah:
    • 'pt': Mengembalikan objek PyTorch torch.Tensor.
    • 'np': Mengembalikan objek NumPy np.ndarray.

Mengembalikan

BatchFeature

BatchFeature dengan bidang berikut:

  • input_ids — Daftar id token yang akan diberikan ke model.
  • attention_mask — Daftar indeks yang menentukan token mana yang harus diperhatikan oleh model (ketika return_attention_mask=True atau jika “attention_mask” ada di self.model_input_names dan jika text bukan None).
  • pixel_values — Nilai piksel yang akan diberikan ke model. Dikembalikan ketika images bukan None.

Siapkan satu atau beberapa gambar untuk model. Menangani validasi input, konversi RGB, dan menambahkan visual_prompt_prefix ke setiap gambar. Secara opsional menghitung label dari token_type_ids ketika suffix disediakan dalam text_kwargs.

process_queries

< >

( text: str | list[str]**kwargs: *<class 'transformers.models.colmodernvbert.processing_colmodernvbert.ColModernVBertProcessorKwargs'> ) → BatchFeature

Parameter

  • text (str, list[str], list[list[str]]) — Sequens atau batch dari sequens yang akan dienkod. Setiap sequens dapat berupa string atau daftar string (string yang sudah dipretokenisasi). Jika sequens diberikan sebagai daftar string (pretokenized), Anda harus mengatur is_split_into_words=True (untuk menghilangkan ambiguitas dengan batch dari sequens).
  • return_tensors (str atau TensorType, opsional) — Jika diset, akan mengembalikan tensor dari framework tertentu. Nilai yang dapat diterima adalah:
    • 'pt': Mengembalikan objek PyTorch torch.Tensor.
    • 'np': Mengembalikan objek NumPy np.ndarray.

Mengembalikan

BatchFeature

BatchFeature dengan bidang berikut:

  • input_ids — Daftar id token yang akan diberikan ke model.
  • attention_mask — Daftar indeks yang menentukan token mana yang harus diperhatikan oleh model (ketika return_attention_mask=True atau jika “attention_mask” ada di self.model_input_names dan jika text bukan None).

Siapkan satu atau beberapa kueri teks untuk model. Menangani validasi input, menambahkan query_prefix di awal, dan menambahkan token augmentasi kueri (digunakan untuk mengisi embedding kueri untuk kinerja pengambilan interaksi akhir yang lebih baik).

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

Parameter

  • query_embeddings (Union[torch.Tensor, list[torch.Tensor]) — Embedding query.
  • passage_embeddings (Union[torch.Tensor, list[torch.Tensor]) — Embedding passage.
  • batch_size (int, opsional, default 128) — Ukuran batch untuk menghitung skor.
  • output_dtype (torch.dtype, opsional, defaultnya torch.float32) — dtype dari tensor output. Jika None, dtype dari input embeddings yang digunakan.
  • output_device (torch.device atau str, opsional, default “cpu”) — Perangkat dari tensor output.

Mengembalikan

torch.Tensor

Tensor dengan bentuk (n_queries, n_passages) yang berisi skor. Tensor skor disimpan pada perangkat “cpu”.

Hitung skor late-interaction/MaxSim (mirip ColBERT) untuk embedding query multi-vektor (qs) dan embedding passage (ps) yang diberikan. Untuk ColQwen2, sebuah passage adalah citra dari halaman dokumen.

Karena tensor embedding bersifat multi-vektor dan karenanya dapat memiliki bentuk yang berbeda, tensor tersebut harus diberikan sebagai: (1) daftar tensor, di mana tensor ke-i memiliki bentuk (sequence_length_i, embedding_dim) (2) satu tensor tunggal dengan bentuk (n_passages, max_sequence_length, embedding_dim) -> biasanya diperoleh dengan melakukan padding pada daftar tensor.

ColModernVBertForRetrieval

kelas transformers.ColModernVBertForRetrieval

< >

( config: ColModernVBertConfig )

Parameter

  • config (ColModernVBertConfig) — Kelas konfigurasi model dengan semua parameter model. Inisialisasi dengan file konfigurasi tidak memuat bobot yang terkait dengan model, hanya konfigurasinya. Lihat metode from_pretrained() untuk memuat bobot model.

Mengikuti pendekatan ColPali, ColModernVBert memanfaatkan VLM untuk membangun embedding multi-vektor yang efisien langsung dari gambar dokumen (“screenshot”) untuk pengambilan dokumen. Model ini dilatih untuk memaksimalkan kemiripan antara embedding dokumen ini dan embedding kueri yang sesuai, menggunakan metode interaksi akhir yang diperkenalkan dalam ColBERT.

Menggunakan ColModernVBert menghilangkan kebutuhan akan pipeline pengenalan tata letak dan OCR yang berpotensi kompleks dan rapuh, dengan satu model yang dapat mempertimbangkan konten teks dan visual (tata letak, grafik, …) dari sebuah dokumen.

ColModernVBert dilatih di atas ModernVBert, dan diperkenalkan dalam paper berikut: ModernVBERT: Towards Smaller Visual Document Retrievers.

ColModernVBert merupakan bagian dari keluarga model ColVision, yang diperkenalkan bersama ColPali dalam paper berikut: ColPali: Efficient Document Retrieval with Vision Language Models.

Model ini mewarisi dari PreTrainedModel. Periksa dokumentasi kelas induk untuk metode generik yang diimplementasikan oleh pustaka untuk semua model (seperti mengunduh atau menyimpan, mengubah ukuran embedding input, memangkas kepala, dll.)

Model ini juga merupakan subclass dari torch.nn.Module PyTorch. Gunakan sebagai PyTorch Module biasa dan merujuk ke dokumentasi PyTorch untuk semua hal yang berkaitan dengan penggunaan dan perilaku umum.

forward

< >

( 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)

Parameter

  • input_ids (torch.LongTensor dengan bentuk (batch_size, sequence_length), opsional) — Indeks token dari urutan input dalam kosakata. Padding akan diabaikan secara default.

    Indeks dapat diperoleh menggunakan AutoTokenizer. Lihat PreTrainedTokenizer.encode() dan PreTrainedTokenizer.call() untuk detailnya.

    Apa itu input ID?

  • pixel_values (torch.Tensor dengan bentuk (batch_size, num_channels, image_size, image_size), opsional) — Tensor yang sesuai dengan gambar input. Nilai piksel dapat diperoleh menggunakan image_processor_class. Lihat image_processor_class.__call__ untuk detailnya (ColModernVBertProcessor menggunakan image_processor_class untuk memproses gambar).
  • attention_mask (torch.Tensor dengan bentuk (batch_size, sequence_length), opsional) — Mask untuk menghindari eksekusi attention pada indeks token padding. Nilai mask dipilih dari [0, 1]:
    • 1 untuk token yang tidak dimasker,
    • 0 untuk token yang dimasker.

    Apa itu attention mask?

Mengembalikan

ColModernVBertForRetrievalOutput atau tuple(torch.Tensor)

ColModernVBertForRetrievalOutput atau tuple dari torch.Tensor (jika return_dict=False diteruskan atau ketika config.return_dict=False) yang terdiri dari berbagai elemen tergantung pada konfigurasi (ColModernVBertConfig) dan input.

Metode forward dari ColModernVBertForRetrieval menimpa metode khusus __call__.

Meskipun resep untuk forward pass perlu didefinisikan di dalam fungsi ini, sebaiknya panggil instance Module setelahnya alih-alih fungsi ini, karena yang pertama menangani langkah-langkah pra-pemrosesan dan pasca-pemrosesan, sedangkan yang kedua mengabaikannya secara diam-diam.

  • loss (torch.Tensor dengan bentuk (1,), opsional, dikembalikan saat labels disediakan) — Loss pemodelan bahasa (untuk prediksi token berikutnya).

  • embeddings (torch.Tensor dengan bentuk (batch_size, sequence_length, hidden_size)) — Embeddings dari model.

  • hidden_states (tuple[torch.Tensor], opsional, dikembalikan saat output_hidden_states=True dilewatkan atau saat config.output_hidden_states=True) — Tuple dari torch.Tensor (satu untuk output dari embeddings, jika model memiliki lapisan embedding, + satu untuk output dari setiap lapisan) dengan bentuk (batch_size, sequence_length, hidden_size).

    Hidden-states model pada output setiap layer ditambah output embedding awal yang opsional.

  • image_hidden_states (tuple(torch.Tensor), opsional, dikembalikan ketika output_hidden_states=True dilewatkan atau ketika config.output_hidden_states=True dan pixel_values disediakan) — Tuple dari torch.Tensor (satu untuk output dari proyeksi modalitas gambar + satu untuk output dari setiap lapisan) dengan bentuk (batch_size, num_channels, image_size, image_size). Hidden-states dari encoder gambar pada output setiap lapisan ditambah output proyeksi modalitas awal.

  • attentions (tuple[torch.Tensor], opsional, dikembalikan saat output_attentions=True dilewatkan atau saat config.output_attentions=True) — Tuple dari torch.Tensor (satu untuk setiap layer) dengan bentuk (batch_size, num_heads, sequence_length, sequence_length).

    Bobot perhatian setelah softmax perhatian, digunakan untuk menghitung rata-rata berbobot di kepala perhatian diri (self-attention).

Contoh:

Update on GitHub

←CohereCompass ColPali→