Hugging Face's logo

Transformers documentation

ColModernVBert

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

نُشر هذا النموذج في أوراق HF في 2025-10-01 وسُهم به في Hugging Face Transformers في 2026-02-23.

ColModernVBert

FlashAttention SDPA

نظرة عامة

ColModernVBert هو نموذج لاسترجاع المستندات المرئية بكفاءة. يستفيد من ModernVBert لبناء تمثيلات متعددة المتجهات مباشرةً من صور المستندات، متبعًا نهج ColPali.

تم تقديم النموذج في ModernVBERT: Towards Smaller Visual Document Retrievers.

Python
import torch
from huggingface_hub import hf_hub_download
from PIL import Image

from transformers import ColModernVBertForRetrieval, ColModernVBertProcessor


processor = ColModernVBertProcessor.from_pretrained("ModernVBERT/colmodernvbert-hf")
model = ColModernVBertForRetrieval.from_pretrained("ModernVBERT/colmodernvbert-hf", device_map="auto")

# Load the test dataset
queries = [
    "A paint on the wall",
    "ColModernVBERT matches the performance of models nearly 10x larger on visual document benchmarks."
]

images = [
    Image.open(hf_hub_download("HuggingFaceTB/SmolVLM", "example_images/rococo.jpg", repo_type="space")),
    Image.open(hf_hub_download("ModernVBERT/colmodernvbert", "table.png", repo_type="model"))
]

# Preprocess the examples
batch_images = processor(images=images).to(model.device)
batch_queries = processor(text=queries).to(model.device)

# Run inference
with torch.inference_mode():
    image_embeddings = model(**batch_images).embeddings
    query_embeddings = model(**batch_queries).embeddings

# Compute retrieval scores
scores = processor.score_retrieval(
    query_embeddings=query_embeddings,
    passage_embeddings=image_embeddings,
)

scores = torch.softmax(scores, dim=-1)

print(scores)    # [[0.9350, 0.0650], [0.0015, 0.9985]]

ColModernVBertConfig

فئة transformers.ColModernVBertConfig

< >

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

المعاملات

  • vlm_config (Union[dict, ~configuration_utils.PreTrainedConfig], اختياري) — كائن الإعداد أو قاموس العمود الفقري لنموذج الرؤية واللغة.
  • embedding_dim (int، اختياري، القيمة الافتراضية 128) — أبعاد التضمينات والحالات المخفية.
  • initializer_range (float، اختياري، القيمة الافتراضية 0.02) — الانحراف المعياري لـ truncated_normal_initializer المستخدم في تهيئة جميع مصفوفات الأوزان.

هذه فئة الإعدادات المخزنة لإعدادات نموذج ColmodernvbertModel. تُستخدم لتوليد نموذج Colmodernvbert وفقاً للحجج المحددة، مع تعريف بنية النموذج. إن إنشاء إعدادات باستخدام القيم الافتراضية سيؤدي إلى الحصول على إعدادات مشابهة لتلك الخاصة بـ ModernVBERT/colmodernvbert-merged

ترث كائنات التهيئة من PreTrainedConfig ويمكن استخدامها للتحكم في مخرجات النموذج. اقرأ التوثيق الخاص بـ PreTrainedConfig لمزيد من المعلومات.

مثال:

from transformers import ColModernVBertConfig, ColModernVBertForRetrieval

config = ColModernVBertConfig()
model = ColModernVBertForRetrieval(config)

ColModernVBertProcessor

فئة transformers.ColModernVBertProcessor

< >

( image_processortokenizer = Nonechat_template = Noneimage_seq_len: int = 64visual_prompt_prefix: str | None = Nonequery_prefix: str | None = None**kwargs )

المعاملات

  • image_processor (image_processor_class) — معالج الصور هو مدخل إلزامي.
  • tokenizer (tokenizer_class) — مُجزِّئ النص (tokenizer) هو مدخل إلزامي.
  • chat_template (str) — قالب Jinja لتحويل قوائم الرسائل في المحادثة إلى نص قابل للتجزئة.
  • image_seq_len (int، اختياري، القيمة الافتراضية 64) — طول تسلسل الصورة، أي عدد الرموز لكل صورة في المدخلات.
  • visual_prompt_prefix (str, اختياري) — نص يُحوَّل إلى رموز ويُضاف قبل رموز الصورة.
  • query_prefix (str، اختياري) — بادئة تُستخدم للاستعلام.

