Hugging Face's logo

Transformers documentation

ColQwen2

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

Model ini dipublikasikan di HF papers pada 2024-06-27 dan disumbangkan ke Hugging Face Transformers pada 2025-06-02.

ColQwen2

ColQwen2 adalah varian dari model ColPali yang dirancang untuk mengambil dokumen dengan menganalisis fitur visualnya. Berbeda dengan sistem tradisional yang sangat bergantung pada ekstraksi teks dan OCR, ColQwen2 memperlakukan setiap halaman sebagai gambar. Model ini menggunakan backbone Qwen2-VL untuk menangkap tidak hanya teks, tetapi juga tata letak, tabel, grafik, dan elemen visual lainnya guna membuat embedding multi-vektor yang detail, yang dapat digunakan untuk pengambilan dengan menghitung skor kemiripan interaksi akhir pairwise. Hal ini menawarkan pemahaman yang lebih komprehensif tentang dokumen dan memungkinkan pengambilan yang lebih efisien dan akurat.

Model ini disumbangkan oleh @tonywu71 (ILLUIN Technology) dan @yonigozlan (HuggingFace).

Anda dapat menemukan semua checkpoint ColPali asli di bawah koleksi Hf-native ColVision Models Vidore.

Klik pada model ColQwen2 di bilah sisi kanan untuk melihat lebih banyak contoh cara menggunakan ColQwen2 untuk pengambilan gambar.

retrieval gambar
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)

Jika Anda mengalami masalah saat memuat gambar dengan PIL, Anda dapat menggunakan kode berikut untuk membuat gambar dummy:

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

Quantization mengurangi beban memori model besar dengan merepresentasikan bobot dalam presisi yang lebih rendah. Lihat ringkasan Quantization untuk backend quantization lain yang tersedia.

Contoh di bawah menggunakan bitsandbytes untuk mengkuantisasi bobot menjadi 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)

Anda juga dapat menggunakan checkpoint untuk ColQwen2.5 yang kompatibel dengan arsitektur ColQwen2. Versi model ini menggunakan Qwen2_5_VL sebagai backbone.

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)

Catatan

  • score_retrieval() mengembalikan tensor 2D di mana dimensi pertama adalah jumlah query dan dimensi kedua adalah jumlah gambar. Skor yang lebih tinggi menunjukkan kemiripan yang lebih besar antara query dan gambar.
  • Berbeda dengan ColPali, ColQwen2 mendukung resolusi dan rasio aspek gambar yang bebas, yang berarti gambar tidak di-resize menjadi persegi berukuran tetap. Hal ini mempertahankan lebih banyak sinyal input asli.
  • Gambar input yang lebih besar menghasilkan embedding multi-vektor yang lebih panjang, memungkinkan pengguna untuk menyesuaikan resolusi gambar guna menyeimbangkan kinerja dan penggunaan memori.

ColQwen2Config

kelas transformers.ColQwen2Config

< >

( 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 = 128initializer_range: float = 0.02 )

Parameter

  • vlm_config (Union[dict, ~configuration_utils.PreTrainedConfig], opsional) — Objek config atau dictionary dari backbone vision-language.
  • embedding_dim (int, opsional, default 128) — Dimensi dari embedding dan hidden states.
  • initializer_range (float, opsional, defaultnya 0.02) — Standar deviasi dari truncated_normal_initializer untuk menginisialisasi semua matriks bobot.

Ini adalah kelas konfigurasi untuk menyimpan konfigurasi dari Colqwen2Model. Kelas ini digunakan untuk membuat instance model Colqwen2 berdasarkan argumen yang ditentukan, yang mendefinisikan arsitektur model. Membuat instance konfigurasi dengan nilai default akan menghasilkan konfigurasi yang serupa dengan konfigurasi dari vidore/colqwen2-v1.0-hf

Objek konfigurasi mewarisi dari PreTrainedConfig dan dapat digunakan untuk mengontrol output model. Baca dokumentasi dari PreTrainedConfig untuk informasi lebih lanjut.

