Transformers documentation
비전 처리 컴포넌트 추가
비전 처리 컴포넌트 추가
비전 모델을 추가하려면 표준 모듈형 접근 방식에 이미지 또는 비디오 처리 구성 요소를 추가해야 합니다. 이미지 전용 모델에는 이미지 프로세서가, 비디오 모델에는 비디오 프로세서가 필요하며, 이 둘은 각각 AutoImageProcessor와 AutoVideoProcessor 진입점을 통해 접근할 수 있습니다.
모델링 및 config 단계의 경우, 먼저 모듈형 가이드를 따르세요.
이미지 프로세서
모델이 이미지를 소비할 때 이미지 프로세서(image processor)를 생성합니다. torchvision 백엔드가 기본이며 GPU 가속을 지원합니다. torchvision이 사용 불가능한 경우 PIL이 폴백으로 사용됩니다.
두 이미지 프로세서 클래스는 동일한 전처리 로직을 공유하지만 백엔드가 다릅니다. 생성자 시그니처와 기본값은 동일해야 합니다. AutoImageProcessor.from_pretrained()는 로드 시점에 백엔드를 선택하며, torchvision이 사용 불가능한 경우 PIL로 폴백합니다. 시그니처가 일치하지 않으면 동일한 저장된 설정이 환경에 따라 다르게 동작합니다.
torchvision
image_processing_<model_name>.py 파일을 만들고 TorchvisionBackend를 상속하는 클래스를 정의하세요. 프로세서가 표준 [ImagesKwargs] 외에 커스텀 파라미터가 필요하면 kwargs 클래스를 정의하세요.
from ...image_processing_backends import TorchvisionBackend
from ...image_utils import OPENAI_CLIP_MEAN, OPENAI_CLIP_STD, PILImageResampling
from ...processing_utils import ImagesKwargs, Unpack
from ...utils import auto_docstring
class MyModelImageProcessorKwargs(ImagesKwargs, total=False):
tile_size: int # any model-specific kwargs
@auto_docstring
class MyModelImageProcessor(TorchvisionBackend):
resample = PILImageResampling.BICUBIC
image_mean = OPENAI_CLIP_MEAN
image_std = OPENAI_CLIP_STD
size = {"shortest_edge": 224}
do_resize = True
do_rescale = True
do_normalize = True
do_convert_rgb = True
def __init__(self, **kwargs: Unpack[MyModelImageProcessorKwargs]):
super().__init__(**kwargs)참고로 LlavaOnevisionImageProcessor를 확인하세요.
PIL
image_processing_pil_<model_name>.py 파일을 PilBackend를 상속하는 클래스로 생성합니다. torchvision이 설치되지 않은 경우 실패할 수 있으므로 torchvision 파일에서 가져오지 않고 kwargs 클래스를 여기에 복제합니다. 두 파일이 동기화되도록 # Adapted from 주석을 추가합니다. 커스텀 파라미터가 없는 프로세서의 경우 ImagesKwargs를 직접 사용합니다.
from ...image_processing_backends import PilBackend
from ...image_utils import OPENAI_CLIP_MEAN, OPENAI_CLIP_STD, PILImageResampling
from ...processing_utils import ImagesKwargs, Unpack
from ...utils import auto_docstring
# Adapted from transformers.models.my_model.image_processing_my_model.MyModelImageProcessorKwargs
class MyModelImageProcessorKwargs(ImagesKwargs, total=False):
tile_size: int # any model-specific kwargs
@auto_docstring
class MyModelImageProcessorPil(PilBackend):
resample = PILImageResampling.BICUBIC
image_mean = OPENAI_CLIP_MEAN
image_std = OPENAI_CLIP_STD
size = {"shortest_edge": 224}
do_resize = True
do_rescale = True
do_normalize = True
do_convert_rgb = True
def __init__(self, **kwargs: Unpack[MyModelImageProcessorKwargs]):
super().__init__(**kwargs)참고로 LlavaOnevisionImageProcessorPil을 확인하세요.
후처리 메서드 추가
프로세서 클래스에 후처리 메서드를 직접 추가합니다. 후처리 메서드는 모델 출력(outputs)과 해당 후처리 메서드에 필요한 추가 인수를 인수로 호출됩니다.
class MyModelImageProcessor(TorchvisionBackend):
...
def post_process_my_task(self, outputs, ...):
...Post-processor는 단순한 객체의 목록(list[str] 또는 list[torch.Tensor]) 또는 복잡한 객체의 목록(list[MyTaskPostProcessorOutput] 또는 list[dict])을 반환합니다. Post-processor의 출력은 src/transformers/image_processing_outputs.py에서 정의되며 BatchFeature를 상속합니다.
class MyTaskPostProcessorOutput(BatchFeature):
predictions: torch.Tensor
scores: torch.Tensor비디오 프로세서
모델이 비디오 또는 샘플링된 비디오 프레임을 소비할 때 비디오 프로세서 추가
모델 디렉터리에 video_processing_<model_name>.py를 생성합니다. BaseVideoProcessor는 TorchvisionBackend를 상속하며, 공유되는 디코딩, 프레임 샘플링, 리사이즈, 리스케일링, 정규화, 저장 및 로드 동작을 제공합니다.
클래스 속성은 기본 전처리 값입니다. 사용자는 초기화 시점 또는 호출 시점에 이를 재정의할 수 있습니다. size, crop_size, do_resize, do_sample_frames, num_frames, fps와 같이 가능한 경우 VideosKwargs와 동일한 이름을 사용하세요.
비디오 프로세서에 표준 VideosKwargs를 넘어선 커스텀 파라미터가 필요한 경우 kwargs 클래스를 정의하세요. 이를 valid_kwargs로 설정하고, 런타임 검증과 자동 생성된 docstring을 위해 __init__의 주석으로 사용하세요.
from ...processing_utils import Unpack, VideosKwargs
from ...utils import auto_docstring
from ...video_processing_utils import BaseVideoProcessor
class MyModelVideoProcessorKwargs(VideosKwargs, total=False):
min_frames: int
max_frames: int
@auto_docstring
class MyModelVideoProcessor(BaseVideoProcessor):
size = {"shortest_edge": 224}
crop_size = {"height": 224, "width": 224}
do_resize = True
do_center_crop = True
do_normalize = True
do_sample_frames = True
num_frames = 16
model_input_names = ["pixel_values_videos"]
valid_kwargs = MyModelVideoProcessorKwargs
def __init__(self, **kwargs: Unpack[MyModelVideoProcessorKwargs]):
super().__init__(**kwargs)기본 균등 샘플러로 표현할 수 없는 샘플링 규칙이 모델에 필요할 때만 sample_frames()를 오버라이드하세요. 예를 들어, 일부 모델은 최소 또는 최대 프레임 수를 강제하거나 모델 특정 제약 조건에 기반하여 샘플링합니다.
모델의 forward 메서드가 레거시 입력 이름을 기대하는 경우, preprocess를 오버라이드하고 기본 구현을 호출한 후 키 이름을 변경하세요.
class MyModelVideoProcessor(BaseVideoProcessor):
model_input_names = ["pixel_values"]
def preprocess(self, videos, **kwargs):
batch = super().preprocess(videos, **kwargs)
batch["pixel_values"] = batch.pop("pixel_values_videos")
return batch변환 스크립트에서 video processor를 인스턴스화하고 save_pretrained()를 호출하여 checkpoint와 함께 저장합니다. ProcessorMixin이 video processor를 래핑하는 경우, 대신 save_pretrained()를 호출합니다. 전처리 설정 파일을 수동으로 생성하거나 수정하지 마세요.
참고로 Qwen3VLVideoProcessor를 확인하세요.
클래스 등록
__all__에 새 클래스를 파일 하단에 추가한 다음, 다음 명령으로 __init__.py를 다시 생성합니다:
python utils/check_inits.py --fix_and_overwrite
Auto 클래스가 새 클래스를 로드할 수 있도록 모델 구성에 매핑합니다. 생성된 자동 매핑 파일의 상단에 경고가 있습니다. 수동으로 편집하지 마세요. 모델 구성을 추가하거나 업데이트한 다음 다음을 실행합니다:
python utils/check_auto.py --fix_and_overwrite
매핑이 생성된 후, src/transformers/models/auto/auto_mappings.py의 관련 매핑에 모델 유형이 표시되는지 확인하세요.
- AutoImageProcessor의
IMAGE_PROCESSOR_MAPPING_NAMES - AutoVideoProcessor의
VIDEO_PROCESSOR_MAPPING_NAMES
테스트
모델 테스트 디렉터리에서 각 비전 처리 컴포넌트에 대한 테스트를 추가합니다. 공유 테스트 믹신을 사용하고 모델별 초기화 kwargs를 제공합니다. 이미지 테스트는 공유 테스터를 통해 프로세서 백엔드를 자동으로 발견하는 반면, 비디오 테스트는 프로세서 클래스와 픽스처를 명시적으로 구성합니다.
이미지 프로세서 테스트
Image processor 테스트는 tests/models/<model_name>/test_image_processing_<model_name>.py에 있습니다. ImageProcessingTester를 상속하는 tester와 ImageProcessingTestMixin 및 unittest.TestCase를 상속하는 test class를 정의합니다.
이미지 처리기 테스터는 프로세서 초기화 인자와 테스트용 랜덤 입력을 생성하는 매개변수와 같은 기본 테스트 속성을 정의합니다. 이미지 프로세서의 기본값과 다르게 설정해야 하는 경우에만 인자를 오버라이드하세요. 예를 들어, 테스트를 빠르게 유지하기 위해 일반적으로 더 작은 이미지 크기로 테스트합니다. 이미지 프로세서 클래스는 IMAGE_PROCESSOR_MAPPING_NAMES에서 자동으로 추론됩니다.
테스트 클래스에 image_processor_tester_class를 설정합니다. 믹신은 self.image_processor_tester를 생성하며, 대부분의 필수 테스트 메서드를 이미 제공합니다.
import unittest
from transformers.testing_utils import require_torch, require_vision
from ...test_image_processing_common import ImageProcessingTestMixin, ImageProcessingTester
class MyModelImageProcessingTester(ImageProcessingTester):
def __init__(self, **kwargs):
# Random test inputs kwargs
kwargs.setdefault("batch_size", 2) # default: 7
kwargs.setdefault("num_channels", 4) # default: 3
kwargs.setdefault("min_resolution", 20) # default: 30
kwargs.setdefault("max_resolution", 100) # default: 400
# Image processor init kwargs
kwargs.setdefault("size", {"shortest_edge": 20})
kwargs.setdefault("crop_size", {"height": 18, "width": 18})
super().__init__(**kwargs)
@require_torch
@require_vision
class MyModelImageProcessingTest(ImageProcessingTestMixin, unittest.TestCase):
image_processor_tester_class = MyModelImageProcessingTester
def test_inherits_from_mixin(self):
# Always iterate over all image processing classes
for image_processing_class in self.image_processing_classes.values():
# self.image_processor_dict contains the default processor init kwargs
# including overrides from the tester.
image_processor = image_processing_class(**self.image_processor_dict)
self.assertIsInstance(image_processor, ImageProcessingMixin)Mixin이 추론할 수 없는 동작, 예를 들어 사용자 정의 리사이징 규칙이나 모델별 kwargs에 대한 집중 테스트를 추가하세요.
tests/test_image_processing_common.py에 후처리 테스트 믹신이 제공되며, ImageProcessingTestMixin 위에 추가됩니다.
class MyModelImageProcessingTest(ImageProcessingTestMixin, MyTaskPostProcessTestMixin, unittest.TestCase):
image_processor_tester_class = MyModelImageProcessingTester테스트는 모델에 올바른 mixins이 사용되는지 자동으로 검증합니다. 새로운 작업에 대한 mixins은 tests/test_image_processing_common.py에 추가해야 합니다.
Video processor 테스트
Video processor 테스트는 보통 tests/models/<model_name>/test_video_processing_<model_name>.py에 위치하며 VideoProcessingTestMixin을 상속받습니다. fast_video_processing_class를 설정하고, video_processor_dict를 정의하며, 모델이 pixel_values_videos 이외의 키를 사용하는 경우 input_name을 오버라이드합니다.
from transformers.testing_utils import require_torch, require_vision
from transformers.utils import is_torchvision_available
from ...test_video_processing_common import VideoProcessingTestMixin
@require_torch
@require_vision
class MyModelVideoProcessingTest(VideoProcessingTestMixin, unittest.TestCase):
fast_video_processing_class = MyModelVideoProcessor if is_torchvision_available() else None
input_name = "pixel_values_videos"
@property
def video_processor_dict(self):
return {"size": {"shortest_edge": 224}, "num_frames": 16}프레임 샘플링, 메타데이터 처리, 디코딩된 비디오 입력, 프레임 목록 입력, 출력 형식에 대한 집중적인 비디오 테스트를 추가합니다. 프로세서가 pixel_values_videos를 이름 변경하는 경우, 이름이 변경된 키가 반환되는지 assert합니다.
모델에 이미지 또는 비디오 프로세서를 래핑하는 ProcessorMixin도 포함된 경우, tests/models/<model_name>/test_processing_<model_name>.py를 추가하고 ProcessorTesterMixin을 상속하세요. processor_class를 설정하고, 인자 없이 생성할 수 없는 컴포넌트에 대해 _setup_<component>() 클래스 메서드를 오버라이드하세요. 공통 프로세서 테스트에서 사용되는 플레이스홀더 토큰을 노출하려면 _setup_test_attributes()를 사용하세요.
from ...test_processing_common import ProcessorTesterMixin
class MyModelProcessorTest(ProcessorTesterMixin, unittest.TestCase):
processor_class = MyModelProcessor
@classmethod
def _setup_image_processor(cls):
return cls._get_component_class_from_processor("image_processor")(size={"shortest_edge": 224})
@classmethod
def _setup_video_processor(cls):
return cls._get_component_class_from_processor("video_processor")(num_frames=2)
@classmethod
def _setup_test_attributes(cls, processor):
cls.image_token = getattr(processor, "image_token", "")
cls.video_token = getattr(processor, "video_token", "")다음 단계
@auto_docstring을 사용하여 일관된 docstring을 자동 생성하는 Auto-generating docstrings 가이드를 읽어보세요.- 사용자 대상 전처리 동작에 대해서는 Image processors 및 Video processors 가이드를 참조하세요.