Transformers documentation

Görüntü işleyicileri

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Görüntü işleyicileri

Görüntü işleyicileri, görüntüleri piksel değerlerine dönüştürür; bu değerler, görüntü renklerini ve boyutunu temsil eden tensörlerdir. Piksel değerleri, bir görme modelinin girdileridir. Ön eğitilmiş bir modelin doğru girdiyi almasını sağlamak için bir görüntü işleyici, bir görüntünün modelin ön eğitimi sırasında kullanılan görüntülerle birebir aynı olmasını sağlamak üzere aşağıdaki işlemleri gerçekleştirebilir.

  • bir görüntüyü merkezden kırpın veya yeniden boyutlandırın
  • piksel değerlerini normalize edin veya yeniden ölçekleyin

Görüntü işleyici yapılandırmasını (görüntü boyutu, normalize etme ve yeniden ölçeklendirme gerekip gerekmediği vb.) Hugging Face Hub'daki veya yerel dizindeki bir görme modelinden yüklemek için from_pretrained() kullanın. Her önceden eğitilmiş modelin yapılandırması bir preprocessor_config.json dosyasında saklanır.

Bir görüntü işleyici, çok modlu bir işleyicinin parçası olduğunda, yapılandırması bunun yerine processor_config.json içinde iç içe yer alır. Ayrıntılar için İşleyiciyi kaydetme ve yükleme bölümüne bakın.

from transformers import AutoImageProcessor

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

Görsel işleyiciye bir görsel iletin ve onu piksel değerlerine dönüştürün; PyTorch tensörlerini döndürmek için return_tensors="pt" ayarlayın. Görselin bir tensör olarak nasıl göründüğünü görmek için girdileri yazdırabilirsiniz.

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

Bu kılavuz, görüntü işleyici sınıfını ve görme modelleri için görüntülerin nasıl ön işleme tabi tutulacağını ele alır.

Görüntü işleyici sınıfları

Görüntü işleyiciler, iki arka uca sahip arka uç tabanlı bir mimari kullanır:

  • TorchvisionBackend — varsayılan torchvision tabanlı uygulama. torch.Tensor girdileri için toplu işlemlerde PIL arka ucundan GPU hızlandırması sayesinde 33 kata kadar daha hızlıdır. Tüm modeller bu arka ucu destekler; daha yeni modeller yalnızca bu arka ucu destekler.
  • PilBackend — PIL/NumPy alternatifi. Taşınabilir ve yalnızca CPU destekli. Yalnızca, orijinal uygulamanın tam sayısal çıktılarını yeniden üretmenin faydalı olduğu eski modeller için kullanılabilir.

Yüklenmiş bir işlemcinin etkin arka ucu, backend özniteliğiyle incelenebilir (ör. processor.backend == "torchvision"). Her görüntü işlemcisi, from_pretrained() ve save_pretrained() yöntemlerini sağlayan ImageProcessingMixin sınıfından türetilir.

Bir görüntü işleyiciyi yüklemenin iki yolu vardır: AutoImageProcessor ile veya doğrudan modele özgü bir sınıftan.

AutoImageProcessor
model-özel görüntü işleyici

AutoClass API'si, görüntü işleyicinin ilişkili olduğu modeli doğrudan belirtmeden bir görüntü işleyici yüklemek için kullanışlı bir yöntem sağlar.

backend argümanını kullanarak from_pretrained() ile backend seçilir. backend belirtilmediğinde (varsayılan), yüklüyse torchvision seçilir, aksi halde PIL kullanılır. backend="pil" yalnızca eski modeller için desteklenir; yeni modeller yalnızca torchvision backend'ini sunar.

Bir modelin eğitim ön işleme sürecine en yakın eşleşme için, belgelerinde veya eğitim kodunda belirtilen arka ucu kullanın. Eğitim hattı PIL kullanıyorsa ve model her iki arka ucu da destekliyorsa, backend="pil" parametresini iletin. Arka uç değiştirildiğinde yeniden boyutlandırılmış piksel değerleri değişebilir; ayrıca Pillow veya torchvision güncellemeleri de bu değerleri değiştirebilir. Tekrarlanabilir ön işleme için arka uç ve görsel kütüphanesi sürümlerini sabit tutun.

Küçük bir eski model seti (Chameleon, Flava, Idefics3, SmolVLM) Lanczos interpolasyonu kullanır. Varsayılan arka uçları, torchvision sürümünüze bağlıdır. torchvision > 0.27 ile Lanczos yerel olarak desteklenir ve bu modeller varsayılan olarak torchvision kullanır. Eski torchvision sürümleri BICUBIC'e geri döner, bu nedenle orijinal çıktıları korumak için varsayılan PIL'dir. Varsayılanı geçersiz kılmak için backend="torchvision" parametresini açıkça iletin.

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 arka uç işlemcileri

TorchvisionBackend, varsayılan arka uçtur. torchvision paketinin yüklü olduğundan emin olun, ardından backend="torchvision" ile yükleyin (veya backend parametresini tamamen atlayın; torchvision mevcut olduğunda otomatik olarak seçilir).

from transformers import AutoImageProcessor

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

