Добавление компонентов обработки изображений

Добавление модели зрения требует компонентов для обработки изображений или видео в дополнение к стандартному модульному подходу. Модели, работающие только с изображениями, нуждаются в процессоре изображений, а модели для видео — в процессоре видео; оба доступны через точки входа AutoImageProcessor и AutoVideoProcessor.

Для шагов моделирования и конфигурации сначала следуйте модульному руководству.

Обработчики изображений

Создавайте обработчики изображений, когда модель принимает изображения в качестве входных данных. Бэкенд torchvision используется по умолчанию и поддерживает ускорение на GPU. PIL применяется как запасной вариант, если torchvision недоступен.

Оба класса процессоров изображений используют одинаковую логику предобработки, но имеют разные бэкенды. Их сигнатуры конструкторов и значения по умолчанию должны быть идентичны. AutoImageProcessor.from_pretrained() выбирает бэкенд при загрузке и переключается на PIL, если torchvision недоступен. Несовпадение сигнатур приводит к тому, что один и тот же сохранённый конфиг ведёт себя по-разному в разных средах.

torchvision

Создайте image_processing_<model_name>.py с классом, наследующим от TorchvisionBackend. Если вашему процессору требуются дополнительные параметры помимо стандартных [ImagesKwargs], определите класс 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)

См. LlavaOnevisionImageProcessor для справки.

PIL

Создайте image_processing_pil_<model_name>.py с классом, наследующим от PilBackend. Дублируйте здесь класс kwargs, а не импортируйте его из файла torchvision, так как импорт может завершиться ошибкой, если torchvision не установлен. Добавьте комментарий # Adapted from, чтобы два файла оставались синхронизированными. Для процессоров без пользовательских параметров используйте ImagesKwargs напрямую.

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)

См. LlavaOnevisionImageProcessorPil для справки.

Добавить методы постобработки

Добавляйте методы постобработки непосредственно в класс процессора. Методы постобработки вызываются с результатами модели (outputs) и любыми дополнительными аргументами, необходимыми для конкретного метода постобработки.

class MyModelImageProcessor(TorchvisionBackend):
    ...

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

Post-processors возвращают либо список простых объектов (list[str] или list[torch.Tensor]), либо список сложных объектов (list[MyTaskPostProcessorOutput] или list[dict]). Выходные данные post-processor'ов определены в src/transformers/image_processing_outputs.py и наследуются от BatchFeature.

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

Процессор видео

Добавьте видео-процессор, если модель обрабатывает видео или кадры, извлечённые из видео.

Создайте video_processing_<model_name>.py в каталоге модели. BaseVideoProcessor наследуется от TorchvisionBackend и обеспечивает общее поведение для декодирования, выборки кадров, изменения размера, масштабирования, нормализации, сохранения и загрузки.

Атрибуты класса представляют значения предобработки по умолчанию. Пользователи могут переопределить их при инициализации или в момент вызова. По возможности используйте те же имена, что и в VideosKwargs, например size, crop_size, do_resize, do_sample_frames, num_frames и fps.

Определите класс kwargs, если вашему видео-процессору требуются дополнительные параметры помимо стандартных VideosKwargs. Укажите его в качестве valid_kwargs и используйте для аннотации __init__ — это обеспечит проверку параметров во время выполнения и автоматически сгенерирует строку документации.

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)

Переопределяйте sample_frames() только в том случае, если модели требуется правило выборки, которое базовый равномерный сэмплер не может выразить. Например, некоторые модели устанавливают минимальное или максимальное количество кадров или выполняют выборку на основе специфичных для модели ограничений.

Если метод forward модели ожидает устаревшее имя входного параметра, переопределите preprocess и переименуйте ключ после вызова базовой реализации.

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

Сохраните видео-процессор вместе с контрольной точкой, создав его экземпляр в скрипте конвертации и вызвав save_pretrained(). Если ProcessorMixin оборачивает видео-процессор, вызовите вместо этого save_pretrained(). Не создавайте и не редактируйте файлы конфигурации предобработки вручную.

