Transformers documentation

Çok modlu işlemciler

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Çok modlu işlemciler

Bir processor, bir tokenizer ile bir veya daha fazla modalite işleyicisini (örneğin bir image processor, video processor veya feature extractor) bir araya getirir. Her girdiyi doğru bileşene yönlendiren ve çıktıları tek bir sözlükte birleştiren tek bir __call__ metodu sunar.

Bazı çok modlu modeller, metni görseller, videolar veya ses ile iç içe geçirir. Bu modeller için ProcessorMixin, <image>, <video> ve <audio> gibi yer tutucu token'ları, modelin beklediği token desenleriyle değiştirebilir.

Yeni bir işlemci ekleme

src/transformers/models/<model>/processing_<my_model_name>.py dosyasını oluşturarak ve ProcessorMixin sınıfından türeterek bir işlemci sınıfı tanımlayın. Varsayılan değerlere sahip bir TypedDict nesnesi tanımlamayı ve bunu cls.valid_processor_kwargs olarak atamayı unutmayın.

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

Gerekirse replace_<modality>_token fonksiyonunu uygulayın. Bu fonksiyon, alt işleyiciden (subprocessor) gelen tam çıktı sözlüğünü ve mevcut girdinin indeksini alır ve o girdi için genişletilmiş değiştirme (replacement) dizesini döndürür. Değiştirme dizesi, modelin girdi dizisinde beklediği her şeydir.

Eğer model placeholder tekrarı hiç kullanmıyorsa (image_token tanımlı değilse), bu yöntemi geçersiz kılmak zorunda değilsiniz. self.image_token değerini ayarlamadan bırakın ve temel sınıf değiştirme işlemini tamamen atlar.

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

İsteğe bağlı olarak prepare_inputs_layout ve validate_inputs yöntemlerini geçersiz kılın. Model, işleme başlamadan önce belirli bir giriş yapısı gerektiriyorsa, örneğin görselleri iç içe geçmiş bir liste olarak yeniden sıralamak veya genel kontrollerin üzerine model özelinde bir doğrulama yapmak gerekiyorsa bu yöntemleri kullanın.

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}."
            )

Referans olarak Gemma4Processor ve Qwen2VLProcessor sınıflarına bakın.

Özel argümanlar ekleme

İşleyiciye özel argüman eklemenin üç yolu vardır:

Nereye eklenirKullanım alanıVarsayılan değerÇalışma zamanında yapılandırılabilirÖrnek
__init__Yapılandırmada (model özellikleri) kaydedilen ayarlarGenellikle bir varsayılan değer içerirHayırGemma3Processor içindeki image_seq_length
__call__Yalnızca çalışma zamanında bilinen girdilerVarsayılan veya None yokEvetimages, labels, suffix vb.
Özel MyModelProcessingKwargs sınıfıÇalışma zamanında yapılandırılabilen ayarlarİşleyici sınıf özniteliği olarak ayarlaEvetMiniCPMV4_7Processor içindeki use_image_id

Varsayılan değere sahip olabilecek çalışma zamanı argümanları, özel bir MyModelProcessingKwargs sınıfına eklenmeli ve __call__ metoduna **kwargs parçası olarak iletilmelidir. Bu değerlerin varsayılanları, işlemci sınıf öznitelikleri olarak ayarlanabilir. Örneğin, belirleyiciye özgü işlemciler için (tokenizör veya görüntü işlemcisi gibi) varsayılanlar da aynı şekilde tanımlanabilir. Bu genellikle gerekmez, çünkü belirleyiciye özgü işlemcilerin kendi sınıflarında zaten varsayılanları tanımlıdır. Bu seçeneği yalnızca işlemcinin, belirleyiciye özgü bir işlemci ayarını geçersiz kılması gerekiyorsa kullanın. Elbette, __call__ metoduna çalışma zamanında iletilen argümanların her zaman tüm varsayılanlardan daha yüksek önceliğe sahip olduğu unutulmamalıdır.

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`

Test

Tüm çok modlu işlemciler, ProcessorTesterMixin'den türeyen bir test sınıfına sahip olmalıdır. Bu mixin, tokenizasyon, görüntü işleme, toplu işlem (batching) ve gidiş-dönüş kodlamayı kapsayan standart bir test paketi sağlar.

# 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")
Update on GitHub