Transformers documentation

Procesadores de imágenes

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Procesadores de imágenes

Los procesadores de imagen convierten las imágenes en valores de píxel, tensores que representan los colores y el tamaño de la imagen. Los valores de píxel son las entradas de un modelo de visión. Para garantizar que un modelo preentrenado reciba la entrada correcta, un procesador de imagen puede realizar las siguientes operaciones para asegurarse de que una imagen sea exactamente como las imágenes con las que se preentrenó el modelo.

  • recortar al centro o redimensionar una imagen
  • normalizar o reescalar los valores de píxeles

Use from_pretrained() para cargar la configuración de un procesador de imágenes (tamaño de imagen, si normalizar y reescalar, etc.) desde un modelo de visión en el Hub de Hugging Face o desde un directorio local. La configuración de cada modelo preentrenado se guarda en un archivo preprocessor_config.json.

Cuando un procesador de imágenes forma parte de un procesador multimodal, su configuración se anida en processor_config.json. Consulte Guardar y cargar un procesador para obtener más detalles.

from transformers import AutoImageProcessor

image_processor = AutoImageProcessor.from_pretrained("google/vit-base-patch16-224")

Pasa una imagen al procesador de imágenes para transformarla en valores de píxeles y establece return_tensors="pt" para devolver tensores de PyTorch. Puedes imprimir las entradas para ver cómo se ve la imagen como tensor.

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

Esta guía cubre la clase de procesador de imágenes y cómo preprocesar imágenes para modelos de visión.

Clases de procesadores de imágenes

Los procesadores de imágenes utilizan una arquitectura basada en backends con dos backends:

  • TorchvisionBackend — la implementación predeterminada con soporte de torchvision. Acelerada por GPU y hasta 33 veces más rápida que el backend de PIL para lotes de entradas torch.Tensor. Todos los modelos admiten este backend; los modelos más nuevos solo admiten este.
  • PilBackend — la alternativa de PIL/NumPy. Portable y solo para CPU. Solo disponible para modelos más antiguos, donde resulta útil reproducir las salidas numéricas exactas de la implementación original.

El backend activo en un procesador cargado se puede inspeccionar con su atributo backend (p. ej., processor.backend == "torchvision"). Cada procesador de imágenes es una subclase de ImageProcessingMixin, que proporciona los métodos from_pretrained() y save_pretrained().

Hay dos formas de cargar un procesador de imágenes: con AutoImageProcessor o directamente desde una clase específica del modelo.

AutoImageProcessor
procesador de imágenes específico del modelo

La API AutoClass ofrece un método conveniente para cargar un procesador de imágenes sin especificar directamente el modelo con el que está asociado el procesador.

Use from_pretrained() con el argumento backend para seleccionar el backend. Cuando se omite backend (el valor predeterminado), se elige torchvision si está instalado y se usa PIL en caso contrario. Tenga en cuenta que backend="pil" solo se admite para modelos más antiguos; los modelos más nuevos solo exponen el backend de torchvision.

Para obtener el preprocesamiento más cercano al entrenamiento de un modelo, utiliza el backend especificado en su documentación o código de entrenamiento. Si el pipeline de entrenamiento usa PIL y el modelo admite ambos backends, pasa backend="pil". Cambiar de backend puede alterar los valores de píxeles redimensionados, y las actualizaciones de Pillow o torchvision también pueden modificarlos. Para un preprocesamiento reproducible, mantén fijas las versiones del backend y de la biblioteca de imágenes.

Un pequeño conjunto de modelos más antiguos (Chameleon, Flava, Idefics3, SmolVLM) utiliza interpolación Lanczos. Su backend predeterminado depende de tu versión de torchvision. Con torchvision > 0.27, Lanczos se admite de forma nativa y estos modelos usan torchvision por defecto. Las versiones anteriores de torchvision recurren a BICUBIC, por lo que el valor predeterminado es PIL para preservar las salidas originales. Pasa backend="torchvision" explícitamente para anular el valor predeterminado.

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

Procesadores de backends de Torchvision

TorchvisionBackend es el backend predeterminado. Asegúrate de que torchvision esté instalado y luego cárgalo con backend="torchvision" (o simplemente omite backend, ya que torchvision se selecciona automáticamente cuando está disponible).

from transformers import AutoImageProcessor

processor = AutoImageProcessor.from_pretrained("facebook/detr-resnet-50", backend="torchvision")

