Adaugă componente de procesare vizuală

Adăugarea unui model vizual necesită componente de procesare a imaginilor sau videoclipurilor pe lângă abordarea standard modulară. Modelele exclusiv pentru imagini au nevoie de procesatoare de imagini, iar modelele video au nevoie de un procesator video, ambele accesibile prin punctele de intrare AutoImageProcessor și AutoVideoProcessor.

Pentru pașii de modelare și configurare, urmează mai întâi ghidul modular.

Procesatoare de imagini

Creează procesatoare de imagini când modelul consumă imagini. Backend-ul torchvision este varianta implicită și suportă accelerarea GPU. PIL este varianta de fallback când torchvision nu este disponibil.

Ambele clase de procesatoare de imagini împart aceeași logică de preprocesare, dar au backend-uri diferite. Semnăturile constructorilor și valorile implicite trebuie să fie identice. AutoImageProcessor.from_pretrained() selectează backend-ul la momentul încărcării și revine la PIL când torchvision nu este disponibil. Semnăturile nepotrivite fac ca același config salvat să se comporte diferit în funcție de mediu.

torchvision

Creează image_processing_<model_name>.py cu o clasă care moștenește din TorchvisionBackend. Dacă procesatorul tău necesită parametri personalizați dincolo de [ImagesKwargs] standard, definește o clasă 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  # orice kwargs specifice modelului

@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)

Vezi LlavaOnevisionImageProcessor ca referință.

PIL

Creează image_processing_pil_<model_name>.py cu o clasă care moștenește din PilBackend. Duplică clasa kwargs aici în loc s-o importezi din fișierul torchvision, pentru că poate eșua când torchvision nu este instalat. Adaugă un comentariu # Adapted from ca cele două să rămână sincronizate. Pentru procesoarele fără parametri personalizați, folosește ImagesKwargs direct.

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

# Adaptat din transformers.models.my_model.image_processing_my_model.MyModelImageProcessorKwargs
class MyModelImageProcessorKwargs(ImagesKwargs, total=False):
    tile_size: int  # orice kwargs specifice modelului

@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)

Vezi LlavaOnevisionImageProcessorPil ca referință.

Procesator video

Adaugă un procesator video când modelul consumă videoclipuri sau cadre video eșantionate.

Creează video_processing_<model_name>.py în folder-ul modelului. BaseVideoProcessor moștenește din TorchvisionBackend și furnizează comportament comun de decodare, eșantionare a cadrelor, redimensionare, rescalare, normalizare, salvare și încărcare.

Atributele de clasă sunt valorile implicite de preprocesare. Utilizatorii le pot suprascrie la inițializare sau la apel. Folosește aceleași nume ca VideosKwargs când e posibil, cum ar fi size, crop_size, do_resize, do_sample_frames, num_frames și fps.

Definește o clasă kwargs dacă procesorul tău video necesită parametri personalizați dincolo de VideosKwargs standard. Seteaz-o ca valid_kwargs și folosește-o ca să adnotezi __init__ atât pentru validarea la rulare, cât și pentru docstring-ul auto-generat.

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)

Suprascrie sample_frames() doar când modelul necesită o regulă de eșantionare pe care eșantionatorul uniform de bază nu o poate exprima. De exemplu, unele modele impun un număr minim sau maxim de cadre sau eșantionează pe baza unor constrângeri specifice modelului.

Dacă metoda forward a modelului așteaptă un nume de input legacy, suprascrie preprocess și redenumește cheia după apelarea implementării de bază.

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

Salvează procesatorul video cu checkpoint-ul instanțiindu-l în scriptul de conversie și apelând save_pretrained(). Dacă un ProcessorMixin dă wrap procesatorului video, apelează save_pretrained() în schimb. Nu crea sau edita manual fișierele de configurație pentru preprocesare.

Vezi Qwen3VLVideoProcessor ca referință.

Înregistrarea claselor

Expune clasele de procesare din __init__.py-ul pachetului modelului. Urmează pattern-ul de import lazy folosit de modelele vecine și protejează importurile cu aceleași dependențe opționale necesare fiecărui backend.

Mapează noile clase la configurația modelului pentru ca clasele Auto să le poată încărca. Fișierul de mapare auto generat are un avertisment la început. Nu îl edita manual. Adaugă sau actualizează configurația modelului, apoi rulează:

python utils/check_auto.py --fix_and_overwrite

După generarea mapării, verifică că tipul de model apare în mapările relevante din src/transformers/models/auto/auto_mappings.py.

• IMAGE_PROCESSOR_MAPPING_NAMES pentru AutoImageProcessor
• VIDEO_PROCESSOR_MAPPING_NAMES pentru AutoVideoProcessor

Testare

Adaugă teste pentru fiecare componentă de procesare vizuală în directorul de teste al modelului. Testele pentru procesoarele de imagini și video urmează același pattern. Moștenești din mixin-ul comun, indici clasele de procesare fast și slow când descoperirea automată nu este suficientă, furnizezi kwargs de inițializare specifice modelului și suprascrii numele inputului când modelul folosește o cheie de ieșire non-implicită.

Teste pentru procesoare de imagini

Testele pentru procesoarele de imagini se află de obicei în tests/models/<model_name>/test_image_processing_<model_name>.py și moștenesc din ImageProcessingTestMixin.

Mixin-ul de procesare a imaginilor găsește clasele de procesoare de imagini din IMAGE_PROCESSOR_MAPPING_NAMES. Expune valorile implicite specifice modelului prin image_processor_dict. Adaugă un obiect tester doar când ai nevoie de input-uri dummy reutilizabile sau metode ajutătoare pentru teste focalizate.

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

@require_torch
@require_vision
class MyModelImageProcessingTest(ImageProcessingTestMixin, unittest.TestCase):
    @property
    def image_processor_dict(self):
        return {"size": {"shortest_edge": 224}, "do_resize": True}

Adaugă teste focalizate pentru comportamentul pe care mixin-ul nu îl poate deduce, cum ar fi regulile de redimensionare personalizate sau kwargs specifice modelului.

Teste pentru procesoare video

Testele pentru procesoarele video trăiesc de obicei în tests/models/<model_name>/test_video_processing_<model_name>.py și moștenesc din VideoProcessingTestMixin. Setează fast_video_processing_class, definește video_processor_dict și suprascrie input_name dacă modelul folosește o altă cheie decât 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}

Adaugă teste video focalizate pentru eșantionarea cadrelor, gestionarea metadatelor, input-urile video decodate, input-urile de tip listă de cadre și formele de ieșire. Dacă procesatorul tău redenumește pixel_values_videos, verifică dacă cheia redenumită este returnată.

Dacă modelul are și un ProcessorMixin care înfășoară procesatorul de imagini sau video, adaugă tests/models/<model_name>/test_processing_<model_name>.py și moștenește din ProcessorTesterMixin. Setează processor_class și suprascrie metodele de clasă _setup_<component>() pentru componentele care nu pot fi construite fără argumente. Folosește _setup_test_attributes() ca să expui token-urile placeholder folosite de testele comune ale procesatorului.

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", "")

Pașii următori

• Citește ghidul Auto-generarea docstring-urilor ca să auto-generezi docstring-uri consistente cu @auto_docstring.
• Citește ghidurile Procesoare de imagini și Procesoare video pentru comportamentul de preprocesare orientat către utilizator.