# ColQwen2

[ColQwen2](https://huggingface.co/papers/2407.01449)는 시각적 특징을 분석하여 문서를 검색하도록 설계된 [ColPali](./colpali) 모델의 변형입니다. 텍스트 추출과 OCR에 크게 의존하는 기존 시스템과 달리, ColQwen2는 각 페이지를 이미지로 취급합니다. [Qwen2-VL](./qwen2_vl) 백본을 사용하여 텍스트뿐만 아니라 레이아웃, 표, 차트 및 기타 시각적 요소까지 포착하여, 쌍별 late interaction 유사도 점수를 계산하여 검색에 사용할 수 있는 상세한 멀티 벡터 임베딩을 생성합니다. 이를 통해 문서에 대한 보다 포괄적인 이해가 가능해지고, 더 효율적이고 정확한 검색이 가능합니다.

이 모델은 [@tonywu71](https://huggingface.co/tonywu71)(ILLUIN Technology)과 [@yonigozlan](https://huggingface.co/yonigozlan)(HuggingFace)이 기여했습니다.

Vidore의 [Hf-native ColVision Models](https://huggingface.co/collections/vidore/hf-native-colvision-models-6755d68fc60a8553acaa96f7) 컬렉션에서 모든 원래 ColPali 체크포인트를 찾을 수 있습니다.

> [!TIP]
> ColQwen2 모델을 우측 사이드바에서 클릭하여 ColQwen2를 이미지 검색에 사용하는 방법에 대한 추가 예제를 확인하세요.

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

PIL로 이미지를 로드하는 데 문제가 있는 경우, 다음 코드를 사용하여 더미 이미지를 생성할 수 있습니다:

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

Quantization은 가중치를 더 낮은 정밀도로 표현하여 대규모 모델의 메모리 부담을 줄입니다. 사용 가능한 다른 양자화 백엔드에 대해서는 [Quantization](../quantization/overview) 개요를 참조하세요.

아래 예시에서는 [bitsandbytes](../quantization/bitsandbytes)를 사용하여 가중치를 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)
```

`ColQwen2.5`의 **ColQwen2 아키텍처와 호환되는** 체크포인트도 사용할 수 있습니다. 이 버전의 모델은 [Qwen2_5_VL](./qwen2_5_vl)을 백본으로 사용합니다.

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

## The input is a single word "Notes".

참고

- `score_retrieval()`은 첫 번째 차원이 쿼리의 수, 두 번째 차원이 이미지의 수인 2D 텐서를 반환합니다. 점수가 높을수록 쿼리와 이미지 간의 유사도가 높음을 의미합니다.
- ColPali와 달리 ColQwen2는 임의의 이미지 해상도와 종횡비를 지원하므로, 이미지를 고정된 크기의 정사각형으로 리사이즈하지 않습니다. 이를 통해 원래 입력 신호의 더 많은 부분이 보존됩니다.
- 더 큰 입력 이미지는 더 긴 다중 벡터 임베딩을 생성하므로, 사용자는 이미지 해상도를 조정하여 성능과 메모리 사용량 사이의 균형을 맞출 수 있습니다.

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

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/colqwen2/configuration_colqwen2.py#L28)

**매개변수:**

vlm_config (`Union[dict, ~configuration_utils.PreTrainedConfig]`, *선택*) : 비전-언어 백본의 config 객체 또는 사전입니다.

embedding_dim (`int`, *선택 사항*, 기본값 `128`) : 임베딩 및 숨겨진 상태의 차원.

initializer_range (`float`, *선택 사항*, 기본값 `0.02`) : 모든 가중치 행렬을 초기화하는 truncated_normal_initializer의 표준 편차입니다.

이것은 Colqwen2Model의 구성을 저장하기 위한 구성 클래스입니다. 지정된 인자에 따라 Colqwen2 모델을 인스턴스화하고 모델 아키텍처를 정의하는 데 사용됩니다. 기본값으로 구성을 인스턴스화하면 [vidore/colqwen2-v1.0-hf](https://huggingface.co/vidore/colqwen2-v1.0-hf)와 유사한 구성이 생성됩니다.

Configuration 객체는 [PreTrainedConfig](/docs/transformers/v5.23.0/ko/main_classes/configuration#transformers.PreTrainedConfig)를 상속하며, 모델 출력을 제어하는 데 사용할 수 있습니다. 자세한 내용은 [PreTrainedConfig](/docs/transformers/v5.23.0/ko/main_classes/configuration#transformers.PreTrainedConfig)의 문서를 참고하세요.

예:

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

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

**매개변수:**

image_processor (`Qwen2VLImageProcessor`) : 이미지 프로세서가 필수 입력입니다.

tokenizer (`Qwen2Tokenizer`) : 토크나이저는 필수 입력값입니다.

chat_template (`str`) : 채팅의 메시지 목록을 토큰화 가능한 문자열로 변환하는 Jinja 템플릿입니다.

visual_prompt_prefix (`str`, *선택 사항*, 기본값은 `"<|im_start|>user\n<|vision_start|><|image_pad|><|vision_end|>Describe the image.<|im_end|><|endoftext|>"`) : 이미지 토큰 앞에 추가되어 토큰화되는 문자열입니다.

query_prefix (`str`, *선택 사항*, 기본값 `"Query : "`): 쿼리에 사용할 접두사.

이미지 프로세서와 토크나이저를 단일 프로세서로 래핑하는 ColQwen2Processor를 생성합니다.

[ColQwen2Processor](/docs/transformers/v5.23.0/ko/model_doc/colqwen2#transformers.ColQwen2Processor)는 [Qwen2VLImageProcessor](/docs/transformers/v5.23.0/ko/model_doc/qwen2_vl#transformers.Qwen2VLImageProcessor)와 [Qwen2Tokenizer](/docs/transformers/v5.23.0/ko/model_doc/qwen2#transformers.Qwen2Tokenizer)의 모든 기능을 제공합니다. 자세한 내용은 [~Qwen2VLImageProcessor](/docs/transformers/v5.23.0/ko/model_doc/qwen2_vl#transformers.Qwen2VLImageProcessor)와 [~Qwen2Tokenizer](/docs/transformers/v5.23.0/ko/model_doc/qwen2#transformers.Qwen2Tokenizer)를 참고하세요.

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

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

**매개변수:**

images (`Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]]`, *선택*) : 전처리할 이미지. 픽셀 값이 0에서 255 범위로 이루어진 단일 이미지 또는 배치 이미지를 기대합니다. 픽셀 값이 0에서 1 범위로 이루어진 이미지를 전달하는 경우 `do_rescale=False`로 설정하세요.

text (`Union[str, list[str], list[list[str]]]`, *선택*) : 인코딩할 시퀀스 또는 시퀀스 배치입니다. 각 시퀀스는 문자열 또는 문자열 목록(사전 토큰화된 문자열)일 수 있습니다. 사전 토큰화된 입력을 전달하는 경우, 배치 입력과의 혼동을 피하기 위해 `is_split_into_words=True`를 설정하세요.

suffix (`str | list[str] | list[list[str]]`, *선택 사항*) : 모든 입력 텍스트에 추가되는 접미사.

return_mm_token_type_ids (`bool`, *kwargs*) : 멀티모달 플레이스홀더 토큰의 위치를 나타내는 멀티모달 토큰 타입 ID를 반환할지 여부.

return_text_replacement_offsets (`bool`, *kwargs*) : 각 멀티모달 플레이스홀더 및 그 대체 문자열의 문자 오프셋을 반환할지 여부.

return_tensors (`str` 또는 [TensorType](/docs/transformers/v5.23.0/ko/internal/file_utils#transformers.TensorType), *optional*) : 설정된 경우, 특정 프레임워크의 텐서를 반환합니다. 허용되는 값은 다음과 같습니다:  - `'pt'`: PyTorch `torch.Tensor` 객체를 반환합니다. - `'np'`: NumPy `np.ndarray` 객체를 반환합니다.

- ****kwargs** ([ProcessingKwargs](/docs/transformers/v5.23.0/ko/main_classes/processors#transformers.ProcessingKwargs), *optional*) : 각 모달리티(텍스트, 이미지, 비디오, 오디오)에 대한 추가 처리 옵션입니다. 모델별 매개변수는 위에 나열되어 있으며, 지원되는 인수의 전체 목록은 TypedDict 클래스를 참조하세요.

**반환값:** [BatchFeature](/docs/transformers/v5.23.0/ko/main_classes/feature_extractor#transformers.BatchFeature)

다음 필드를 가진 [BatchFeature](/docs/transformers/v5.23.0/ko/main_classes/feature_extractor#transformers.BatchFeature):

- **input_ids** -- 모델에 입력할 토큰 ID 목록. `text`가 `None`이 아닐 때 반환됩니다. `suffix`가 제공되면 `input_ids`에는 접미사 입력 ID도 포함됩니다.
- **attention_mask** -- 모델이 어떤 토큰에 주의를 기울여야 하는지 지정하는 인덱스 목록 (`return_attention_mask=True`이거나, `self.model_input_names`에 *"attention_mask"*가 포함되어 있고 `text`가 `None`이 아닌 경우).
- **pixel_values** -- 모델에 입력할 픽셀 값. `images`가 `None`이 아닌 경우 반환됩니다.
- **labels** -- `suffix`가 None이 아닌 경우 학습과 호환되는 레이블

## ColQwen2ForRetrieval[[transformers.ColQwen2ForRetrieval]]

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

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

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

**매개변수:**

config ([ColQwen2Config](/docs/transformers/v5.23.0/ko/model_doc/colqwen2#transformers.ColQwen2Config)) : 모델의 모든 매개변수를 포함하는 모델 구성 클래스입니다. 구성 파일로 초기화하는 것은 모델과 관련된 가중치를 로드하지 않으며, 구성 정보만 로드합니다. 모델 가중치를 로드하려면 [from_pretrained()](/docs/transformers/v5.23.0/ko/main_classes/model#transformers.PreTrainedModel.from_pretrained) 메서드를 확인하세요.

ColPali 접근 방식을 따르는 ColQwen2는 VLM을 활용하여 문서 이미지(“스크린샷”)에서 직접 효율적인 멀티 벡터 임베딩을 생성하여 문서 검색을 수행합니다. 이 모델은 ColBERT에서 도입된 late interaction 방법을 사용하여 이러한 문서 임베딩과 해당 쿼리 임베딩 간의 유사도를 최대화하도록 학습됩니다.

ColQwen2를 사용하면 문서의 텍스트 및 시각적 콘텐츠(레이아웃, 차트 등)를 모두 고려할 수 있는 단일 모델로, 잠재적으로 복잡하고 취약할 수 있는 레이아웃 인식 및 OCR 파이프라인의 필요성을 제거할 수 있습니다.

ColQwen2는 ColPali와 함께 다음 논문에서 소개된 ColVision 모델 계열의 일부입니다: [*ColPali: Efficient Document Retrieval with Vision Language Models*](https://huggingface.co/papers/2407.01449).

이 모델은 [PreTrainedModel](/docs/transformers/v5.23.0/ko/main_classes/model#transformers.PreTrainedModel)에서 상속됩니다. 라이브러리가 모든 모델에 대해 구현하는 일반적 메서드(다운로드 또는 저장, 입력 임베딩 크기 조정, 헤드 프루닝 등)에 대해서는 상위 클래스 문서를 확인하세요.

이 모델은 또한 PyTorch [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module)의 하위 클래스입니다. 일반적인 PyTorch Module처럼 사용하며, 일반적인 사용법과 동작에 관한 모든 사항은 PyTorch 문서를 참조하세요.

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

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

**매개변수:**

input_ids (`torch.LongTensor`, shape `(batch_size, sequence_length)`, *선택 사항*) : 어휘(input sequence tokens)의 인덱스입니다. 기본적으로 패딩은 무시됩니다. [AutoTokenizer](/docs/transformers/v5.23.0/ko/model_doc/auto#transformers.AutoTokenizer)를 사용하여 인덱스를 얻을 수 있습니다. 자세한 내용은 [PreTrainedTokenizer.encode()](/docs/transformers/v5.23.0/ko/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) 및 [PreTrainedTokenizer.__call__()](/docs/transformers/v5.23.0/ko/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__)를 참조하세요. [입력 ID란 무엇인가요?](../glossary#input-ids)

attention_mask (`torch.Tensor`, shape `(batch_size, sequence_length)`, *선택 사항*) : 패딩 토큰 인덱스에 대한 attention을 수행하지 않도록 방지하는 마스크입니다. `[0, 1]`에서 선택된 마스크 값: - **마스크되지 않은** 토큰은 1, - **마스크된** 토큰은 0. [attention 마스크란?](../glossary#attention-mask)

position_ids (`torch.LongTensor`, shape `(batch_size, sequence_length)`, *선택 사항*) : 각 입력 시퀀스의 토큰 위치 인덱스입니다. `[0, config.n_positions - 1]` 범위에서 선택됩니다. [위치 ID란 무엇인가요?](../glossary#position-ids)

past_key_values (`~cache_utils.Cache`, *선택*) : 순차적 디코딩을 가속화할 수 있는 사전 계산된 hidden-states(셀프 어텐션 블록과 크로스 어텐션 블록의 key 및 value)입니다. 일반적으로 `use_cache=True` 또는 `config.use_cache=True`일 때 모델이 디코딩의 이전 단계에서 반환한 `past_key_values`로 구성됩니다. 입력으로 [Cache](/docs/transformers/v5.23.0/ko/internal/generation_utils#transformers.Cache) 인스턴스만 허용되며, [kv cache 가이드](https://huggingface.co/docs/transformers/en/kv_cache)를 참조하세요. `past_key_values`가 전달되지 않으면 기본적으로 [DynamicCache](/docs/transformers/v5.23.0/ko/internal/generation_utils#transformers.DynamicCache)가 초기화됩니다. 모델은 입력으로 제공된 것과 동일한 캐시 형식을 출력합니다. `past_key_values`를 사용하는 경우, 이 모델에 과거 key value 상태가 제공되지 않은 `input_ids`(처리되지 않은 항목)만 `(batch_size, unprocessed_length)` 형식으로 입력해야 하며, `(batch_size, sequence_length)` 형식의 모든 `input_ids`를 입력하지 않습니다.

labels (`torch.LongTensor`, shape `(batch_size, sequence_length)`, *선택 사항*) : masked language modeling loss를 계산하기 위한 라벨. 인덱스는 `[0, ..., config.vocab_size]` 범위 내이거나 -100이어야 합니다(`input_ids` docstring 참조). 인덱스가 `-100`으로 설정된 토큰은 무시(마스크)되며, loss는 `[0, ..., config.vocab_size]` 범위의 라벨을 가진 토큰에 대해서만 계산됩니다.

inputs_embeds (`torch.Tensor`, shape `(batch_size, sequence_length, hidden_size)`, *선택 사항*) : `input_ids`를 전달하는 대신 임베디드 표현을 직접 전달할 수 있습니다. 이는 모델의 내부 임베딩 조회 행렬보다 `input_ids` 인덱스를 관련 벡터로 변환하는 방식에 대해 더 많은 제어가 필요한 경우 유용합니다.

use_cache (`bool`, *선택 사항*) : `True`로 설정하면 `past_key_values` 키 값 상태가 반환되며, 디코딩 속도를 높이는 데 사용할 수 있습니다(`past_key_values` 참조).

output_attentions (`bool`, *선택 사항*) : 모든 어텐션 레이어의 어텐션 텐서를 반환할지 여부. 자세한 내용은 반환 텐서 섹션의 `attentions`를 참조하세요.

output_hidden_states (`bool`, *선택 사항*) : 모든 레이어의 hidden states를 반환할지 여부. 자세한 내용은 반환되는 텐서 중 `hidden_states` 항목을 참조하세요.

return_dict (`bool`, *선택 사항*) : 일반 튜플 대신 [ModelOutput](/docs/transformers/v5.23.0/ko/main_classes/output#transformers.utils.ModelOutput)를 반환할지 여부.

pixel_values (`torch.Tensor`, shape `(batch_size, num_channels, image_size, image_size)`, *선택 사항*) : 입력 이미지에 해당하는 텐서입니다. 픽셀 값은 [Qwen2VLImageProcessor](/docs/transformers/v5.23.0/ko/model_doc/qwen2_vl#transformers.Qwen2VLImageProcessor)를 사용하여 얻을 수 있습니다. 자세한 내용은 [Qwen2VLImageProcessor.__call__()](/docs/transformers/v5.23.0/ko/model_doc/molmo2#transformers.Molmo2ImageProcessor.__call__)를 참조하세요 ([ColQwen2Processor](/docs/transformers/v5.23.0/ko/model_doc/colqwen2#transformers.ColQwen2Processor)는 이미지 처리에 [Qwen2VLImageProcessor](/docs/transformers/v5.23.0/ko/model_doc/qwen2_vl#transformers.Qwen2VLImageProcessor)를 사용합니다).

image_grid_thw (`torch.LongTensor`, shape `(num_images, 3)`, *선택 사항*) : LLM에서 각 이미지의 feature shape의 시간, 높이, 너비입니다.

**반환값:** `ColQwen2ForRetrievalOutput` 또는 `tuple(torch.Tensor)`

`ColQwen2ForRetrievalOutput` 또는 `torch.Tensor`의 튜플(`return_dict=False`가 전달되었거나 `config.return_dict=False`인 경우)로, 구성([ColQwen2Config](/docs/transformers/v5.23.0/ko/model_doc/colqwen2#transformers.ColQwen2Config)) 및 입력에 따라 다양한 요소를 포함합니다.

[ColQwen2ForRetrieval](/docs/transformers/v5.23.0/ko/model_doc/colqwen2#transformers.ColQwen2ForRetrieval)의 forward 메서드는 `__call__` 특수 메서드를 오버라이드합니다.

`Module` 인스턴스는 전처리 및 후처리 단계를 실행하는 것을 처리하지만, 이 함수는 해당 단계를 조용히 무시하므로, 순전파(forward pass) 레시피를 이 함수 내에서 정의해야 하더라도 이후에는 이 함수 대신 `Module` 인스턴스를 호출해야 합니다.

- **loss** (`torch.Tensor`, shape `(1,)`, *선택 사항*, `labels`가 제공될 때 반환됨) -- 언어 모델링 손실(다음 토큰 예측용).
- **embeddings** (shape가 `(batch_size, sequence_length, hidden_size)`인 `torch.Tensor`) -- 모델의 임베딩.
- **past_key_values** (`Cache`, *선택 사항*, `use_cache=True`가 전달되었거나 `config.use_cache=True`인 경우 반환됨) -- [Cache](/docs/transformers/v5.23.0/ko/internal/generation_utils#transformers.Cache) 인스턴스입니다. 자세한 내용은 [kv cache 가이드](https://huggingface.co/docs/transformers/en/kv_cache)를 참조하세요.

  순차적 디코딩을 가속화하는 데 사용할 수 있는 사전 계산된 hidden-states(셀프 어텐션 블록의 key와 value)를 포함합니다(입력 `past_key_values` 참조).
- **hidden_states** (`tuple[torch.Tensor]`, *선택*, `output_hidden_states=True`가 전달되었거나 `config.output_hidden_states=True`인 경우 반환됨) -- `torch.Tensor`의 튜플(모델에 임베딩 레이어가 있는 경우 임베딩 출력용 1개 + 각 레이어의 출력용 1개)로, 모양은 `(batch_size, sequence_length, hidden_size)`입니다.

  각 레이어의 출력에서 모델의 Hidden-states와 선택적 초기 임베딩 출력을 포함합니다.
- **attentions** (`tuple[torch.Tensor]`, *선택*, `output_attentions=True`가 전달되었거나 `config.output_attentions=True`인 경우 반환됨) -- 각 레이어마다 하나씩 포함된 `torch.Tensor`의 튜플로, 모양은 `(batch_size, num_heads, sequence_length, sequence_length)`입니다.

  self-attention 헤드에서 가중 평균을 계산하는 데 사용되는 attention softmax 이후의 attention 가중치입니다.

예:

```python
```

