Transformers documentation
Processeurs multimodaux
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ù ajouter | Utilisation | Valeur par défaut | Configurable à l'exécution | Exemple |
|---|---|---|---|---|
__init__ | Paramètres enregistrés dans la configuration (propriétés du modèle) | A généralement une valeur par défaut | Non | image_seq_length dans Gemma3Processor |
__call__ | Entrées connues uniquement à l'exécution | Aucune valeur par défaut ou None | Oui | images, labels, suffix, etc. |
Classe MyModelProcessingKwargs personnalisée | Paramètres configurables à l'exécution | Définir en tant qu'attribut de classe du processeur | Oui | use_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")