Transformers documentation

Processeurs d'images

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

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.

AutoImageProcessor
processeur d'images spécifique au 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")

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 examples

Appliquez 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))
avant
après

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
Update on GitHub