Transformers documentation
Processeurs d'images
Processeurs d'images
Les processeurs d’images convertissent les images en valeurs de pixels, des tenseurs qui représentent les couleurs et la taille des images. Les valeurs de pixels constituent les entrées d’un modèle de vision. Pour s’assurer qu’un modèle pré-entraîné reçoit la bonne entrée, un processeur d’images peut effectuer les opérations suivantes afin de garantir qu’une image est exactement identique aux images sur lesquelles le modèle a été pré-entraîné.
- centrer-cadrer ou redimensionner une image
- normaliser ou rééchelonner les valeurs des pixels
Utilisez from_pretrained() pour charger la configuration d'un processeur d'images (taille de l'image, normalisation et mise à l'échelle, etc.) à partir d'un modèle de vision sur le Hub Hugging Face ou d'un répertoire local. La configuration de chaque modèle pré-entraîné est enregistrée dans un fichier preprocessor_config.json.
Lorsqu'un processeur d'images fait partie d'un processeur multimodal, sa configuration est imbriquée dans processor_config.json. Consultez Enregistrer et charger un processeur pour plus de détails.
from transformers import AutoImageProcessor
image_processor = AutoImageProcessor.from_pretrained("google/vit-base-patch16-224")Passez une image au processeur d'images pour la transformer en valeurs de pixels, et définissez return_tensors="pt" pour retourner des tenseurs PyTorch. N'hésitez pas à afficher les entrées pour voir à quoi ressemble l'image en tant que tenseur.
from PIL import Image
import requests
url = "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/transformers/image_processor_example.png"
image = Image.open(requests.get(url, stream=True).raw).convert("RGB")
inputs = image_processor(image, return_tensors="pt")Ce guide présente la classe de processeur d'images et explique comment prétraiter les images pour les modèles de vision.
Classes de processeur d'images
Les processeurs d’images utilisent une architecture basée sur des backends avec deux backends :
- TorchvisionBackend — l’implémentation par défaut basée sur torchvision. Accélérée par GPU et jusqu’à 33 fois plus rapide que le backend PIL pour des lots d’entrées torch.Tensor. Tous les modèles prennent en charge ce backend ; les modèles plus récents n’en prennent en charge que celui-ci.
- PilBackend — l’alternative PIL/NumPy. Portable et limitée au CPU. Disponible uniquement pour les anciens modèles, où il est utile de reproduire les sorties numériques exactes de l’implémentation d’origine.
Le backend actif d'un processeur chargé peut être inspecté via son attribut backend (par exemple, processor.backend == "torchvision"). Chaque processeur d'images est une sous-classe de ImageProcessingMixin, qui fournit les méthodes from_pretrained() et save_pretrained().
Il existe deux façons de charger un processeur d'images : avec AutoImageProcessor ou directement depuis une classe spécifique à un modèle.
L'API AutoClass fournit une méthode pratique pour charger un processeur d'images sans spécifier directement le modèle auquel ce processeur est associé.
Utilisez from_pretrained() avec l'argument backend pour sélectionner le backend. Lorsque backend est omis (par défaut), torchvision est choisi s'il est installé, sinon PIL est utilisé. Notez que backend="pil" n'est pris en charge que pour les anciens modèles ; les nouveaux modèles n'exposent que le backend torchvision.
Pour obtenir le prétraitement le plus proche de celui utilisé lors de l’entraînement d’un modèle, utilisez le backend spécifié dans sa documentation ou son code d’entraînement. Si le pipeline d’entraînement utilise PIL et que le modèle prend en charge les deux backends, passez backend="pil". Le changement de backend peut modifier les valeurs des pixels redimensionnés, et les mises à jour de Pillow ou de torchvision peuvent également les modifier. Pour un prétraitement reproductible, maintenez les versions du backend et de la bibliothèque d’images fixes.
Un petit ensemble de modèles plus anciens (Chameleon, Flava, Idefics3, SmolVLM) utilise l'interpolation Lanczos. Leur backend par défaut dépend de votre version de torchvision. Avec torchvision > 0.27, Lanczos est pris en charge nativement et ces modèles utilisent torchvision par défaut. Les versions plus anciennes de torchvision basculent sur BICUBIC, de sorte que le backend par défaut est PIL afin de préserver les sorties d'origine. Passez explicitement
backend="torchvision"pour outrepasser le défaut.
from transformers import AutoImageProcessor
# Default: picks torchvision if available, otherwise pil
image_processor = AutoImageProcessor.from_pretrained("google/vit-base-patch16-224")
# Explicitly request the torchvision backend
image_processor = AutoImageProcessor.from_pretrained("google/vit-base-patch16-224", backend="torchvision")
# Explicitly request the PIL backend (only for models that support it)
image_processor = AutoImageProcessor.from_pretrained("google/vit-base-patch16-224", backend="pil")Chaque processeur d’images est associé à un modèle de vision préentraîné spécifique, et sa configuration contient la taille attendue par le modèle ainsi que ses paramètres de normalisation.
Chargez le processeur du backend torchvision directement depuis la classe spécifique au modèle.
from transformers import ViTImageProcessor
image_processor = ViTImageProcessor.from_pretrained("google/vit-base-patch16-224")Pour les modèles qui le prennent en charge, vous pouvez charger le backend PIL avec la classe suffixée par Pil. Cela est utile lorsque vous avez besoin d'une parité numérique exacte avec l'implémentation d'origine.
from transformers import ViTImageProcessorPil
image_processor = ViTImageProcessorPil.from_pretrained("google/vit-base-patch16-224")Processeurs de backend Torchvision
TorchvisionBackend est le backend par défaut. Assurez-vous que torchvision est installé, puis chargez-le avec backend="torchvision" (ou omettez simplement backend, car torchvision est sélectionné automatiquement lorsqu’il est disponible).
from transformers import AutoImageProcessor
processor = AutoImageProcessor.from_pretrained("facebook/detr-resnet-50", backend="torchvision")Contrôlez le dispositif sur lequel le traitement est effectué à l'aide de l'argument device. Par défaut, le traitement est effectué sur le même dispositif que l'entrée si les entrées sont des tenseurs, sinon il bascule sur le CPU. L'exemple ci-dessous exécute le traitement sur un accélérateur.
import torch
from torchvision.io import read_image
from transformers import DetrImageProcessor
device = torch.accelerator.current_accelerator().type if torch.accelerator.is_available() else "cpu"
images = read_image("image.jpg")
processor = DetrImageProcessor.from_pretrained("facebook/detr-resnet-50")
images_processed = processor(images, return_tensors="pt", device=device)Benchmarks
Les benchmarks sont obtenus à partir d'une instance AWS EC2 g5.2xlarge équipée d'un GPU NVIDIA A10G Tensor Core.




