Transformers documentation
이미지 프로세서
이미지 프로세서
Image processor는 이미지를 픽셀 값으로 변환합니다. 픽셀 값은 이미지의 색상과 크기를 나타내는 tensor이며, vision model의 입력으로 사용됩니다. 사전 학습된 모델이 올바른 입력을 받도록 보장하기 위해, image processor는 이미지가 모델이 사전 학습된 이미지와 정확히 일치하도록 다음 연산을 수행할 수 있습니다.
- 이미지를 center-crop하거나 resize
- 픽셀 값을 정규화하거나 다시 스케일링
Hugging Face Hub 또는 로컬 디렉터리의 비전 모델에서 이미지 프로세서 구성(이미지 크기, 정규화 및 재스케일링 여부 등)을 로드하려면 from_pretrained()를 사용합니다. 각 사전 학습 모델의 구성은 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는 두 가지 백엔드를 사용하는 백엔드 기반 아키텍처를 사용합니다:
- TorchvisionBackend — 기본 torchvision 기반 구현입니다. torch.Tensor 입력 배치의 경우 GPU 가속을 지원하며 PIL 백엔드보다 최대 33배 빠릅니다. 모든 모델이 이 백엔드를 지원하며, 새로운 모델은 이 백엔드만 지원합니다.
- PilBackend — PIL/NumPy 대안입니다. 이식성이 뛰어나며 CPU만 지원합니다. 원래 구현의 정확한 수치 출력을 재현하는 데 유용한 구형 모델에서만 사용할 수 있습니다.
로드된 프로세서의 활성 백엔드는 backend 속성으로 확인할 수 있습니다(예: processor.backend == "torchvision"). 각 이미지 프로세서는 ImageProcessingMixin을 서브클래스로 가지며, 이 믹신은 from_pretrained() 및 save_pretrained() 메서드를 제공합니다.
이미지 프로세서 로딩 방법은 두 가지가 있습니다. AutoImageProcessor를 사용하거나 모델별 클래스에서 직접 로딩하는 것입니다.
AutoClass API는 이미지 프로세서와 연관된 모델을 직접 지정하지 않고도 이미지 프로세서를 로드할 수 있는 편리한 방법을 제공합니다.
Use from_pretrained() with the backend argument to select the backend. When backend is omitted (the default), torchvision is picked when it is installed and PIL is used otherwise. Note that backend="pil" is only supported for older models; newer models only expose the torchvision backend.
모델의 학습 전처리와 가장 가까운 설정을 사용하려면, 해당 모델의 문서나 학습 코드에 명시된 백엔드를 사용하세요. 학습 파이프라인에서 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")각 이미지 프로세서(image processor)는 특정 사전 학습된 비전 모델과 연결되며, 그 구성에는 모델이 기대하는 크기 및 정규화 파라미터가 포함되어 있습니다.
모델별 클래스에서 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)동적 해상도
대부분의 이미지 프로세서(Processor)는 모든 이미지를 하나의 고정된 해상도로 리사이즈합니다. 동적 해상도(Dynamic resolution)는 일부 모델이 원래의 종횡비를 유지하도록 허용하며, 전처리 데이터의 양이 이미지에 따라 증가하게 합니다. 따라서 상세한 사진은 작은 아이콘보다 더 많은 패치(Patch)를 생성하며, 모델은 실제로 살펴볼 것이 있는 부분에 컴퓨트(Compute)를 집중하게 됩니다.
이미지가 어떻게 분할되는지는 모델에 따라 다릅니다. 일부 모델은 min_patches와 max_patches와 같은 매개변수로 제한되는 가변 개수의 고정 크기 패치로 이미지를 크롭합니다. 다른 모델은 미리 정의된 종횡비 목록에서 선택하거나 픽셀 예산에서 유도된, 이미지에 가장 적합한 해상도로 이미지를 리사이즈합니다.
모델의 매개변수, 기본값 및 출력 형식은 해당 모델의 문서 페이지를 참조하세요.
전처리
Transformers의 비전 모델은 픽셀 값의 PyTorch 텐서를 입력으로 기대합니다. 이미지 프로세서가 이미지를 픽셀 값으로 변환하는 역할을 담당하며, 이는 배치 크기, 채널 수, 높이, 너비로 표현됩니다. 이를 위해 이미지는 리사이즈(중앙 크롭)되고, 픽셀 값은 모델이 기대하는 값으로 정규화 및 재스케일링됩니다.
이미지 전처리와 이미지 증강은 다릅니다. 이미지 증강은 새로운 학습 예시를 생성하거나 과적합을 방지하기 위해 이미지에 변경 사항(밝기, 색상, 회전 등)을 가합니다. 이미지 전처리는 사전 학습된 모델이 기대하는 입력 형식에 맞추기 위해 이미지에 변경 사항을 가합니다.
일반적으로 이미지는 성능 향상을 위해 증강(augmentation)된 후, 모델에 전달되기 전에 전처리됩니다. 증강에는 어떤 라이브러리(Albumentations, Kornia)든 사용할 수 있으며, 전처리에는 이미지 프로세서(image processor)를 사용합니다.
이 가이드는 증강을 위해 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 형식으로 변환합니다. 그런 다음 증강된 이미지를 이미지 프로세서에 전달하여 픽셀 값을 반환합니다.
이미지가 증강 단계에서 RandomResizedCrop에 의해 이미 리사이즈되었기 때문에 do_resize 파라미터는 False로 설정됩니다. 이미지를 증강하지 않는 경우, 이미지 프로세서가 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 examplesset_transform를 사용하여 결합된 증강 및 전처리 함수를 데이터셋 전체에 온더플라이로 적용합니다.
dataset.set_transform(transforms)
pixel values를 다시 이미지로 변환하여 이미지가 어떻게 증강 및 전처리되었는지 확인합니다.
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


