# إضافة مكوّنات معالجة الرؤية

يتطلب إضافة نموذج رؤية مكوّنات معالجة الصور أو الفيديو إلى جانب النهج [المنفصل](./modular_transformers) القياسي. تحتاج النماذج التي تعمل بالصور فقط إلى معالجات صور، بينما تحتاج نماذج الفيديو إلى معالج فيديو، وكلاهما متاح خلف نقاط الدخول [AutoImageProcessor](/docs/transformers/main/ar/model_doc/auto#transformers.AutoImageProcessor) و[AutoVideoProcessor](/docs/transformers/main/ar/model_doc/auto#transformers.AutoVideoProcessor).

> [!NOTE]
> لخطوات النمذجة والإعداد، اتبع أولاً دليل [modular](./modular_transformers).

## معالجات الصور

أنشئ معالجات الصور عندما يستهلك النموذج الصور. الخلفية الافتراضية هي [torchvision](https://docs.pytorch.org/vision/stable/index.html) وتدعم تسريع وحدة معالجة الرسوميات (GPU). أما [PIL](https://pillow.readthedocs.io/en/stable/index.html) فهي الخيار البديل عندما لا تكون torchvision متاحة.

تشارك كلا فئتي معالج الصور منطق ما قبل المعالجة نفسه، لكنهما تستخدمان واجهات خلفية مختلفة. يجب أن تكون توقيعات دوال الإنشاء والقيم الافتراضية متطابقة تمامًا. يختار [AutoImageProcessor.from_pretrained()](/docs/transformers/main/ar/model_doc/auto#transformers.AutoImageProcessor.from_pretrained) الواجهة الخلفية عند التحميل، ويلجأ إلى PIL عندما لا يكون torchvision متاحًا. يؤدي عدم تطابق التوقيعات إلى اختلاف سلوك نفس الإعداد المحفوظ عبر البيئات المختلفة.

### torchvision

أنشئ `image_processing_<model_name>.py` يحتوي على فئة ترث من [TorchvisionBackend](/docs/transformers/main/ar/main_classes/image_processor#transformers.TorchvisionBackend). إذا كان المعالج الخاص بك يحتاج إلى معاملات مخصصة تتجاوز المعايير القياسية [ImagesKwargs]، فعرّف فئة kwargs.

```py
from ...image_processing_backends import TorchvisionBackend
from ...image_utils import OPENAI_CLIP_MEAN, OPENAI_CLIP_STD, PILImageResampling
from ...processing_utils import ImagesKwargs, Unpack
from ...utils import auto_docstring

class MyModelImageProcessorKwargs(ImagesKwargs, total=False):
    tile_size: int  # any model-specific kwargs

@auto_docstring
class MyModelImageProcessor(TorchvisionBackend):
    resample = PILImageResampling.BICUBIC
    image_mean = OPENAI_CLIP_MEAN
    image_std = OPENAI_CLIP_STD
    size = {"shortest_edge": 224}
    do_resize = True
    do_rescale = True
    do_normalize = True
    do_convert_rgb = True

    def __init__(self, **kwargs: Unpack[MyModelImageProcessorKwargs]):
        super().__init__(**kwargs)
```

> [!TIP]
> راجع [LlavaOnevisionImageProcessor](/docs/transformers/main/ar/model_doc/llava_onevision#transformers.LlavaOnevisionImageProcessor) للاطلاع على التفاصيل.

### PIL

أنشئ `image_processing_pil_<model_name>.py` يحتوي على فئة ترث من [PilBackend](/docs/transformers/main/ar/main_classes/image_processor#transformers.PilBackend). انسخ فئة kwargs هنا بدلاً من استيرادها من ملف torchvision، لأن ذلك قد يفشل عند عدم تثبيت torchvision. أضف تعليق `# Adapted from` حتى تبقى النسختان متزامنتين. بالنسبة للمعالجات التي لا تحتوي على معاملات مخصصة، استخدم [ImagesKwargs](/docs/transformers/main/ar/main_classes/processors#transformers.ImagesKwargs) مباشرة.

```py
from ...image_processing_backends import PilBackend
from ...image_utils import OPENAI_CLIP_MEAN, OPENAI_CLIP_STD, PILImageResampling
from ...processing_utils import ImagesKwargs, Unpack
from ...utils import auto_docstring

# Adapted from transformers.models.my_model.image_processing_my_model.MyModelImageProcessorKwargs
class MyModelImageProcessorKwargs(ImagesKwargs, total=False):
    tile_size: int  # any model-specific kwargs

@auto_docstring
class MyModelImageProcessorPil(PilBackend):
    resample = PILImageResampling.BICUBIC
    image_mean = OPENAI_CLIP_MEAN
    image_std = OPENAI_CLIP_STD
    size = {"shortest_edge": 224}
    do_resize = True
    do_rescale = True
    do_normalize = True
    do_convert_rgb = True

    def __init__(self, **kwargs: Unpack[MyModelImageProcessorKwargs]):
        super().__init__(**kwargs)
```

> [!TIP]
> راجع [LlavaOnevisionImageProcessorPil](/docs/transformers/main/ar/model_doc/llava_onevision#transformers.LlavaOnevisionImageProcessorPil) للاطلاع على التفاصيل.

### إضافة طرق ما بعد المعالجة

أضف طرق ما بعد المعالجة مباشرةً إلى فئة المعالج. تُستدعى طرق ما بعد المعالجة مع مخرجات النموذج (`outputs`) وأي حُجج إضافية مطلوبة للطريقة المحددة.

```py
class MyModelImageProcessor(TorchvisionBackend):
    ...

    def post_process_my_task(self, outputs, ...):
        ...
```

تُعيد معالجات ما بعد المعالجة إما قائمة من الكائنات البسيطة (`list[str]` أو `list[torch.Tensor]`) أو قائمة من الكائنات المعقدة (`list[MyTaskPostProcessorOutput]` أو `list[dict]`). تُعرَّف مخرجات معالج ما بعد المعالجة في `src/transformers/image_processing_outputs.py` وتورث من [BatchFeature](/docs/transformers/main/ar/main_classes/feature_extractor#transformers.BatchFeature).

```py
class MyTaskPostProcessorOutput(BatchFeature):
    predictions: torch.Tensor
    scores: torch.Tensor
```

## معالج الفيديو

أضف معالج فيديو عندما يستهلك النموذج مقاطع فيديو أو إطارات فيديو مُستخرجة.

أنشئ `video_processing_<model_name>.py` في مجلد النموذج. يرث [BaseVideoProcessor](/docs/transformers/main/ar/main_classes/video_processor#transformers.BaseVideoProcessor) من [TorchvisionBackend](/docs/transformers/main/ar/main_classes/image_processor#transformers.TorchvisionBackend) ويوفر سلوكًا مشتركًا لفك الترميز، وعيّنات الإطارات، وتغيير الحجم، وإعادة المقياس، والتطبيع، والحفظ، والتحميل.

تُمثّل سمات الفئة قيم المعالجة المسبقة الافتراضية. يمكن للمستخدمين تجاوزها عند التهيئة أو عند الاستدعاء. استخدم نفس أسماء [VideosKwargs](/docs/transformers/main/ar/main_classes/processors#transformers.VideosKwargs) كلما أمكن ذلك، مثل `size` و`crop_size` و`do_resize` و`do_sample_frames` و`num_frames` و`fps`.

حدد فئة kwargs إذا كان معالج الفيديو الخاص بك يحتاج إلى معاملات مخصصة تتجاوز المعايير القياسية [VideosKwargs](/docs/transformers/main/ar/main_classes/processors#transformers.VideosKwargs). اضبطها كـ `valid_kwargs` واستخدمها لتعليق `__init__` من أجل التحقق في وقت التشغيل وتوليد التوثيق تلقائيًا.

```py
from ...processing_utils import Unpack, VideosKwargs
from ...utils import auto_docstring
from ...video_processing_utils import BaseVideoProcessor

class MyModelVideoProcessorKwargs(VideosKwargs, total=False):
    min_frames: int
    max_frames: int

@auto_docstring
class MyModelVideoProcessor(BaseVideoProcessor):
    size = {"shortest_edge": 224}
    crop_size = {"height": 224, "width": 224}
    do_resize = True
    do_center_crop = True
    do_normalize = True
    do_sample_frames = True
    num_frames = 16
    model_input_names = ["pixel_values_videos"]
    valid_kwargs = MyModelVideoProcessorKwargs

    def __init__(self, **kwargs: Unpack[MyModelVideoProcessorKwargs]):
        super().__init__(**kwargs)
```

لا تُعدّل [sample_frames()](/docs/transformers/main/ar/main_classes/video_processor#transformers.BaseVideoProcessor.sample_frames) إلا عندما يتطلب النموذج قاعدة أخذ عينات لا يستطيع مُعيّن التوزيع المنتظم الأساسي التعبير عنها. على سبيل المثال، تفرض بعض النماذج حدًا أدنى أو أقصى لعدد الإطارات، أو تأخذ العينات بناءً على قيود خاصة بالنموذج.

If the model's forward method expects a legacy input name, override `preprocess` and rename the key after calling the base implementation.

```py
class MyModelVideoProcessor(BaseVideoProcessor):
    model_input_names = ["pixel_values"]

    def preprocess(self, videos, **kwargs):
        batch = super().preprocess(videos, **kwargs)
        batch["pixel_values"] = batch.pop("pixel_values_videos")
        return batch
```

احفظ معالج الفيديو مع نقطة الحفظ عن طريق إنشاء مثيل له في سكربت التحويل واستدعاء [save_pretrained()](/docs/transformers/main/ar/main_classes/video_processor#transformers.VideoProcessorMixin.save_pretrained). إذا كان [ProcessorMixin](/docs/transformers/main/ar/main_classes/processors#transformers.ProcessorMixin) يغلّف معالج الفيديو، فاستدعِ [save_pretrained()](/docs/transformers/main/ar/model_doc/wav2vec2#transformers.Wav2Vec2Processor.save_pretrained) بدلاً من ذلك. لا تنشئ أو تحرر ملفات إعدادات ما قبل المعالجة يدوياً.

> [!TIP]
> راجع [Qwen3VLVideoProcessor](/docs/transformers/main/ar/model_doc/qwen3_vl#transformers.Qwen3VLVideoProcessor) للاطلاع على التفاصيل.

## تسجيل الفئات

أضف الفئات الجديدة إلى `__all__` في أسفل الملف، ثم أعد توليد `__init__.py` باستخدام:

```bash
python utils/check_inits.py --fix_and_overwrite
```

خريطة الفئات الجديدة إلى إعدادات النموذج حتى تتمكن فئات `Auto` من تحميلها. يحتوي ملف الخرائط التلقائية المولّد على تحذير في الأعلى. لا تحرّره يدويًا. أضف أو حدّث إعدادات النموذج، ثم نفّذ:

```bash
python utils/check_auto.py --fix_and_overwrite
```

بعد إنشاء الترميز، تحقق من ظهور نوع النموذج في الترميزات ذات الصلة في `src/transformers/models/auto/auto_mappings.py`.

- `IMAGE_PROCESSOR_MAPPING_NAMES` لـ [AutoImageProcessor](/docs/transformers/main/ar/model_doc/auto#transformers.AutoImageProcessor)
- `VIDEO_PROCESSOR_MAPPING_NAMES` لـ [AutoVideoProcessor](/docs/transformers/main/ar/model_doc/auto#transformers.AutoVideoProcessor)

## الاختبار

أضِف اختبارات لكل مكوّن معالجة الرؤية في دليل اختبارات النموذج. استخدم خلطات الاختبار المشتركة وفوِّد معاملات التهيئة الخاصة بالنموذج. تكتشف اختبارات الصور واجهات المعالجة تلقائيًا عبر مُختبِر مشترك، بينما تُهيّئ اختبارات الفيديو فئة المعالجة والتثبيتات بشكل صريح.

### اختبارات معالج الصور

توجد اختبارات معالج الصور في `tests/models/<model_name>/test_image_processing_<model_name>.py`. عرّف مُختبِرًا يرث من `ImageProcessingTester` وفئة اختبار ترث من `ImageProcessingTestMixin` و`unittest.TestCase`.

يحدد مُختبِر معالجة الصور سمات الاختبار الافتراضية، مثل معاملات تهيئة المُعالِج والمعاملات لإنشاء مدخلات عشوائية للاختبارات. لا تُبدِل المعاملات إلا إذا كان ينبغي أن تكون مختلفة عن قيم المُعالِج الافتراضية. على سبيل المثال، نختبر عادةً بأحجام صور أصغر للحفاظ على سرعة الاختبارات. تُستنتج فئات مُعالِج الصور تلقائيًا من `IMAGE_PROCESSOR_MAPPING_NAMES`.

اضبط `image_processor_tester_class` على فئة الاختبار. يقوم المزيج بإنشاء `self.image_processor_tester` ويغطي بالفعل معظم طرق الاختبار المطلوبة.

```py
import unittest

from transformers.testing_utils import require_torch, require_vision
from ...test_image_processing_common import ImageProcessingTestMixin, ImageProcessingTester

class MyModelImageProcessingTester(ImageProcessingTester):
    def __init__(self, **kwargs):
        # Random test inputs kwargs
        kwargs.setdefault("batch_size", 2)          # default: 7     
        kwargs.setdefault("num_channels", 4)        # default: 3
        kwargs.setdefault("min_resolution", 20)     # default: 30
        kwargs.setdefault("max_resolution", 100)    # default: 400

        # Image processor init kwargs
        kwargs.setdefault("size", {"shortest_edge": 20})
        kwargs.setdefault("crop_size", {"height": 18, "width": 18})

        super().__init__(**kwargs)

@require_torch
@require_vision
class MyModelImageProcessingTest(ImageProcessingTestMixin, unittest.TestCase):
    image_processor_tester_class = MyModelImageProcessingTester

    def test_inherits_from_mixin(self):
        # Always iterate over all image processing classes
        for image_processing_class in self.image_processing_classes.values():
            # self.image_processor_dict contains the default processor init kwargs
            # including overrides from the tester.
            image_processor = image_processing_class(**self.image_processor_dict)
            self.assertIsInstance(image_processor, ImageProcessingMixin)
```

أضِف اختبارات مركّزة للسلوك الذي لا يمكن لـ mixin استنتاجه، مثل قواعد تغيير الحجم المخصّصة أو معاملات kwargs الخاصة بالنموذج.

تتوفر اختبارات ما بعد المعالجة في `tests/test_image_processing_common.py` وتُضاف فوق `ImageProcessingTestMixin`.

```py
class MyModelImageProcessingTest(ImageProcessingTestMixin, MyTaskPostProcessTestMixin, unittest.TestCase):
    image_processor_tester_class = MyModelImageProcessingTester
```

تحقّق الاختبارات تلقائيًا من استخدام الميكسينات (mixins) الصحيحة لنموذجك. يجب إضافة الميكسينات للمهام الجديدة إلى `tests/test_image_processing_common.py`.

### اختبارات معالج الفيديو

توجد اختبارات معالج الفيديو عادةً في `tests/models/<model_name>/test_video_processing_<model_name>.py` وتورث من `VideoProcessingTestMixin`. اضبط `fast_video_processing_class`، وحدد `video_processor_dict`، وأعد تعريف `input_name` إذا كان النموذج يستخدم مفتاحًا غير `pixel_values_videos`.

```py
from transformers.testing_utils import require_torch, require_vision
from transformers.utils import is_torchvision_available
from ...test_video_processing_common import VideoProcessingTestMixin

@require_torch
@require_vision
class MyModelVideoProcessingTest(VideoProcessingTestMixin, unittest.TestCase):
    fast_video_processing_class = MyModelVideoProcessor if is_torchvision_available() else None
    input_name = "pixel_values_videos"

    @property
    def video_processor_dict(self):
        return {"size": {"shortest_edge": 224}, "num_frames": 16}
```

أضِف اختبارات فيديو مركّزة لعينة الإطارات، ومعالجة البيانات الوصفية، ومدخلات الفيديو المُفكّكة، ومدخلات قائمة الإطارات، وأبعاد المخرجات. إذا قام المعالج بإعادة تسمية `pixel_values_videos`، فتأكّد من أن المفتاح المُعاد تسميته هو الذي يُعاد.

إذا كان النموذج يحتوي أيضًا على [ProcessorMixin](/docs/transformers/main/ar/main_classes/processors#transformers.ProcessorMixin) يغلّف معالج الصور أو الفيديو، أضف `tests/models/<model_name>/test_processing_<model_name>.py` وارث من `ProcessorTesterMixin`. اضبط `processor_class` وأعد تعريف أساليب الفئة `_setup_<component>()` للمكونات التي لا يمكن إنشاؤها دون حُجج. استخدم `_setup_test_attributes()` لعرض الرموز الوهمية المستخدمة في اختبارات المعالج الشائعة.

```py
from ...test_processing_common import ProcessorTesterMixin

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

    @classmethod
    def _setup_image_processor(cls):
        return cls._get_component_class_from_processor("image_processor")(size={"shortest_edge": 224})

    @classmethod
    def _setup_video_processor(cls):
        return cls._get_component_class_from_processor("video_processor")(num_frames=2)

    @classmethod
    def _setup_test_attributes(cls, processor):
        cls.image_token = getattr(processor, "image_token", "")
        cls.video_token = getattr(processor, "video_token", "")
```

## الخطوات التالية

- اقرأ دليل [توليد توثيق الدوال تلقائيًا](./auto_docstring) لتوليد توثيق متسق تلقائيًا باستخدام `@auto_docstring`.
- اقرأ أدلة [معالجات الصور](./image_processors) و[معالجات الفيديو](./video_processors) لمعرفة سلوك ما قبل المعالجة الموجه للمستخدم.