Transformers documentation

Pemroses multimodal

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Pemroses multimodal

Processor menggabungkan tokenizer dengan satu atau beberapa pemroses modalitas, seperti image processor, video processor, atau feature extractor. Ia mengekspos satu metode __call__ yang mengarahkan setiap input ke komponen yang tepat dan menggabungkan output menjadi satu dictionary.

Beberapa model multimodal menyisipkan teks dengan gambar, video, atau audio. Untuk model-model ini, ProcessorMixin dapat mengganti token placeholder seperti <image>, <video>, dan <audio> dengan pola token yang diharapkan oleh model.

Menambahkan prosesor baru

Definisikan kelas prosesor dengan membuat src/transformers/models/<model>/processing_<my_model_name>.py dan subclass ProcessorMixin. Pastikan untuk mendefinisikan objek TypedDict dengan nilai default dan menugaskannya sebagai cls.valid_processor_kwargs

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

Implementasikan replace_<modality>_token jika diperlukan. Fungsi ini menerima dict output lengkap dari subprocessor dan indeks dari input saat ini, lalu mengembalikan string penggantian yang telah diperluas untuk input tersebut. String penggantian adalah apa pun yang diharapkan oleh model dalam urutan input.

Jika model sama sekali tidak menggunakan pengulangan placeholder (tidak ada image_token yang didefinisikan), Anda tidak perlu menimpa metode ini. Biarkan self.image_token tidak disetel dan kelas dasar akan sepenuhnya melewati proses penggantian.

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

Secara opsional, timpa metode prepare_inputs_layout dan validate_inputs. Jika model memerlukan struktur input tertentu sebelum pemrosesan dimulai, seperti pengurutan ulang gambar sebagai daftar bersarang, atau validasi spesifik model di atas pemeriksaan umum.

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

Lihat Gemma4Processor dan Qwen2VLProcessor sebagai referensi.

Menambahkan argumen kustom

Ada tiga cara untuk menambahkan argumen kustom ke sebuah processor:

Di mana harus ditambahkanDigunakan untukNilai defaultDapat dikonfigurasi saat runtimeContoh
__init__Pengaturan yang disimpan dalam config (properti model)Biasanya memiliki nilai defaultTidakimage_seq_length di Gemma3Processor
__call__Input yang hanya diketahui saat runtimeTidak ada default atau NoneYaimages, labels, suffix, dan sebagainya.
Kelas MyModelProcessingKwargs kustomPengaturan yang dapat dikonfigurasi saat runtimeSet sebagai atribut kelas processorYause_image_id di MiniCPMV4_7Processor

Argumen runtime yang dapat memiliki nilai default harus ditambahkan ke MyModelProcessingKwargs kustom dan akan diteruskan sebagai bagian dari **kwargs ke __call__. Nilai default untuk nilai-nilai ini dapat diset sebagai atribut kelas prosesor. Nilai default untuk prosesor yang spesifik pada modalitas, misalnya tokenizer atau image processor, dapat didefinisikan dengan cara yang sama. Hal ini biasanya tidak diperlukan karena prosesor yang spesifik pada modalitas sudah memiliki nilai default yang didefinisikan di kelas masing-masing. Gunakan opsi ini hanya jika prosesor harus menimpa pengaturan prosesor yang spesifik pada modalitas. Tentu saja, argumen yang diteruskan saat runtime ke __call__ selalu memiliki prioritas lebih tinggi daripada nilai default apa pun.

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`

Pengujian

Semua pemroses multimodal harus memiliki kelas uji yang mewarisi dari ProcessorTesterMixin. Mixin ini menyediakan serangkaian standar yang mencakup tokenisasi, pemrosesan gambar, batching, dan pengodean bolak-balik.

# 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