Résolution dynamique
La plupart des processeurs d’images redimensionnent chaque image vers une résolution fixe. La résolution dynamique permet à certains modèles de conserver le ratio d’aspect d’origine et de laisser la quantité de données prétraitées croître avec l’image, de sorte qu’une photo détaillée génère plus de patches qu’une petite icône et que le modèle consacre ses calculs là où il y a quelque chose à observer.
La manière dont l'image est découpée dépend du modèle. Certains modèles découpent l'image en un nombre variable de patches de taille fixe, borné par des paramètres tels que min_patches et max_patches. D'autres modèles redimensionnent l'image à la résolution qui lui convient le mieux, choisie dans une liste prédéfinie de rapports d'aspect ou dérivée d'un budget de pixels.
Consultez la page de documentation d’un modèle pour connaître ses paramètres, valeurs par défaut et formes de sortie.
Prétraitement
Les modèles de vision de Transformers s’attendent à recevoir l’entrée sous forme de tenseurs PyTorch de valeurs de pixels. Un processeur d’images gère la conversion des images en valeurs de pixels, représentées par la taille du lot, le nombre de canaux, la hauteur et la largeur. Pour ce faire, une image est redimensionnée (recadrée au centre) et les valeurs de pixels sont normalisées et rééchelonnées aux valeurs attendues par les modèles.
Le prétraitement d’images ne se confond pas avec l’augmentation d’images. L’augmentation d’images consiste à apporter des modifications (luminosité, couleurs, rotation, etc.) à une image afin de créer de nouveaux exemples d’entraînement ou de prévenir le surapprentissage. Le prétraitement d’images, lui, modifie une image pour qu’elle corresponde au format d’entrée attendu par un modèle préentraîné.
En général, les images sont augmentées (pour améliorer les performances) puis prétraitées avant d’être transmises à un modèle. Vous pouvez utiliser n’importe quelle bibliothèque (Albumentations, Kornia) pour l’augmentation et un processeur d’images pour le prétraitement.
Ce guide utilise le module transforms de torchvision pour l'augmentation.
Commencez par charger un petit échantillon du jeu de données food101.
from datasets import load_dataset
dataset = load_dataset("ethz/food101", split="train[:100]")À partir du module transforms, utilisez l'API Compose pour enchaîner RandomResizedCrop et ColorJitter. Ces transformations effectuent un recadrage et un redimensionnement aléatoires d'une image, ainsi qu'un ajustement aléatoire de ses couleurs.
La taille de l’image vers laquelle effectuer un recadrage aléatoire peut être récupérée depuis le processeur d’images. Pour certains modèles, une hauteur et une largeur exactes sont attendues, tandis que pour d’autres, seule la shortest_edge est requise.
from torchvision.transforms import RandomResizedCrop, ColorJitter, Compose
size = (
image_processor.size["shortest_edge"]
if "shortest_edge" in image_processor.size
else (image_processor.size["height"], image_processor.size["width"])
)
_transforms = Compose([RandomResizedCrop(size), ColorJitter(brightness=0.5, hue=0.5)])Appliquez les transformations aux images et convertissez-les au format RGB. Puis, transmettez les images augmentées au processeur d'images pour obtenir les valeurs de pixels.
Le paramètre do_resize est défini sur False car les images ont déjà été redimensionnées à l’étape d’augmentation par RandomResizedCrop. Si vous n’augmentez pas les images, le processeur d’images redimensionne et normalise automatiquement les images avec les valeurs image_mean et image_std. Ces valeurs se trouvent dans le fichier de configuration du préprocesseur.
def transforms(examples):
images = [_transforms(img.convert("RGB")) for img in examples["image"]]
examples["pixel_values"] = image_processor(images, do_resize=False, return_tensors="pt")["pixel_values"]
return examplesAppliquez la fonction d'augmentation et de prétraitement combinée à l'ensemble du jeu de données à la volée avec set_transform.
dataset.set_transform(transforms)
Convertissez les valeurs de pixels en image pour voir comment l'image a été augmentée et prétraitée.
import numpy as np
import matplotlib.pyplot as plt
img = dataset[0]["pixel_values"]
plt.imshow(img.permute(1, 2, 0))
Pour d'autres tâches de vision comme la détection d'objets ou la segmentation, le processeur d'images inclut des méthodes de post-traitement pour convertir la sortie brute d'un modèle en prédictions significatives, telles que des boîtes englobantes ou des cartes de segmentation.
Remplissage
Certains modèles, comme DETR, appliquent une scale augmentation pendant l’entraînement, ce qui peut entraîner des images de tailles différentes au sein d’un même lot. Les images de tailles différentes ne peuvent pas être regroupées dans un même lot.
Pour corriger cela, remplacez les images par le jeton de bourrage spécial 0. Utilisez la méthode pad pour bourrer les images et définissez une fonction de collation personnalisée pour les regrouper en lot.
def collate_fn(batch):
pixel_values = [item["pixel_values"] for item in batch]
encoding = image_processor.pad(pixel_values, return_tensors="pt")
labels = [item["labels"] for item in batch]
batch = {}
batch["pixel_values"] = encoding["pixel_values"]
batch["pixel_mask"] = encoding["pixel_mask"]
batch["labels"] = labels
return batch