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

Bu model 2025-10-01 tarihinde HF papers'ta yayımlandı ve 2026-02-23 tarihinde Hugging Face Transformers'a katkıda bulunuldu.

ColModernVBert

FlashAttention SDPA

Genel Bakış

ColModernVBert, görsel belge geri getirme için verimli bir modeldir. ModernVBert'yi kullanarak ColPali yaklaşımını izleyerek belge görüntülerinden doğrudan çoklu vektör gömme (embedding) oluşturur.

Model, ModernVBERT: Towards Smaller Visual Document Retrievers makalesinde tanıtılmıştır.

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

sınıf 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 )

Parametreler

  • vlm_config (Union[dict, ~configuration_utils.PreTrainedConfig], isteğe bağlı) — Görüntü-dil omurgasının yapılandırma nesnesi veya sözlüğü.
  • embedding_dim (int, isteğe bağlı, varsayılan 128) — Gömme ve gizli durumların boyutluluğu.
  • initializer_range (float, isteğe bağlı, varsayılan 0.02) — Tüm ağırlık matrislerini başlatmak için kullanılan truncated_normal_initializer'ın standart sapması.

Bu, bir ColmodernvbertModel yapılandırmasını depolamak için kullanılan yapılandırma sınıfıdır. Belirtilen argümanlara göre bir Colmodernvbert modelini örneklemek ve model mimarisini tanımlamak için kullanılır. Varsayılan değerlerle bir yapılandırma örneği oluşturmak, ModernVBERT/colmodernvbert-merged ile benzer bir yapılandırmaya yol açar.

Yapılandırma nesneleri PreTrainedConfig sınıfından devralır ve model çıktılarını kontrol etmek için kullanılabilir. Daha fazla bilgi için PreTrainedConfig belgesini okuyun.

Örnek:

from transformers import ColModernVBertConfig, ColModernVBertForRetrieval

config = ColModernVBertConfig()
model = ColModernVBertForRetrieval(config)

ColModernVBertProcessor

sınıf transformers.ColModernVBertProcessor

< >

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

Parametreler

  • image_processor (image_processor_class) — Görüntü işleyici zorunlu bir girdidir.
  • tokenizer (tokenizer_class) — Tokenizer zorunlu bir girdidir.
  • chat_template (str) — Bir sohbet içindeki mesaj listelerini tokenize edilebilir bir dizeye dönüştürmek için kullanılan bir Jinja şablonu.
  • image_seq_len (int, isteğe bağlı, varsayılan 64) — Görsel dizisinin uzunluğu, yani girdideki görsel başına token sayısı.
  • visual_prompt_prefix (str, isteğe bağlı) — Görsel jetonların başına eklenmek için jetonlaştırılan bir dize.
  • query_prefix (str, isteğe bağlı) — Sorgu için kullanılacak bir önek.

Bir görüntü işleyiciyi ve bir belirteçleyiciyi tek bir işleyicide birleştiren bir ColModernVBertProcessor oluşturur.

ColModernVBertProcessor, image_processor_class ve tokenizer_class sınıflarının tüm işlevlerini sunar. Daha fazla bilgi için ~image_processor_class ve ~tokenizer_class belgelerine bakın.

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

Parametreler

  • images (PIL.Image.Image, np.ndarray, torch.Tensor, list[PIL.Image.Image], list[np.ndarray], list[torch.Tensor]) — Hazırlanacak görüntü veya görüntü grubu. Her görüntü bir PIL görüntüsü, NumPy dizisi veya PyTorch tensörü olabilir. NumPy dizisi/PyTorch tensörü durumunda, her görüntünün şekli (C, H, W) olmalıdır; burada C kanal sayısı, H ve W ise görüntü yüksekliği ve genişliğidir.
  • return_tensors (str veya TensorType, isteğe bağlı) — Belirlenirse, belirli bir çerçeveye ait tensörler döndürülür. Kabul edilen değerler şunlardır:
    • 'pt': PyTorch torch.Tensor nesnelerini döndürür.
    • 'np': NumPy np.ndarray nesnelerini döndürür.

Dönüş değeri

BatchFeature

Aşağıdaki alanlara sahip bir BatchFeature:

  • input_ids — Bir modele verilecek token kimliklerinin listesi.
  • attention_mask — Modelin hangi token'lara dikkat etmesi gerektiğini belirleyen indeks listesi (return_attention_mask=True olduğunda veya “attention_mask” self.model_input_names içindeyse ve text None değilse).
  • pixel_values — Bir modele verilecek piksel değerleri. images None olmadığında döndürülür.

Model için bir veya birden fazla görüntü hazırlar. Girdi doğrulamasını ve RGB dönüşümünü işler, her görüntünün başına visual_prompt_prefix ekler. text_kwargs içinde suffix sağlandığında, token_type_ids üzerinden etiketleri hesaplar.

