Transformers documentation

멀티모달 프로세서

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

멀티모달 프로세서

Processor는 토크나이저와 이미지 프로세서, 비디오 프로세서, 피처 추출기 등 하나 이상의 모달리티 프로세서를 결합합니다. 단일 __call__ 메서드를 노출하며, 각 입력을 올바른 구성 요소로 라우팅하고 출력들을 하나의 딕셔너리로 병합합니다.

일부 멀티모달 모델은 텍스트와 이미지, 비디오, 오디오를 번갈아 배치합니다. 이러한 모델의 경우 ProcessorMixin은 <image>, <video>, <audio>와 같은 플레이스홀더 토큰을 모델이 기대하는 토큰 패턴으로 대체할 수 있습니다.

새 프로세서 추가

src/transformers/models/<model>/processing_<my_model_name>.py 파일을 생성하고 ProcessorMixin을 서브클래스로 만들어 프로세서 클래스를 정의합니다. 기본값이 포함된 TypedDict 객체를 정의하고 이를 cls.valid_processor_kwargs에 할당하는지 확인하세요.

from ...processing_utils import ProcessorMixin

class MyModelProcessor(ProcessorMixin):

    def __init__(self, image_processor, tokenizer, chat_template=None, **kwargs):
        self.image_token = tokenizer.image_token
        self.image_token_id = tokenizer.image_token_id
        super().__init__(
            image_processor=image_processor,
            tokenizer=tokenizer,
            chat_template=chat_template,
            **kwargs,
        )

필요한 경우 replace_<modality>_token을 구현합니다. 이 메서드는 서브프로세서(subprocessor)에서 반환된 전체 출력 dict와 현재 입력의 인덱스를 인수로 받아, 해당 입력에 대한 확장된 치환 문자열을 반환합니다. 치환 문자열은 모델이 입력 시퀀스에서 기대하는 값입니다.

모델이 플레이스홀더 반복을 전혀 사용하지 않는 경우(image_token이 정의되지 않음)에는 이 메서드를 오버라이드할 필요가 없습니다. self.image_token을 설정하지 않으면 베이스 클래스가 치환을 완전히 건너뜁니다.

def replace_image_token(self, image_inputs: dict, image_idx: int) -> str:
    num_crops = image_inputs["num_crops"][image_idx]
    return f"{self.boi_token}{self.image_token * self.num_image_tokens * num_crops}{self.eoi_token}"

prepare_inputs_layout 및 validate_inputs 메서드를 선택적으로 오버라이드할 수 있습니다. 처리가 시작되기 전에 특정 입력 구조가 필요한 경우, 예를 들어 이미지를 중첩된 리스트로 재배열하거나, 공통 검사 외에 모델에 특화된 검사가 필요한 경우에 사용합니다.

def prepare_inputs_layout(self, images=None, text=None, videos=None, audio=None, **kwargs):
    # Call `super()` to apply common preparation steps first 
    images, text, videos, audio = super().prepare_inputs_layout(images, text, videos, audio)
    if images is not None:
        images = make_nested_list_of_images(images)
    return images, text, videos, audio

def validate_inputs(self, images=None, text=None, videos=None, audio=None, **kwargs):
    super().validate_inputs(images=images, text=text, **kwargs)
    if text is not None and images is not None:
        n_tokens = [s.count(self.image_token) for s in text]
        n_images = [len(img_list) for img_list in images]
        if n_tokens != n_images:
            raise ValueError(
                f"Number of {self.image_token} tokens in text {n_tokens} does not match "
                f"number of images {n_images}."
            )

참고로 Gemma4Processor와 Qwen2VLProcessor를 확인해 보세요.

커스텀 인자 추가

프로세서에 사용자 지정 인수를 추가하는 방법은 세 가지입니다:

추가 위치사용기본값런타임에 구성 가능예시
__init__config(모델 속성)에 저장된 설정일반적으로 기본값이 있습니다아니요Gemma3Processor의 image_seq_length
__call__러타임에才知道되는 입력기본값 또는 None 없음예images, labels, suffix 등
사용자 정의 MyModelProcessingKwargs 클래스런타임에 설정할 수 있는 설정프로세서 클래스 속성으로 설정예MiniCPMV4_7Processor의 use_image_id

기본값을 가질 수 있는 런타임 인수는 사용자 정의 MyModelProcessingKwargs에 추가해야 하며, __call__에 **kwargs의 일부로 전달됩니다. 이러한 값의 기본값은 프로세서 클래스 속성으로 설정할 수 있습니다. 토크나이저나 이미지 프로세서와 같은 모달리티별 프로세서의 기본값도 동일한 방식으로 정의할 수 있습니다. 모달리티별 프로세서는 이미 해당 클래스에서 기본값이 정의되어 있는 경우가 많으므로, 프로세서가 모달리티별 프로세서 설정을 오버라이드해야 하는 경우에만 이 옵션을 사용하십시오. 물론, __call__에 런타임으로 전달된 인수는 항상 모든 기본값보다 우선순위가 높습니다.

from ...processing_utils import ProcessingKwargs, ProcessorMixin, Unpack

class MyModelProcessorKwargs(ProcessingKwargs, total=False):
    """
    use_image_id (`bool`, defaults to `False`):
        Whether to prepend an image-id tag (``<image_id>N</image_id>``) before
        each image placeholder.
    """
    use_image_id: bool


class MyModelProcessor(ProcessorMixin):
    valid_processor_kwargs = MyModelProcessorKwargs
    use_image_id = False

    text_kwargs = {"padding": True}   # default passed to tokenizer

    def __init__(self, image_processor=None, tokenizer=None, chat_template=None, image_seq_length: int = 256, **kwargs):
        super().__init__(image_processor, tokenizer, chat_template=chat_template, **kwargs)
        self.image_seq_length = image_seq_length

    @auto_docstring
    def __call__(
        self,
        images: ImageInput | None = None,
        text: TextInput | PreTokenizedInput | list[TextInput] | list[PreTokenizedInput] | None = None,
        suffix: str | None = None,
        **kwargs: Unpack[MyModelProcessorKwargs],
    ):
        images, text, videos, audio = self.prepare_inputs_layout(images=images, text=text, **kwargs)
        self.validate_inputs(images=images, text=text, **kwargs)

        merged_kwargs = self._merge_kwargs(tokenizer_init_kwargs=self.tokenizer.init_kwargs, **kwargs)

        merged_kwargs["use_image_id"] # is `False` as default from class attribute is added by _merge_kwargs
        merged_kwargs["text_kwargs"]["padding"] # is `True`

테스트

모든 멀티모달 프로세서에는 ProcessorTesterMixin을 상속하는 테스트 클래스가 있어야 합니다. 이 mixin은 토큰화, 이미지 처리, 배치 처리, 왕복 인코딩을 포괄하는 표준 테스트 스위트를 제공합니다.

# tests/models/my_model_name/test_processor_<my_model_name>.py

from transformers.testing_utils import require_vision
from transformers.utils import is_vision_available
from ...test_processing_common import ProcessorTesterMixin

if is_vision_available():
    from transformers import MyModelProcessor

@require_vision
class MyModelProcessorTest(ProcessorTesterMixin, unittest.TestCase):
    processor_class = MyModelProcessor

    def get_processor(self):
        return MyModelProcessor.from_pretrained("hf-internal-testing/my-model-test")
Update on GitHub