Transformers documentation

Processeurs multimodaux

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Processeurs multimodaux

Un processeur combine un tokeniseur avec un ou plusieurs processeurs de modalités, tels qu'un processeur d'images, un processeur de vidéos ou un extracteur de caractéristiques. Il expose une unique méthode __call__ qui achemine chaque entrée vers le composant approprié et fusionne les sorties en un seul dictionnaire.

Certains modèles multimodaux alternent du texte avec des images, des vidéos ou de l’audio. Pour ces modèles, ProcessorMixin peut remplacer les jetons de substitution tels que <image>, <video> et <audio> par le motif de jetons attendu par le modèle.

Ajout d'un nouveau processeur

Définissez une classe de processeur en créant src/transformers/models/<model>/processing_<my_model_name>.py et en sous-classant ProcessorMixin. Assurez-vous de définir un objet TypedDict avec des valeurs par défaut et de l'assigner à 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,
        )

Implémentez replace_<modality>_token si nécessaire. Il reçoit le dictionnaire de sortie complet du sous-processeur ainsi que l'index de l'entrée courante, et renvoie la chaîne de remplacement développée pour cette entrée. La chaîne de remplacement est ce que le modèle attend dans la séquence d'entrée.

Si le modèle n'utilise pas du tout la répétition de jetons de substitution (aucun image_token défini), vous n'avez pas besoin de redéfinir cette méthode. Laissez self.image_token non défini et la classe de base ignorera entièrement le remplacement.

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

Facultativement, surchargez les méthodes prepare_inputs_layout et validate_inputs. Si le modèle exige une structure d’entrée spécifique avant le début du traitement, par exemple réorganiser les images sous forme de liste imbriquée, ou une validation propre au modèle en plus des vérifications communes.

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

Voir Gemma4Processor et Qwen2VLProcessor pour référence.

Ajout d'arguments personnalisés

Il existe trois façons d'ajouter des arguments personnalisés à un processeur :

Où ajouterUtilisationValeur par défautConfigurable à l'exécutionExemple
__init__Paramètres enregistrés dans la configuration (propriétés du modèle)A généralement une valeur par défautNonimage_seq_length dans Gemma3Processor
__call__Entrées connues uniquement à l'exécutionAucune valeur par défaut ou NoneOuiimages, labels, suffix, etc.
Classe MyModelProcessingKwargs personnaliséeParamètres configurables à l'exécutionDéfinir en tant qu'attribut de classe du processeurOuiuse_image_id dans MiniCPMV4_7Processor

Les arguments d’exécution pouvant avoir une valeur par défaut doivent être ajoutés à un MyModelProcessingKwargs personnalisé et seront transmis en tant que partie de **kwargs à __call__. Les valeurs par défaut de ces paramètres peuvent être définies en tant qu’attributs de la classe de processeur. Les valeurs par défaut des processeurs spécifiques à une modalité, par exemple le tokenizer ou le processeur d’images, peuvent être définies de la même manière. Cela n’est généralement pas nécessaire, car les processeurs spécifiques à une modalité ont déjà des valeurs par défaut définies dans leurs classes respectives. N’utilisez cette option que si le processeur doit remplacer un paramètre d’un processeur spécifique à une modalité. Bien entendu, les arguments transmis à l’exécution à __call__ ont toujours une priorité supérieure à toute valeur par défaut.

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`

Tests

Tous les processeurs multimodaux doivent disposer d'une classe de test qui hérite de ProcessorTesterMixin. Ce mixin fournit une suite standard couvrant la tokenisation, le traitement d'images, le batch et l'encodage aller-retour.

# 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