Contoh:

from transformers.models.colqwen2 import ColQwen2Config, ColQwen2ForRetrieval

config = ColQwen2Config()
model = ColQwen2ForRetrieval(config)

ColQwen2Processor

kelas transformers.ColQwen2Processor

< >

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

Parameter

  • image_processor (Qwen2VLImageProcessor) — Prosesor gambar adalah input yang wajib.
  • tokenizer (Qwen2Tokenizer) — Tokenizer adalah input yang wajib.
  • chat_template (str) — Template Jinja untuk mengubah daftar pesan dalam chat menjadi string yang dapat ditokenisasi.
  • visual_prompt_prefix (str, opsional, defaultnya "<|im_start|>user\n<|vision_start|><|image_pad|><|vision_end|>Describe the image.<|im_end|><|endoftext|>") — String yang ditokenisasi dan ditambahkan di depan token gambar.
  • query_prefix (str, opsional, defaultnya "Query -- "): Awalan yang akan digunakan untuk query.

Membangun ColQwen2Processor yang membungkus image processor dan tokenizer menjadi satu processor.

ColQwen2Processor menyediakan semua fungsionalitas dari Qwen2VLImageProcessor dan Qwen2Tokenizer. Lihat ~Qwen2VLImageProcessor dan ~Qwen2Tokenizer untuk informasi lebih lanjut.

__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.colqwen2.processing_colqwen2.ColQwen2ProcessorKwargs'> ) → BatchFeature

Parameter

  • images (Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]], opsional) — Gambar yang akan dipreprocess. Mengharapkan satu gambar atau batch gambar dengan nilai piksel berkisar dari 0 hingga 255. Jika mengirimkan gambar dengan nilai piksel antara 0 dan 1, atur do_rescale=False.
  • text (Union[str, list[str], list[list[str]]], opsional) — Sequens atau batch dari sequens yang akan dienkod. Setiap sequens dapat berupa string atau daftar string (string yang sudah dipretokenisasi). Jika Anda memasukkan input yang sudah dipretokenisasi, atur is_split_into_words=True untuk menghindari ambiguitas dengan input yang di-batch.
  • return_tensors (str atau TensorType, opsional) — Jika diset, akan mengembalikan tensor dari framework tertentu. Nilai yang dapat diterima adalah:
    • 'pt': Mengembalikan objek PyTorch torch.Tensor.
    • 'np': Mengembalikan objek NumPy np.ndarray.
  • **kwargs (ProcessingKwargs, opsional) — Opsi pemrosesan tambahan untuk setiap modalitas (teks, gambar, video, audio). Parameter spesifik model tercantum di atas; lihat kelas TypedDict untuk daftar lengkap argumen yang didukung.

Mengembalikan

BatchFeature

BatchFeature dengan bidang berikut:

  • input_ids — Daftar token id yang akan diberikan ke model. Dikembalikan ketika text bukan None. Jika suffix disediakan, input_ids juga akan berisi input id dari suffix.
  • attention_mask — Daftar indeks yang menentukan token mana yang harus diperhatikan oleh model (ketika return_attention_mask=True atau jika “attention_mask” ada di self.model_input_names dan jika text bukan None).
  • pixel_values — Nilai piksel yang akan diberikan ke model. Dikembalikan ketika images bukan None.
  • labels — Label yang kompatibel dengan pelatihan jika suffix bukan None

ColQwen2ForRetrieval

kelas transformers.ColQwen2ForRetrieval

< >

( config: ColQwen2Config )

Parameter

  • config (ColQwen2Config) — Kelas konfigurasi model dengan semua parameter model. Inisialisasi dengan file konfigurasi tidak memuat bobot yang terkait dengan model, hanya konfigurasinya. Lihat metode from_pretrained() untuk memuat bobot model.

