Transformers documentation

ColQwen2

Transformers

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v5.22.1).

Join the Hugging Face community

and get access to the augmented documentation experience

Collaborate on models, datasets and Spaces

Faster examples with accelerated inference

Switch between documentation themes

to get started

이 모델은 2024-06-27에 HF papers에 게시되었으며, 2025-06-02에 Hugging Face Transformers에 기여되었습니다.

ColQwen2

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

이 모델은 @tonywu71(ILLUIN Technology)과 @yonigozlan(HuggingFace)이 기여했습니다.

Vidore의 Hf-native ColVision Models 컬렉션에서 모든 ColPali 원본 체크포인트를 찾을 수 있습니다.

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

이미지 검색

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

아래 예시에서는 bitsandbytes를 사용하여 가중치를 int4로 양자화합니다.

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을 백본으로 사용합니다.

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

< source >

매개변수

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와 유사한 설정이 생성됩니다.

Configuration 객체는 PreTrainedConfig를 상속하며 모델 출력을 제어하는 데 사용할 수 있습니다. 자세한 내용은 PreTrainedConfig의 문서를 참고하세요.

예:

from transformers.models.colqwen2 import ColQwen2Config, ColQwen2ForRetrieval

config = ColQwen2Config()
model = ColQwen2ForRetrieval(config)

ColQwen2Processor

클래스 transformers.ColQwen2Processor

< source >

( image_processor = Nonetokenizer = Nonechat_template = Nonevisual_prompt_prefix: str | None = Nonequery_prefix: str | None = None**kwargs )

매개변수

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는 Qwen2VLImageProcessor와 Qwen2Tokenizer의 모든 기능을 제공합니다. 자세한 내용은 ~Qwen2VLImageProcessor와 ~Qwen2Tokenizer를 참고하세요.

call

< source >

( images: typing.Union[ForwardRef('PIL.Image.Image'), numpy.ndarray, ForwardRef('torch.Tensor'), list['PIL.Image.Image'], list[numpy.ndarray], list['torch.Tensor'], NoneType] = Nonetext: str | list[str] | list[list[str]] = None**kwargs: *<class 'transformers.models.colqwen2.processing_colqwen2.ColQwen2ProcessorKwargs'> ) → BatchFeature

매개변수

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를 설정하세요.
return_tensors (str 또는 TensorType, 선택 사항) — 설정된 경우, 특정 프레임워크의 텐서를 반환합니다. 허용되는 값은 다음과 같습니다:
- 'pt': PyTorch torch.Tensor 객체를 반환합니다.
- 'np': NumPy np.ndarray 객체를 반환합니다.
**kwargs (ProcessingKwargs, 선택) — 각 모달리티(텍스트, 이미지, 비디오, 오디오)에 대한 추가 처리 옵션입니다. 모델별 매개변수는 위에 나열되어 있으며, 지원되는 인수의 전체 목록은 TypedDict 클래스를 참조하세요.

반환값

BatchFeature

다음 필드를 가진 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

class transformers.ColQwen2ForRetrieval

< source >

( config: ColQwen2Config )

매개변수

config (ColQwen2Config) — 모델의 모든 매개변수를 포함하는 모델 구성 클래스입니다. 구성 파일로 초기화하는 것은 모델과 관련된 가중치를 로드하지 않으며, 구성 정보만 로드합니다. 모델 가중치를 로드하려면 from_pretrained() 메서드를 확인하세요.

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

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

ColQwen2는 ColPali와 함께 다음 논문에서 소개된 ColVision 모델 계열의 일부입니다: ColPali: Efficient Document Retrieval with Vision Language Models.

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

이 모델은 또한 PyTorch torch.nn.Module의 하위 클래스입니다. 일반적인 PyTorch Module처럼 사용하며, 일반적인 사용법 및 동작과 관련된 모든 사항은 PyTorch 문서를 참조하세요.

forward

< source >

( input_ids: typing.Optional[torch.LongTensor] = Noneattention_mask: typing.Optional[torch.Tensor] = Noneposition_ids: typing.Optional[torch.LongTensor] = Nonepast_key_values: transformers.cache_utils.Cache | None = Nonelabels: typing.Optional[torch.LongTensor] = Noneinputs_embeds: typing.Optional[torch.Tensor] = Noneuse_cache: bool | None = Noneoutput_attentions: bool | None = Noneoutput_hidden_states: bool | None = Nonereturn_dict: bool | None = Nonepixel_values: typing.Optional[torch.Tensor] = Noneimage_grid_thw: typing.Optional[torch.LongTensor] = None**kwargs ) → ColQwen2ForRetrievalOutput or tuple(torch.Tensor)

