Transformers documentation
Обработчики изображений
Обработчики изображений
Обработчики изображений преобразуют изображения в пиксельные значения — тензоры, описывающие цвета и размеры изображения. Пиксельные значения являются входными данными для модели зрения. Чтобы гарантировать, что предобученная модель получает корректный вход, обработчик изображений может выполнять следующие операции, обеспечивая точное соответствие изображения тем, на которых модель была предобучена.
- center-crop или resize изображения
- нормализовать или масштабировать значения пикселей
Используйте from_pretrained() для загрузки конфигурации процессора изображений (размер изображения, необходимость нормализации и масштабирования и т. д.) из визуальной модели на Hugging Face Hub или из локального каталога. Конфигурация каждой предобученной модели сохраняется в файле preprocessor_config.json.
Если процессор изображений является частью мультимодального процессора, его конфигурация вложенным образом хранится в processor_config.json. Подробности см. в разделе Сохранение и загрузка процессора.
from transformers import AutoImageProcessor
image_processor = AutoImageProcessor.from_pretrained("google/vit-base-patch16-224")Передайте изображение в image processor, чтобы преобразовать его в пиксельные значения, и установите return_tensors="pt", чтобы получить тензоры PyTorch. При необходимости выведите входные данные, чтобы увидеть, как изображение выглядит в виде тензора.
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")Это руководство описывает класс процессора изображений и способы предобработки изображений для моделей зрения.
Классы процессоров изображений
Обработчики изображений используют архитектуру на основе бэкендов с двумя бэкендами:
- TorchvisionBackend — реализация по умолчанию, использующая torchvision. Поддерживает ускорение на GPU и до 33 раз быстрее, чем бэкенд PIL, для пакетов входных данных torch.Tensor. Все модели поддерживают этот бэкенд; более новые модели поддерживают только его.
- PilBackend — альтернатива на базе PIL/NumPy. Переносимый, работает только на CPU. Доступен только для старых моделей, где полезно воспроизвести точные численные результаты исходной реализации.
Активный бэкенд загруженного процессора можно проверить с помощью его атрибута backend (например, processor.backend == "torchvision"). Каждый класс-наследник класса обработки изображений наследует от ImageProcessingMixin, который предоставляет методы from_pretrained() и save_pretrained().
Существует два способа загрузки обработчика изображений: с помощью AutoImageProcessor или напрямую из класса, специфичного для модели.
API AutoClass предоставляет удобный способ загрузить процессор изображений, не указывая напрямую модель, с которой он связан.
Используйте from_pretrained() с аргументом backend, чтобы выбрать бэкенд. Если backend не указан (значение по умолчанию), используется torchvision, если он установлен, в противном случае — PIL. Обратите внимание, что backend="pil" поддерживается только для старых моделей; новые модели предоставляют только бэкенд torchvision.
Для максимально точного соответствия предобработке, использованной при обучении модели, применяйте тот бэкенд, который указан в её документации или коде обучения. Если конвейер обучения использует PIL, а модель поддерживает оба бэкенда, передайте backend="pil". Смена бэкенда может изменить значения пикселей после изменения размера, а обновления Pillow или torchvision также могут повлиять на них. Для воспроизводимой предобработки фиксируйте версии бэкенда и библиотек для работы с изображениями.
Небольшой набор более старых моделей (Chameleon, Flava, Idefics3, SmolVLM) использует интерполяцию Lanczos. Их backend по умолчанию зависит от версии torchvision. При torchvision > 0.27 Lanczos поддерживается нативно, и эти модели по умолчанию используют torchvision. В более старых версиях torchvision используется BICUBIC, поэтому по умолчанию применяется PIL, чтобы сохранить исходные результаты. Явно передайте
backend="torchvision", чтобы переопределить значение по умолчанию.
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")Каждый image processor связан с конкретной предобученной vision-моделью, а его конфигурация содержит ожидаемый размер модели и параметры нормализации.
Загрузите процессор бэкенда torchvision непосредственно из класса, специфичного для модели.
from transformers import ViTImageProcessor
image_processor = ViTImageProcessor.from_pretrained("google/vit-base-patch16-224")Для моделей, которые это поддерживают, вы можете загрузить бэкенд PIL с помощью класса с суффиксом Pil. Это полезно, когда вам нужна точная численная идентичность с исходной реализацией.
from transformers import ViTImageProcessorPil
image_processor = ViTImageProcessorPil.from_pretrained("google/vit-base-patch16-224")Процессоры бэкенда Torchvision
TorchvisionBackend — это по умолчанию используемый бэкенд. Убедитесь, что torchvision установлен, затем загрузите его с помощью backend="torchvision" (или просто опустите backend, так как torchvision выбирается автоматически, если доступен).
from transformers import AutoImageProcessor
processor = AutoImageProcessor.from_pretrained("facebook/detr-resnet-50", backend="torchvision")С помощью аргумента device можно управлять устройством, на котором выполняется обработка. По умолчанию, если входные данные являются тензорами, обработка выполняется на том же устройстве, что и входные данные; в противном случае используется CPU. В примере ниже обработка выполняется на ускорителе.
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)Динамическое разрешение
Большинство процессоров изображений масштабируют каждое изображение до одного фиксированного разрешения. Динамическое разрешение позволяет некоторым моделям сохранять исходное соотношение сторон и увеличивать объём предобработанных данных вместе с размером изображения, так что детализированное фото получает больше патчей, чем маленькая иконка, и модель тратит вычислительные ресурсы там, где есть что рассматривать.
Способ разделения изображения зависит от конкретной модели. Некоторые модели разрезают изображение на переменное количество фиксированных по размеру фрагментов, ограниченных параметрами, такими как min_patches и max_patches. Другие модели изменяют разрешение изображения до того, которое лучше всего ему подходит, выбирая его из предопределённого списка соотношений сторон или вычисляя на основе бюджета пикселей.
Список параметров, значений по умолчанию и форм выходных данных модели указан на её странице документации.
Предобработка
Модели компьютерного зрения в Transformers ожидают вход в виде тензоров PyTorch со значениями пикселей. Процессор изображений выполняет преобразование изображений в значения пикселей, представленные размером батча, количеством каналов, высотой и шириной. Для этого изображение изменяется в размере (с центрированным кадрированием), а значения пикселей нормализуются и масштабируются до значений, ожидаемых моделью.
Предобработка изображений не то же самое, что аугментация изображений. Аугментация вносит изменения (яркость, цвета, поворот и т. д.) в изображение с целью создания новых обучающих примеров или предотвращения переобучения. Предобработка вносит изменения в изображение с целью приведения его к ожидаемому формату входных данных предобученной модели.
Как правило, изображения подвергаются аугментации (для повышения производительности), а затем предобработки перед передачей в модель. Для аугментации можно использовать любую библиотеку (Albumentations, Kornia), а для предобработки — процессор изображений.
В этом руководстве для аугментации используется модуль transforms из torchvision.
Начните с загрузки небольшой выборки из набора данных food101.
from datasets import load_dataset
dataset = load_dataset("ethz/food101", split="train[:100]")Из модуля transforms используйте API Compose, чтобы объединить RandomResizedCrop и ColorJitter. Эти трансформации случайно вырезают и изменяют размер изображения, а также случайно корректируют его цвета.
Размер изображения, к которому выполняется случайное обрезание, можно получить из процессора изображений. Для некоторых моделей ожидаются точные значения высоты и ширины, тогда как для других достаточно указать только 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)])Примените трансформации к изображениям и преобразуйте их в формат RGB. Затем передайте аугментированные изображения в процессор изображений, чтобы получить пиксельные значения.
Параметр do_resize установлен в False, так как изображения уже были изменены в размере на этапе аугментации с помощью RandomResizedCrop. Если вы не применяете аугментацию, процессор изображений автоматически изменяет размер изображений и нормализует их с помощью значений image_mean и image_std. Эти значения находятся в файле конфигурации преобразователя.
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Примените объединённую функцию аугментации и предобработки ко всему набору данных на лету с помощью set_transform.
dataset.set_transform(transforms)
Преобразуйте значения пикселей обратно в изображение, чтобы увидеть, как оно было дополнено и предобработано.
import numpy as np
import matplotlib.pyplot as plt
img = dataset[0]["pixel_values"]
plt.imshow(img.permute(1, 2, 0))
Для других задач компьютерного зрения, таких как обнаружение объектов или сегментация, процессор изображений включает методы постобработки для преобразования сырого вывода модели в осмысленные предсказания, такие как ограничивающие рамки или карты сегментации.
Заполнение
Некоторые модели, например DETR, применяют scale augmentation во время обучения, из-за чего изображения в одном батче могут иметь разные размеры. Изображения с разными размерами нельзя объединять в один батч.
Чтобы исправить это, дополните изображения специальным токеном отступов 0. Используйте метод pad для дополнения изображений и определите пользовательскую функцию collate для объединения их в батч.
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


