Transformers documentation

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

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

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

Görüntü modeli eklemek, standart modüler 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 ve AutoVideoProcessor giriş noktalarının arkasından erişilebilir.

Modelleme ve yapılandırma adımları için önce modüler kılavuza bakın.

Görüntü işleyicileri

Model görüntü tükettiğinde görüntü işleyicileri oluşturun. torchvision arka ucu varsayılandır ve GPU hızlandırmayı destekler. PIL, torchvision kullanılamadığında yedek çözümdü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 aynı olmalıdır. AutoImageProcessor.from_pretrained() yüklenme sırasında arka ucu seçer ve torchvision kullanılamadığında PIL'e geri döner. İmzalardaki uyumsuzluklar, aynı kaydedilen yapılandırmanın farklı ortamlarda farklı davranmasına neden olur.

torchvision

image_processing_<model_name>.py dosyasını, 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.

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)

Referans için LlavaOnevisionImageProcessor'a bakın.

PIL

image_processing_pil_<model_name>.py dosyasını, PilBackend sınıfından türeyen bir sınıf içerecek şekilde oluşturun. torchvision yüklü olmadığında hata verebileceği için, kwargs sınıfını torchvision dosyasından içe aktarmak yerine buraya kopyalayın. İki dosyanın senkron kalması için bir # Adapted from yorumu ekleyin. Özel parametreleri olmayan işlemciler için ImagesKwargs sınıfını doğrudan kullanın.

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)

Referans için 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.

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 sınıfından devralır.

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, 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 ile aynı adları kullanın; örneğin size, crop_size, do_resize, do_sample_frames, num_frames ve fps.

Video işleyiciniz standart 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.

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() 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ıtlamalara 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ından sonra anahtarı yeniden adlandırın.

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() çağrılarak kontrol noktasıyla birlikte kaydedin. ProcessorMixin video işleyiciyi sarmalıyorsa, bunun yerine save_pretrained() çağrın. Ön işleme yapılandırma dosyalarını manuel olarak oluşturmaya veya düzenlemeye çalışmayın.

Referans için 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:

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:

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.

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.

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)

Karışımın çıkaramayacağı 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.

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.

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

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

Update on GitHub