# ColModernVBert

## Tổng quan

ColModernVBert là một mô hình để truy xuất tài liệu trực quan hiệu quả. Nó tận dụng [ModernVBert](modernvbert) để xây dựng các embedding đa vector trực tiếp từ hình ảnh tài liệu, theo cách tiếp cận của ColPali.

Mô hình được giới thiệu trong [ModernVBERT: Towards Smaller Visual Document Retrievers](https://huggingface.co/papers/2510.01149).

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

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

**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.

initializer_range (`float`, *optional*, mặc định là `0.02`) : Độ lệch chuẩn của truncated_normal_initializer để khởi tạo tất cả các ma trận trọng số.

Đây là lớp cấu hình để lưu trữ cấu hình của một ColmodernvbertModel. Nó được sử dụng để khởi tạo một mô hình Colmodernvbert 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 [ModernVBERT/colmodernvbert-merged](https://huggingface.co/ModernVBERT/colmodernvbert-merged)

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

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

**Tham số:**

image_processor (`image_processor_class`) : 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.

image_seq_len (`int`, *tuỳ chọn*, mặc định là 64) : Độ dài của chuỗi hình ảnh, tức là số lượng token cho mỗi hình ảnh trong đầu vào.

visual_prompt_prefix (`str`, *tùy chọn*) : 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*) : Tiền tố được sử dụng cho truy vấn.

Tạo một ColModernVBertProcessor, đóng gói một bộ xử lý ảnh và một bộ phân từ thành một bộ xử lý duy nhất.

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

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

[Nguồn](https://github.com/huggingface/transformers/blob/main/src/transformers/models/colmodernvbert/processing_colmodernvbert.py#L319)

**Tham số:**

images (`PIL.Image.Image`, `np.ndarray`, `torch.Tensor`, `list[PIL.Image.Image]`, `list[np.ndarray]`, `list[torch.Tensor]`) : Ảnh hoặc lô ảnh cần được chuẩn bị. Mỗi ảnh có thể là ảnh PIL, mảng NumPy hoặc tensor PyTorch. Trong trường hợp là mảng NumPy/tensor PyTorch, mỗi ảnh nên có dạng (C, H, W), trong đó C là số kênh, H và W là chiều cao và chiều rộng của ảnh.

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.

**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 id token để đưa vào mô hình.
- **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`.

Chuẩn bị một hoặc nhiều hình ảnh cho mô hình. Xử lý xác thực đầu vào, chuyển đổi RGB và thêm `visual_prompt_prefix` vào đầu mỗi hình ảnh. Tùy chọn tính toán nhãn từ `token_type_ids` khi có `suffix` được cung cấp trong `text_kwargs`.

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

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

[Nguồn](https://github.com/huggingface/transformers/blob/main/src/transformers/models/colmodernvbert/processing_colmodernvbert.py#L385)

**Tham số:**

text (`str`, `list[str]`, `list[list[str]]`) : 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 các chuỗi được cung cấp dưới dạng danh sách các chuỗi ký tự (đã tách token trước), bạn phải đặt `is_split_into_words=True` (để loại bỏ sự mơ hồ với một lô các chuỗi).

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.

**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 id token để đưa vào mô hình.
- **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`).

Chuẩn bị một hoặc nhiều truy vấn văn bản cho mô hình. Xử lý xác thực đầu vào, thêm `query_prefix` vào đầu và thêm các token tăng cường truy vấn (được dùng để đệm các embedding truy vấn nhằm cải thiện hiệu suất truy xuất tương tác muộn).

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

[Nguồn](https://github.com/huggingface/transformers/blob/main/src/transformers/models/colmodernvbert/processing_colmodernvbert.py#L442)

**Tham số:**

query_embeddings (`Union[torch.Tensor, list[torch.Tensor]`) : Nhúng truy vấn.

passage_embeddings (`Union[torch.Tensor, list[torch.Tensor]`) : Nhúng câu (passage embeddings).

batch_size (`int`, *tuỳ chọn*, mặc định là 128) : Kích thước lô (batch size) để tính điểm.

output_dtype (`torch.dtype`, *tùy chọn*, mặc định là `torch.float32`) : Kiểu dữ liệu của tensor đầu ra. Nếu là `None`, sẽ sử dụng kiểu dữ liệu của embeddings đầu vào.

output_device (`torch.device` hoặc `str`, *tùy chọn*, mặc định là "cpu") : Thiết bị của tensor đầu ra.

**Trả về:** `torch.Tensor`

Một tensor có hình dạng `(n_queries, n_passages)` chứa các điểm số. Tensor điểm số được lưu trên thiết bị "cpu".

Tính điểm late-interaction/MaxSim (giống ColBERT) cho các embedding truy vấn đa vector (`qs`) và embedding đoạn văn (`ps`) đã cho. Đối với ColQwen2, một đoạn văn là ảnh của một trang tài liệu.

Vì các tensor nhúng là đa vector và do đó có thể có các hình dạng khác nhau, chúng nên được đưa vào dưới dạng: (1) một danh sách các tensor, trong đó tensor thứ i có hình dạng (sequence_length_i, embedding_dim) (2) một tensor duy nhất có hình dạng (n_passages, max_sequence_length, embedding_dim) -> thường được thu được bằng cách đệm (padding) danh sách các tensor.

## ColModernVBertForRetrieval[[transformers.ColModernVBertForRetrieval]]

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

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

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

**Tham số:**

config ([ColModernVBertConfig](/docs/transformers/main/vi/model_doc/colmodernvbert#transformers.ColModernVBertConfig)) : 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.

Theo cách tiếp cận ColPali, ColModernVBert 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 (“screenshots”) 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 ColModernVBert loại bỏ nhu cầu về các pipeline nhận diện 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 lẫn nội dung trực quan (bố cục, biểu đồ, ...) của tài liệu.

ColModernVBert được huấn luyện dựa trên ModernVBert và được giới thiệu trong bài báo sau: [*ModernVBERT: Towards Smaller Visual Document Retrievers*](https://arxiv.org/abs/2510.01149).

ColModernVBert là một phần của họ mô hình ColVision, được giới thiệu cùng với ColPali 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.ColModernVBertForRetrieval.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/colmodernvbert/modeling_colmodernvbert.py#L105)

**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 ([ColModernVBertProcessor](/docs/transformers/main/vi/model_doc/colmodernvbert#transformers.ColModernVBertProcessor) 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ề:** `ColModernVBertForRetrievalOutput` hoặc `tuple(torch.Tensor)`

Một `ColModernVBertForRetrievalOutput` 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 ([ColModernVBertConfig](/docs/transformers/main/vi/model_doc/colmodernvbert#transformers.ColModernVBertConfig)) và đầu vào.

Phương thức forward của [ColModernVBertForRetrieval](/docs/transformers/main/vi/model_doc/colmodernvbert#transformers.ColModernVBertForRetrieval) 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.
- **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.
- **image_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` và `pixel_values` được cung cấp) -- Tuple của `torch.Tensor` (một cho đầu ra của phép chiếu modality hình ảnh + một cho đầu ra của mỗi lớp) có hình dạng `(batch_size, num_channels, image_size, image_size)`. Hidden-states của bộ mã hóa hình ảnh tại đầu ra của mỗi lớp cùng với đầu ra của phép chiếu modality ban đầu.
- **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.

Ví dụ:

```python
```