Agregar componentes de procesamiento de visión

Agregar un modelo de visión requiere componentes de procesamiento de imágenes o video además del enfoque modular estándar. Los modelos solo de imagen necesitan procesadores de imagen y los modelos de video necesitan un procesador de video, ambos accesibles a través de los puntos de entrada AutoImageProcessor y AutoVideoProcessor.

Para los pasos de modelado y configuración, sigue primero la guía modular.

Procesadores de imágenes

Cree procesadores de imágenes cuando el modelo consuma imágenes. El backend torchvision es el predeterminado y admite aceleración por GPU. PIL es la alternativa cuando torchvision no está disponible.

Ambas clases de procesador de imágenes comparten la misma lógica de preprocesamiento, pero tienen backends diferentes. Sus firmas de constructor y valores predeterminados deben ser idénticos. AutoImageProcessor.from_pretrained() selecciona el backend en el momento de la carga y recurre a PIL cuando torchvision no está disponible. Las firmas no coincidentes provocan que la misma configuración guardada se comporte de manera diferente en distintos entornos.

torchvision

Crea image_processing_<model_name>.py con una clase que herede de TorchvisionBackend. Si tu procesador necesita parámetros personalizados además de los estándar de [ImagesKwargs], define una clase de 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)

Consulte LlavaOnevisionImageProcessor como referencia.

PIL

Crea image_processing_pil_<model_name>.py con una clase que herede de PilBackend. Duplica la clase de kwargs aquí en lugar de importarla del archivo de torchvision, ya que puede fallar si torchvision no está instalado. Añade un comentario # Adapted from para que ambos se mantengan sincronizados. Para procesadores sin parámetros personalizados, usa ImagesKwargs directamente.

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)

Consulte LlavaOnevisionImageProcessorPil como referencia.

Agregar métodos de posprocesamiento

Agregue métodos de posprocesamiento directamente a la clase de procesador. Los métodos de posprocesamiento se invocan con las salidas del modelo (outputs) y cualquier argumento adicional requerido para el método de posprocesamiento específico.

class MyModelImageProcessor(TorchvisionBackend):
    ...

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

Los postprocesadores devuelven una lista de objetos simples (list[str] o list[torch.Tensor]) o una lista de objetos complejos (list[MyTaskPostProcessorOutput] o list[dict]). Las salidas de los postprocesadores se definen en src/transformers/image_processing_outputs.py y heredan de BatchFeature.

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

Procesador de video

Agregue un procesador de video cuando el modelo consuma videos o fotogramas de video muestreados.

Cree video_processing_<model_name>.py en el directorio del modelo. BaseVideoProcessor hereda de TorchvisionBackend y proporciona un comportamiento compartido para la decodificación, la muestreo de fotogramas, el redimensionado, la reescalado, la normalización, el guardado y la carga.

Los atributos de la clase son los valores de preprocesamiento predeterminados. Los usuarios pueden sobrescribirlos en la inicialización o en el momento de la llamada. Utilice los mismos nombres que VideosKwargs cuando sea posible, como size, crop_size, do_resize, do_sample_frames, num_frames y fps.

Defina una clase de kwargs si su procesador de videos necesita parámetros personalizados además de los estándar VideosKwargs. Establézcala como valid_kwargs y úsela para anotar __init__ para la validación en tiempo de ejecución y la cadena de documentación generada automáticamente.

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)

Sobrescribe sample_frames() solo cuando el modelo requiera una regla de muestreo que el muestreador uniforme base no pueda expresar. Por ejemplo, algunos modelos imponen un número mínimo o máximo de fotogramas, o muestrean en función de restricciones específicas del modelo.

Si el método forward del modelo espera un nombre de entrada heredado, sobrescribe preprocess y cambia el nombre de la clave después de llamar a la implementación base.

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

Guarde el procesador de video junto con el punto de control instanciándolo en el script de conversión y llamando a save_pretrained(). Si un ProcessorMixin envuelve el procesador de video, llame a save_pretrained() en su lugar. No cree ni edite manualmente los archivos de configuración de preprocesamiento.

Consulte Qwen3VLVideoProcessor como referencia.

Registrar las clases

