# ColModernVBert

## Genel Bakış

ColModernVBert, görsel belge geri getirme için verimli bir modeldir. [ModernVBert](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](https://huggingface.co/papers/2510.01149) 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[[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)
```

[Kaynak](https://github.com/huggingface/transformers/blob/main/src/transformers/models/colmodernvbert/configuration_colmodernvbert.py#L31)

**Parametreler:**

vlm_config (`Union[dict, ~configuration_utils.PreTrainedConfig]`, *isteğe bağlı*) : Görsel-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`, *opsiyonel*, 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ılanlarla bir yapılandırma örneği oluşturmak, [ModernVBERT/colmodernvbert-merged](https://huggingface.co/ModernVBERT/colmodernvbert-merged) ile benzer bir yapılandırmaya yol açar.

Yapılandırma nesneleri [PreTrainedConfig](/docs/transformers/main/tr/main_classes/configuration#transformers.PreTrainedConfig) sınıfından türetilir ve model çıktılarını kontrol etmek için kullanılabilir. Daha fazla bilgi için [PreTrainedConfig](/docs/transformers/main/tr/main_classes/configuration#transformers.PreTrainedConfig) belgesini okuyun.

Örnek:

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

[Kaynak](https://github.com/huggingface/transformers/blob/main/src/transformers/models/colmodernvbert/processing_colmodernvbert.py#L55)

**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 metne dönüştürmek için kullanılan bir Jinja şablonu.

image_seq_len (`int`, *isteğe bağlı*, varsayılan 64) : Görsel dizininin uzunluğu, yani girdideki görsel başına token sayısı.

visual_prompt_prefix (`str`, *isteğe bağlı*) : Görsel jetonlarının başına eklenmek üzere 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](/docs/transformers/main/tr/model_doc/colmodernvbert#transformers.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[[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'>)
```

[Kaynak](https://github.com/huggingface/transformers/blob/main/src/transformers/models/colmodernvbert/processing_colmodernvbert.py#L324)

**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](/docs/transformers/main/tr/internal/file_utils#transformers.TensorType), *opsiyonel*) : Ayarlanırsa, belirli bir çerçeveye ait tensörleri döndürür. Kabul edilen değerler:  - `'pt'`: PyTorch `torch.Tensor` nesnelerini döndürür. - `'np'`: NumPy `np.ndarray` nesnelerini döndürür.

**Dönüş:** [BatchFeature](/docs/transformers/main/tr/main_classes/feature_extractor#transformers.BatchFeature)

Aşağıdaki alanlara sahip bir [BatchFeature](/docs/transformers/main/tr/main_classes/feature_extractor#transformers.BatchFeature):

- **input_ids** -- Bir modele verilecek token kimliklerinin listesi.
- **attention_mask** -- Modelin hangi jetonlara 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 ve her görüntünün başına `visual_prompt_prefix` ekler. `text_kwargs` içinde bir `suffix` sağlandığında, `token_type_ids` üzerinden etiketleri hesaplar.

#### process_queries[[transformers.ColModernVBertProcessor.process_queries]]

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

[Kaynak](https://github.com/huggingface/transformers/blob/main/src/transformers/models/colmodernvbert/processing_colmodernvbert.py#L390)

**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 (önceden tokenize edilmiş) olarak 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](/docs/transformers/main/tr/internal/file_utils#transformers.TensorType), *opsiyonel*) : Ayarlanırsa, belirli bir çerçeveye ait tensörleri döndürür. Kabul edilen değerler:  - `'pt'`: PyTorch `torch.Tensor` nesnelerini döndürür. - `'np'`: NumPy `np.ndarray` nesnelerini döndürür.

**Dönüş:** [BatchFeature](/docs/transformers/main/tr/main_classes/feature_extractor#transformers.BatchFeature)

Aşağıdaki alanlara sahip bir [BatchFeature](/docs/transformers/main/tr/main_classes/feature_extractor#transformers.BatchFeature):

- **input_ids** -- Bir modele verilecek token kimliklerinin listesi.
- **attention_mask** -- Modelin hangi jetonlara 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[[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')
```

[Kaynak](https://github.com/huggingface/transformers/blob/main/src/transformers/models/colmodernvbert/processing_colmodernvbert.py#L447)

**Parametreler:**

query_embeddings (`Union[torch.Tensor, list[torch.Tensor]`) : Sorgu gömme değerleri.

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 parti boyutu.

output_dtype (`torch.dtype`, *isteğe bağlı*, varsayılan `torch.float32`) : Çıktı tensörünün dtype'ı. `None` ise, girdi gömlemelerinin 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üş:** `torch.Tensor`

Puanları içeren, şekli `(n_queries, n_passages)` olan 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) tensör listesi, burada i. tensörün şekli (sequence_length_i, embedding_dim) şeklindedir (2) (n_passages, max_sequence_length, embedding_dim) şeklinde tek bir tensör -> genellikle tensör listesinin dolgu (padding) ile elde edilir.

## ColModernVBertForRetrieval[[transformers.ColModernVBertForRetrieval]]

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

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

[Kaynak](https://github.com/huggingface/transformers/blob/main/src/transformers/models/colmodernvbert/modeling_colmodernvbert.py#L91)

**Parametreler:**

config ([ColModernVBertConfig](/docs/transformers/main/tr/model_doc/colmodernvbert#transformers.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()](/docs/transformers/main/tr/main_classes/model#transformers.PreTrainedModel.from_pretrained) yöntemine bakın.

ColPali yaklaşımını izleyen ColModernVBert, belge görüntülerinden (“ekran görüntülerinden”) doğrudan verimli çok vektörlü gömlemler oluşturmak için VLM’leri 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*](https://arxiv.org/abs/2510.01149).

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*](https://huggingface.co/papers/2407.01449).

Bu model [PreTrainedModel](/docs/transformers/main/tr/main_classes/model#transformers.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 ayarlama, başları budama vb.) için üst sınıf belgelendirmesine bakın.

Bu model aynı zamanda bir PyTorch [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#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[[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'>)
```

[Kaynak](https://github.com/huggingface/transformers/blob/main/src/transformers/models/colmodernvbert/modeling_colmodernvbert.py#L105)

**Parametreler:**

input_ids (`torch.LongTensor`, şekli `(batch_size, sequence_length)`, *isteğe bağlı*) : Sözlükteki girdi dizisi belirteçlerinin (token) indeksleri. Varsayılan olarak dolgu (padding) yoksayılır. İndeksler [AutoTokenizer](/docs/transformers/main/tr/model_doc/auto#transformers.AutoTokenizer) kullanılarak elde edilebilir. Ayrıntılar için [PreTrainedTokenizer.encode()](/docs/transformers/main/tr/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) ve [PreTrainedTokenizer.__call__()](/docs/transformers/main/tr/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__) yöntemlerine bakın. [Girdi kimlikları (input IDs) nedir?](../glossary#input-ids)

pixel_values (`torch.FloatTensor` şekli `(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](/docs/transformers/main/tr/model_doc/colmodernvbert#transformers.ColModernVBertProcessor), görüntüleri işlemek için `image_processor_class` kullanır).

attention_mask (`torch.Tensor`, şekli `(batch_size, sequence_length)`, *isteğe bağlı*) : Dolgu (padding) token indekslerinde dikkat (attention) işleminin uygulanmamasını sağlayan maske. `[0, 1]` aralığında seçilen maske değerleri:  - **maske uygulanmayan** tokenlar için 1, - **maske uygulanan** tokenlar için 0.  [Dikkat maskeleri nelerdir?](../glossary#attention-mask)

**Dönüş:** `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ırma ([ColModernVBertConfig](/docs/transformers/main/tr/model_doc/colmodernvbert#transformers.ColModernVBertConfig)) ve girdilere bağlı olarak çeşitli öğelerden oluşur.

[ColModernVBertForRetrieval](/docs/transformers/main/tr/model_doc/colmodernvbert#transformers.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ü ilki ö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 tuple. 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` (her katman için bir tane) içeren bir tuple, şekli `(batch_size, num_heads, sequence_length, sequence_length)`.

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

Örnek:

```python
```