process_queries

< >

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

Parametreler

  • text (str, list[str], list[list[str]]) — Kodlanacak dizi veya dizi grubu. Her dizi bir metin veya metin listesi (önceden tokenize edilmiş metin) olabilir. Diziler metin listesi olarak (önceden tokenize edilmiş) sağlanıyorsa, is_split_into_words=True değerini ayarlamanız gerekir (dizi grubu ile karışıklığı önlemek için).
  • return_tensors (str veya TensorType, isteğe bağlı) — Belirlenirse, belirli bir çerçeveye ait tensörler döndürülür. Kabul edilen değerler şunlardır:
    • 'pt': PyTorch torch.Tensor nesnelerini döndürür.
    • 'np': NumPy np.ndarray nesnelerini döndürür.

Dönüş değeri

BatchFeature

Aşağıdaki alanlara sahip bir BatchFeature:

  • input_ids — Bir modele verilecek token kimliklerinin listesi.
  • attention_mask — Modelin hangi token'lara dikkat etmesi gerektiğini belirleyen indeks listesi (return_attention_mask=True olduğunda veya “attention_mask” self.model_input_names içindeyse ve text None değilse).

Model için bir veya birden fazla metin sorgusu hazırlar. Girdi doğrulamasını işler, query_prefix ekler ve sorgu artırım belirteçlerini (geç etkileşimli geri getirme performansını iyileştirmek için sorgu gömme vektörlerini doldurmak üzere kullanılan) sonuna ekler.

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