Agrega las nuevas clases a __all__ al final del archivo y, a continuación, regenera __init__.py con:

python utils/check_inits.py --fix_and_overwrite

Mapea las nuevas clases a la configuración del modelo para que las clases Auto puedan cargarlas. El archivo de mapeo automático generado tiene una advertencia en la parte superior. No lo edites a mano. Añade o actualiza la configuración del modelo y luego ejecuta:

python utils/check_auto.py --fix_and_overwrite

Después de que se genere el mapeo, verifica que el tipo de modelo aparezca en los mapeos relevantes de src/transformers/models/auto/auto_mappings.py.

IMAGE_PROCESSOR_MAPPING_NAMES para AutoImageProcessor
VIDEO_PROCESSOR_MAPPING_NAMES para AutoVideoProcessor

Pruebas

Añada pruebas para cada componente de procesamiento de visión en el directorio de pruebas del modelo. Utilice los mixins de prueba compartidos y proporcione los kwargs de inicialización específicos del modelo. Las pruebas de imagen detectan automáticamente los backends del procesador a través de un tester compartido, mientras que las pruebas de video configuran explícitamente su clase de procesador y sus fixtures.

Pruebas del procesador de imágenes

Las pruebas del procesador de imágenes se encuentran en tests/models/<model_name>/test_image_processing_<model_name>.py. Defina un tester que herede de ImageProcessingTester y una clase de prueba que herede de ImageProcessingTestMixin y unittest.TestCase.

El probador de procesamiento de imágenes define atributos de prueba predeterminados, como los argumentos de inicialización del procesador y los parámetros para crear entradas aleatorias para las pruebas. Solo debe sobrescribir los argumentos si deben ser diferentes de los valores predeterminados del procesador de imágenes. Por ejemplo, normalmente se prueba con tamaños de imagen más pequeños para mantener las pruebas rápidas. Las clases de procesador de imágenes se infieren automáticamente desde IMAGE_PROCESSOR_MAPPING_NAMES.

Establezca image_processor_tester_class en la clase de prueba. El mixin crea self.image_processor_tester y ya cubre la mayoría de los métodos de prueba requeridos.

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)

Añada pruebas centradas en el comportamiento que el mixin no puede inferir, como reglas de redimensionado personalizadas o kwargs específicos del modelo.

Los mixins de pruebas de posprocesamiento están disponibles en tests/test_image_processing_common.py y se añaden sobre ImageProcessingTestMixin.

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

Las pruebas verifican automáticamente que se utilicen los mixins correctos para su modelo. Los mixins para nuevas tareas deben agregarse a tests/test_image_processing_common.py.

Pruebas del procesador de video

Las pruebas del procesador de video suelen estar en tests/models/<model_name>/test_video_processing_<model_name>.py y heredan de VideoProcessingTestMixin. Establece fast_video_processing_class, define video_processor_dict y sobrescribe input_name si el modelo usa una clave distinta de 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}

Añade pruebas de vídeo centradas en la muestreo de fotogramas, el manejo de metadatos, las entradas de vídeo decodificadas, las entradas de listas de fotogramas y las formas de salida. Si tu procesador cambia el nombre de pixel_values_videos, afirma que se devuelve la clave renombrada.

Si el modelo también tiene un ProcessorMixin que envuelve el procesador de imágenes o de vídeo, añade tests/models/<model_name>/test_processing_<model_name>.py y hereda de ProcessorTesterMixin. Establece processor_class y sobrescribe los métodos de clase _setup_<component>() para los componentes que no se pueden construir sin argumentos. Utiliza _setup_test_attributes() para exponer los tokens de marcador de posición utilizados por las pruebas comunes del procesador.

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

Próximos pasos

Lee la guía Generación automática de docstrings para generar docstrings consistentes automáticamente con @auto_docstring.
Lea las guías de Image processors y Video processors para conocer el comportamiento de preprocesamiento orientado al usuario.

Update on GitHub

Transformers

Agregar componentes de procesamiento de visión

Procesadores de imágenes

torchvision

PIL

Agregar métodos de posprocesamiento

Procesador de video

Registrar las clases

Pruebas

Pruebas del procesador de imágenes

Pruebas del procesador de video

Próximos pasos