# ColQwen2

[ColQwen2](https://huggingface.co/papers/2407.01449) là một biến thể của mô hình [ColPali](./colpali), đượ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, ColQwen2 xem mỗi trang như một hình ảnh. Nó sử dụng bộ khung [Qwen2-VL](./qwen2_vl) để nắm bắt không chỉ văn bản mà còn cả bố cục, bảng biểu, biểu đồ và các yếu tố trực quan khác, nhằm tạo ra các embedding đa vector chi tiết có thể dùng cho truy xuất bằng cách tính toán đ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ả, 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 ColQwen2 ở thanh bên phải để xem thêm các ví dụ về cách sử dụng ColQwen2 cho việc truy xuất hình ảnh.

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

from transformers import ColQwen2ForRetrieval, ColQwen2Processor
from transformers.utils.import_utils import is_flash_attn_2_available

# Load the model and the processor
model_name = "vidore/colqwen2-v1.0-hf"

model = ColQwen2ForRetrieval.from_pretrained(
    model_name,
    device_map="auto",  # "cpu", "cuda", "xpu" or "mps" for Apple Silicon
    attn_implementation="flash_attention_2" if is_flash_attn_2_available() else "sdpa",
)
processor = ColQwen2Processor.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, ColQwen2ForRetrieval, ColQwen2Processor

model_name = "vidore/colqwen2-v1.0-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 = ColQwen2ForRetrieval.from_pretrained(
    model_name,
    quantization_config=bnb_config,
    device_map="auto",
).eval()

processor = ColQwen2Processor.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)
```

Bạn cũng có thể sử dụng các checkpoint cho `ColQwen2.5` **tương thích với kiến trúc ColQwen2**. Phiên bản này của mô hình sử dụng [Qwen2_5_VL](./qwen2_5_vl) làm backbone.

```python
from transformers import ColQwen2ForRetrieval, ColQwen2Processor
from transformers.utils.import_utils import is_flash_attn_2_available

model_name = "Sahil-Kabir/colqwen2.5-v0.2-hf" # An existing compatible checkpoint

