# ColPali

[ColPali](https://huggingface.co/papers/2407.01449) là một mô hình được thiết kế để truy xuất tài liệu bằng cách phân tích các đặc điểm trực quan của chúng. Khác với các hệ thống truyền thống phụ thuộc nhiều vào việc trích xuất văn bản và OCR, ColPali xem mỗi trang như một hình ảnh. Nó sử dụng [Paligemma-3B](./paligemma) để nắm bắt không chỉ văn bản mà còn bố cục, bảng biểu, biểu đồ và các yếu tố trực quan khác để tạo ra các embedding đa vector chi tiết, có thể được sử dụng cho việc truy xuất bằng cách tính toán các điểm tương đồng tương tác muộn theo từng cặp. Điều này mang lại sự hiểu biết toàn diện hơn về tài liệu và cho phép truy xuất hiệu quả và chính xác hơn.

Mô hình này được đóng góp bởi [@tonywu71](https://huggingface.co/tonywu71) (ILLUIN Technology) và [@yonigozlan](https://huggingface.co/yonigozlan) (HuggingFace).

Bạn có thể tìm thấy tất cả các checkpoint ColPali gốc trong bộ sưu tập [Hf-native ColVision Models](https://huggingface.co/collections/vidore/hf-native-colvision-models-6755d68fc60a8553acaa96f7) của Vidore.

> [!TIP]
> Nhấp vào các mô hình ColPali ở thanh bên phải để xem thêm các ví dụ về cách sử dụng ColPali cho việc truy xuất hình ảnh.

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

Nếu bạn gặp sự cố khi tải ảnh bằng PIL, bạn có thể sử dụng đoạn mã sau để tạo ảnh giả lập:

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

Quantization giảm gánh nặng bộ nhớ của các mô hình lớn bằng cách biểu diễn trọng số ở độ chính xác thấp hơn. Tham khảo tổng quan về [Quantization](../quantization/overview) để biết thêm các backend quantization khả dụng.

Ví dụ bên dưới sử dụng [bitsandbytes](../quantization/bitsandbytes) để lượng tử hóa trọng số xuống 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)
```

## Ghi chú

- `score_retrieval()` trả về một tensor 2D trong đó chiều đầu tiên là số lượng truy vấn và chiều thứ hai là số lượng hình ảnh. Điểm càng cao cho thấy mức độ tương đồng giữa truy vấn và hình ảnh càng lớn.

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

[Nguồn](https://github.com/huggingface/transformers/blob/main/src/transformers/models/colpali/configuration_colpali.py#L28)

**Tham số:**

vlm_config (`Union[dict, ~configuration_utils.PreTrainedConfig]`, *tùy chọn*) : Đối tượng config hoặc từ điển của backbone thị giác-ngôn ngữ.

embedding_dim (`int`, *tuỳ chọn*, mặc định là `128`) : Độ chiều của các embedding và trạng thái ẩn.

Đây là lớp cấu hình để lưu trữ cấu hình của một ColpaliModel. Nó được sử dụng để khởi tạo một mô hình Colpali theo các đối số được chỉ định, xác định kiến trúc của mô hình. Khởi tạo một cấu hình với các giá trị mặc định sẽ tạo ra một cấu hình tương tự như cấu hình của [vidore/colpali-v1.2](https://huggingface.co/vidore/colpali-v1.2)

Các đối tượng cấu hình kế thừa từ [PreTrainedConfig](/docs/transformers/main/vi/main_classes/configuration#transformers.PreTrainedConfig) và có thể được sử dụng để kiểm soát đầu ra của mô hình. Đọc tài liệu từ [PreTrainedConfig](/docs/transformers/main/vi/main_classes/configuration#transformers.PreTrainedConfig) để biết thêm thông tin.

Ví dụ:

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

[Nguồn](https://github.com/huggingface/transformers/blob/main/src/transformers/models/colpali/processing_colpali.py#L54)

**Tham số:**

image_processor (`SiglipImageProcessor`) : Bộ xử lý ảnh là một đầu vào bắt buộc.

tokenizer (`tokenizer_class`) : Tokenizer là đầu vào bắt buộc.

chat_template (`str`) : Một mẫu Jinja để chuyển đổi các danh sách tin nhắn trong một cuộc trò chuyện thành chuỗi có thể token hóa.

visual_prompt_prefix (`str`, *tùy chọn*, mặc định là `"Describe the image."`) : Một chuỗi được token hóa và thêm vào trước các token của hình ảnh.

query_prefix (`str`, *tùy chọn*, mặc định là `"Question : "`): Tiền tố được sử dụng cho truy vấn.

Tạo một ColPaliProcessor đóng gói một bộ xử lý ảnh và một tokenizer thành một bộ xử lý duy nhất.

[ColPaliProcessor](/docs/transformers/main/vi/model_doc/colpali#transformers.ColPaliProcessor) cung cấp đầy đủ các chức năng của [SiglipImageProcessor](/docs/transformers/main/vi/model_doc/siglip#transformers.SiglipImageProcessor) và `tokenizer_class`. Xem [~SiglipImageProcessor](/docs/transformers/main/vi/model_doc/siglip#transformers.SiglipImageProcessor) và `~tokenizer_class` để biết thêm thông tin.

#### __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, **kwargs: *<class 'transformers.models.colpali.processing_colpali.ColPaliProcessorKwargs'>)
```

[Nguồn](https://github.com/huggingface/transformers/blob/main/src/transformers/models/colpali/processing_colpali.py#L94)

**Tham số:**

images (`Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]]`, *tùy chọn*) : Ảnh cần tiền xử lý. Kỳ vọng một ảnh đơn hoặc một lô ảnh với giá trị pixel dao động từ 0 đến 255. Nếu truyền vào các ảnh có giá trị pixel nằm trong khoảng từ 0 đến 1, hãy đặt `do_rescale=False`.

text (`Union[str, list[str], list[list[str]]]`, *tùy chọn*) : Chuỗi hoặc lô các chuỗi cần được mã hóa. Mỗi chuỗi có thể là một chuỗi ký tự hoặc một danh sách các chuỗi ký tự (chuỗi đã được tách token trước). Nếu bạn truyền vào đầu vào đã tách token trước, hãy đặt `is_split_into_words=True` để tránh nhầm lẫn với các đầu vào dạng lô.

return_tensors (`str` hoặc [TensorType](/docs/transformers/main/vi/internal/file_utils#transformers.TensorType), *optional*) : Nếu được đặt, sẽ trả về các tensor của một framework cụ thể. Các giá trị chấp nhận được là:  - `'pt'`: Trả về các đối tượng `torch.Tensor` của PyTorch. - `'np'`: Trả về các đối tượng `np.ndarray` của NumPy.

- ****kwargs** ([ProcessingKwargs](/docs/transformers/main/vi/main_classes/processors#transformers.ProcessingKwargs), *optional*) : Các tùy chọn xử lý bổ sung cho từng phương thức (text, images, videos, audio). Các tham số cụ thể của model được liệt kê ở trên; xem lớp TypedDict để biết danh sách đầy đủ các đối số được hỗ trợ.

**Trả về:** [BatchFeature](/docs/transformers/main/vi/main_classes/feature_extractor#transformers.BatchFeature)

Một [BatchFeature](/docs/transformers/main/vi/main_classes/feature_extractor#transformers.BatchFeature) với các trường sau:

- **input_ids** -- Danh sách các token id để đưa vào mô hình. Được trả về khi `text` không phải `None`. Nếu `suffix` được cung cấp, `input_ids` cũng sẽ chứa các input id của suffix.
- **attention_mask** -- Danh sách các chỉ số chỉ định những token nào nên được mô hình chú ý đến (khi `return_attention_mask=True` hoặc nếu *"attention_mask"* nằm trong `self.model_input_names` và nếu `text` không phải là `None`).
- **pixel_values** -- Giá trị pixel để đưa vào mô hình. Được trả về khi `images` không phải `None`.
- **labels** -- Nhãn tương thích với huấn luyện nếu `suffix` không phải None

## ColPaliForRetrieval[[transformers.ColPaliForRetrieval]]

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

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

[Nguồn](https://github.com/huggingface/transformers/blob/main/src/transformers/models/colpali/modeling_colpali.py#L90)

**Tham số:**

config ([ColPaliConfig](/docs/transformers/main/vi/model_doc/colpali#transformers.ColPaliConfig)) : Lớp cấu hình mô hình chứa tất cả các tham số của mô hình. Khởi tạo bằng tệp cấu hình sẽ không tải trọng số liên quan đến mô hình, chỉ tải cấu hình. Xem phương thức [from_pretrained()](/docs/transformers/main/vi/main_classes/model#transformers.PreTrainedModel.from_pretrained) để tải trọng số mô hình.

Kiến trúc ColPali tận dụng VLM để xây dựng các embedding đa vector hiệu quả trực tiếp từ hình ảnh tài liệu (“ảnh chụp màn hình”) phục vụ cho việc truy xuất tài liệu. Mô hình được huấn luyện để tối đa hóa độ tương đồng giữa các embedding tài liệu này và các embedding truy vấn tương ứng, sử dụng phương pháp tương tác muộn (late interaction) được giới thiệu trong ColBERT.

Việc sử dụng ColPali loại bỏ nhu cầu về các pipeline nhận dạng bố cục và OCR có thể phức tạp và kém ổn định, bằng cách sử dụng một mô hình duy nhất có thể xem xét cả nội dung văn bản và trực quan (bố cục, biểu đồ, v.v.) của tài liệu.

ColPali là một phần của họ mô hình ColVision, được giới thiệu lần đầu trong bài báo sau: [*ColPali: Efficient Document Retrieval with Vision Language Models*](https://huggingface.co/papers/2407.01449).

Mô hình này kế thừa từ [PreTrainedModel](/docs/transformers/main/vi/main_classes/model#transformers.PreTrainedModel). Xem tài liệu của lớp cha để biết các phương thức chung mà thư viện triển khai cho tất cả các mô hình của nó (chẳng hạn như tải xuống hoặc lưu trữ, thay đổi kích thước các nhúng đầu vào, cắt tỉa các đầu ra, v.v.)

Mô hình này cũng là một lớp con của [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) trong PyTorch. Hãy sử dụng nó như một Module PyTorch thông thường và tham khảo tài liệu PyTorch cho mọi vấn đề liên quan đến cách sử dụng và hành vi chung.

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

[Nguồn](https://github.com/huggingface/transformers/blob/main/src/transformers/models/colpali/modeling_colpali.py#L104)

**Tham số:**

input_ids (`torch.LongTensor` có hình dạng `(batch_size, sequence_length)`, *tùy chọn*) : Chỉ số của các token trong chuỗi đầu vào theo từ vựng. Mặc định, các token đệm (padding) sẽ bị bỏ qua. Có thể lấy chỉ số bằng cách sử dụng [AutoTokenizer](/docs/transformers/main/vi/model_doc/auto#transformers.AutoTokenizer). Xem [PreTrainedTokenizer.encode()](/docs/transformers/main/vi/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) và [PreTrainedTokenizer.__call__()](/docs/transformers/main/vi/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__) để biết chi tiết. [ID đầu vào là gì?](../glossary#input-ids)

pixel_values (`torch.Tensor` có shape `(batch_size, num_channels, image_size, image_size)`, *tùy chọn*) : Các tensor tương ứng với các ảnh đầu vào. Giá trị pixel có thể được lấy bằng cách sử dụng `image_processor_class`. Xem `image_processor_class.__call__` để biết chi tiết (`processor_class` sử dụng `image_processor_class` để xử lý ảnh).

attention_mask (`torch.Tensor` có hình dạng `(batch_size, sequence_length)`, *tùy chọn*) : Mặt nạ để tránh thực hiện chú ý trên các chỉ số token đệm. Các giá trị mặt nạ được chọn trong `[0, 1]`:  - 1 cho các token **không bị che**, - 0 cho các token **bị che**.  [Mặt nạ chú ý là gì?](../glossary#attention-mask)

**Trả về:** `ColPaliForRetrievalOutput` hoặc `tuple(torch.Tensor)`

Một `ColPaliForRetrievalOutput` hoặc một tuple của `torch.Tensor` (nếu `return_dict=False` được truyền hoặc khi `config.return_dict=False`) bao gồm các phần tử khác nhau tùy thuộc vào cấu hình (`None`) và đầu vào.

Phương thức forward của [ColPaliForRetrieval](/docs/transformers/main/vi/model_doc/colpali#transformers.ColPaliForRetrieval) ghi đè lên phương thức đặc biệt `__call__`.

Mặc dù công thức cho bước truyền tiến cần được định nghĩa bên trong hàm này, bạn nên gọi instance của `Module` sau đó thay vì gọi hàm này, vì instance `Module` sẽ đảm nhận việc thực hiện các bước tiền xử lý và hậu xử lý, trong khi hàm này sẽ bỏ qua chúng một cách im lặng.

- **loss** (`torch.Tensor` có shape `(1,)`, *optional*, được trả về khi `labels` được cung cấp) -- Loss của language modeling (cho next-token prediction).
- **embeddings** (`torch.Tensor` có hình dạng `(batch_size, sequence_length, hidden_size)`) -- Các embeddings của mô hình.
- **past_key_values** (`Cache`, *tùy chọn*, được trả về khi `use_cache=True` được truyền vào hoặc khi `config.use_cache=True`) -- Đây là một instance của [Cache](/docs/transformers/main/vi/internal/generation_utils#transformers.Cache). Để biết thêm chi tiết, hãy xem [hướng dẫn về kv cache](https://huggingface.co/docs/transformers/en/kv_cache) của chúng tôi.

  Chứa các hidden-states đã được tính trước (key và values trong các khối self-attention) có thể được sử dụng (xem đầu vào `past_key_values`) để tăng tốc độ giải mã tuần tự.
- **hidden_states** (`tuple[torch.Tensor]`, *tuỳ chọn*, được trả về khi `output_hidden_states=True` được truyền vào hoặc khi `config.output_hidden_states=True`) -- Bộ tuple các `torch.Tensor` (một cho đầu ra của embeddings, nếu mô hình có lớp embedding, + một cho đầu ra của mỗi lớp) có hình dạng `(batch_size, sequence_length, hidden_size)`.

  Trạng thái ẩn của mô hình tại đầu ra của mỗi lớp cùng với các đầu ra embedding ban đầu tùy chọn.
- **attentions** (`tuple[torch.Tensor]`, *tuỳ chọn*, được trả về khi `output_attentions=True` được truyền vào hoặc khi `config.output_attentions=True`) -- Bộ tuple của `torch.Tensor` (một cho mỗi lớp) có hình dạng `(batch_size, num_heads, sequence_length, sequence_length)`.

  Trọng số chú ý sau softmax của attention, được sử dụng để tính trung bình có trọng số trong các đầu self-attention.
- **image_hidden_states** (`torch.Tensor`, *tùy chọn*) -- Một `torch.Tensor` có kích thước `(batch_size, num_images, sequence_length, hidden_size)`. image_hidden_states của mô hình do bộ mã hóa thị giác tạo ra sau khi chiếu trạng thái ẩn cuối cùng.