Transformers documentation

Ajouter des composants de traitement de la vision

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Ajouter des composants de traitement de la vision

L’ajout d’un modèle de vision nécessite des composants de traitement d’images ou de vidéos en plus de l’approche modulaire standard. Les modèles uniquement pour images ont besoin de processeurs d’images et les modèles pour vidéos ont besoin d’un processeur de vidéos, tous deux accessibles via les points d’entrée AutoImageProcessor et AutoVideoProcessor.

Pour les étapes de modélisation et de configuration, suivez d'abord le guide modulaire.

Processeurs d'images

Créez des processeurs d’images lorsque le modèle consomme des images. L’arrière-plan torchvision est celui par défaut et prend en charge l’accélération GPU. PIL est utilisé en secours lorsque torchvision n’est pas disponible.

Les deux classes de processeur d’image partagent la même logique de prétraitement mais utilisent des backends différents. Leurs signatures de constructeur et leurs valeurs par défaut doivent être identiques. AutoImageProcessor.from_pretrained() sélectionne le backend au moment du chargement et bascule sur PIL si torchvision n’est pas disponible. Des signatures non conformes font en sorte qu’une même configuration enregistrée se comporte différemment selon les environnements.

torchvision

Créez image_processing_<model_name>.py avec une classe qui hérite de TorchvisionBackend. Si votre processeur a besoin de paramètres personnalisés en plus des [ImagesKwargs] standard, définissez une classe 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)

Voir LlavaOnevisionImageProcessor pour référence.

PIL

Créez image_processing_pil_<model_name>.py avec une classe qui hérite de PilBackend. Dupliquez la classe kwargs ici au lieu de l’importer depuis le fichier torchvision, car cela peut échouer si torchvision n’est pas installé. Ajoutez un commentaire # Adapted from pour que les deux restent synchronisés. Pour les processeurs sans paramètres personnalisés, utilisez directement 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)

Voir LlavaOnevisionImageProcessorPil pour référence.

Ajouter des méthodes de post-traitement

Ajoutez des méthodes de post-traitement directement à la classe de processeur. Les méthodes de post-traitement sont appelées avec les sorties du modèle (outputs) et les arguments supplémentaires requis pour la méthode de post-traitement spécifique.

class MyModelImageProcessor(TorchvisionBackend):
    ...

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

Les post-processeurs renvoient soit une liste d'objets simples (list[str] ou list[torch.Tensor]), soit une liste d'objets complexes (list[MyTaskPostProcessorOutput] ou list[dict]). Les sorties des post-processeurs sont définies dans src/transformers/image_processing_outputs.py et héritent de BatchFeature.

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

Processeur vidéo

Ajoutez un processeur de vidéo lorsque le modèle consomme des vidéos ou des images vidéo échantillonnées.

Créez video_processing_<model_name>.py dans le répertoire du modèle. BaseVideoProcessor hérite de TorchvisionBackend et fournit un comportement commun pour le décodage, l'échantillonnage des images, le redimensionnement, le rééchelonnement, la normalisation, l'enregistrement et le chargement.

Les attributs de classe sont les valeurs de prétraitement par défaut. Les utilisateurs peuvent les remplacer lors de l’initialisation ou de l’appel. Utilisez les mêmes noms que VideosKwargs lorsque c’est possible, tels que size, crop_size, do_resize, do_sample_frames, num_frames et fps.

Définissez une classe kwargs si votre processeur vidéo nécessite des paramètres personnalisés en plus des paramètres standard VideosKwargs. Définissez-la comme valid_kwargs et utilisez-la pour annoter __init__ afin d’assurer à la fois la validation à l’exécution et la génération automatique de la docstring.

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)

N’implémentez sample_frames() que si le modèle exige une règle d’échantillonnage que l’échantillonneur uniforme de base ne peut pas exprimer. Par exemple, certains modèles imposent un nombre minimal ou maximal de frames, ou effectuent l’échantillonnage en fonction de contraintes spécifiques au modèle.

Si la méthode forward du modèle s’attend à un nom d’entrée hérité, surchargez preprocess et renommez la clé après avoir appelé l’implémentation de 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

