Tambahkan komponen pemrosesan visi

Menambahkan model visi memerlukan komponen pemrosesan gambar atau video di atas pendekatan modular standar. Model yang hanya menggunakan gambar memerlukan image processor, sedangkan model video memerlukan video processor, keduanya dapat diakses melalui titik masuk AutoImageProcessor dan AutoVideoProcessor.

Untuk langkah pemodelan dan konfigurasi, ikuti panduan modular terlebih dahulu.

Pemroses gambar

Buat image processor ketika model mengonsumsi gambar. Backend torchvision adalah default dan mendukung akselerasi GPU. PIL adalah fallback ketika torchvision tidak tersedia.

Kedua kelas image processor berbagi logika pra-pemrosesan yang sama tetapi memiliki backend yang berbeda. Tanda tangan konstruktor dan nilai default mereka harus identik. AutoImageProcessor.from_pretrained() memilih backend saat pemuatan dan beralih ke PIL ketika torchvision tidak tersedia. Tanda tangan yang tidak cocok menyebabkan konfigurasi yang disimpan berperilaku berbeda di berbagai lingkungan.

torchvision

Buat image_processing_<model_name>.py dengan kelas yang mewarisi dari TorchvisionBackend. Jika prosesor Anda membutuhkan parameter kustom di luar [ImagesKwargs] standar, definisikan kelas kwargs.

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)

Lihat LlavaOnevisionImageProcessor untuk referensi.

PIL

Buat image_processing_pil_<model_name>.py dengan kelas yang mewarisi dari PilBackend. Duplikat kelas kwargs di sini alih-alih mengimpor dari file torchvision karena dapat gagal saat torchvision tidak terpasang. Tambahkan komentar # Adapted from agar keduanya tetap sinkron. Untuk prosesor tanpa parameter kustom, gunakan ImagesKwargs secara langsung.

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)

Lihat LlavaOnevisionImageProcessorPil untuk referensi.

Tambahkan metode pasca-pemrosesan

Tambahkan metode pascaproses langsung ke kelas prosesor. Metode pascaproses dipanggil dengan keluaran model (outputs) dan argumen tambahan apa pun yang diperlukan untuk metode pascaproses tertentu.

class MyModelImageProcessor(TorchvisionBackend):
    ...

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

Post-processor mengembalikan daftar objek sederhana (list[str] atau list[torch.Tensor]) atau daftar objek kompleks (list[MyTaskPostProcessorOutput] atau list[dict]). Output post-processor didefinisikan di src/transformers/image_processing_outputs.py dan mewarisi dari BatchFeature.

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

Pemroses video

Tambahkan video processor ketika model mengonsumsi video atau bingkai video yang disampelkan.

Buat video_processing_<model_name>.py di direktori model. BaseVideoProcessor mewarisi dari TorchvisionBackend dan menyediakan perilaku bersama untuk decoding, pengambilan sampel frame, pengubahan ukuran, penskalaan ulang, normalisasi, penyimpanan, dan pemuatan.

Atribut kelas adalah nilai pra-pemrosesan default. Pengguna dapat menimpanya saat inisialisasi atau saat pemanggilan. Gunakan nama yang sama dengan VideosKwargs jika memungkinkan, seperti size, crop_size, do_resize, do_sample_frames, num_frames, dan fps.

Definisikan kelas kwargs jika video processor Anda memerlukan parameter kustom di luar VideosKwargs standar. Atur sebagai valid_kwargs dan gunakan untuk mengannotasi __init__ untuk validasi runtime dan docstring yang dibuat otomatis.

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)

Override sample_frames() hanya ketika model memerlukan aturan sampling yang tidak dapat diekspresikan oleh sampler uniform dasar. Sebagai contoh, beberapa model menerapkan jumlah minimum atau maksimum frame, atau melakukan sampling berdasarkan kendala yang spesifik pada model.

Jika metode forward model mengharapkan nama input lama, timpa preprocess dan ubah nama kunci setelah memanggil implementasi dasar.

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

Simpan video processor bersama checkpoint dengan menginstansiasikannya di skrip konversi dan memanggil save_pretrained(). Jika ProcessorMixin membungkus video processor, panggil save_pretrained() sebagai gantinya. Jangan membuat atau mengedit file konfigurasi pra-pemrosesan secara manual.

Lihat Qwen3VLVideoProcessor untuk referensi.

Daftarkan kelas

