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

Mô hình này được công bố trên HF papers vào ngày 2024-06-27 và được đóng góp cho Hugging Face Transformers vào ngày 2024-12-17.

ColPali

ColPali là một mô hình đượ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, ColPali xem mỗi trang như một hình ảnh. Nó sử dụng Paligemma-3B để nắm bắt không chỉ văn bản mà còn bố cục, bảng biểu, biểu đồ và các yếu tố trực quan khác để tạo ra các embedding đa vector chi tiết, có thể được sử dụng cho việc truy xuất bằng cách tính toán các đ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ả và chính xác hơn.

Mô hình này được đóng góp bởi @tonywu71 (ILLUIN Technology) và @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 của Vidore.

Nhấp vào các mô hình ColPali ở thanh bên phải để xem thêm các ví dụ về cách sử dụng ColPali cho việc truy xuất hình ảnh.

tìm kiếm hình ảnh
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)

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:

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 để biết thêm các backend quantization khả dụng.

Ví dụ bên dưới sử dụng bitsandbytes để lượng tử hóa trọng số xuống 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)

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.

ColPaliConfig

lớp 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 )

Tham số

  • vlm_config (Union[dict, ~configuration_utils.PreTrainedConfig], tùy chọn) — Đối tượng cấu hình hoặc từ điển của bộ khung thị giác-ngôn ngữ.
  • embedding_dim (int, tùy chọn, mặc định là 128) — Kích thước của các embedding và trạng thái ẩn.

Đây là lớp cấu hình để lưu trữ cấu hình của một ColpaliModel. Nó được sử dụng để khởi tạo một mô hình Colpali theo các đối số được chỉ định, xác định kiến trúc của mô hình. Việc 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 vidore/colpali-v1.2

Các đối tượng cấu hình kế thừa từ 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 để biết thêm thông tin.

Ví dụ:

from transformers.models.colpali import ColPaliConfig, ColPaliForRetrieval

config = ColPaliConfig()
model = ColPaliForRetrieval(config)

ColPaliProcessor

lớp transformers.ColPaliProcessor

< >

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

Tham số

  • image_processor (SiglipImageProcessor) — 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.
  • visual_prompt_prefix (str, tùy chọn, mặc định là "Describe the image.") — 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à "Question -- "): Một tiền tố được sử dụng cho truy vấn.

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

ColPaliProcessor cung cấp đầy đủ các chức năng của SiglipImageProcessor và tokenizer_class. Xem ~SiglipImageProcessor và ~tokenizer_class để biết thêm thông tin.

__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

Tham số

  • images (Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]], tuỳ chọn) — Hình ảnh cần tiền xử lý. Kỳ vọng một hình ảnh đơn lẻ hoặc một lô hình ảnh có giá trị pixel từ 0 đến 255. Nếu truyền vào các hình ảnh có giá trị pixel 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 dữ liệu đầu vào đã được 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ô.
  • return_tensors (str hoặc TensorType, tùy chọn) — Nếu được đặt, sẽ trả về 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, optional) — Các tùy chọn xử lý bổ sung cho từng modality (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

Một 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

ColPaliForRetrieval

lớp transformers.ColPaliForRetrieval

< >

( config: ColPaliConfig )

Tham số

  • config (ColPaliConfig) — 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() để tải trọng số của mô hình.

Kiến trúc ColPali 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 ColPali loại bỏ nhu cầu về các pipeline nhận dạng bố cục và OCR có thể phức tạp và kém ổn định, bằng một mô hình duy nhất có thể xem xét cả nội dung văn bản và trực quan (bố cục, biểu đồ, v.v.) của tài liệu.

ColPali là một phần của họ mô hình ColVision, được giới thiệu lần đầu trong bài báo sau: ColPali: Efficient Document Retrieval with Vision Language Models.

Mô hình này kế thừa từ 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, v.v.)

Mô hình này cũng là một lớp con của 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

< >

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

Tham số

  • input_ids (torch.LongTensor có 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ừ điển. Mặc định, padding sẽ bị bỏ qua.

    Các chỉ số có thể được lấy bằng cách sử dụng AutoTokenizer. Xem PreTrainedTokenizer.encode() và PreTrainedTokenizer.call() để biết thêm chi tiết.

    ID đầu vào là gì?

  • pixel_values (torch.Tensor có hình dạng (batch_size, num_channels, image_size, image_size), tùy chọn) — Các tensor tương ứng với các hình ả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 (processor_class sử dụng image_processor_class để xử lý hình ả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ì?

Trả về

ColPaliForRetrievalOutput hoặc tuple(torch.Tensor)

Một ColPaliForRetrievalOutput 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 thành phần khác nhau tùy thuộc vào cấu hình (None) và đầu vào.

Phương thức forward của ColPaliForRetrieval 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, người dùng 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ẽ lặng lẽ bỏ qua chúng.

  • loss (torch.Tensor có shape (1,), tùy chọn, đượ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. Để biết thêm chi tiết, hãy xem hướng dẫn về 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) — Tuple của 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) — 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.

  • image_hidden_states (torch.Tensor, tuỳ chọn) — Một torch.Tensor có kích thước (batch_size, num_images, sequence_length, hidden_size). image_hidden_states của mô hình do bộ mã hóa thị giác tạo ra sau khi chiếu trạng thái ẩn cuối cùng.

Update on GitHub

←ColModernVBert ColQwen2→