# Görüntü işleme bileşenleri ekleyin

Görüntü modeli eklemek, standart [modüler](./modular_transformers) yaklaşımın üzerine görüntü veya video işleme bileşenleri gerektirir. Sadece görüntü modelleri görüntü işleyicileri, video modelleri ise video işleyicileri gerektirir; her ikisi de [AutoImageProcessor](/docs/transformers/v5.23.0/tr/model_doc/auto#transformers.AutoImageProcessor) ve [AutoVideoProcessor](/docs/transformers/v5.23.0/tr/model_doc/auto#transformers.AutoVideoProcessor) giriş noktalarının arkasından erişilebilir.

> [!NOTE]
> Modelleme ve yapılandırma adımları için önce [modüler](./modular_transformers) kılavuza bakın.

## Görüntü işleyicileri

Model görüntü tükettiğinde görüntü işleyicileri oluşturun. [torchvision](https://docs.pytorch.org/vision/stable/index.html) arka ucu varsayılandır ve GPU hızlandırmayı destekler. [PIL](https://pillow.readthedocs.io/en/stable/index.html), torchvision kullanılamadığında yedek olarak kullanılır.

Her iki görüntü işleyici sınıfı da aynı ön işleme mantığını paylaşır ancak farklı arka uçlara sahiptir. Oluşturucu imzaları ve varsayılan değerleri birebir aynı olmalıdır. [AutoImageProcessor.from_pretrained()](/docs/transformers/v5.23.0/tr/model_doc/auto#transformers.AutoImageProcessor.from_pretrained) yüklenme sırasında arka ucu seçer ve torchvision kullanılamadığında PIL'e geri düşer. İmzalardaki uyumsuzluklar, aynı kaydedilmiş yapılandırmanın farklı ortamlarda farklı davranmasına neden olur.

### torchvision

`image_processing_<model_name>.py` dosyasını, [TorchvisionBackend](/docs/transformers/v5.23.0/tr/main_classes/image_processor#transformers.TorchvisionBackend) sınıfından türeyen bir sınıf içerecek şekilde oluşturun. İşleyiciniz standart [ImagesKwargs] dışında özel parametrelere ihtiyaç duyuyorsa, bir kwargs sınıfı tanımlayın.

```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]
> Referans için [LlavaOnevisionImageProcessor](/docs/transformers/v5.23.0/tr/model_doc/llava_onevision#transformers.LlavaOnevisionImageProcessor)'a bakın.

### PIL

`image_processing_pil_<model_name>.py` dosyasını, [PilBackend](/docs/transformers/v5.23.0/tr/main_classes/image_processor#transformers.PilBackend) sınıfından türeyen bir sınıf içerecek şekilde oluşturun. torchvision yüklü olmadığında hata verebileceğinden, kwargs sınıfını torchvision dosyasından içe aktarmak yerine burada kopyalayın. İki dosyanın senkron kalması için bir `# Adapted from` yorumu ekleyin. Özel parametreleri olmayan işleyiciler için [ImagesKwargs](/docs/transformers/v5.23.0/tr/main_classes/processors#transformers.ImagesKwargs) sınıfını doğrudan kullanın.

```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]
> Referans için [LlavaOnevisionImageProcessorPil](/docs/transformers/v5.23.0/tr/model_doc/llava_onevision#transformers.LlavaOnevisionImageProcessorPil) sayfasına bakın.

### Son işleme yöntemleri ekleyin

Son işleme yöntemlerini doğrudan işlemci sınıfına ekleyin. Son işleme yöntemleri, model çıktılarını (`outputs`) ve ilgili son işleme yöntemi için gerekli ek argümanları alır.

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

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

Post-processors, basit nesnelerin (`list[str]` veya `list[torch.Tensor]`) ya da karmaşık nesnelerin (`list[MyTaskPostProcessorOutput]` veya `list[dict]`) listesini döndürür. Post-processor çıktıları `src/transformers/image_processing_outputs.py` içinde tanımlanır ve [BatchFeature](/docs/transformers/v5.23.0/tr/main_classes/feature_extractor#transformers.BatchFeature) sınıfından devralır.

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

## Video işleyici

Model videoları veya örneklenmiş video karelerini işliyorsa bir video işlemci ekleyin.

Model dizininde `video_processing_<model_name>.py` dosyasını oluşturun. [BaseVideoProcessor](/docs/transformers/v5.23.0/tr/main_classes/video_processor#transformers.BaseVideoProcessor), [TorchvisionBackend](/docs/transformers/v5.23.0/tr/main_classes/image_processor#transformers.TorchvisionBackend) sınıfından devralır ve ortak çözümleme, kare örneklemesi, yeniden boyutlandırma, yeniden ölçekleme, normalizasyon, kaydetme ve yükleme davranışlarını sağlar.

Sınıf öznitelikleri varsayılan ön işleme değerleridir. Kullanıcılar bunları başlatma veya çağrı anında geçersiz kılabilir. Mümkün olduğunda [VideosKwargs](/docs/transformers/v5.23.0/tr/main_classes/processors#transformers.VideosKwargs) ile aynı adları kullanın; örneğin `size`, `crop_size`, `do_resize`, `do_sample_frames`, `num_frames` ve `fps`.

Video işleyiciniz standart [VideosKwargs](/docs/transformers/v5.23.0/tr/main_classes/processors#transformers.VideosKwargs) dışında özel parametrelere ihtiyaç duyuyorsa bir kwargs sınıfı tanımlayın. Bunu `valid_kwargs` olarak ayarlayın ve hem çalışma zamanı doğrulama hem de otomatik oluşturulan dokümantasyon dizgesi için `__init__` işaretlemesinde kullanın.

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

Model, taban uniform örnekleyicinin ifade edemediği bir örneklem kuralı gerektirdiğinde yalnızca [sample_frames()](/docs/transformers/v5.23.0/tr/main_classes/video_processor#transformers.BaseVideoProcessor.sample_frames) işlevini geçersiz kılın. Örneğin, bazı modeller minimum veya maksimum kare sayısını zorunlu tutar veya modele özgü kısıtlara dayalı olarak örneklem yapar.

Modelin forward metodu eski bir girdi adı bekliyorsa, `preprocess` metodunu geçersiz kılın ve temel uygulamanın çağrılmasının ardından anahtarı yeniden adlandırın.

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

Video işleyiciyi, dönüştürme betiğinde örnekleyerek ve [save_pretrained()](/docs/transformers/v5.23.0/tr/main_classes/video_processor#transformers.VideoProcessorMixin.save_pretrained) çağrılarak kontrol noktasıyla birlikte kaydedin. [ProcessorMixin](/docs/transformers/v5.23.0/tr/main_classes/processors#transformers.ProcessorMixin) video işleyiciyi sarmalıyorsa, bunun yerine [save_pretrained()](/docs/transformers/v5.23.0/tr/model_doc/wav2vec2#transformers.Wav2Vec2Processor.save_pretrained) çağrın. Ön işleme yapılandırma dosyalarını manuel olarak oluşturmaya veya düzenlemeye çalışmayın.

> [!TIP]
> Referans için [Qwen3VLVideoProcessor](/docs/transformers/v5.23.0/tr/model_doc/qwen3_vl#transformers.Qwen3VLVideoProcessor)'a bakın.

## Sınıfları kaydet

Yeni sınıfları dosyanın altındaki `__all__` listesine ekleyin, ardından `__init__.py` dosyasını şu komutla yeniden oluşturun:

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

Yeni sınıfları, `Auto` sınıflarının bunları yükleyebilmesi için model yapılandırmasına eşleyin. Oluşturulan otomatik eşleme dosyasının başında bir uyarı bulunur. Bunu elle düzenlemeyin. Model yapılandırmasını ekleyin veya güncelleyin, ardından şunu çalıştırın:

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

Eşleme oluşturulduktan sonra, model türünün `src/transformers/models/auto/auto_mappings.py` içindeki ilgili eşlemelerde göründüğünü doğrulayın.

- [AutoImageProcessor](/docs/transformers/v5.23.0/tr/model_doc/auto#transformers.AutoImageProcessor) için `IMAGE_PROCESSOR_MAPPING_NAMES`
- [AutoVideoProcessor](/docs/transformers/v5.23.0/tr/model_doc/auto#transformers.AutoVideoProcessor) için `VIDEO_PROCESSOR_MAPPING_NAMES`

## Test

Model test dizininde, modeldeki her bir görme işleme bileşeni için testler ekleyin. Ortak test karışımlarını (mixins) kullanın ve modele özgü başlatma (initialization) anahtar kelime argümanlarını (kwargs) sağlayın. Görüntü testleri, ortak bir test edici (tester) aracılığıyla işlemci (processor) arka uçlarını otomatik olarak keşfederken, video testleri işlemci sınıfını ve sabitlerini (fixtures) açıkça yapılandırır.

### Görüntü işleyici testleri

Görüntü işleyici testleri `tests/models/<model_name>/test_image_processing_<model_name>.py` dosyasında bulunur. `ImageProcessingTester` sınıfından türeyen bir tester ve `ImageProcessingTestMixin` ile `unittest.TestCase` sınıflarından türeyen bir test sınıfı tanımlayın.

Görüntü işleme test edicisi, testler için rastgele girdiler oluşturmak üzere işlemci başlatma argümanları ve parametreleri gibi varsayılan test özniteliklerini tanımlar. Argümanları yalnızca görüntü işlemcisi varsayılanlarından farklı olmaları gerekiyorsa geçersiz kılın. Örneğin, testlerin hızlı kalmasını sağlamak için genellikle daha küçük görüntü boyutlarıyla test edilir. Görüntü işlemci sınıfları `IMAGE_PROCESSOR_MAPPING_NAMES` içinden otomatik olarak çıkarılır.

Test sınıfında `image_processor_tester_class` değerini ayarlayın. Mixin, `self.image_processor_tester` nesnesini oluşturur ve gerekli test yöntemlerinin çoğunu zaten kapsar.

```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'in çıkarılamayacağı davranışlar için, örneğin özel yeniden boyutlandırma kuralları veya modele özgü kwargs gibi, odaklı testler ekleyin.

Son işleme test karışımları `tests/test_image_processing_common.py` dosyasında mevcuttur ve `ImageProcessingTestMixin` üzerine eklenir.

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

Testler, modeliniz için doğru mixin'lerin kullanıldığını otomatik olarak doğrular. Yeni görevler için mixin'ler `tests/test_image_processing_common.py` dosyasına eklenmelidir.

### Video işleyici testleri

Video işlemci testleri genellikle `tests/models/<model_name>/test_video_processing_<model_name>.py` dosyasında bulunur ve `VideoProcessingTestMixin` sınıfından devralır. `fast_video_processing_class` değerini ayarlayın, `video_processor_dict` değişkenini tanımlayın ve model `pixel_values_videos` dışında bir anahtar kullanıyorsa `input_name` değerini geçersiz kılın.

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

Çerçeve örneklemesi, meta veri işleme, çözümlenmiş video girdileri, çerçeve listesi girdileri ve çıktı şekilleri için odaklı video testleri ekleyin. İşleyiciniz `pixel_values_videos` anahtarını yeniden adlandırıyorsa, yeniden adlandırılan anahtarın döndürüldüğünü doğrulayın.

Eğer modelin, görüntü veya video işleyicisini saran bir [ProcessorMixin](/docs/transformers/v5.23.0/tr/main_classes/processors#transformers.ProcessorMixin) de varsa, `tests/models/<model_name>/test_processing_<model_name>.py` dosyasını ekleyin ve `ProcessorTesterMixin` sınıfından türetin. `processor_class` değerini ayarlayın ve argümansız oluşturulamayan bileşenler için `_setup_<component>()` sınıf yöntemlerini geçersiz kılın. Ortak işleyici testlerinde kullanılan yer tutucu jetonları (placeholder tokens) açığa çıkarmak için `_setup_test_attributes()` yöntemini kullanın.

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

## Sonraki adımlar

- Tutarlı docstring'leri `@auto_docstring` ile otomatik oluşturmak için [Docstring'leri otomatik oluşturma](./auto_docstring) kılavuzunu okuyun.
- Kullanıcı odaklı ön işleme davranışı için [Görsel işleyiciler](./image_processors) ve [Video işleyiciler](./video_processors) kılavuzlarını okuyun.

