transformers/main/ro/add_vision_processing_components.md

# Adaugă componente de procesare vizuală

Adăugarea unui model vizual necesită componente de procesare a imaginilor sau videoclipurilor pe lângă abordarea standard [modulară](./modular_transformers). 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`.

> [!NOTE]
> Pentru pașii de modelare și configurare, urmează mai întâi ghidul [modular](./modular_transformers).

## Procesatoare de imagini

Creează procesatoare de imagini când modelul consumă imagini. Backend-ul [torchvision](https://docs.pytorch.org/vision/stable/index.html) este varianta implicită și suportă accelerarea GPU. [PIL](https://pillow.readthedocs.io/en/stable/index.html) 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.

```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  # 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)
```

> [!TIP]
> 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.

```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

# 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)
```

> [!TIP]
> 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.

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

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ă.

```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
```

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.

> [!TIP]
> 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ă:

```bash
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.

```py
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`.

```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}
```

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.

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

## Pașii următori

- Citește ghidul [Auto-generarea docstring-urilor](./auto_docstring) ca să auto-generezi docstring-uri consistente cu `@auto_docstring`.
- Citește ghidurile [Procesoare de imagini](./image_processors) și [Procesoare video](./video_processors) pentru comportamentul de preprocesare orientat către utilizator.