Transformers documentation
멀티모달 프로세서
멀티모달 프로세서
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")