# ColPali

[ColPali](https://huggingface.co/papers/2407.01449) adalah model yang dirancang untuk mengambil dokumen dengan menganalisis fitur visualnya. Berbeda dengan sistem tradisional yang sangat bergantung pada ekstraksi teks dan OCR, ColPali memperlakukan setiap halaman sebagai gambar. Model ini menggunakan [Paligemma-3B](./paligemma) untuk menangkap tidak hanya teks, tetapi juga tata letak, tabel, grafik, dan elemen visual lainnya untuk membuat embedding multi-vektor yang detail, yang dapat digunakan untuk pengambilan dengan menghitung skor kemiripan interaksi akhir pairwise. Hal ini memberikan pemahaman yang lebih komprehensif tentang dokumen dan memungkinkan pengambilan yang lebih efisien dan akurat.

Model ini disumbangkan oleh [@tonywu71](https://huggingface.co/tonywu71) (ILLUIN Technology) dan [@yonigozlan](https://huggingface.co/yonigozlan) (HuggingFace).

Anda dapat menemukan semua checkpoint ColPali asli di bawah koleksi [Hf-native ColVision Models](https://huggingface.co/collections/vidore/hf-native-colvision-models-6755d68fc60a8553acaa96f7) Vidore.

> [!TIP]
> Klik pada model ColPali di bilah sisi kanan untuk melihat lebih banyak contoh cara menggunakan ColPali untuk pengambilan gambar.

```python
import requests
import torch
from PIL import Image

from transformers import ColPaliForRetrieval, ColPaliProcessor

# Load the model and the processor
model_name = "vidore/colpali-v1.3-hf"

model = ColPaliForRetrieval.from_pretrained(
    model_name,
    device_map="auto",  # "cpu", "cuda", "xpu", or "mps" for Apple Silicon
)
processor = ColPaliProcessor.from_pretrained(model_name)

# The document page screenshots from your corpus
url1 = "https://upload.wikimedia.org/wikipedia/commons/8/89/US-original-Declaration-1776.jpg"
url2 = "https://upload.wikimedia.org/wikipedia/commons/thumb/4/4c/Romeoandjuliet1597.jpg/500px-Romeoandjuliet1597.jpg"

images = [
    Image.open(requests.get(url1, stream=True).raw),
    Image.open(requests.get(url2, stream=True).raw),
]

# The queries you want to retrieve documents for
queries = [
    "When was the United States Declaration of Independence proclaimed?",
    "Who printed the edition of Romeo and Juliet?",
]

# Process the inputs
inputs_images = processor(images=images).to(model.device)
inputs_text = processor(text=queries).to(model.device)

# Forward pass
with torch.no_grad():
    image_embeddings = model(**inputs_images).embeddings
    query_embeddings = model(**inputs_text).embeddings

# Score the queries against the images
scores = processor.score_retrieval(query_embeddings, image_embeddings)

print("Retrieval scores (query x image):")
print(scores)
```

Jika Anda mengalami masalah saat memuat gambar dengan PIL, Anda dapat menggunakan kode berikut untuk membuat gambar dummy:

```python
images = [
    Image.new("RGB", (128, 128), color="white"),
    Image.new("RGB", (64, 32), color="black"),
]
```

Quantization mengurangi beban memori model besar dengan merepresentasikan bobot dalam presisi yang lebih rendah. Lihat ringkasan [Quantization](../quantization/overview) untuk backend quantization lain yang tersedia.

Contoh di bawah menggunakan [bitsandbytes](../quantization/bitsandbytes) untuk mengkuantisasi bobot menjadi int4.

```python
import requests
import torch
from PIL import Image

from transformers import BitsAndBytesConfig, ColPaliForRetrieval, ColPaliProcessor

model_name = "vidore/colpali-v1.3-hf"

# 4-bit quantization configuration
bnb_config = BitsAndBytesConfig(
    load_in_4bit=True,
    bnb_4bit_use_double_quant=True,
    bnb_4bit_quant_type="nf4",
    bnb_4bit_compute_dtype=torch.float16,
)

model = ColPaliForRetrieval.from_pretrained(
    model_name,
    quantization_config=bnb_config,
    device_map="auto",
)

processor = ColPaliProcessor.from_pretrained(model_name)

url1 = "https://upload.wikimedia.org/wikipedia/commons/8/89/US-original-Declaration-1776.jpg"
url2 = "https://upload.wikimedia.org/wikipedia/commons/thumb/4/4c/Romeoandjuliet1597.jpg/500px-Romeoandjuliet1597.jpg"

images = [
    Image.open(requests.get(url1, stream=True).raw),
    Image.open(requests.get(url2, stream=True).raw),
]

queries = [
    "When was the United States Declaration of Independence proclaimed?",
    "Who printed the edition of Romeo and Juliet?",
]

# Process the inputs
inputs_images = processor(images=images, return_tensors="pt").to(model.device)
inputs_text = processor(text=queries, return_tensors="pt").to(model.device)

# Forward pass
with torch.no_grad():
    image_embeddings = model(**inputs_images).embeddings
    query_embeddings = model(**inputs_text).embeddings

# Score the queries against the images
scores = processor.score_retrieval(query_embeddings, image_embeddings)

print("Retrieval scores (query x image):")
print(scores)
```

## Catatan

- `score_retrieval()` mengembalikan tensor 2D di mana dimensi pertama adalah jumlah query dan dimensi kedua adalah jumlah gambar. Skor yang lebih tinggi menunjukkan kemiripan yang lebih besar antara query dan gambar.

## ColPaliConfig[[transformers.ColPaliConfig]]

#### transformers.ColPaliConfig[[transformers.ColPaliConfig]]

```python
transformers.ColPaliConfig(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)
```

[Sumber](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/colpali/configuration_colpali.py#L28)

**Parameter:**

vlm_config (`Union[dict, ~configuration_utils.PreTrainedConfig]`, *opsional*) : Objek config atau dictionary dari backbone vision-language.

embedding_dim (`int`, *opsional*, defaultnya `128`) : Dimensi dari embedding dan hidden states.

Ini adalah kelas konfigurasi untuk menyimpan konfigurasi dari ColpaliModel. Kelas ini digunakan untuk membuat instans model Colpali sesuai dengan argumen yang ditentukan, yang mendefinisikan arsitektur model. Membuat instans konfigurasi dengan nilai bawaan akan menghasilkan konfigurasi yang serupa dengan konfigurasi dari [vidore/colpali-v1.2](https://huggingface.co/vidore/colpali-v1.2)

Objek konfigurasi mewarisi dari [PreTrainedConfig](/docs/transformers/v5.23.0/id/main_classes/configuration#transformers.PreTrainedConfig) dan dapat digunakan untuk mengontrol keluaran model. Baca dokumentasi dari [PreTrainedConfig](/docs/transformers/v5.23.0/id/main_classes/configuration#transformers.PreTrainedConfig) untuk informasi lebih lanjut.

Contoh:

```python
from transformers.models.colpali import ColPaliConfig, ColPaliForRetrieval

config = ColPaliConfig()
model = ColPaliForRetrieval(config)
```

## ColPaliProcessor[[transformers.ColPaliProcessor]]

#### transformers.ColPaliProcessor[[transformers.ColPaliProcessor]]

```python
transformers.ColPaliProcessor(image_processor = None, tokenizer = None, chat_template = None, visual_prompt_prefix: str = 'Describe the image.', query_prefix: str = 'Question: ')
```

[Sumber](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/colpali/processing_colpali.py#L42)

**Parameter:**

image_processor (`SiglipImageProcessor`) : Prosesor gambar adalah input yang wajib.

tokenizer (`tokenizer_class`) : Tokenizer adalah input yang wajib.

chat_template (`str`) : Template Jinja untuk mengonversi daftar pesan dalam chat menjadi string yang dapat ditokenisasi.

visual_prompt_prefix (`str`, *opsional*, defaultnya `"Describe the image."`) : String yang ditokenisasi dan ditambahkan di depan token gambar.

query_prefix (`str`, *opsional*, defaultnya `"Question : "`): Prefiks yang akan digunakan untuk kueri.

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

[ColPaliProcessor](/docs/transformers/v5.23.0/id/model_doc/colpali#transformers.ColPaliProcessor) menyediakan semua fungsionalitas dari [SiglipImageProcessor](/docs/transformers/v5.23.0/id/model_doc/siglip#transformers.SiglipImageProcessor) dan `tokenizer_class`. Lihat [~SiglipImageProcessor](/docs/transformers/v5.23.0/id/model_doc/siglip#transformers.SiglipImageProcessor) dan `~tokenizer_class` untuk informasi lebih lanjut.

#### __call__[[transformers.ColPaliProcessor.__call__]]

```python
__call__(images: typing.Union[ForwardRef('PIL.Image.Image'), numpy.ndarray, ForwardRef('torch.Tensor'), list['PIL.Image.Image'], list[numpy.ndarray], list['torch.Tensor'], NoneType] = None, text: str | list[str] | list[list[str]] = None, suffix: str | None = None, **kwargs: *<class 'transformers.processing_utils.ProcessingKwargs'>)
```

[Sumber](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/colpali/processing_colpali.py#L90)

**Parameter:**

images (`Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]]`, *opsional*) : Gambar untuk dipreprocess. Mengharapkan satu gambar atau batch gambar dengan nilai piksel berkisar dari 0 hingga 255. Jika memasukkan gambar dengan nilai piksel antara 0 dan 1, atur `do_rescale=False`.

text (`Union[str, list[str], list[list[str]]]`, *opsional*) : Urutan atau batch dari urutan yang akan dienkod. Setiap urutan dapat berupa string atau daftar string (string yang sudah dipretokenisasi). Jika Anda memasukkan input yang sudah dipretokenisasi, setel `is_split_into_words=True` untuk menghindari ambiguitas dengan input yang di-batch.

suffix (`str | list[str] | list[list[str]]`, *opsional*) : Sufiks yang ditambahkan ke semua teks input.

return_mm_token_type_ids (`bool`, *kwargs*) : Apakah akan mengembalikan id tipe token multimodal yang menunjukkan posisi token placeholder multimodal.

return_text_replacement_offsets (`bool`, *kwargs*) : Apakah akan mengembalikan offset karakter untuk setiap placeholder multimodal dan pengantinya.

return_tensors (`str` atau [TensorType](/docs/transformers/v5.23.0/id/internal/file_utils#transformers.TensorType), *opsional*) : Jika diatur, akan mengembalikan tensor dari framework tertentu. Nilai yang dapat diterima adalah:  - `'pt'`: Mengembalikan objek `torch.Tensor` PyTorch. - `'np'`: Mengembalikan objek `np.ndarray` NumPy.

- ****kwargs** ([ProcessingKwargs](/docs/transformers/v5.23.0/id/main_classes/processors#transformers.ProcessingKwargs), *opsional*) : Opsi pemrosesan tambahan untuk setiap modalitas (teks, gambar, video, audio). Parameter spesifik model tercantum di atas; lihat kelas TypedDict untuk daftar lengkap argumen yang didukung.

**Mengembalikan:** [BatchFeature](/docs/transformers/v5.23.0/id/main_classes/feature_extractor#transformers.BatchFeature)

[BatchFeature](/docs/transformers/v5.23.0/id/main_classes/feature_extractor#transformers.BatchFeature) dengan bidang berikut:

- **input_ids** -- Daftar token id yang akan diberikan ke model. Dikembalikan ketika `text` bukan `None`. Jika `suffix` disediakan, `input_ids` juga akan berisi input id dari suffix.
- **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`.
- **labels** -- Label yang kompatibel dengan pelatihan jika `suffix` bukan None

## ColPaliForRetrieval[[transformers.ColPaliForRetrieval]]

#### transformers.ColPaliForRetrieval[[transformers.ColPaliForRetrieval]]

```python
transformers.ColPaliForRetrieval(config: ColPaliConfig)
```

[Sumber](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/colpali/modeling_colpali.py#L90)

**Parameter:**

config ([ColPaliConfig](/docs/transformers/v5.23.0/id/model_doc/colpali#transformers.ColPaliConfig)) : Kelas konfigurasi model dengan semua parameter model. Inisialisasi dengan file konfigurasi tidak memuat bobot yang terkait dengan model, hanya konfigurasinya. Lihat metode [from_pretrained()](/docs/transformers/v5.23.0/id/main_classes/model#transformers.PreTrainedModel.from_pretrained) untuk memuat bobot model.

Arsitektur ColPali 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 tersebut dan embedding kueri yang sesuai, menggunakan metode interaksi akhir yang diperkenalkan dalam ColBERT.

Menggunakan ColPali 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, dll.) dari sebuah dokumen.

ColPali merupakan bagian dari keluarga model ColVision, yang pertama kali diperkenalkan dalam makalah berikut: [*ColPali: Efficient Document Retrieval with Vision Language Models*](https://huggingface.co/papers/2407.01449).

Model ini mewarisi dari [PreTrainedModel](/docs/transformers/v5.23.0/id/main_classes/model#transformers.PreTrainedModel). Periksa dokumentasi kelas induk untuk metode generik yang diimplementasikan oleh pustaka ini untuk semua model (seperti mengunduh atau menyimpan, mengubah ukuran input embeddings, memangkas heads, dll.)

Model ini juga merupakan subclass dari [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#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[[transformers.ColPaliForRetrieval.forward]]

```python
forward(input_ids: typing.Optional[torch.LongTensor] = None, pixel_values: typing.Optional[torch.Tensor] = None, attention_mask: typing.Optional[torch.Tensor] = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[Sumber](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/colpali/modeling_colpali.py#L104)

**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](/docs/transformers/v5.23.0/id/model_doc/auto#transformers.AutoTokenizer). Lihat [PreTrainedTokenizer.encode()](/docs/transformers/v5.23.0/id/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) dan [PreTrainedTokenizer.__call__()](/docs/transformers/v5.23.0/id/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__) untuk detailnya. [Apa itu input IDs?](../glossary#input-ids)

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 (`processor_class` menggunakan `image_processor_class` untuk memproses gambar).

attention_mask (`torch.Tensor` dengan bentuk `(batch_size, sequence_length)`, *opsional*) : Mask untuk menghindari pelaksanaan attention pada indeks token padding. Nilai mask dipilih dalam `[0, 1]`:  - 1 untuk token yang **tidak di-mask**, - 0 untuk token yang **di-mask**.  [Apa itu attention masks?](../glossary#attention-mask)

**Mengembalikan:** `ColPaliForRetrievalOutput` atau `tuple(torch.Tensor)`

Sebuah `ColPaliForRetrievalOutput` atau tuple dari `torch.Tensor` (jika `return_dict=False` dilewatkan atau ketika `config.return_dict=False`) yang terdiri dari berbagai elemen tergantung pada konfigurasi (`None`) dan input.

Metode forward [ColPaliForRetrieval](/docs/transformers/v5.23.0/id/model_doc/colpali#transformers.ColPaliForRetrieval) 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.
- **past_key_values** (`Cache`, *opsional*, dikembalikan saat `use_cache=True` dilewatkan atau saat `config.use_cache=True`) -- Ini adalah instance [Cache](/docs/transformers/v5.23.0/id/internal/generation_utils#transformers.Cache). Untuk detail lebih lanjut, lihat [panduan kv cache](https://huggingface.co/docs/transformers/en/kv_cache) kami.

  Berisi hidden-states yang telah dihitung sebelumnya (key dan values di blok self-attention) yang dapat digunakan (lihat input `past_key_values`) untuk mempercepat decoding berurutan.
- **hidden_states** (`tuple[torch.Tensor]`, *opsional*, dikembalikan ketika `output_hidden_states=True` dilewatkan atau ketika `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.
- **attentions** (`tuple[torch.Tensor]`, *opsional*, dikembalikan ketika `output_attentions=True` dilewatkan atau ketika `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 self-attention.
- **image_hidden_states** (`torch.Tensor`, *opsional*) -- Sebuah `torch.Tensor` berukuran `(batch_size, num_images, sequence_length, hidden_size)`. image_hidden_states dari model yang dihasilkan oleh vision encoder setelah memproyeksikan last hidden state.