Controle en qué dispositivo se realiza el procesamiento con el argumento device. Por defecto, el procesamiento se realiza en el mismo dispositivo que la entrada si las entradas son tensores; de lo contrario, se recurre a la CPU. El ejemplo siguiente ejecuta el procesamiento en un acelerador.

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

Los benchmarks se obtienen de una instancia AWS EC2 g5.2xlarge con una GPU NVIDIA A10G Tensor Core.

Resolución dinámica

La mayoría de los procesadores de imagen redimensionan cada imagen a una resolución fija. La resolución dinámica permite que algunos modelos conserven la relación de aspecto original y que la cantidad de datos preprocesados crezca con la imagen, de modo que una foto detallada recibe más parches que un icono pequeño y el modelo destina su capacidad de cómputo a donde hay algo que ver.

La forma en que se divide la imagen depende del modelo. Algunos modelos recortan la imagen en un número variable de parches de tamaño fijo, limitado por parámetros como min_patches y max_patches. Otros modelos redimensionan la imagen a la resolución que mejor se ajuste, ya sea elegida de una lista predefinida de relaciones de aspecto o derivada de un presupuesto de píxeles.

Consulte la página de documentación de un modelo para conocer sus parámetros, valores predeterminados y formas de salida.

Preprocesar

Los modelos de visión de Transformers esperan la entrada como tensores de PyTorch de valores de píxeles. Un procesador de imágenes gestiona la conversión de imágenes a valores de píxeles, que se representa por el tamaño del lote, el número de canales, la altura y el ancho. Para lograrlo, la imagen se redimensiona (recorte centrado) y los valores de píxeles se normalizan y reescalan a los valores esperados por los modelos.

El preprocesamiento de imágenes no es lo mismo que la augmentación de imágenes. La augmentación de imágenes realiza modificaciones (brillo, colores, rotación, etc.) en una imagen con el objetivo de crear nuevos ejemplos de entrenamiento o prevenir el sobreajuste. El preprocesamiento de imágenes realiza modificaciones en una imagen con el objetivo de adaptarla al formato de entrada esperado por un modelo preentrenado.

Por lo general, las imágenes se aumentan (para mejorar el rendimiento) y luego se preprocesan antes de pasarlas a un modelo. Puede utilizar cualquier biblioteca (Albumentations, Kornia) para el aumento y un procesador de imágenes para el preprocesamiento.

Esta guía utiliza el módulo transforms de torchvision para la aumentación.

Comience cargando una pequeña muestra del conjunto de datos food101.

from datasets import load_dataset

dataset = load_dataset("ethz/food101", split="train[:100]")

Desde el módulo transforms, use la API Compose para encadenar RandomResizedCrop y ColorJitter. Estas transformaciones recortan y redimensionan una imagen de forma aleatoria, y ajustan los colores de una imagen de forma aleatoria.

El tamaño de imagen al que recortar aleatoriamente se puede obtener del procesador de imágenes. Para algunos modelos se esperan una altura y un ancho exactos, mientras que para otros solo se requiere shortest_edge.

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)])

Aplica las transformaciones a las imágenes y conviértelas al formato RGB. Luego, pasa las imágenes aumentadas al procesador de imágenes para que devuelva los valores de píxeles.

El parámetro do_resize se establece en False porque las imágenes ya se han redimensionado en el paso de aumento mediante RandomResizedCrop. Si no aumentas las imágenes, el procesador de imágenes redimensiona y normaliza automáticamente las imágenes con los valores de image_mean y image_std. Estos valores se encuentran en el archivo de configuración del preprocesador.

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

Aplica la función combinada de aumento y preprocesamiento a todo el conjunto de datos sobre la marcha con set_transform.

dataset.set_transform(transforms)

Convierte los valores de píxeles de nuevo en una imagen para ver cómo se ha aumentado y preprocesado la imagen.

import numpy as np
import matplotlib.pyplot as plt

img = dataset[0]["pixel_values"]
plt.imshow(img.permute(1, 2, 0))
antes
después

Para otras tareas de visión, como la detección de objetos o la segmentación, el procesador de imágenes incluye métodos de posprocesamiento para convertir la salida cruda de un modelo en predicciones significativas, como cajas delimitadoras o mapas de segmentación.

Relleno

Algunos modelos, como DETR, aplican scale augmentation durante el entrenamiento, lo que puede provocar que las imágenes de un lote tengan tamaños diferentes. Las imágenes de tamaños distintos no se pueden agrupar en un mismo lote.

Para solucionarlo, rellena las imágenes con el token de relleno especial 0. Usa el método pad para rellenar las imágenes y define una función de collate personalizada para agruparlas en lotes.

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