매개변수

input_ids (torch.LongTensor 형상이 (batch_size, sequence_length), 선택 사항) — 어휘(input vocabulary)에서 입력 시퀀스 토큰의 인덱스입니다. 기본적으로 패딩은 무시됩니다.
AutoTokenizer를 사용하여 인덱스를 얻을 수 있습니다. 자세한 내용은 PreTrainedTokenizer.encode() 및 PreTrainedTokenizer.call()를 참조하세요.

입력 ID란 무엇인가요?
attention_mask (torch.Tensor 형상이 (batch_size, sequence_length), 선택 사항) — 패딩 토큰 인덱스에 대한 attention을 수행하지 않도록 방지하는 마스크. [0, 1]에서 선택된 마스크 값: 마스크되지 않은 토큰은 1, 마스크된 토큰은 0. attention mask란 무엇인가요? [0, 1]:
- 마스크되지 않은 토큰에 대해 1
- 마스크된 토큰에 대해 0
어텐션 마스크란 무엇인가요?
position_ids (torch.LongTensor 의 shape (batch_size, sequence_length), , 선택 사항) — 위치 임베딩에서 각 입력 시퀀스 토큰의 위치 인덱스. 범위 [0, config.n_positions - 1].
포지션 ID란 무엇인가요?
past_key_values (~cache_utils.Cache, 선택 사항) — 순차적 디코딩을 가속화할 수 있는 사전 계산된 hidden-states(self-attention 블록과 cross-attention 블록의 key 및 value). 일반적으로 이는 past_key_values 디코딩의 이전 단계에서 모델이 반환한 use_cache=True 또는 config.use_cache=True.
입력으로 Cache 인스턴스만 허용되며, kv cache 가이드를 참고하세요. past_key_values가 전달되지 않으면 기본적으로 DynamicCache가 초기화됩니다.

모델은 입력으로 제공된 것과 동일한 캐시 형식을 출력합니다.

past_key_values를 사용하는 경우, 이 모델에 과거 키 값 상태가 제공되지 않은 input_ids만 입력해야 하며, 이때의 shape은 (batch_size, unprocessed_length)입니다. shape이 (batch_size, sequence_length)인 전체 input_ids를 입력하지 않습니다.
labels (torch.LongTensor, shape (batch_size, sequence_length), 선택 사항) — 마스크 언어 모델링 손실을 계산하는 데 사용되는 라벨입니다. 인덱스는 [0, ..., config.vocab_size] 범위 내의 값이거나 -100이어야 합니다(input_ids docstring 참조). 인덱스가 -100으로 설정된 토큰은 무시(마스크)되며, 손실은 [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, 선택 사항) — 모든 attention 레이어의 attentions 텐서를 반환할지 여부. 자세한 내용은 반환 텐서 섹션의 attentions 항목을 참조하세요.
output_hidden_states (bool, 선택 사항) — 모든 레이어의 hidden states를 반환할지 여부입니다. 자세한 내용은 반환되는 텐서 중 hidden_states 항목을 참고하세요.
return_dict (bool, 선택) — 일반 튜플 대신 ModelOutput를 반환할지 여부.
pixel_values (torch.Tensor, shape (batch_size, num_channels, image_size, image_size), 선택 사항) — 입력 이미지에 해당하는 텐서입니다. 픽셀 값은 Qwen2VLImageProcessor를 사용하여 얻을 수 있습니다. 자세한 내용은 Qwen2VLImageProcessor.call()를 참조하세요 (ColQwen2Processor는 이미지 처리에 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)과 입력에 따라 다양한 요소를 포함합니다.

ColQwen2ForRetrieval의 forward 메서드는 __call__ 특수 메서드를 오버라이드합니다.

이 함수 내에서 forward pass의 레시피를 정의해야 하지만, 이후에는 이 함수 대신 Module 인스턴스를 호출해야 합니다. 전자는 전처리 및 후처리 단계를 실행하는 것을 처리하는 반면, 후자는 이를 조용히 무시하기 때문입니다.

loss (torch.Tensor, shape (1,), 선택 사항, labels이 제공될 때 반환됨) — 언어 모델링 손실(다음 토큰 예측용).
임베딩 (torch.Tensor, shape (batch_size, sequence_length, hidden_size)) — 모델의 임베딩입니다.
past_key_values (Cache, 선택 사항, use_cache=True가 전달되었거나 config.use_cache=True인 경우 반환됨) — Cache 인스턴스입니다. 자세한 내용은 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 가중치.

예:

Update on GitHub

←ColPali Cosmos3 Edge→