图像处理器
图像处理器将图像转换为像素值,即表示图像颜色和尺寸的张量。像素值是视觉模型的输入。为了确保预训练模型接收到正确的输入,图像处理器可以执行以下操作,以确认图像与模型预训练时所使用的图像完全一致。
- 对图像进行中心裁剪或调整大小
- 对像素值进行归一化或重新缩放
使用 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")将图像传入图像处理器以将其转换为像素值,并设置 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-backed 实现。对于 torch.Tensor 输入批次,其 GPU 加速性能比 PIL 后端快至 33 倍。所有模型均支持此后端;较新的模型仅支持此后端。
- PilBackend — PIL/NumPy 替代方案。可移植且仅支持 CPU。仅适用于较旧的模型,在这些模型中,它有助于复现原始实现的精确数值输出。
已加载的处理器可通过其 backend 属性检查当前使用的后端(例如 processor.backend == "torchvision")。每个图像处理器都继承自 ImageProcessingMixin,该混入类提供了 from_pretrained() 和 save_pretrained() 方法。
加载图像处理器有两种方式:使用 AutoImageProcessor,或直接从特定于模型的类中加载。
AutoClass API 提供了一种便捷的方法来加载图像处理器,而无需直接指定该图像处理器所关联的模型。
使用 from_pretrained() 并传入 backend 参数来选择后端。如果省略 backend(默认情况),则优先使用已安装的 torchvision,否则使用 PIL。请注意,backend="pil" 仅适用于较旧的模型;较新的模型仅支持 torchvision 后端。
要最接近模型训练时的预处理,请使用其文档或训练代码中指定的后端。如果训练流水线使用 PIL 且模型同时支持两种后端,请传入 backend="pil"。切换后端可能会改变调整大小后的像素值,Pillow 或 torchvision 的更新也可能导致其变化。为了实现可复现的预处理,请固定后端和图像库的版本。
少数较旧的模型(Chameleon、Flava、Idefics3、SmolVLM)使用 Lanczos 插值。它们的默认后端取决于您的 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")每个图像处理器都与特定的预训练视觉模型相关联,其配置包含该模型所期望的尺寸和归一化参数。
直接从模型特定的类中加载 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)动态分辨率
大多数图像处理器会将所有图像调整为固定的分辨率。动态分辨率允许某些模型保留原始宽高比,并让预处理后的数据量随图像大小而增长,因此细节丰富的照片会比小图标生成更多的 patch,模型的计算资源也会集中在有内容可分析的区域。
图像的划分方式因模型而异。一些模型会将图像裁剪为数量可变的固定尺寸块,其数量受 min_patches 和 max_patches 等参数限制。其他模型则会将图像调整到最合适的分辨率,该分辨率要么从预定义的宽高比列表中选取,要么根据像素预算推导得出。
有关模型的参数、默认值和输出形状,请参阅该模型的文档页面。
预处理
Transformers 的视觉模型期望输入为像素值的 PyTorch 张量。图像处理器负责将图像转换为像素值,其表示形式为批次大小、通道数、高度和宽度。为此,图像会被调整大小(中心裁剪),并且像素值会被归一化和重新缩放至模型所期望的数值范围。
图像预处理与图像增强不同。图像增强会对图像进行修改(例如亮度、颜色、旋转等),目的是创建新的训练样本或防止过拟合。图像预处理则对图像进行修改,目的是使其符合预训练模型所期望的输入格式。
通常,图像会先进行数据增强(以提升性能),然后再进行预处理,最后传入模型。您可以使用任意库(Albumentations、Kornia)进行数据增强,并使用图像处理器进行预处理。
本指南使用 torchvision 的 transforms 模块进行数据增强。
首先加载 food101 数据集的一个小型样本。
from datasets import load_dataset
dataset = load_dataset("ethz/food101", split="train[:100]")从 transforms 模块中,使用 Compose API 将 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


