# 비전 처리 컴포넌트 추가

비전 모델을 추가하려면 표준 [모듈형](./modular_transformers) 접근 방식에 이미지 또는 비디오 처리 구성 요소를 추가해야 합니다. 이미지 전용 모델에는 이미지 프로세서가, 비디오 모델에는 비디오 프로세서가 필요하며, 이 둘은 각각 [AutoImageProcessor](/docs/transformers/v5.23.0/ko/model_doc/auto#transformers.AutoImageProcessor)와 [AutoVideoProcessor](/docs/transformers/v5.23.0/ko/model_doc/auto#transformers.AutoVideoProcessor) 진입점을 통해 접근할 수 있습니다.

> [!NOTE]
> 모델링 및 config 단계의 경우, 먼저 [모듈형](./modular_transformers) 가이드를 따르세요.

## 이미지 프로세서

모델이 이미지를 소비할 때 이미지 프로세서(image processor)를 생성합니다. [torchvision](https://docs.pytorch.org/vision/stable/index.html) 백엔드가 기본이며 GPU 가속을 지원합니다. torchvision이 사용 불가능한 경우 [PIL](https://pillow.readthedocs.io/en/stable/index.html)이 폴백으로 사용됩니다.

두 이미지 프로세서 클래스는 동일한 전처리 로직을 공유하지만 백엔드가 다릅니다. 생성자 시그니처와 기본값은 동일해야 합니다. [AutoImageProcessor.from_pretrained()](/docs/transformers/v5.23.0/ko/model_doc/auto#transformers.AutoImageProcessor.from_pretrained)는 로드 시점에 백엔드를 선택하며, torchvision이 사용 불가능한 경우 PIL로 폴백합니다. 시그니처가 일치하지 않으면 동일한 저장된 설정이 환경에 따라 다르게 동작할 수 있습니다.

### torchvision

`image_processing_<model_name>.py` 파일을 만들고 [TorchvisionBackend](/docs/transformers/v5.23.0/ko/main_classes/image_processor#transformers.TorchvisionBackend)를 상속하는 클래스를 정의하세요. 프로세서가 표준 [ImagesKwargs] 외에 커스텀 파라미터가 필요하면 kwargs 클래스를 정의하세요.

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

> [!TIP]
> 참고로 [LlavaOnevisionImageProcessor](/docs/transformers/v5.23.0/ko/model_doc/llava_onevision#transformers.LlavaOnevisionImageProcessor)를 확인하세요.

### PIL

`image_processing_pil_<model_name>.py` 파일을 [PilBackend](/docs/transformers/v5.23.0/ko/main_classes/image_processor#transformers.PilBackend)를 상속하는 클래스로 생성합니다. torchvision이 설치되지 않은 경우 실패할 수 있으므로, torchvision 파일에서 가져오지 않고 kwargs 클래스를 여기에 중복 정의합니다. 두 파일이 동기화되도록 `# Adapted from` 주석을 추가합니다. 커스텀 파라미터가 없는 프로세서의 경우 [ImagesKwargs](/docs/transformers/v5.23.0/ko/main_classes/processors#transformers.ImagesKwargs)를 직접 사용합니다.

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

> [!TIP]
> 참고로 [LlavaOnevisionImageProcessorPil](/docs/transformers/v5.23.0/ko/model_doc/llava_onevision#transformers.LlavaOnevisionImageProcessorPil)을 확인하세요.

### 후처리 메서드 추가

프로세서 클래스에 후처리 메서드를 직접 추가합니다. 후처리 메서드는 모델 출력(`outputs`)과 해당 후처리 메서드에 필요한 추가 인수를 인수로 호출됩니다.

```py
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](/docs/transformers/v5.23.0/ko/main_classes/feature_extractor#transformers.BatchFeature)를 상속합니다.

```py
class MyTaskPostProcessorOutput(BatchFeature):
    predictions: torch.Tensor
    scores: torch.Tensor
```

## 비디오 프로세서

모델이 비디오 또는 샘플링된 비디오 프레임을 소비할 때 비디오 프로세서 추가

모델 디렉터리에 `video_processing_<model_name>.py`를 생성합니다. [BaseVideoProcessor](/docs/transformers/v5.23.0/ko/main_classes/video_processor#transformers.BaseVideoProcessor)는 [TorchvisionBackend](/docs/transformers/v5.23.0/ko/main_classes/image_processor#transformers.TorchvisionBackend)를 상속하며, 공유되는 디코딩, 프레임 샘플링, 리사이즈, 리스케일링, 정규화, 저장 및 로드 동작을 제공합니다.

클래스 속성은 기본 전처리 값입니다. 사용자는 초기화 시점 또는 호출 시점에 이를 재정의할 수 있습니다. `size`, `crop_size`, `do_resize`, `do_sample_frames`, `num_frames`, `fps`와 같이 가능한 경우 [VideosKwargs](/docs/transformers/v5.23.0/ko/main_classes/processors#transformers.VideosKwargs)와 동일한 이름을 사용하세요.

비디오 프로세서에 표준 [VideosKwargs](/docs/transformers/v5.23.0/ko/main_classes/processors#transformers.VideosKwargs)를 넘어선 커스텀 파라미터가 필요한 경우 kwargs 클래스를 정의하세요. 이를 `valid_kwargs`로 설정하고, 런타임 검증과 자동 생성된 docstring을 위해 `__init__`의 주석으로 사용하세요.

```py
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()](/docs/transformers/v5.23.0/ko/main_classes/video_processor#transformers.BaseVideoProcessor.sample_frames)를 오버라이드하세요. 예를 들어, 일부 모델은 최소 또는 최대 프레임 수를 강제하거나, 모델에 특화된 제약 조건에 따라 샘플링합니다.

모델의 forward 메서드가 레거시 입력 이름을 기대하는 경우, `preprocess`를 오버라이드하고 기본 구현을 호출한 후 키 이름을 변경하세요.

```py
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()](/docs/transformers/v5.23.0/ko/main_classes/video_processor#transformers.VideoProcessorMixin.save_pretrained)를 호출하여 checkpoint와 함께 저장합니다. [ProcessorMixin](/docs/transformers/v5.23.0/ko/main_classes/processors#transformers.ProcessorMixin)이 video processor를 래핑하는 경우, 대신 [save_pretrained()](/docs/transformers/v5.23.0/ko/model_doc/wav2vec2#transformers.Wav2Vec2Processor.save_pretrained)를 호출합니다. 전처리 설정 파일을 수동으로 생성하거나 수정하지 마세요.

> [!TIP]
> 참고로 [Qwen3VLVideoProcessor](/docs/transformers/v5.23.0/ko/model_doc/qwen3_vl#transformers.Qwen3VLVideoProcessor)를 확인하세요.

## 클래스 등록

`__all__`에 새 클래스를 파일 하단에 추가한 다음, 다음 명령으로 `__init__.py`를 다시 생성합니다:

```bash
python utils/check_inits.py --fix_and_overwrite
```

`Auto` 클래스가 새 클래스를 로드할 수 있도록 모델 구성에 매핑합니다. 생성된 자동 매핑 파일의 상단에 경고가 있습니다. 수동으로 편집하지 마세요. 모델 구성을 추가하거나 업데이트한 다음 다음을 실행합니다:

```bash
python utils/check_auto.py --fix_and_overwrite
```

매핑이 생성된 후, `src/transformers/models/auto/auto_mappings.py`의 관련 매핑에 모델 유형이 표시되는지 확인하세요.

- [AutoImageProcessor](/docs/transformers/v5.23.0/ko/model_doc/auto#transformers.AutoImageProcessor)의 `IMAGE_PROCESSOR_MAPPING_NAMES`
- [AutoVideoProcessor](/docs/transformers/v5.23.0/ko/model_doc/auto#transformers.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`를 생성하며, 대부분의 필수 테스트 메서드를 이미 제공합니다.

```py
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` 위에 추가됩니다.

```py
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`을 오버라이드합니다.

```py
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](/docs/transformers/v5.23.0/ko/main_classes/processors#transformers.ProcessorMixin)도 포함된 경우, `tests/models/<model_name>/test_processing_<model_name>.py`를 추가하고 `ProcessorTesterMixin`을 상속하세요. `processor_class`를 설정하고, 인자 없이 생성할 수 없는 컴포넌트에 대해서는 `_setup_<component>()` 클래스 메서드를 오버라이드하세요. 공통 프로세서 테스트에서 사용하는 플레이스홀더 토큰을 노출하려면 `_setup_test_attributes()`를 사용하세요.

```py
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](./auto_docstring) 가이드를 읽어보세요.
- 사용자 대상 전처리 동작에 대해서는 [Image processors](./image_processors) 및 [Video processors](./video_processors) 가이드를 참조하세요.

