画像プロセッサ

Image processorは、画像をピクセル値に変換します。ピクセル値は、画像の色とサイズを表すテンソルであり、ビジョンモデルへの入力となります。事前学習済みモデルが正しい入力を確実に受け取れるようにするため、Image processorは、画像がモデルの事前学習に使用された画像と完全に一致するよう、以下の操作を実行できます。

画像を中央クロップまたはリサイズする
ピクセル値を正規化または再スケーリング

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

このガイドでは、画像プロセッサクラスと、ビジョンモデル用の画像の前処理方法について説明します。

画像プロセッサクラス

Image processor は、2 つのバックエンドを持つバックエンドベースのアーキテクチャを使用します:

TorchvisionBackend — デフォルトの torchvision ベースの実装です。GPU 加速に対応しており、torch.Tensor 入力のバッチ処理では PIL バックエンドと比較して最大 33 倍高速です。すべてのモデルがこのバックエンドをサポートしています。新しいモデルは、このバックエンドのみをサポートします。
PilBackend — PIL/NumPy による代替実装。ポータブルで CPU のみ対応です。元の実装と完全に一致する数値出力を再現する必要がある場合、古いモデルでのみ利用可能です。

読み込まれたプロセッサのアクティブなバックエンドは、そのbackend属性（例: processor.backend == "torchvision"）で確認できます。各イメージプロセッサはImageProcessingMixinをサブクラス化しており、from_pretrained()およびsave_pretrained()メソッドが提供されています。

画像プロセッサを読み込む方法には2つあります。AutoImageProcessorを使用する方法と、モデル固有のクラスから直接読み込む方法です。

AutoImageProcessor

モデル固有の画像プロセッサ

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)

Benchmarks

ベンチマークは、NVIDIA A10G Tensor Core GPUを搭載したAWS EC2 g5.2xlargeインスタンスから取得されています。

動的解像度

ほとんどの画像プロセッサは、すべての画像を1つの固定解像度にリサイズします。動的解像度により、一部のモデルは元の縦横比を維持でき、前処理データの量が画像の大きさに応じて増加します。これにより、詳細な写真には小さなアイコンよりも多くのパッチが割り当てられ、モデルは注目すべき内容がある箇所に計算リソースを集中させることができます。

画像の分割方法はモデルによって異なります。一部のモデルでは、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形式に変換します。次に、拡張された画像をimage processorに渡し、ピクセル値を返します。

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

前

後

オブジェクト検出やセグメンテーションなどの他のビジョンタスクでは、image processorには、モデルの生出力をバウンディングボックスやセグメンテーションマップといった意味のある予測に変換する後処理メソッドが含まれています。

パディング

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

Update on GitHub