Hugging Face's logo

Transformers documentation

ColPali

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).
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

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

ColPali

ColPali는 문서의 시각적 특징을 분석하여 문서를 검색하도록 설계된 모델입니다. 텍스트 추출과 OCR에 크게 의존하는 기존 시스템과 달리, ColPali는 각 페이지를 이미지로 취급합니다. Paligemma-3B를 사용하여 텍스트뿐만 아니라 레이아웃, 표, 차트 및 기타 시각적 요소까지 포착하여, pairwise late interaction similarity score를 계산하여 검색에 활용할 수 있는 상세한 multi-vector embedding을 생성합니다. 이를 통해 문서에 대한 보다 포괄적인 이해가 가능해지고, 더 효율적이고 정확한 검색이 가능합니다.

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

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

ColPali를 이미지 검색에 사용하는 방법에 대한 추가 예제는 오른쪽 사이드바의 ColPali 모델에 클릭하여 확인하세요.

이미지 검색
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)

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

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

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

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

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)

The input is a single word "Notes". 참고

  • score_retrieval()은 첫 번째 차원이 쿼리의 수, 두 번째 차원이 이미지의 수인 2D 텐서를 반환합니다. 점수가 높을수록 쿼리와 이미지 간의 유사도가 높음을 의미합니다.

ColPaliConfig

클래스 transformers.ColPaliConfig

< >

( transformers_version: str | None = Nonearchitectures: list[str] | None = Noneoutput_hidden_states: bool | None = Falsereturn_dict: bool | None = Truedtype: str | torch.dtype | None = Nonechunk_size_feed_forward: int = 0is_encoder_decoder: bool = Falseid2label: dict[int, str] | dict[str, str] | None = Nonelabel2id: dict[str, int] | dict[str, str] | None = Noneproblem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = Nonevlm_config: dict | transformers.configuration_utils.PreTrainedConfig | None = Noneembedding_dim: int = 128 )

매개변수

  • vlm_config (Union[dict, ~configuration_utils.PreTrainedConfig], 선택) — 비전-언어 백본의 config 객체 또는 사전입니다.
  • embedding_dim (int, 선택 사항, 기본값 128) — 임베딩 및 숨겨진 상태의 차원입니다.

이것은 ColpaliModel의 구성을 저장하기 위한 구성 클래스입니다. 지정된 인자에 따라 Colpali 모델을 인스턴스화하고 모델 아키텍처를 정의하는 데 사용됩니다. 기본값으로 구성을 인스턴스화하면 vidore/colpali-v1.2와 유사한 구성이 생성됩니다.

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

예:

from transformers.models.colpali import ColPaliConfig, ColPaliForRetrieval

config = ColPaliConfig()
model = ColPaliForRetrieval(config)

ColPaliProcessor

클래스 transformers.ColPaliProcessor

< >

( image_processor = Nonetokenizer = Nonechat_template = Nonevisual_prompt_prefix: str = 'Describe the image.'query_prefix: str = 'Question: ' )

매개변수

  • image_processor (SiglipImageProcessor) — 이미지 프로세서는 필수 입력값입니다.
  • tokenizer (tokenizer_class) — 토크나이저는 필수 입력값입니다.
  • chat_template (str) — 채팅의 메시지 목록을 토큰화 가능한 문자열로 변환하는 Jinja 템플릿입니다.
  • visual_prompt_prefix (str, 선택, 기본값 "Describe the image.") — 이미지 토큰 앞에 붙여지는 문자열로, 토큰화됩니다.
  • query_prefix (str, 선택 사항, 기본값 "Question -- "): 쿼리에 사용할 접두사입니다.

이미지 프로세서와 토크나이저를 단일 프로세서로 감싸는 ColPaliProcessor를 생성합니다.

ColPaliProcessor는 SiglipImageProcessor와 tokenizer_class의 모든 기능을 제공합니다. 자세한 내용은 ~SiglipImageProcessor와 ~tokenizer_class를 참고하세요.

__call__

< >

( 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.colpali.processing_colpali.ColPaliProcessorKwargs'> ) → 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이 아닌 경우 학습과 호환되는 레이블

ColPaliForRetrieval

class transformers.ColPaliForRetrieval

< >

( config: ColPaliConfig )

매개변수

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

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

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

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

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

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

forward

< >

( input_ids: typing.Optional[torch.LongTensor] = Nonepixel_values: typing.Optional[torch.Tensor] = Noneattention_mask: typing.Optional[torch.Tensor] = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → ColPaliForRetrievalOutput or tuple(torch.Tensor)

매개변수

  • input_ids (torch.LongTensor 형상이 (batch_size, sequence_length), 선택 사항) — 어휘(input vocabulary)에서 입력 시퀀스 토큰의 인덱스입니다. 기본적으로 패딩은 무시됩니다.

    AutoTokenizer를 사용하여 인덱스를 얻을 수 있습니다. 자세한 내용은 PreTrainedTokenizer.encode() 및 PreTrainedTokenizer.call()를 참조하세요.

    입력 ID란 무엇인가요?

  • pixel_values (torch.Tensor, shape (batch_size, num_channels, image_size, image_size), 선택 사항) — 입력 이미지에 해당하는 텐서입니다. 픽셀 값은 image_processor_class를 사용하여 얻을 수 있습니다. 자세한 내용은 image_processor_class.__call__를 참조하세요 (processor_class는 이미지 처리에 image_processor_class를 사용합니다).
  • attention_mask (torch.Tensor 형상이 (batch_size, sequence_length), 선택 사항) — 패딩 토큰 인덱스에 대한 attention을 수행하지 않도록 방지하는 마스크. [0, 1]에서 선택된 마스크 값: 마스크되지 않은 토큰은 1, 마스크된 토큰은 0. attention mask란 무엇인가요? [0, 1]:
    • 마스크되지 않은 토큰에 대해 1
    • 마스크된 토큰에 대해 0

    어텐션 마스크란 무엇인가요?

반환값

ColPaliForRetrievalOutput 또는 tuple(torch.Tensor)

ColPaliForRetrievalOutput 또는 torch.Tensor의 튜플(return_dict=False가 전달되었거나 config.return_dict=False인 경우)로, 구성(None)과 입력에 따라 다양한 요소를 포함합니다.

ColPaliForRetrieval의 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 가중치.

  • image_hidden_states (torch.Tensor, 선택 사항) — 크기가 (batch_size, num_images, sequence_length, hidden_size)인 torch.Tensor입니다. 비전 인코더가 마지막 hidden state를 투사한 후 모델이 생성한 image_hidden_states입니다.

Update on GitHub

←ColModernVBert ColQwen2→