model = ColQwen2ForRetrieval.from_pretrained(
    model_name,
    device_map="auto",
    attn_implementation="flash_attention_2" if is_flash_attn_2_available() else "sdpa"
)
processor = ColQwen2Processor.from_pretrained(model_name)
```

## 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.
- Khác với ColPali, ColQwen2 hỗ trợ độ phân giải và tỷ lệ khung hình tùy ý cho hình ảnh, điều này có nghĩa là hình ảnh không bị thay đổi kích thước thành các hình vuông có kích thước cố định. Điều này giúp bảo tồn nhiều hơn tín hiệu đầu vào gốc.
- Hình ảnh đầu vào lớn hơn tạo ra các nhúng đa vector dài hơn, cho phép người dùng điều chỉnh độ phân giải hình ảnh để cân bằng giữa hiệu suất và mức sử dụng bộ nhớ.

## ColQwen2Config[[transformers.ColQwen2Config]]

#### transformers.ColQwen2Config[[transformers.ColQwen2Config]]

```python
transformers.ColQwen2Config(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/v5.23.0/src/transformers/models/colqwen2/configuration_colqwen2.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.

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 Colqwen2Model. Nó được sử dụng để khởi tạo một mô hình Colqwen2 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ủa [vidore/colqwen2-v1.0-hf](https://huggingface.co/vidore/colqwen2-v1.0-hf)

Các đối tượng cấu hình kế thừa từ [PreTrainedConfig](/docs/transformers/v5.23.0/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/v5.23.0/vi/main_classes/configuration#transformers.PreTrainedConfig) để biết thêm thông tin.

Ví dụ:

```python
from transformers.models.colqwen2 import ColQwen2Config, ColQwen2ForRetrieval

config = ColQwen2Config()
model = ColQwen2ForRetrieval(config)
```

## ColQwen2Processor[[transformers.ColQwen2Processor]]

#### transformers.ColQwen2Processor[[transformers.ColQwen2Processor]]

```python
transformers.ColQwen2Processor(image_processor = None, tokenizer = None, chat_template = None, visual_prompt_prefix: str | None = None, query_prefix: str | None = None, **kwargs)
```

[Nguồn](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/colqwen2/processing_colqwen2.py#L40)

**Tham số:**

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

tokenizer (`Qwen2Tokenizer`) : 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à `"<|im_start|>user\n<|vision_start|><|image_pad|><|vision_end|>Describe the image.<|im_end|><|endoftext|>"`) : 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à `"Query : "`): Tiền tố được sử dụng cho truy vấn.

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

[ColQwen2Processor](/docs/transformers/v5.23.0/vi/model_doc/colqwen2#transformers.ColQwen2Processor) cung cấp đầy đủ các chức năng của [Qwen2VLImageProcessor](/docs/transformers/v5.23.0/vi/model_doc/qwen2_vl#transformers.Qwen2VLImageProcessor) và [Qwen2Tokenizer](/docs/transformers/v5.23.0/vi/model_doc/qwen2#transformers.Qwen2Tokenizer). Xem [~Qwen2VLImageProcessor](/docs/transformers/v5.23.0/vi/model_doc/qwen2_vl#transformers.Qwen2VLImageProcessor) và [~Qwen2Tokenizer](/docs/transformers/v5.23.0/vi/model_doc/qwen2#transformers.Qwen2Tokenizer) để biết thêm thông tin.

#### __call__[[transformers.ColQwen2Processor.__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'>)
```

[Nguồn](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/colqwen2/processing_colqwen2.py#L73)

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

suffix (`str | list[str] | list[list[str]]`, *tùy chọn*) : Hậu tố được thêm vào tất cả các văn bản đầu vào.

return_mm_token_type_ids (`bool`, *kwargs*) : Có nên trả về các id loại token đa phương thức chỉ định vị trí của các token placeholder đa phương thức hay không.

return_text_replacement_offsets (`bool`, *kwargs*) : Có nên trả về các vị trí ký tự cho mỗi placeholder đa phương thức và phần thay thế của nó hay không.

return_tensors (`str` hoặc [TensorType](/docs/transformers/v5.23.0/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/v5.23.0/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/v5.23.0/vi/main_classes/feature_extractor#transformers.BatchFeature)

Một [BatchFeature](/docs/transformers/v5.23.0/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

## ColQwen2ForRetrieval[[transformers.ColQwen2ForRetrieval]]

#### transformers.ColQwen2ForRetrieval[[transformers.ColQwen2ForRetrieval]]

```python
transformers.ColQwen2ForRetrieval(config: ColQwen2Config)
```

[Nguồn](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/colqwen2/modeling_colqwen2.py#L92)

**Tham số:**

config ([ColQwen2Config](/docs/transformers/v5.23.0/vi/model_doc/colqwen2#transformers.ColQwen2Config)) : 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/v5.23.0/vi/main_classes/model#transformers.PreTrainedModel.from_pretrained) để tải trọng số mô hình.

Theo cách tiếp cận ColPali, ColQwen2 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 ColQwen2 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.

ColQwen2 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/v5.23.0/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.ColQwen2ForRetrieval.forward]]

```python
forward(input_ids: typing.Optional[torch.LongTensor] = None, attention_mask: typing.Optional[torch.Tensor] = None, position_ids: typing.Optional[torch.LongTensor] = None, past_key_values: transformers.cache_utils.Cache | None = None, labels: typing.Optional[torch.LongTensor] = None, inputs_embeds: typing.Optional[torch.Tensor] = None, use_cache: bool | None = None, output_attentions: bool | None = None, output_hidden_states: bool | None = None, return_dict: bool | None = None, pixel_values: typing.Optional[torch.Tensor] = None, image_grid_thw: typing.Optional[torch.LongTensor] = None, **kwargs)
```

[Nguồn](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/colqwen2/modeling_colqwen2.py#L106)

**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/v5.23.0/vi/model_doc/auto#transformers.AutoTokenizer). Xem [PreTrainedTokenizer.encode()](/docs/transformers/v5.23.0/vi/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) và [PreTrainedTokenizer.__call__()](/docs/transformers/v5.23.0/vi/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__) để biết chi tiết. [ID đầu vào là gì?](../glossary#input-ids)

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)

position_ids (`torch.LongTensor` có hình dạng `(batch_size, sequence_length)`, *tùy chọn*) : Chỉ số của vị trí các token trong mỗi chuỗi đầu vào trong các embedding vị trí. Được chọn trong khoảng `[0, config.n_positions - 1]`.  [Position IDs là gì?](../glossary#position-ids)

past_key_values (`~cache_utils.Cache`, *tùy chọn*) : Các hidden-states đã tính trước (key và values trong các khối self-attention và cross-attention) có thể được sử dụng để tăng tốc giải mã tuần tự. Điều này thường bao gồm `past_key_values` do mô hình trả về ở một giai đoạn giải mã trước đó, khi `use_cache=True` hoặc `config.use_cache=True`.  Chỉ cho phép [Cache](/docs/transformers/v5.23.0/vi/internal/generation_utils#transformers.Cache) instance làm đầu vào, xem [hướng dẫn kv cache](https://huggingface.co/docs/transformers/en/kv_cache) của chúng tôi. Nếu không truyền `past_key_values`, [DynamicCache](/docs/transformers/v5.23.0/vi/internal/generation_utils#transformers.DynamicCache) sẽ được khởi tạo theo mặc định.  Mô hình sẽ xuất ra cùng định dạng cache được đưa vào làm đầu vào.  Nếu sử dụng `past_key_values`, người dùng được kỳ vọng chỉ nhập các `input_ids` chưa được xử lý (những phần chưa có trạng thái key value quá khứ được cung cấp cho mô hình này) có shape `(batch_size, unprocessed_length)` thay vì tất cả `input_ids` có shape `(batch_size, sequence_length)`.

labels (`torch.LongTensor` có hình dạng `(batch_size, sequence_length)`, *tùy chọn*) : Nhãn để tính toán tổn thất mô hình hóa ngôn ngữ có mặt nạ. Chỉ số phải nằm trong `[0, ..., config.vocab_size]` hoặc -100 (xem docstring của `input_ids`). Các token có chỉ số được đặt thành `-100` sẽ bị bỏ qua (mặt nạ), tổn thất chỉ được tính cho các token có nhãn nằm trong `[0, ..., config.vocab_size]`.

inputs_embeds (`torch.Tensor` có hình dạng `(batch_size, sequence_length, hidden_size)`, *tùy chọn*) : Tùy chọn, thay vì truyền `input_ids`, bạn có thể chọn cách truyền trực tiếp một biểu diễn nhúng. Điều này hữu ích nếu bạn muốn kiểm soát nhiều hơn cách chuyển đổi các chỉ số `input_ids` thành các vector liên quan so với ma trận tra cứu nhúng nội bộ của mô hình.

use_cache (`bool`, *tùy chọn*) : Nếu được đặt thành `True`, các trạng thái khóa và giá trị `past_key_values` sẽ được trả về và có thể được sử dụng để tăng tốc quá trình giải mã (xem `past_key_values`).

output_attentions (`bool`, *tùy chọn*) : Có trả về các tensor chú ý của tất cả các lớp chú ý hay không. Xem `attentions` trong phần tensor trả về để biết thêm chi tiết.

output_hidden_states (`bool`, *tuỳ chọn*) : Có trả về trạng thái ẩn của tất cả các lớp hay không. Xem `hidden_states` trong phần tensor trả về để biết thêm chi tiết.

return_dict (`bool`, *tùy chọn*) : Có trả về [ModelOutput](/docs/transformers/v5.23.0/vi/main_classes/output#transformers.utils.ModelOutput) thay vì một tuple thông thường hay không.

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 [Qwen2VLImageProcessor](/docs/transformers/v5.23.0/vi/model_doc/qwen2_vl#transformers.Qwen2VLImageProcessor). Xem [Qwen2VLImageProcessor.__call__()](/docs/transformers/v5.23.0/vi/model_doc/molmo2#transformers.Molmo2ImageProcessor.__call__) để biết chi tiết ([ColQwen2Processor](/docs/transformers/v5.23.0/vi/model_doc/colqwen2#transformers.ColQwen2Processor) sử dụng [Qwen2VLImageProcessor](/docs/transformers/v5.23.0/vi/model_doc/qwen2_vl#transformers.Qwen2VLImageProcessor) để xử lý ảnh).

image_grid_thw (`torch.LongTensor` có hình dạng `(num_images, 3)`, *tùy chọn*) : Thời gian, chiều cao và chiều rộng của hình dạng đặc trưng của mỗi hình ảnh trong LLM.

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

Một `ColQwen2ForRetrievalOutput` 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 ([ColQwen2Config](/docs/transformers/v5.23.0/vi/model_doc/colqwen2#transformers.ColQwen2Config)) và đầu vào.

Phương thức forward của [ColQwen2ForRetrieval](/docs/transformers/v5.23.0/vi/model_doc/colqwen2#transformers.ColQwen2ForRetrieval) 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/v5.23.0/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.

Ví dụ:

```python
```