ينشئ ColModernVBertProcessor الذي يجمع معالج الصور ومعالج الرموز في معالج واحد.

يوفر ColModernVBertProcessor جميع وظائف image_processor_class وtokenizer_class. راجع ~image_processor_class و~tokenizer_class لمزيد من المعلومات.

process_images

< >

( images: typing.Union[ForwardRef('PIL.Image.Image'), numpy.ndarray, ForwardRef('torch.Tensor'), list['PIL.Image.Image'], list[numpy.ndarray], list['torch.Tensor'], NoneType] = None**kwargs: *<class 'transformers.models.colmodernvbert.processing_colmodernvbert.ColModernVBertProcessorKwargs'> ) → BatchFeature

المعاملات

  • images (PIL.Image.Image، np.ndarray، torch.Tensor، list[PIL.Image.Image]، list[np.ndarray]، list[torch.Tensor]) — الصورة أو مجموعة الصور التي سيتم تجهيزها. يمكن أن تكون كل صورة صورة PIL، أو مصفوفة NumPy، أو متجه PyTorch. في حالة استخدام مصفوفة NumPy أو متجه PyTorch، يجب أن تكون كل صورة على شكل (C, H, W)، حيث C هو عدد القنوات، وH وW هما ارتفاع الصورة وعرضها.
  • return_tensors (str أو TensorType, اختياري) — إذا تم تعيينه، فسيُعاد تينسورات من إطار عمل محدد. القيم المقبولة هي:
    • 'pt': إرجاع كائنات torch.Tensor من PyTorch.
    • 'np': إرجاع كائنات np.ndarray من NumPy.

يعيد

BatchFeature

BatchFeature يحتوي على الحقول التالية:

  • input_ids — قائمة معرّفات الرموز التي تُغذّى بها النموذج.
  • attention_mask — قائمة بالفهارس تحدد الرموز التي يجب على النموذج الانتباه إليها (عندما يكون return_attention_mask=True أو إذا كان “attention_mask” ضمن self.model_input_names وإذا لم يكن text None).
  • pixel_values — قيم البكسلات التي تُمرَّر إلى النموذج. تُعاد عندما لا تكون images بقيمة None.

يُعدّ النموذج صورة واحدة أو عدة صور. يتعامل مع التحقق من صحة المدخلات، والتحويل إلى RGB، ويضيف visual_prompt_prefix إلى بداية كل صورة. كما يحسب التسميات اختيارياً من token_type_ids عند توفير suffix في text_kwargs.

process_queries

< >

( text: str | list[str]**kwargs: *<class 'transformers.models.colmodernvbert.processing_colmodernvbert.ColModernVBertProcessorKwargs'> ) → BatchFeature

المعاملات

  • text (str، list[str]، list[list[str]]) — التسلسل أو الدفعة من التسلسلات المراد ترميزها. يمكن أن يكون كل تسلسل نصًا أو قائمة من النصوص (نصوص مُقسّمة مسبقًا إلى رموز). إذا تم تقديم التسلسلات على شكل قائمة من النصوص (مقسّمة مسبقًا)، فيجب تعيين is_split_into_words=True (لرفع الغموض مع دفعة من التسلسلات).
  • return_tensors (str أو TensorType, اختياري) — إذا تم تعيينه، فسيُعاد تينسورات من إطار عمل محدد. القيم المقبولة هي:
    • 'pt': إرجاع كائنات torch.Tensor من PyTorch.
    • 'np': إرجاع كائنات np.ndarray من NumPy.

يعيد

BatchFeature

BatchFeature يحتوي على الحقول التالية:

  • input_ids — قائمة معرّفات الرموز التي تُغذّى بها النموذج.
  • attention_mask — قائمة بالفهارس تحدد الرموز التي يجب على النموذج الانتباه إليها (عندما يكون return_attention_mask=True أو إذا كان “attention_mask” ضمن self.model_input_names وإذا لم يكن text None).

استعدّ لاستعلام نصّي واحد أو عدة استعلامات نصية للنموذج. يتعامل مع التحقق من صحة المدخلات، ويضيف بادئة query_prefix في البداية، ويضيف رموز تعزيز الاستعلام (تُستخدم لحشو تمثيلات الاستعلام لتحسين أداء الاسترجاع المتأخر التفاعلي).

