Transformers documentation

Processadores multimodais

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Processadores multimodais

Um processor combina um tokenizer com um ou mais processadores de modalidade, como um processador de imagem, processador de vídeo ou extrator de recursos. Ele expõe um único método __call__ que encaminha cada entrada para o componente adequado e mescla as saídas em um único dicionário.

Alguns modelos multimodais intercalam texto com imagens, vídeos ou áudio. Para esses modelos, o ProcessorMixin pode substituir tokens de espaço reservado, como <image>, <video> e <audio>, pelo padrão de tokens esperado pelo modelo.

Adicionando um novo processador

Defina uma classe de processador criando src/transformers/models/<model>/processing_<my_model_name>.py e subclasse ProcessorMixin. Certifique-se de definir um objeto TypedDict com valores padrão e atribuí-lo como 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,
        )

Implemente replace_<modality>_token se necessário. Ele recebe o dicionário de saída completo do subprocessador e o índice da entrada atual, e retorna a string de substituição expandida para essa entrada. A string de substituição é o que o modelo espera na sequência de entrada.

Se o modelo não usa repetição de placeholders de forma alguma (nenhum image_token definido), você não precisa sobrescrever este método. Deixe self.image_token não definido e a classe base ignorará a substituição por completo.

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}"

Opcionalmente, substitua os métodos prepare_inputs_layout e validate_inputs. Isso é necessário se o modelo exigir uma estrutura de entrada específica antes do início do processamento, como a reordenação de imagens em uma lista aninhada, ou uma validação específica do modelo além das verificações comuns.

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}."
            )

Consulte Gemma4Processor e Qwen2VLProcessor como referência.

Adicionando argumentos personalizados

Existem três maneiras de adicionar argumentos personalizados a um processador:

Onde adicionarUsar paraValor padrãoConfigurável em tempo de execuçãoExemplo
__init__Configurações salvas na configuração (propriedades do modelo)Normalmente possui um padrãoNãoimage_seq_length em Gemma3Processor
__call__Entradas conhecidas apenas em tempo de execuçãoNo padrão ou NoneSimimages, labels, suffix, etc.
Classe MyModelProcessingKwargs personalizadaConfigurações que podem ser configuradas em tempo de execuçãoDefinir como atributo de classe do processadorSimuse_image_id em MiniCPMV4_7Processor

Argumentos de runtime que podem ter um valor padrão devem ser adicionados a um MyModelProcessingKwargs personalizado e serão passados como parte de **kwargs para __call__. Os padrões para esses valores podem ser definidos como atributos da classe do processador. Os padrões para processadores específicos de modalidade, por exemplo, o tokenizer ou o processador de imagem, podem ser definidos da mesma forma. Isso geralmente não é necessário, pois os processadores específicos de modalidade já têm padrões definidos em suas respectivas classes. Use essa opção apenas se o processador precisar sobrescrever uma configuração de um processador específico de modalidade. Claro, os argumentos passados em runtime para __call__ sempre têm prioridade mais alta do que qualquer padrão.

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`

Testes

Todos os processadores multimodais devem ter uma classe de teste que herda de ProcessorTesterMixin. Este mixin fornece um conjunto padrão de testes que cobre tokenização, processamento de imagem, loteamento e codificação de ida e volta.

# 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