İşlemin hangi cihazda gerçekleştirileceğini device argümanı ile kontrol edin. Girdiler tensörlerse, varsayılan olarak işleme girdilerle aynı cihazda yapılır; aksi halde CPU'ya geri düşülür. Aşağıdaki örnek, işlemin bir hızlandırıcıda çalıştırılmasını gösterir.

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

Benchmarks, NVIDIA A10G Tensor Core GPU'ya sahip bir AWS EC2 g5.2xlarge örneğinden elde edilmiştir.

Dinamik çözünürlük

Çoğu görüntü işleyici, her görüntüyü tek bir sabit çözünürlüğe yeniden boyutlandırır. Dinamik çözünürlük, bazı modellerin orijinal en-boy oranını korumasına ve ön işlenmiş veri miktarının görüntüyle birlikte artmasına olanak tanır; böylece detaylı bir fotoğraf, küçük bir simgeye kıyasla daha fazla yama (patch) alır ve model, üzerinde durulacak bir şey olduğu yerlerde hesaplama gücünü harcar.

Görüntünün nasıl bölündüğü modele özgüdür. Bazı modeller, görüntüyü min_patches ve max_patches gibi parametrelerle sınırlanan değişken sayıda sabit boyutlu yamaya (patch) böler. Diğer modeller ise görüntüyü, önceden tanımlı bir en-boy oranı listesinden seçilen veya piksel bütçesinden türetilen en uygun çözünürlüğe yeniden boyutlandırır.

Parametreler, varsayılan değerler ve çıktı biçimleri için modelin dokümantasyon sayfasına başvurun.

Ön işleme

Transformers’ görsele dayalı modelleri, girdiyi piksel değerlerinden oluşan PyTorch tensörleri olarak bekler. Bir görüntü işleyici, görüntülerin piksel değerlerine dönüştürülmesini yönetir; bu değerler, parti boyutu, kanal sayısı, yükseklik ve genişlik ile temsil edilir. Bunu başarmak için bir görüntü yeniden boyutlandırılır (merkezden kırpılır) ve piksel değerleri, modelin beklediği değerlere göre normalize edilip yeniden ölçeklenir.

Görsel ön işleme, görsel artırma ile aynı şey değildir. Görsel artırma, yeni eğitim örnekleri oluşturmak veya aşırı uyumu önlemek amacıyla bir görselde değişiklikler (parlaklık, renkler, döndürme vb.) yapar. Görsel ön işleme ise bir önceden eğitilmiş modelin beklenen girdi biçimine uyum sağlamak amacıyla bir görselde değişiklikler yapar.

Genellikle görüntüler, modele aktarılmadan önce performans artışı sağlamak amacıyla artırılır (augmentation) ve ardından ön işlemden geçirilir. Artırma için herhangi bir kütüphaneyi (Albumentations, Kornia) ve ön işleme için bir görüntü işleyiciyi kullanabilirsiniz.

Bu kılavuz, artırma (augmentation) için torchvision transforms modülünü kullanır.

food101 veri setinin küçük bir örneğini yükleyerek başlayın.

from datasets import load_dataset

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

transforms modülünden, Compose API'sini kullanarak RandomResizedCrop ve ColorJitter dönüşümlerini bir araya getirin. Bu dönüşümler bir görüntüyü rastgele kırpıp yeniden boyutlandırır ve görüntünün renklerini rastgele ayarlar.

Rastgele kırpılacak görüntü boyutu, görüntü işleyiciden alınabilir. Bazı modellerde kesin bir yükseklik ve genişlik beklenirken, diğerlerinde yalnızca shortest_edge gereklidir.

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

Dönüşümleri görüntülere uygulayın ve onları RGB biçimine dönüştürün. Ardından artırılmış görüntüleri, piksel değerlerini döndürmesi için görüntü işleyicisine iletin.

do_resize parametresi, görüntülerin artırma adımında RandomResizedCrop tarafından zaten yeniden boyutlandırıldığı için False olarak ayarlanır. Görüntüleri artırmıyorsanız, görüntü işleyicisi görüntüleri image_mean ve image_std değerleriyle otomatik olarak yeniden boyutlandırır ve normalleştirir. Bu değerler ön işleyici yapılandırma dosyasında bulunur.

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

Birleşik artırma ve ön işleme işlevini set_transform ile tüm veri setine anlık olarak uygulayın.

dataset.set_transform(transforms)

Görüntünün nasıl artırıldığını ve ön işlendiğini görmek için piksel değerlerini tekrar bir görüntüye dönüştürün.

import numpy as np
import matplotlib.pyplot as plt

img = dataset[0]["pixel_values"]
plt.imshow(img.permute(1, 2, 0))
önce
sonra

Nesne tespiti veya segmentasyon gibi diğer görü görevlerinde, görüntü işleyici, bir modelin ham çıktısını sınırlayıcı kutular veya segmentasyon haritaları gibi anlamlı tahminlere dönüştürmek için son işleme yöntemleri içerir.

Dolgu

DETR gibi bazı modeller, eğitim sırasında scale augmentation uygular ve bu, bir batch içindeki görüntülerin farklı boyutlarda olmasına neden olabilir. Farklı boyutlardaki görüntüler birlikte batchlenemez.

Bunu düzeltmek için görüntüleri 0 özel dolgu belirteciyle doldurun. Görüntüleri doldurmak için pad yöntemini kullanın ve onları birlikte gruplamak için özel bir collate işlevi tanımlayın.

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