Mengikuti pendekatan ColPali, ColQwen2 memanfaatkan VLM untuk membangun embedding multi-vektor yang efisien langsung dari gambar dokumen (“screenshot”) untuk pengambilan dokumen. Model ini dilatih untuk memaksimalkan kemiripan antara embedding dokumen ini dan embedding kueri yang sesuai, menggunakan metode interaksi akhir yang diperkenalkan dalam ColBERT.

Menggunakan ColQwen2 menghilangkan kebutuhan akan pipeline pengenalan tata letak dan OCR yang berpotensi kompleks dan rapuh, dengan satu model yang dapat mempertimbangkan konten teks dan visual (tata letak, grafik, …) dari sebuah dokumen.

ColQwen2 merupakan bagian dari keluarga model ColVision, yang diperkenalkan bersama ColPali dalam paper berikut: ColPali: Efficient Document Retrieval with Vision Language Models.

Model ini mewarisi dari PreTrainedModel. Periksa dokumentasi kelas induk untuk metode generik yang diimplementasikan oleh pustaka untuk semua model (seperti mengunduh atau menyimpan, mengubah ukuran embedding input, memangkas kepala, dll.)

Model ini juga merupakan subclass dari torch.nn.Module PyTorch. Gunakan sebagai PyTorch Module biasa dan merujuk ke dokumentasi PyTorch untuk semua hal yang berkaitan dengan penggunaan dan perilaku umum.

forward

< >

( 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.FloatTensor] = 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.FloatTensor)

Parameter

  • input_ids (torch.LongTensor dengan bentuk (batch_size, sequence_length), opsional) — Indeks token dari urutan input dalam kosakata. Padding akan diabaikan secara default.

    Indeks dapat diperoleh menggunakan AutoTokenizer. Lihat PreTrainedTokenizer.encode() dan PreTrainedTokenizer.call() untuk detailnya.

    Apa itu input ID?

  • attention_mask (torch.Tensor dengan bentuk (batch_size, sequence_length), opsional) — Mask untuk menghindari eksekusi attention pada indeks token padding. Nilai mask dipilih dari [0, 1]:
    • 1 untuk token yang tidak dimasker,
    • 0 untuk token yang dimasker.

    Apa itu attention mask?

  • position_ids (torch.LongTensor dengan bentuk (batch_size, sequence_length), opsional) — Indeks posisi token dari setiap urutan input dalam position embeddings. Dipilih dalam rentang [0, config.n_positions - 1].

    Apa itu ID posisi?

  • past_key_values (~cache_utils.Cache, opsional) — Hidden-states yang sudah dihitung sebelumnya (key dan values di blok self-attention dan di blok cross-attention) yang dapat digunakan untuk mempercepat decoding berurutan. Ini biasanya terdiri dari past_key_values yang dikembalikan oleh model pada tahap decoding sebelumnya, ketika use_cache=True atau config.use_cache=True.

    Hanya instance Cache yang diizinkan sebagai input, lihat panduan kv cache kami. Jika tidak ada past_key_values yang diteruskan, DynamicCache akan diinisialisasi secara default.

    Model akan menghasilkan format cache yang sama dengan yang diberikan sebagai input.

    Jika past_key_values digunakan, pengguna diharapkan hanya memasukkan input_ids yang belum diproses (yang tidak memiliki state past key value yang diberikan ke model ini) dengan bentuk (batch_size, unprocessed_length) alih-alih semua input_ids dengan bentuk (batch_size, sequence_length).

  • labels (torch.LongTensor dengan bentuk (batch_size, sequence_length), opsional) — Label untuk menghitung kerugian pemodelan bahasa yang disamarkan (masked language modeling). Indeks harus berada dalam [0, ..., config.vocab_size] atau -100 (lihat docstring input_ids). Token dengan indeks yang disetel ke -100 diabaikan (disamarkan), kerugian hanya dihitung untuk token dengan label dalam [0, ..., config.vocab_size].
  • inputs_embeds (torch.FloatTensor dengan bentuk (batch_size, sequence_length, hidden_size), opsional) — Secara opsional, alih-alih meneruskan input_ids, Anda dapat memilih untuk langsung meneruskan representasi tertanam. Hal ini berguna jika Anda ingin memiliki kendali lebih atas cara mengonversi indeks input_ids menjadi vektor terkait, dibandingkan dengan matriks pencarian penanaman internal model.
  • use_cache (bool, opsional) — Jika diset ke True, state kunci-nilai past_key_values akan dikembalikan dan dapat digunakan untuk mempercepat decoding (lihat past_key_values).
  • output_attentions (bool, opsional) — Apakah akan mengembalikan tensor attentions dari semua lapisan attention. Lihat attentions di bawah tensor yang dikembalikan untuk detail lebih lanjut.
  • output_hidden_states (bool, opsional) — Apakah akan mengembalikan hidden states dari semua lapisan. Lihat hidden_states di bawah tensor yang dikembalikan untuk detail lebih lanjut.
  • return_dict (bool, opsional) — Apakah akan mengembalikan ModelOutput alih-alih tuple biasa.
  • pixel_values (torch.Tensor dengan bentuk (batch_size, num_channels, image_size, image_size), opsional) — Tensor yang sesuai dengan gambar input. Nilai piksel dapat diperoleh menggunakan Qwen2VLImageProcessor. Lihat Qwen2VLImageProcessor.call() untuk detailnya (ColQwen2Processor menggunakan Qwen2VLImageProcessor untuk memproses gambar).
  • image_grid_thw (torch.LongTensor dengan bentuk (num_images, 3), opsional) — Dimensi temporal, tinggi, dan lebar dari bentuk fitur setiap gambar dalam LLM.