Tambahkan kelas baru ke __all__ di bagian bawah file, lalu buat ulang __init__.py dengan:

python utils/check_inits.py --fix_and_overwrite

Petakan kelas baru ke konfigurasi model agar kelas Auto dapat memuatnya. File pemetaan auto yang dihasilkan memiliki peringatan di bagian atas. Jangan mengeditnya secara manual. Tambahkan atau perbarui konfigurasi model, lalu jalankan:

python utils/check_auto.py --fix_and_overwrite

Setelah pemetaan dibuat, pastikan tipe model muncul dalam pemetaan yang relevan di src/transformers/models/auto/auto_mappings.py.

IMAGE_PROCESSOR_MAPPING_NAMES untuk AutoImageProcessor
VIDEO_PROCESSOR_MAPPING_NAMES untuk AutoVideoProcessor

Pengujian

Tambahkan tes untuk setiap komponen pemrosesan visi di direktori tes model. Gunakan mixin tes bersama dan berikan kwargs inisialisasi yang spesifik untuk model. Tes gambar menemukan backend prosesor secara otomatis melalui tester bersama, sedangkan tes video mengonfigurasi kelas prosesor dan fixture secara eksplisit.

Uji pemroses gambar

Uji pemroses gambar berada di tests/models/<model_name>/test_image_processing_<model_name>.py. Definisikan tester yang mewarisi dari ImageProcessingTester dan kelas uji yang mewarisi dari ImageProcessingTestMixin dan unittest.TestCase.

Tester pemrosesan gambar mendefinisikan atribut uji default seperti argumen inisialisasi prosesor dan parameter untuk membuat input acak untuk pengujian. Hanya timpa argumen jika seharusnya berbeda dari default prosesor gambar. Misalnya, kami biasanya menguji dengan ukuran gambar yang lebih kecil agar pengujian tetap cepat. Kelas prosesor gambar disimpulkan secara otomatis dari IMAGE_PROCESSOR_MAPPING_NAMES.

Set image_processor_tester_class pada kelas pengujian. Mixin membuat self.image_processor_tester dan sudah mencakup sebagian besar metode pengujian yang diperlukan.

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)

Tambahkan pengujian yang berfokus pada perilaku yang tidak dapat disimpulkan oleh mixin, seperti aturan pengubahan ukuran kustom atau kwargs yang spesifik untuk model.

Mixin pengujian pasca-pemrosesan tersedia di tests/test_image_processing_common.py dan ditambahkan di atas ImageProcessingTestMixin.

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

Uji coba secara otomatis memverifikasi bahwa mixin yang benar digunakan untuk model Anda. Mixin untuk tugas baru harus ditambahkan ke tests/test_image_processing_common.py.

Uji pemroses video

Uji pemroses video biasanya berada di tests/models/<model_name>/test_video_processing_<model_name>.py dan mewarisi dari VideoProcessingTestMixin. Atur fast_video_processing_class, definisikan video_processor_dict, dan timpa input_name jika model menggunakan kunci selain pixel_values_videos.

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}

Tambahkan pengujian video yang berfokus pada pengambilan sampel frame, penanganan metadata, input video yang telah didekode, input berupa daftar frame, dan bentuk output. Jika prosesor Anda mengganti nama pixel_values_videos, pastikan kunci yang telah diganti nama tersebut dikembalikan.

Jika model juga memiliki ProcessorMixin yang membungkus prosesor gambar atau video, tambahkan tests/models/<model_name>/test_processing_<model_name>.py dan warisi dari ProcessorTesterMixin. Atur processor_class dan timpa metode kelas _setup_<component>() untuk komponen yang tidak dapat dikonstruksi tanpa argumen. Gunakan _setup_test_attributes() untuk mengekspos token placeholder yang digunakan oleh tes prosesor umum.

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

Langkah selanjutnya

Baca panduan Menghasilkan docstring secara otomatis untuk menghasilkan docstring yang konsisten secara otomatis dengan @auto_docstring.
Baca panduan Image processors dan Video processors untuk perilaku pra-pemrosesan yang berorientasi pada pengguna.

Update on GitHub

Transformers

Tambahkan komponen pemrosesan visi

Pemroses gambar

torchvision

PIL

Tambahkan metode pasca-pemrosesan

Pemroses video

Daftarkan kelas

Pengujian

Uji pemroses gambar

Uji pemroses video

Langkah selanjutnya