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

يتطلب إضافة نموذج رؤية مكوّنات معالجة الصور أو الفيديو إلى جانب النهج المنفصل القياسي. تحتاج النماذج التي تعمل بالصور فقط إلى معالجات صور، بينما تحتاج نماذج الفيديو إلى معالج فيديو، وكلاهما متاح خلف نقاط الدخول AutoImageProcessor وAutoVideoProcessor.

لخطوات النمذجة والإعداد، اتبع أولاً دليل modular.

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

أنشئ معالجات الصور عندما يستهلك النموذج صورًا. الخلفية torchvision هي الافتراضية وتدعم تسريع وحدة معالجة الرسوميات. PIL هو الخيار البديل عندما لا يتوفر torchvision.

تشارك كلا فئتي معالج الصور منطق ما قبل المعالجة نفسه، لكنهما تستخدمان واجهات خلفية مختلفة. يجب أن تكون توقيعات منشئيهما والقيم الافتراضية لهما متطابقة. يختار AutoImageProcessor.from_pretrained() الواجهة الخلفية عند التحميل، ويلجأ إلى PIL عندما لا يكون torchvision متاحًا. يؤدي عدم تطابق التوقيعات إلى اختلاف سلوك نفس الإعداد المحفوظ عبر البيئات المختلفة.

torchvision

أنشئ image_processing_<model_name>.py يحتوي على فئة ترث من TorchvisionBackend. إذا كان المعالج الخاص بك يحتاج إلى معاملات مخصصة تتجاوز المعايير القياسية [ImagesKwargs]، فعرّف فئة kwargs.

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)

راجع LlavaOnevisionImageProcessor للاطلاع على التفاصيل.

PIL

أنشئ image_processing_pil_<model_name>.py بفئة ترث من PilBackend. انسخ فئة kwargs هنا بدلاً من استيرادها من ملف torchvision لأن ذلك قد يفشل عند عدم تثبيت torchvision. أضف تعليق # Adapted from حتى تبقى النسختان متزامنتين. بالنسبة للمعالجات التي لا تحتوي على معاملات مخصصة، استخدم ImagesKwargs مباشرة.

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)

راجع LlavaOnevisionImageProcessorPil للاطلاع على التفاصيل.

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

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

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.

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

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

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

أنشئ video_processing_<model_name>.py في مجلد النموذج. يرث BaseVideoProcessor من TorchvisionBackend ويوفر سلوكًا مشتركًا لفك الترميز، وعيّنات الإطارات، وتغيير الحجم، وإعادة المقياس، والتطبيع، والحفظ، والتحميل.

تُمثّل سمات الفئة قيم المعالجة المسبقة الافتراضية. يمكن للمستخدمين تجاوزها عند التهيئة أو عند الاستدعاء. استخدم نفس أسماء VideosKwargs كلما أمكن ذلك، مثل size وcrop_size وdo_resize وdo_sample_frames وnum_frames وfps.

حدد فئة kwargs إذا كان معالج الفيديو الخاص بك يحتاج إلى معاملات مخصصة تتجاوز المعايير القياسية VideosKwargs. اضبطها كـ valid_kwargs واستخدمها لتعليق __init__ من أجل التحقق في وقت التشغيل وتوليد التوثيق تلقائيًا.

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() فقط عندما يتطلب النموذج قاعدة أخذ عينات لا يمكن للمُعيّن المنتظم الأساسي التعبير عنها. على سبيل المثال، تفرض بعض النماذج حدًا أدنى أو أقصى لعدد الإطارات، أو تأخذ العينات بناءً على قيود خاصة بالنموذج.

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

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(). إذا كان ProcessorMixin يغلّف معالج الفيديو، فاستدعِ save_pretrained() بدلاً من ذلك. لا تنشئ أو تحرر ملفات إعدادات ما قبل المعالجة يدوياً.

راجع Qwen3VLVideoProcessor للاطلاع على التفاصيل.

تسجيل الفئات

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

python utils/check_inits.py --fix_and_overwrite

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

python utils/check_auto.py --fix_and_overwrite

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

• IMAGE_PROCESSOR_MAPPING_NAMES لـ AutoImageProcessor
• VIDEO_PROCESSOR_MAPPING_NAMES لـ 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 ويغطي بالفعل معظم طرق الاختبار المطلوبة.

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.

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.

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 الذي يغلّف معالج الصور أو الفيديو، أضف tests/models/<model_name>/test_processing_<model_name>.py وارث من ProcessorTesterMixin. اضبط processor_class وأعد تعريف طرق الفئة _setup_<component>() للمكونات التي لا يمكن إنشاؤها دون حُجج. استخدم _setup_test_attributes() لعرض الرموز الوهمية المستخدمة في اختبارات المعالج الشائعة.

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.
• اقرأ أدلة معالجات الصور ومعالجات الفيديو لمعرفة سلوك ما قبل المعالجة الموجه للمستخدم.