# المعالجات متعددة الوسائط

يجمع المُعالِج بين مُجزِّئ (tokenizer) ومعالِج واحد أو أكثر للأنماط (modality processors)، مثل مُعالِج الصور أو مُعالِج الفيديو أو مستخرج الميزات. يعرّض طريقة `__call__` واحدة تُوجّه كل مدخل إلى المكوّن المناسب وتدمج المخرجات في قاموس واحد.

تقوم بعض النماذج متعددة الوسائط بتبديل النص مع الصور أو مقاطع الفيديو أو الصوت. ولأغراض هذه النماذج، يمكن لـ [ProcessorMixin](/docs/transformers/v5.23.0/ar/main_classes/processors#transformers.ProcessorMixin) استبدال الرموز الوهمية مثل `<image>` و`<video>` و`<audio>` بنمط الرموز الذي يتوقعه النموذج.

## إضافة معالج جديد

حدد فئة المعالج (processor) من خلال إنشاء `src/transformers/models/<model>/processing_<my_model_name>.py` وإرث فئة `ProcessorMixin`. تأكد من تعريف كائن `TypedDict` بقيم افتراضية وتعيينه كـ `cls.valid_processor_kwargs`

```python
from ...processing_utils import ProcessorMixin

class MyModelProcessor(ProcessorMixin):

    def __init__(self, image_processor, tokenizer, chat_template=None, **kwargs):
        self.image_token = tokenizer.image_token
        self.image_token_id = tokenizer.image_token_id
        super().__init__(
            image_processor=image_processor,
            tokenizer=tokenizer,
            chat_template=chat_template,
            **kwargs,
        )
```

نفّذ `replace_<modality>_token` عند الحاجة. يستقبل هذا الدالة قاموس المخرجات الكامل من المعالج الفرعي (subprocessor) وفهرس الإدخال الحالي، ويعيد سلسلة الاستبدال الموسّعة لذلك الإدخال. وتكون سلسلة الاستبدال هي ما يتوقعه النموذج في تسلسل الإدخال.

إذا لم يستخدم النموذج تكرار الرموز الوهمية على الإطلاق (لم يُعرَّف `image_token`)، فلا حاجة إلى تجاوز هذه الطريقة. اترك `self.image_token` غير مضبوط، وستتخطى الفئة الأساسية عملية الاستبدال بالكامل.

```python
def replace_image_token(self, image_inputs: dict, image_idx: int) -> str:
    num_crops = image_inputs["num_crops"][image_idx]
    return f"{self.boi_token}{self.image_token * self.num_image_tokens * num_crops}{self.eoi_token}"
```

يمكنك اختيارياً تجاوز طريقتي `prepare_inputs_layout` و`validate_inputs`. إذا كان النموذج يتطلب بنية إدخال محددة قبل بدء المعالجة، مثل إعادة ترتيب الصور كقائمة متداخلة، أو التحقق من صحة خاص بالنموذج فوق الفحوصات الشائعة.

```python
def prepare_inputs_layout(self, images=None, text=None, videos=None, audio=None, **kwargs):
    # Call `super()` to apply common preparation steps first 
    images, text, videos, audio = super().prepare_inputs_layout(images, text, videos, audio)
    if images is not None:
        images = make_nested_list_of_images(images)
    return images, text, videos, audio

def validate_inputs(self, images=None, text=None, videos=None, audio=None, **kwargs):
    super().validate_inputs(images=images, text=text, **kwargs)
    if text is not None and images is not None:
        n_tokens = [s.count(self.image_token) for s in text]
        n_images = [len(img_list) for img_list in images]
        if n_tokens != n_images:
            raise ValueError(
                f"Number of {self.image_token} tokens in text {n_tokens} does not match "
                f"number of images {n_images}."
            )
```

> [!TIP]
> راجع [Gemma4Processor](/docs/transformers/v5.23.0/ar/model_doc/gemma4#transformers.Gemma4Processor) و [Qwen2VLProcessor](/docs/transformers/v5.23.0/ar/model_doc/qwen2_vl#transformers.Qwen2VLProcessor) للاطلاع على التفاصيل.

### إضافة حُجج مخصصة

هناك ثلاث طرق لإضافة حُجج مخصصة إلى المعالج:

| أين تضيف | يُستخدم | القيمة الافتراضية | قابلة للتهيئة وقت التشغيل | مثال |
|---|---|---|---|---|
| `__init__` | الإعدادات المحفوظة في ملف الإعداد (خصائص النموذج) | عادةً ما يكون له قيمة افتراضية | لا | `image_seq_length` في [Gemma3Processor](/docs/transformers/v5.23.0/ar/model_doc/gemma3#transformers.Gemma3Processor) |
| `__call__` | المدخلات التي لا تُعرف إلا وقت التشغيل | لا يوجد افتراضي أو `None` | نعم | `images`، `labels`، `suffix`، وما إلى ذلك. |
| فئة `MyModelProcessingKwargs` مخصصة | الإعدادات التي يمكن تكوينها وقت التشغيل | تعيينه كخاصية لفئة المعالج | نعم | `use_image_id` في [MiniCPMV4_7Processor](/docs/transformers/v5.23.0/ar/model_doc/minicpmv4_7#transformers.MiniCPMV4_7Processor) |

يجب إضافة حُجج وقت التشغيل التي يمكن أن تمتلك قيمة افتراضية إلى `MyModelProcessingKwargs` مخصص، وستُمرر كجزء من `**kwargs` إلى `__call__`. يمكن تعيين القيم الافتراضية لهذه القيم كخصائص لفئة المعالج. وبالمثل، يمكن تعريف القيم الافتراضية لمعالجات محددة حسب النمط، مثل مُرمّز النص أو مُعالج الصور. وعادةً لا يكون هذا ضروريًا لأن معالجات النمط المحدد تمتلك بالفعل قيمًا افتراضية معرّفة في فئاتها الخاصة. استخدم هذا الخيار فقط إذا كان المعالج يجب أن يتجاوز إعدادًا لمعالج نمط محدد. وبالطبع، فإن الحُجج الممررة وقت التشغيل إلى `__call__` لها دائمًا أولوية أعلى من أي قيم افتراضية.

```python
from ...processing_utils import ProcessingKwargs, ProcessorMixin, Unpack

class MyModelProcessorKwargs(ProcessingKwargs, total=False):
    """
    use_image_id (`bool`, defaults to `False`):
        Whether to prepend an image-id tag (``<image_id>N</image_id>``) before
        each image placeholder.
    """
    use_image_id: bool

class MyModelProcessor(ProcessorMixin):
    valid_processor_kwargs = MyModelProcessorKwargs
    use_image_id = False

    text_kwargs = {"padding": True}   # default passed to tokenizer

    def __init__(self, image_processor=None, tokenizer=None, chat_template=None, image_seq_length: int = 256, **kwargs):
        super().__init__(image_processor, tokenizer, chat_template=chat_template, **kwargs)
        self.image_seq_length = image_seq_length

    @auto_docstring
    def __call__(
        self,
        images: ImageInput | None = None,
        text: TextInput | PreTokenizedInput | list[TextInput] | list[PreTokenizedInput] | None = None,
        suffix: str | None = None,
        **kwargs: Unpack[MyModelProcessorKwargs],
    ):
        images, text, videos, audio = self.prepare_inputs_layout(images=images, text=text, **kwargs)
        self.validate_inputs(images=images, text=text, **kwargs)

        merged_kwargs = self._merge_kwargs(tokenizer_init_kwargs=self.tokenizer.init_kwargs, **kwargs)

        merged_kwargs["use_image_id"] # is `False` as default from class attribute is added by _merge_kwargs
        merged_kwargs["text_kwargs"]["padding"] # is `True`
```

## الاختبار

يجب أن تمتلك جميع المعالجات متعددة الوسائط فئة اختبار ترث من `ProcessorTesterMixin`. يوفر هذا المزيج مجموعة قياسية تغطي الترميز، ومعالجة الصور، والتجميع، والتشفير ذهاباً وإياباً.

```python
# tests/models/my_model_name/test_processor_<my_model_name>.py

from transformers.testing_utils import require_vision
from transformers.utils import is_vision_available
from ...test_processing_common import ProcessorTesterMixin

if is_vision_available():
    from transformers import MyModelProcessor

@require_vision
class MyModelProcessorTest(ProcessorTesterMixin, unittest.TestCase):
    processor_class = MyModelProcessor

    def get_processor(self):
        return MyModelProcessor.from_pretrained("hf-internal-testing/my-model-test")
```