Mengembalikan

ColQwen2ForRetrievalOutput atau tuple(torch.FloatTensor)

ColQwen2ForRetrievalOutput atau tuple dari torch.FloatTensor (jika return_dict=False diteruskan atau ketika config.return_dict=False) yang terdiri dari berbagai elemen tergantung pada konfigurasi (ColQwen2Config) dan input.

Metode forward dari ColQwen2ForRetrieval menimpa metode khusus __call__.

Meskipun resep untuk forward pass perlu didefinisikan di dalam fungsi ini, sebaiknya panggil instance Module setelahnya alih-alih fungsi ini, karena yang pertama menangani langkah-langkah pra-pemrosesan dan pasca-pemrosesan, sedangkan yang kedua mengabaikannya secara diam-diam.

  • loss (torch.FloatTensor dengan bentuk (1,), opsional, dikembalikan saat labels disediakan) — Loss pemodelan bahasa (untuk prediksi token berikutnya).

  • embeddings (torch.FloatTensor dengan bentuk (batch_size, sequence_length, hidden_size)) — Embeddings dari model.

  • past_key_values (Cache, opsional, dikembalikan saat use_cache=True dilewatkan atau saat config.use_cache=True) — Ini adalah instance Cache. Untuk detail lebih lanjut, lihat panduan kv cache kami.

    Berisi hidden-states yang telah dihitung sebelumnya (key dan values di blok self-attention) yang dapat digunakan (lihat input past_key_values) untuk mempercepat decoding berurutan.

  • hidden_states (tuple[torch.FloatTensor], opsional, dikembalikan saat output_hidden_states=True dilewatkan atau saat config.output_hidden_states=True) — Tuple dari torch.FloatTensor (satu untuk output dari embeddings, jika model memiliki lapisan embedding, + satu untuk output dari setiap lapisan) dengan bentuk (batch_size, sequence_length, hidden_size).

    Hidden-states model pada output setiap layer ditambah output embedding awal yang opsional.

  • attentions (tuple[torch.FloatTensor], opsional, dikembalikan saat output_attentions=True dilewatkan atau saat config.output_attentions=True) — Tuple dari torch.FloatTensor (satu untuk setiap layer) dengan bentuk (batch_size, num_heads, sequence_length, sequence_length).

    Bobot perhatian setelah softmax perhatian, digunakan untuk menghitung rata-rata berbobot di kepala perhatian diri (self-attention).

Contoh:

Update on GitHub

←ColPali Cosmos3 Edge→