# ColModernVBert

## نظرة عامة

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

تم تقديم النموذج في [ModernVBERT: Towards Smaller Visual Document Retrievers](https://huggingface.co/papers/2510.01149).

```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.ColModernVBertConfig[[transformers.ColModernVBertConfig]]

```python
transformers.ColModernVBertConfig(transformers_version: str | None = None, architectures: list[str] | None = None, output_hidden_states: bool | None = False, return_dict: bool | None = True, dtype: str | torch.dtype | None = None, chunk_size_feed_forward: int = 0, is_encoder_decoder: bool = False, id2label: dict[int, str] | dict[str, str] | None = None, label2id: dict[str, int] | dict[str, str] | None = None, problem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = None, vlm_config: dict | transformers.configuration_utils.PreTrainedConfig | None = None, embedding_dim: int = 128, initializer_range: float = 0.02)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/models/colmodernvbert/configuration_colmodernvbert.py#L31)

**المعاملات:**

vlm_config (`Union[dict, ~configuration_utils.PreTrainedConfig]`، *اختياري*) : كائن الإعدادات أو قاموس العمود الفقري لنموذج الرؤية واللغة.

embedding_dim (`int`، *اختياري*، القيمة الافتراضية `128`) : أبعاد التضمينات والحالات المخفية.

initializer_range (`float`، *اختياري*، القيمة الافتراضية `0.02`) : الانحراف المعياري لـ truncated_normal_initializer المستخدم في تهيئة جميع مصفوفات الأوزان.

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

ترث كائنات الإعداد من [PreTrainedConfig](/docs/transformers/main/ar/main_classes/configuration#transformers.PreTrainedConfig) ويمكن استخدامها للتحكم في مخرجات النموذج. اقرأ التوثيق الخاص بـ [PreTrainedConfig](/docs/transformers/main/ar/main_classes/configuration#transformers.PreTrainedConfig) لمزيد من المعلومات.

مثال:

```python
from transformers import ColModernVBertConfig, ColModernVBertForRetrieval

config = ColModernVBertConfig()
model = ColModernVBertForRetrieval(config)
```

## ColModernVBertProcessor[[transformers.ColModernVBertProcessor]]

#### transformers.ColModernVBertProcessor[[transformers.ColModernVBertProcessor]]

```python
transformers.ColModernVBertProcessor(image_processor, tokenizer = None, chat_template = None, image_seq_len: int = 64, visual_prompt_prefix: str | None = None, query_prefix: str | None = None, **kwargs)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/models/colmodernvbert/processing_colmodernvbert.py#L55)

**المعاملات:**

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](/docs/transformers/main/ar/model_doc/colmodernvbert#transformers.ColModernVBertProcessor) جميع وظائف `image_processor_class` و`tokenizer_class`. راجع `~image_processor_class` و`~tokenizer_class` لمزيد من المعلومات.

#### process_images[[transformers.ColModernVBertProcessor.process_images]]

```python
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'>)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/models/colmodernvbert/processing_colmodernvbert.py#L324)

**المعاملات:**

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](/docs/transformers/main/ar/internal/file_utils#transformers.TensorType)، *اختياري*) : إذا تم تعيينه، فسيُرجع تينسورات من إطار عمل محدد. القيم المقبولة هي:  - `'pt'`: يُرجع كائنات `torch.Tensor` من PyTorch. - `'np'`: يُرجع كائنات `np.ndarray` من NumPy.

**يعيد:** [BatchFeature](/docs/transformers/main/ar/main_classes/feature_extractor#transformers.BatchFeature)

[BatchFeature](/docs/transformers/main/ar/main_classes/feature_extractor#transformers.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[[transformers.ColModernVBertProcessor.process_queries]]

```python
process_queries(text: str | list[str], **kwargs: *<class 'transformers.models.colmodernvbert.processing_colmodernvbert.ColModernVBertProcessorKwargs'>)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/models/colmodernvbert/processing_colmodernvbert.py#L390)

**المعاملات:**

text (`str`، `list[str]`، `list[list[str]]`) : التسلسل أو الدفعة من التسلسلات المراد ترميزها. يمكن أن يكون كل تسلسل نصًا أو قائمة من النصوص (نص مُقسَّم مسبقًا إلى وحدات). إذا تم تقديم التسلسلات على شكل قائمة من النصوص (مُقسَّمة مسبقًا)، فيجب تعيين `is_split_into_words=True` (لرفع الغموض مع دفعة من التسلسلات).

return_tensors (`str` أو [TensorType](/docs/transformers/main/ar/internal/file_utils#transformers.TensorType)، *اختياري*) : إذا تم تعيينه، فسيُرجع تينسورات من إطار عمل محدد. القيم المقبولة هي:  - `'pt'`: يُرجع كائنات `torch.Tensor` من PyTorch. - `'np'`: يُرجع كائنات `np.ndarray` من NumPy.

**يعيد:** [BatchFeature](/docs/transformers/main/ar/main_classes/feature_extractor#transformers.BatchFeature)

[BatchFeature](/docs/transformers/main/ar/main_classes/feature_extractor#transformers.BatchFeature) يحتوي على الحقول التالية:

- **input_ids** -- قائمة معرّفات الرموز المراد تغذيتها إلى النموذج.
- **attention_mask** -- قائمة بالفهارس تحدد الرموز التي يجب أن يوليها النموذج انتباهه (عندما يكون `return_attention_mask=True` أو إذا كان *"attention_mask"* ضمن `self.model_input_names` وإذا لم يكن `text` مساوياً لـ `None`).

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

#### score_retrieval[[transformers.ColModernVBertProcessor.score_retrieval]]

```python
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 = 128, output_dtype: typing.Optional[ForwardRef('torch.dtype')] = None, output_device: typing.Union[ForwardRef('torch.device'), str] = 'cpu')
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/models/colmodernvbert/processing_colmodernvbert.py#L447)

**المعاملات:**

query_embeddings (`Union[torch.Tensor, list[torch.Tensor]`) : تمثيلات الاستعلام.

passage_embeddings (`Union[torch.Tensor, list[torch.Tensor]`) : تمثيلات المقاطع.

batch_size (`int`، *اختياري*، القيمة الافتراضية 128) : حجم الدفعة (Batch size) لحساب الدرجات.

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]]

#### transformers.ColModernVBertForRetrieval[[transformers.ColModernVBertForRetrieval]]

```python
transformers.ColModernVBertForRetrieval(config: ColModernVBertConfig)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/models/colmodernvbert/modeling_colmodernvbert.py#L91)

**المعاملات:**

config ([ColModernVBertConfig](/docs/transformers/main/ar/model_doc/colmodernvbert#transformers.ColModernVBertConfig)) : فئة إعدادات النموذج التي تحتوي على جميع معاملات النموذج. عند التهيئة باستخدام ملف إعدادات، لا يتم تحميل الأوزان المرتبطة بالنموذج، بل الإعدادات فقط. راجع طريقة [from_pretrained()](/docs/transformers/main/ar/main_classes/model#transformers.PreTrainedModel.from_pretrained) لتحميل أوزان النموذج.

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

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

يُدرَّب ColModernVBert فوق ModernVBert، وقد قُدِّم في الورقة البحثية التالية: [*ModernVBERT: Towards Smaller Visual Document Retrievers*](https://arxiv.org/abs/2510.01149).

يُعدّ ColModernVBert جزءًا من عائلة نماذج ColVision، التي تم تقديمها مع ColPali في الورقة البحثية التالية: [*ColPali: Efficient Document Retrieval with Vision Language Models*](https://huggingface.co/papers/2407.01449).

يرث هذا النموذج من [PreTrainedModel](/docs/transformers/main/ar/main_classes/model#transformers.PreTrainedModel). راجع توثيق الفئة الأصلية لمعرفة الطرق العامة التي تنفذها المكتبة لجميع نماذجها (مثل التنزيل أو الحفظ، وتغيير حجم تضمينات الإدخال، وقص الرؤوس، وما إلى ذلك).

هذا النموذج هو أيضاً فئة فرعية من [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) في PyTorch. استخدمه كوحدة PyTorch عادية، وارجع إلى توثيق PyTorch لكل ما يتعلق بالاستخدام العام والسلوك.

#### forward[[transformers.ColModernVBertForRetrieval.forward]]

```python
forward(input_ids: typing.Optional[torch.LongTensor] = None, pixel_values: typing.Optional[torch.Tensor] = None, attention_mask: typing.Optional[torch.Tensor] = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/models/colmodernvbert/modeling_colmodernvbert.py#L105)

**المعاملات:**

input_ids (`torch.LongTensor` من الشكل `(batch_size, sequence_length)`، *اختياري*) : فهارس رموز تسلسل الإدخال في قاموس الكلمات. سيتم تجاهل الحشو افتراضيًا. يمكن الحصول على الفهارس باستخدام [AutoTokenizer](/docs/transformers/main/ar/model_doc/auto#transformers.AutoTokenizer). راجع [PreTrainedTokenizer.encode()](/docs/transformers/main/ar/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) و [PreTrainedTokenizer.__call__()](/docs/transformers/main/ar/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__) للتفاصيل. [ما هي معرّفات الإدخال؟](../glossary#input-ids)

pixel_values (`torch.Tensor` من الشكل `(batch_size, num_channels, image_size, image_size)`، *اختياري*) : المصفوفات المقابلة للصور المدخلة. يمكن الحصول على قيم البكسل باستخدام `image_processor_class`. راجع `image_processor_class.__call__` للتفاصيل ([ColModernVBertProcessor](/docs/transformers/main/ar/model_doc/colmodernvbert#transformers.ColModernVBertProcessor) يستخدم `image_processor_class` لمعالجة الصور).

attention_mask (`torch.Tensor` من الشكل `(batch_size, sequence_length)`، *اختياري*) : قناع لتجنب تنفيذ الانتباه على فهارس رموز الحشو. قيم القناع المختارة من `[0, 1]`: - 1 للرموز التي **ليست مقنّعة**، - 0 للرموز التي **مقنّعة**.  [ما هي أقنعة الانتباه؟](../glossary#attention-mask)

**يعيد:** `ColModernVBertForRetrievalOutput` أو `tuple(torch.Tensor)`

`ColModernVBertForRetrievalOutput` أو مجموعة مرتبة من `torch.Tensor` (إذا تم تمرير `return_dict=False` أو عندما يكون `config.return_dict=False`) وتتضمن عناصر مختلفة اعتمادًا على الإعداد ([ColModernVBertConfig](/docs/transformers/main/ar/model_doc/colmodernvbert#transformers.ColModernVBertConfig)) والمدخلات.

تتجاوز طريقة [ColModernVBertForRetrieval](/docs/transformers/main/ar/model_doc/colmodernvbert#transformers.ColModernVBertForRetrieval) الخاصة بالتقديم (forward) الطريقة الخاصة `__call__`.

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

- **loss** (`torch.Tensor` من الشكل `(1,)`، *اختياري*، يُعاد عند توفير `labels`) -- خسارة نمذجة اللغة (لتوقع الرمز التالي).
- **التمثيلات** (`torch.Tensor` من الشكل `(batch_size, sequence_length, hidden_size)`) -- تمثيلات النموذج.
- **hidden_states** (`tuple[torch.Tensor]`، *اختياري*، يُعاد عند تمرير `output_hidden_states=True` أو عند تعيين `config.output_hidden_states=True`) -- مجموعة (Tuple) من `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)`. حالات المخفية لمشفّر الصورة عند إخراج كل طبقة بالإضافة إلى مخرجات إسقاط النمط الأولية.
- **attentions** (`tuple[torch.Tensor]`، *اختياري*، يُعاد عند تمرير `output_attentions=True` أو عند تعيين `config.output_attentions=True`) -- مجموعة من `torch.Tensor` (واحدة لكل طبقة) بأبعاد `(batch_size, num_heads, sequence_length, sequence_length)`.

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

مثال:

```python
```