Parametreler

  • query_embeddings (Union[torch.Tensor, list[torch.Tensor]) — Sorgu gömlemeleri.
  • passage_embeddings (Union[torch.Tensor, list[torch.Tensor]) — Paragraf gömme değerleri.
  • batch_size (int, isteğe bağlı, varsayılan 128) — Skorları hesaplamak için kullanılan parti boyutu.
  • output_dtype (torch.dtype, isteğe bağlı, varsayılan torch.float32) — Çıktı tensörünün dtype'ı. None ise, girdi gömme değerlerinin dtype'ı kullanılır.
  • output_device (torch.device veya str, isteğe bağlı, varsayılan “cpu”) — Çıktı tensörünün cihazı.

Dönüş değeri

torch.Tensor

(n_queries, n_passages) biçiminde, puanları içeren bir tensör. Puan tensörü “cpu” cihazında saklanır.

Verilen çok vektörlü sorgu gömme değerleri (qs) ve paragraf gömme değerleri (ps) için geç etkileşim/MaxSim puanını (ColBERT benzeri) hesaplayın. ColQwen2 için bir paragraf, bir belge sayfasının görüntüsüdür.

Gömme tensörleri çok vektörlü olduğundan farklı şekillere sahip olabilirler; bu nedenle şu şekilde beslenmelidirler: (1) i. tensörünün (sequence_length_i, embedding_dim) şeklinde olduğu bir tensör listesi (2) (n_passages, max_sequence_length, embedding_dim) şeklinde tek bir tensör -> genellikle tensör listesinin dolgu (padding) ile elde edilir.

ColModernVBertForRetrieval

sınıf transformers.ColModernVBertForRetrieval

< >

( config: ColModernVBertConfig )

Parametreler

  • config (ColModernVBertConfig) — Modelin tüm parametrelerini içeren model yapılandırma sınıfı. Bir yapılandırma dosyasıyla başlatmak, modelle ilişkili ağırlıkları yüklemez, yalnızca yapılandırmayı yükler. Model ağırlıklarını yüklemek için from_pretrained() yöntemine bakın.

ColPali yaklaşımını izleyen ColModernVBert, VLM'leri kullanarak belge görüntülerinden (“ekran görüntülerinden”) doğrudan belge geri getirme için verimli çoklu vektör gömlemleri oluşturmak üzere kullanır. Model, ColBERT'te tanıtılan geç etkileşim yöntemini kullanarak bu belge gömlemleri ile ilgili sorgu gömlemleri arasındaki benzerliği en üst düzeye çıkarmak üzere eğitilir.

ColModernVBert kullanmak, bir belgenin hem metinsel hem de görsel içeriğini (yerleşim, grafikler, …) dikkate alabilen tek bir model sayesinde, potansiyel olarak karmaşık ve kırılgan yerleşim tanıma ve OCR iş akışlarına duyulan ihtiyacı ortadan kaldırır.

ColModernVBert, ModernVBert üzerine eğitilmiştir ve aşağıdaki makalede tanıtılmıştır: ModernVBERT: Towards Smaller Visual Document Retrievers.

ColModernVBert, ColPali ile birlikte aşağıdaki makalede tanıtılan ColVision model ailesinin bir parçasıdır: ColPali: Efficient Document Retrieval with Vision Language Models.

Bu model PreTrainedModel sınıfından devralır. Kütüphanenin tüm modelleri için uyguladığı genel yöntemler (indirme veya kaydetme, giriş gömme boyutlarını yeniden boyutlandırma, başları budama vb.) için üst sınıf belgelendirmesine bakın.

Bu model aynı zamanda bir PyTorch torch.nn.Module alt sınıfıdır. Bunu standart bir PyTorch Module olarak kullanın ve genel kullanım ve davranışla ilgili tüm konular için PyTorch dokümantasyonuna başvurun.

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)

Parametreler

  • input_ids (torch.LongTensor şeklinde (batch_size, sequence_length), isteğe bağlı) — Sözlükteki girdi dizisi belirteçlerinin (token) indeksleri. Varsayılan olarak dolgu (padding) yok sayılır.

    Dizinler AutoTokenizer kullanılarak elde edilebilir. Ayrıntılar için PreTrainedTokenizer.encode() ve PreTrainedTokenizer.call() konularına bakın.

    Girdi kimlikleri nelerdir?

  • pixel_values (torch.FloatTensor of shape (batch_size, num_channels, image_size, image_size), isteğe bağlı) — Girdi görüntülerine karşılık gelen tensörler. Piksel değerleri image_processor_class kullanılarak elde edilebilir. Ayrıntılar için image_processor_class.__call__ bölümüne bakın (ColModernVBertProcessor, görüntüleri işlemek için image_processor_class kullanır).
  • attention_mask (torch.Tensor şeklinde (batch_size, sequence_length), isteğe bağlı) — Doldurma (padding) token indekslerinde dikkat (attention) işlemi yapmaktan kaçınmak için kullanılan maske. Seçilen maske değerleri [0, 1]:
    • 1, maskelenmemiş jetonlar için,
    • maskelenmiş jetonlar için 0.

    Dikkat maskeleri nedir?

Dönüş değeri

ColModernVBertForRetrievalOutput veya tuple(torch.FloatTensor)

ColModernVBertForRetrievalOutput veya bir torch.FloatTensor demeti (return_dict=False geçirildiğinde veya config.return_dict=False olduğunda), yapılandırmaya (ColModernVBertConfig) ve girdilere bağlı olarak çeşitli öğelerden oluşur.

ColModernVBertForRetrieval forward metodu, __call__ özel metodunu geçersiz kılar.

İleri geçiş tarifi bu fonksiyon içinde tanımlanmalı olsa da, sonrasında bunun yerine Module örneğini çağırmak gerekir; çünkü önceki, ön ve son işleme adımlarını çalıştırmaktan sorumluyken ikincisi bunları sessizce yok sayar.

  • loss (torch.FloatTensor, şekli (1,), opsiyonel, labels sağlandığında döndürülür) — Dil modelleme kaybı (sonraki token tahmini için).

  • embeddings (torch.FloatTensor, şekli (batch_size, sequence_length, hidden_size)) — Modelin gömme değerleri.

  • hidden_states (tuple[torch.FloatTensor], isteğe bağlı, output_hidden_states=True geçirildiğinde veya config.output_hidden_states=True olduğunda döndürülür) — torch.FloatTensor (modelin bir gömme katmanı varsa gömme katmanının çıktısı için bir tane + her katmanın çıktısı için birer tane) içeren, (batch_size, sequence_length, hidden_size) biçiminde bir demet.

    Her katmanın çıktısında modelin gizli durumları ve isteğe bağlı başlangıç gömme çıktıları.

  • image_hidden_states (tuple(torch.FloatTensor), opsiyonel, output_hidden_states=True geçirildiğinde veya config.output_hidden_states=True ve pixel_values sağlandığında döndürülür) — torch.FloatTensor (görsel modalite projeksiyonunun çıktısı için bir tane + her katman için bir tane) içeren, (batch_size, num_channels, image_size, image_size) biçiminde bir demet. Görsel kodlayıcının her katman çıktısındaki gizli durumları ve başlangıç modalite projeksiyon çıktıları.

  • attentions (tuple[torch.FloatTensor], isteğe bağlı, output_attentions=True geçirildiğinde veya config.output_attentions=True olduğunda döndürülür) — torch.FloatTensor (katman başına bir tane) içeren bir tuple, şekli (batch_size, num_heads, sequence_length, sequence_length).

    Dikkat softmax'ı sonrası dikkat ağırlıkları, öz-dikkat başlıklarında ağırlıklı ortalamanın hesaplanmasında kullanılır.

Örnek:

Update on GitHub

←CohereCompass ColPali→