# 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](/docs/transformers/v5.23.0/pt/main_classes/processors#transformers.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`

```python
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.

```python
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.

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

> [!TIP]
> Consulte [Gemma4Processor](/docs/transformers/v5.23.0/pt/model_doc/gemma4#transformers.Gemma4Processor) e [Qwen2VLProcessor](/docs/transformers/v5.23.0/pt/model_doc/qwen2_vl#transformers.Qwen2VLProcessor) como referência.

### Adicionando argumentos personalizados

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

| Onde adicionar | Usar para | Valor padrão | Configurável em tempo de execução | Exemplo |
|---|---|---|---|---|
| `__init__` | Configurações salvas na configuração (propriedades do modelo) | Normalmente possui um padrão | Não | `image_seq_length` em [Gemma3Processor](/docs/transformers/v5.23.0/pt/model_doc/gemma3#transformers.Gemma3Processor) |
| `__call__` | Entradas conhecidas apenas em tempo de execução | No padrão ou `None` | Sim | `images`, `labels`, `suffix`, etc. |
| Classe `MyModelProcessingKwargs` personalizada | Configurações que podem ser configuradas em tempo de execução | Definir como atributo de classe do processador | Sim | `use_image_id` em [MiniCPMV4_7Processor](/docs/transformers/v5.23.0/pt/model_doc/minicpmv4_7#transformers.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.

```python
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.

```python
# 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")
```