Enregistrez le processeur de vidéo avec le point de contrôle en l’instanciant dans le script de conversion et en appelant save_pretrained(). Si un ProcessorMixin encapsule le processeur de vidéo, appelez plutôt save_pretrained(). Ne créez ni ne modifiez manuellement les fichiers de configuration de prétraitement.

Voir Qwen3VLVideoProcessor pour référence.

Enregistrer les classes

Ajoutez les nouvelles classes à __all__ en bas du fichier, puis régénérez __init__.py avec :

python utils/check_inits.py --fix_and_overwrite

Associez les nouvelles classes à la configuration du modèle afin que les classes Auto puissent les charger. Le fichier de correspondance auto généré comporte un avertissement en haut. Ne le modifiez pas manuellement. Ajoutez ou mettez à jour la configuration du modèle, puis exécutez :

python utils/check_auto.py --fix_and_overwrite

Une fois la correspondance générée, vérifiez que le type de modèle apparaît dans les correspondances pertinentes de src/transformers/models/auto/auto_mappings.py.

Tests

Ajoutez des tests pour chaque composant de traitement visuel dans le répertoire de tests du modèle. Utilisez les mixins de tests partagés et fournissez les kwargs d’initialisation spécifiques au modèle. Les tests d’images découvrent automatiquement les backends du processeur via un testeur partagé, tandis que les tests de vidéo configurent explicitement leur classe de processeur et leurs fixtures.

Tests du processeur d'images

Les tests de processeur d’images se trouvent dans tests/models/<model_name>/test_image_processing_<model_name>.py. Définissez un tester qui hérite de ImageProcessingTester et une classe de test qui hérite de ImageProcessingTestMixin et de unittest.TestCase.

Le testeur de traitement d’images définit des attributs de test par défaut, tels que les arguments d’initialisation du processeur et les paramètres pour créer des entrées aléatoires pour les tests. N’écrit par-dessus les arguments que s’ils doivent différer des valeurs par défaut du processeur d’images. Par exemple, nous testons généralement avec des tailles d’images plus petites pour garder les tests rapides. Les classes de processeur d’images sont inférées automatiquement à partir de IMAGE_PROCESSOR_MAPPING_NAMES.

Définissez image_processor_tester_class sur la classe de test. Le mixin crée self.image_processor_tester et couvre déjà la plupart des méthodes de test requises.

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)

Ajoutez des tests ciblés pour les comportements que le mixin ne peut pas inférer, tels que des règles de redimensionnement personnalisées ou des kwargs spécifiques au modèle.

Les mixins de test de post-traitement sont disponibles dans tests/test_image_processing_common.py et sont ajoutés en plus de ImageProcessingTestMixin.

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

Les tests vérifient automatiquement que les mixins corrects sont utilisés pour votre modèle. Les mixins pour les nouvelles tâches doivent être ajoutés à tests/test_image_processing_common.py.

Tests du processeur vidéo

Les tests de processeur vidéo se trouvent généralement dans tests/models/<model_name>/test_video_processing_<model_name>.py et héritent de VideoProcessingTestMixin. Définissez fast_video_processing_class, définissez video_processor_dict et surchargez input_name si le modèle utilise une clé autre que 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}

Ajoutez des tests vidéo ciblés pour l'échantillonnage des images, la gestion des métadonnées, les entrées vidéo décodées, les entrées de listes d'images et les formes de sortie. Si votre processeur renomme pixel_values_videos, vérifiez que la clé renommée est bien retournée.

Si le modèle dispose également d'un ProcessorMixin qui encapsule le processeur d'images ou de vidéos, ajoutez tests/models/<model_name>/test_processing_<model_name>.py et héritez de ProcessorTesterMixin. Définissez processor_class et surchargez les méthodes de classe _setup_<component>() pour les composants qui ne peuvent pas être construits sans arguments. Utilisez _setup_test_attributes() pour exposer les jetons de substitution utilisés par les tests de processeur communs.

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

Étapes suivantes

Update on GitHub