score_retrieval

< >

( query_embeddings: typing.Union[ForwardRef('torch.Tensor'), list['torch.Tensor']]passage_embeddings: typing.Union[ForwardRef('torch.Tensor'), list['torch.Tensor']]batch_size: int = 128output_dtype: typing.Optional[ForwardRef('torch.dtype')] = Noneoutput_device: typing.Union[ForwardRef('torch.device'), str] = 'cpu' ) → torch.Tensor

المعاملات

  • query_embeddings (Union[torch.Tensor, list[torch.Tensor]) — تمثيلات الاستعلام.
  • passage_embeddings (Union[torch.Tensor, list[torch.Tensor]) — تمثيلات المقاطع.
  • batch_size (int، اختياري، القيمة الافتراضية 128) — حجم الدفعة لحساب الدرجات.
  • output_dtype (torch.dtype، اختياري، القيمة الافتراضية torch.float32) — نوع البيانات (dtype) للمصفوفة الناتجة. إذا كانت None، يتم استخدام نوع بيانات التضمينات المدخلة.
  • output_device (torch.device أو str، اختياري، القيمة الافتراضية هي “cpu”) — جهاز المصفوفة الناتجة.

يعيد

torch.Tensor

مصفوفة (Tensor) ذات الشكل (n_queries, n_passages) تحتوي على الدرجات. تُحفظ مصفوفة الدرجات على جهاز "cpu".

احسب درجة التفاعل المتأخر/MaxSim (على غرار ColBERT) لمتجهات الاستعلام متعددة المتجهات (qs) ومتجهات المقاطع (ps) المعطاة. في حالة ColQwen2، يكون المقطع هو صورة صفحة من المستند.

بما أن متجهات التضمين متعددة المتجهات، فقد تختلف أشكالها، لذا يجب إدخالها على النحو التالي: (1) قائمة من المتجهات، حيث يكون شكل المتجه رقم i هو (sequence_length_i, embedding_dim) (2) متجه واحد من الشكل (n_passages, max_sequence_length, embedding_dim) -> وهو ما يُحصل عليه عادةً عن طريق ملء قائمة المتجهات.

ColModernVBertForRetrieval

فئة transformers.ColModernVBertForRetrieval

< >

( config: ColModernVBertConfig )

المعاملات

  • config (ColModernVBertConfig) — فئة إعدادات النموذج التي تحتوي على جميع معاملات النموذج. لا يؤدي التهيئة باستخدام ملف الإعدادات إلى تحميل الأوزان المرتبطة بالنموذج، بل الإعدادات فقط. راجع طريقة from_pretrained() لتحميل أوزان النموذج.

باتباع نهج ColPali، يستفيد ColModernVBert من نماذج اللغة البصرية (VLMs) لبناء تمثيلات متعددة المتجهات (multi-vector embeddings) فعالة مباشرةً من صور المستندات ("لقطات الشاشة") لأغراض استرجاع المستندات. يتم تدريب النموذج على تعظيم التشابه بين تمثيلات المستندات هذه وتمثيلات الاستعلامات المقابلة، باستخدام طريقة التفاعل المتأخر (late interaction) المقدمة في ColBERT.

يُزيل استخدام ColModernVBert الحاجة إلى خطوط معالجة معقدة وهشة محتملاً للتعرف على التخطيط ومعالجة الحروف الضوئية، من خلال نموذج واحد قادر على مراعاة المحتوى النصي والبصري (التخطيط، الرسوم البيانية، ...) للمستند.

يُدرَّب ColModernVBert فوق ModernVBert، وقد قُدِّم في الورقة البحثية التالية: ModernVBERT: Towards Smaller Visual Document Retrievers.

يُعدّ ColModernVBert جزءًا من عائلة نماذج ColVision، التي تم تقديمها مع ColPali في الورقة البحثية التالية: ColPali: Efficient Document Retrieval with Vision Language Models.

يرث هذا النموذج من PreTrainedModel. راجع توثيق الفئة الأصلية لمعرفة الطرق العامة التي تنفذها المكتبة لجميع نماذجها (مثل التحميل أو الحفظ، وتغيير حجم تضمينات الإدخال، وقص الرؤوس، وما إلى ذلك).

هذا النموذج هو أيضًا فئة فرعية من torch.nn.Module في PyTorch. استخدمه كوحدة PyTorch عادية، وارجع إلى توثيق 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'> ) → ColModernVBertForRetrievalOutput or tuple(torch.Tensor)

المعاملات

  • input_ids (torch.LongTensor بشكل (batch_size, sequence_length), اختياري) — مؤشرات رموز تسلسل الإدخال في قاموس الكلمات. سيتم تجاهل الحشو افتراضيًا.

    يمكن الحصول على الفهارس باستخدام AutoTokenizer. راجع PreTrainedTokenizer.encode() و PreTrainedTokenizer.call() للتفاصيل.

    ما هي معرّفات الإدخال؟

  • pixel_values (torch.Tensor من الشكل (batch_size, num_channels, image_size, image_size)، اختياري) — المصفوفات المقابلة للصور المدخلة. يمكن الحصول على قيم البكسل باستخدام image_processor_class. راجع image_processor_class.__call__ للتفاصيل (يستخدم ColModernVBertProcessor image_processor_class لمعالجة الصور).
  • attention_mask (torch.Tensor بشكل (batch_size, sequence_length), اختياري) — قناع لتجنب تنفيذ الانتباه على فهارس رموز الحشو. القيم المختارة للقناع هي [0, 1]:
    • 1 للرموز التي لم تُقنَّع،
    • 0 للرموز التي تم إخفاؤها.

    ما هي أقنعة الانتباه؟

يعيد

ColModernVBertForRetrievalOutput أو tuple(torch.Tensor)

ColModernVBertForRetrievalOutput أو مجموعة مرتبة من torch.Tensor (إذا تم تمرير return_dict=False أو عندما يكون config.return_dict=False) وتتضمن عناصر مختلفة اعتمادًا على الإعداد (ColModernVBertConfig) والمدخلات.

تتجاوز طريقة ColModernVBertForRetrieval الخاصة بالتقديم (forward) الطريقة الخاصة __call__.

على الرغم من أنه يجب تعريف وصفة المرور الأمامي داخل هذه الدالة، إلا أنه ينبغي استدعاء كائن Module بدلاً من هذه الدالة، لأن الكائن يتولى تنفيذ خطوات المعالجة المسبقة والمعالجة اللاحقة، بينما تتجاهل الدالة هذه الخطوات بصمت.

  • loss (torch.Tensor of shape (1,), اختياري, يُعاد عند توفير labels) — خسارة نمذجة اللغة (لتوقع الرمز التالي).

  • التمثيلات (torch.Tensor من الشكل (batch_size, sequence_length, hidden_size)) — التمثيلات الخاصة بالنموذج.

  • hidden_states (tuple[torch.Tensor]، اختياري، يُعاد عند تمرير output_hidden_states=True أو عند تعيين config.output_hidden_states=True) — مجموعة من torch.Tensor (واحدة لإخراج الطبقات المضمنة، إذا كان النموذج يحتوي على طبقة تضمين، + واحدة لإخراج كل طبقة) من الشكل (batch_size, sequence_length, hidden_size).

    حالات النموذج المخفية عند مخرج كل طبقة بالإضافة إلى مخرجات التضمين الأولي الاختيارية.

  • image_hidden_states (tuple(torch.Tensor)، اختياري، يُعاد عند تمرير output_hidden_states=True أو عند تعيين config.output_hidden_states=True وتوفير pixel_values) — مجموعة من torch.Tensor (واحدة لإخراج إسقاط نمط الصورة + واحدة لإخراج كل طبقة) بأبعاد (batch_size, num_channels, image_size, image_size). حالات الإخفاء (Hidden-states) لمشفّر الصورة عند إخراج كل طبقة بالإضافة إلى مخرجات إسقاط النمط الأولية.

  • attentions (tuple[torch.Tensor]، اختياري، يُعاد عند تمرير output_attentions=True أو عند تعيين config.output_attentions=True) — مجموعة من torch.Tensor (واحدة لكل طبقة) بأبعاد (batch_size, num_heads, sequence_length, sequence_length).

    أوزان الانتباه بعد تطبيق دالة softmax على الانتباه، وتُستخدم لحساب المتوسط الموزون في رؤوس الانتباه الذاتي.

مثال:

Update on GitHub

←CohereCompass ColPali→