См. Qwen3VLVideoProcessor для справки.

Регистрация классов

Добавьте новые классы в __all__ в конце файла, затем пересоздайте __init__.py с помощью:

python utils/check_inits.py --fix_and_overwrite

Соотнесите новые классы с конфигурацией модели, чтобы классы Auto могли их загрузить. В сгенерированном файле авто-сопоставления вверху есть предупреждение. Не редактируйте его вручную. Добавьте или обновите конфигурацию модели, затем выполните:

python utils/check_auto.py --fix_and_overwrite

После генерации маппинга убедитесь, что тип модели присутствует в соответствующих маппингах в src/transformers/models/auto/auto_mappings.py.

• IMAGE_PROCESSOR_MAPPING_NAMES для AutoImageProcessor
• VIDEO_PROCESSOR_MAPPING_NAMES для AutoVideoProcessor

Тестирование

Добавьте тесты для каждого компонента обработки изображений в каталоге тестов модели. Используйте общие тестовые миксины и передайте специфичные для модели аргументы инициализации. Тесты изображений автоматически обнаруживают бэкенды процессора через общий тестер, тогда как тесты видео явно настраивают класс процессора и фикстуры.

Тесты процессора изображений

Тесты процессоров изображений находятся в tests/models/<model_name>/test_image_processing_<model_name>.py. Определите тестер, наследующийся от ImageProcessingTester, и класс тестов, наследующийся от ImageProcessingTestMixin и unittest.TestCase.

Тестер обработки изображений определяет атрибуты тестов по умолчанию, такие как аргументы инициализации процессора и параметры для создания случайных входных данных для тестов. Переопределяйте аргументы только в том случае, если они должны отличаться от значений по умолчанию для процессора изображений. Например, мы обычно тестируем с меньшими размерами изображений, чтобы тесты выполнялись быстро. Классы процессоров изображений выводятся автоматически из IMAGE_PROCESSOR_MAPPING_NAMES.

Укажите image_processor_tester_class в тестовом классе. Миксин создаёт self.image_processor_tester и уже покрывает большинство необходимых тестовых методов.

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)

Добавляйте целенаправленные тесты для поведения, которое миксин не может вывести, например, для пользовательских правил изменения размера или специфичных для модели аргументов kwargs.

Миксины для тестов постобработки доступны в tests/test_image_processing_common.py и добавляются поверх ImageProcessingTestMixin.

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

Тесты автоматически проверяют, что для вашей модели используются правильные миксины. Миксины для новых задач необходимо добавить в tests/test_image_processing_common.py.

Тесты процессора видео

Тесты видео-процессоров обычно находятся в tests/models/<model_name>/test_video_processing_<model_name>.py и наследуются от VideoProcessingTestMixin. Установите fast_video_processing_class, определите video_processor_dict и переопределите input_name, если модель использует ключ, отличный от 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}

Добавьте целенаправленные тесты видео для выборки кадров, обработки метаданных, декодированных видео-входов, входов в виде списка кадров и форм выходных данных. Если ваш процессор переименовывает pixel_values_videos, убедитесь, что возвращается переименованный ключ.

Если у модели также есть ProcessorMixin, который оборачивает процессор изображений или видео, добавьте tests/models/<model_name>/test_processing_<model_name>.py и унаследуйте класс от ProcessorTesterMixin. Задайте processor_class и переопределите класс-методы _setup_<component>() для компонентов, которые не могут быть созданы без аргументов. Используйте _setup_test_attributes(), чтобы объявить плейсхолдер-токены, используемые в общих тестах процессора.

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

Дальнейшие шаги

• Ознакомьтесь с руководством Автоматическая генерация docstrings, чтобы автоматически генерировать согласованные docstrings с помощью @auto_docstring.
• Ознакомьтесь с руководствами Image processors и Video processors, чтобы узнать о поведении предобработки, доступном пользователю.