Transformers documentation
Ajouter des composants de traitement de la vision
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.TensorProcesseur 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 batchEnregistrez 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.
IMAGE_PROCESSOR_MAPPING_NAMESpour AutoImageProcessorVIDEO_PROCESSOR_MAPPING_NAMESpour AutoVideoProcessor
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 = MyModelImageProcessingTesterLes 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
- Lisez le guide Génération automatique des docstrings pour générer automatiquement des docstrings cohérentes avec
@auto_docstring. - Consultez les guides Image processors et Video processors pour le comportement de prétraitement destiné aux utilisateurs.