Transformers documentation
المعالجات متعددة الوسائط
المعالجات متعددة الوسائط
يجمع المُعالِج بين مُجزِّئ (tokenizer) ومعالِج واحد أو أكثر للأنماط (modality processors)، مثل مُعالِج الصور أو مُعالِج الفيديو أو مستخرج الميزات. يعرّض طريقة __call__ واحدة تُوجّه كل مدخل إلى المكوّن المناسب وتدمج المخرجات في قاموس واحد.
تقوم بعض النماذج متعددة الوسائط بتبديل النص مع الصور أو مقاطع الفيديو أو الصوت. ولأغراض هذه النماذج، يمكن لـ ProcessorMixin استبدال الرموز الوهمية مثل <image> و<video> و<audio> بنمط الرموز الذي يتوقعه النموذج.
إضافة معالج جديد
حدد فئة المعالج (processor) من خلال إنشاء src/transformers/models/<model>/processing_<my_model_name>.py وإرث فئة ProcessorMixin. تأكد من تعريف كائن TypedDict بقيم افتراضية وتعيينه كـ cls.valid_processor_kwargs
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 غير مضبوط، وستتخطى الفئة الأساسية عملية الاستبدال بالكامل.
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. إذا كان النموذج يتطلب بنية إدخال محددة قبل بدء المعالجة، مثل إعادة ترتيب الصور كقائمة متداخلة، أو التحقق من صحة خاص بالنموذج فوق الفحوصات الشائعة.
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}."
)راجع Gemma4Processor و Qwen2VLProcessor للاطلاع على التفاصيل.
إضافة حُجج مخصصة
هناك ثلاث طرق لإضافة حُجج مخصصة إلى المعالج:
| أين تضيف | يُستخدم | القيمة الافتراضية | قابلة للتهيئة وقت التشغيل | مثال |
|---|---|---|---|---|
__init__ | الإعدادات المحفوظة في ملف الإعداد (خصائص النموذج) | عادةً ما يكون له قيمة افتراضية | لا | image_seq_length في Gemma3Processor |
__call__ | المدخلات التي لا تُعرف إلا وقت التشغيل | لا يوجد افتراضي أو None | نعم | images، labels، suffix، وما إلى ذلك. |
فئة MyModelProcessingKwargs مخصصة | الإعدادات التي يمكن تكوينها وقت التشغيل | تعيينه كخاصية لفئة المعالج | نعم | use_image_id في MiniCPMV4_7Processor |
يجب إضافة حُجج وقت التشغيل التي يمكن أن تمتلك قيمة افتراضية إلى MyModelProcessingKwargs مخصص، وستُمرر كجزء من **kwargs إلى __call__. يمكن تعيين القيم الافتراضية لهذه القيم كخصائص لفئة المعالج. وبالمثل، يمكن تعريف القيم الافتراضية لمعالجات محددة حسب النمط، مثل مُرمّز النص أو مُعالج الصور. وعادةً لا يكون هذا ضروريًا لأن معالجات النمط المحدد تمتلك بالفعل قيمًا افتراضية معرّفة في فئاتها الخاصة. استخدم هذا الخيار فقط إذا كان المعالج يجب أن يتجاوز إعدادًا لمعالج نمط محدد. وبالطبع، فإن الحُجج الممررة وقت التشغيل إلى __call__ لها دائمًا أولوية أعلى من أي قيم افتراضية.
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. يوفر هذا المزيج مجموعة قياسية تغطي الترميز، ومعالجة الصور، والتجميع، والتشفير ذهاباً وإياباً.
# 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")