Transformers documentation
Processeurs
Processeurs
Processeurs multi-modaux
Tout modèle multi-modal nécessite un objet pour encoder ou décoder les données regroupant plusieurs modalités (parmi le texte, la vision et l’audio). Cela est géré par des objets appelés processeurs, qui regroupent deux objets de traitement ou plus, tels que des tokenizers (pour la modalité texte), des image processors (pour la vision) et des feature extractors (pour l’audio).
Ces processeurs héritent de la classe de base suivante qui implémente les fonctionnalités d'enregistrement et de chargement :
Il s’agit d’un mixin utilisé pour fournir la fonctionnalité de sauvegarde/chargement pour toutes les classes de processeur.
__call__
< source >( images: typing.Union[ForwardRef('PIL.Image.Image'), numpy.ndarray, ForwardRef('torch.Tensor'), list['PIL.Image.Image'], list[numpy.ndarray], list['torch.Tensor'], NoneType] = Nonetext: str | list[str] | list[list[str]] | None = Nonevideos: typing.Union[list['PIL.Image.Image'], numpy.ndarray, ForwardRef('torch.Tensor'), list[numpy.ndarray], list['torch.Tensor'], list[list['PIL.Image.Image']], list[list[numpy.ndarray]], list[list['torch.Tensor']], transformers.video_utils.URL, list[transformers.video_utils.URL], list[list[transformers.video_utils.URL]], transformers.video_utils.Path, list[transformers.video_utils.Path], list[list[transformers.video_utils.Path]], NoneType] = Noneaudio: typing.Union[numpy.ndarray, ForwardRef('torch.Tensor'), collections.abc.Sequence[numpy.ndarray], collections.abc.Sequence['torch.Tensor'], NoneType] = None**kwargs: *<class 'transformers.processing_utils.ProcessingKwargs'> )
Paramètres
- images (
Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]], facultatif) — Image à prétraiter. S'attend à une image unique ou à un lot d'images dont les valeurs de pixels vont de 0 à 255. Si vous passez des images dont les valeurs de pixels sont comprises entre 0 et 1, définissezdo_rescale=False. - text (
Union[str, list[str], list[list[str]]], facultatif) — La séquence ou le lot de séquences à encoder. Chaque séquence peut être une chaîne de caractères ou une liste de chaînes de caractères (chaînes pré-tokenisées). Si vous passez une entrée pré-tokenisée, définissezis_split_into_words=Truepour éviter toute ambiguïté avec les entrées en lot. - videos (
Union[list[PIL.Image.Image], numpy.ndarray, torch.Tensor, list[numpy.ndarray], list[torch.Tensor], list[list[PIL.Image.Image]], list[list[numpy.ndarray]], list[list[torch.Tensor]], ~video_utils.URL, list[~video_utils.URL], list[list[~video_utils.URL]], ~video_utils.Path, list[~video_utils.Path], list[list[~video_utils.Path]]], facultatif) — Vidéo à prétraiter. S’attend à une vidéo unique ou à un lot de vidéos dont les valeurs de pixels vont de 0 à 255. Si vous passez des vidéos dont les valeurs de pixels sont comprises entre 0 et 1, définissezdo_rescale=False. - audio (
Union[numpy.ndarray, torch.Tensor, collections.abc.Sequence[numpy.ndarray], collections.abc.Sequence[torch.Tensor]], facultatif) — L’audio ou le lot d’audios à préparer. Chaque audio peut être un tableau NumPy ou un tenseur PyTorch. Dans le cas d’un tableau NumPy/tenseur PyTorch, chaque audio doit avoir la forme (C, T), où C est le nombre de canaux et T est la longueur d’échantillonnage de l’audio. - return_tensors (
strou TensorType, facultatif) — Si défini, renvoie des tenseurs d'un framework particulier. Les valeurs acceptées sont :'pt': Renvoie des objetstorch.Tensorde PyTorch.'np': Renvoie des objets NumPynp.ndarray.
- **kwargs (ProcessingKwargs, facultatif) — Options de traitement supplémentaires pour chaque modalité (texte, images, vidéos, audio). Les paramètres spécifiques au modèle sont répertoriés ci-dessus ; consultez la classe TypedDict pour la liste complète des arguments pris en charge.
prepare_inputs_layout
< source >( images: typing.Union[ForwardRef('PIL.Image.Image'), numpy.ndarray, ForwardRef('torch.Tensor'), list['PIL.Image.Image'], list[numpy.ndarray], list['torch.Tensor'], NoneType] = Nonetext: str | list[str] | list[list[str]] | None = Nonevideos: typing.Union[list['PIL.Image.Image'], numpy.ndarray, ForwardRef('torch.Tensor'), list[numpy.ndarray], list['torch.Tensor'], list[list['PIL.Image.Image']], list[list[numpy.ndarray]], list[list['torch.Tensor']], transformers.video_utils.URL, list[transformers.video_utils.URL], list[list[transformers.video_utils.URL]], transformers.video_utils.Path, list[transformers.video_utils.Path], list[list[transformers.video_utils.Path]], NoneType] = Noneaudio: typing.Union[numpy.ndarray, ForwardRef('torch.Tensor'), collections.abc.Sequence[numpy.ndarray], collections.abc.Sequence['torch.Tensor'], NoneType] = None**kwargs: *<class 'transformers.processing_utils.ProcessingKwargs'> )
Normalise et précharge les entrées avant le traitement. Enveloppe le texte dans une liste pour les processeurs multimodaux, récupère les images et les audio distants si des URL sont fournies, et s’assure que l’audio est correctement groupé par lots. Renvoie le tuple normalisé (images, text, videos, audio).
validate_inputs
< source >( images: typing.Union[ForwardRef('PIL.Image.Image'), numpy.ndarray, ForwardRef('torch.Tensor'), list['PIL.Image.Image'], list[numpy.ndarray], list['torch.Tensor'], NoneType] = Nonetext: str | list[str] | list[list[str]] | None = Nonevideos: typing.Union[list['PIL.Image.Image'], numpy.ndarray, ForwardRef('torch.Tensor'), list[numpy.ndarray], list['torch.Tensor'], list[list['PIL.Image.Image']], list[list[numpy.ndarray]], list[list['torch.Tensor']], transformers.video_utils.URL, list[transformers.video_utils.URL], list[list[transformers.video_utils.URL]], transformers.video_utils.Path, list[transformers.video_utils.Path], list[list[transformers.video_utils.Path]], NoneType] = Noneaudio: typing.Union[numpy.ndarray, ForwardRef('torch.Tensor'), collections.abc.Sequence[numpy.ndarray], collections.abc.Sequence['torch.Tensor'], NoneType] = None**kwargs: *<class 'transformers.processing_utils.ProcessingKwargs'> )
Valide qu'au moins une entrée est fournie et qu'aucun argument mot-clé obsolète n'est utilisé. Lève ValueError dans le cas contraire.
À surcharger lorsque le processeur a besoin d'une validation supplémentaire sur les arguments d'entrée.
get_text_with_replacements
< source >( text: listimages_replacements: list = []videos_replacements: list = []audio_replacements: list = [] ) → tuple[list[str], list[dict[str, Any]]]
Paramètres
- text (list[str]) — Lot de chaînes de texte brutes, chacune pouvant contenir des jetons de remplacement multimodaux. Notez qu'il sera modifié en place et renvoyé.
- images_replacements (list[str], facultatif, par défaut []) — Chaînes de remplacement développées pour chaque image, dans l'ordre où elles apparaissent dans le lot. Générées par self._process_images.
- videos_replacements (list[str], facultatif, par défaut []) — Chaînes de remplacement développées pour chaque vidéo. Produites par self._process_videos.
- audio_replacements (list[str], facultatif, par défaut []) — Chaînes de remplacement développées pour chaque entrée audio. Générées par self._process_audio.
Retourne
tuple[list[str], list[dict[str, Any]]]
Un tuple de :
- Le lot de text modifié avec tous les jetons de substitution dépliés.
- batch_replacement_offsets : une entrée par élément du lot, chacune étant une liste de dictionnaires avec les clés :
- “type” (str) : nom de la modalité — “image”, “video” ou “audio”
- “span” (tuple[int, int]) : décalages de caractères d'origine (start, end) du jeton de substitution
- “new_span” (tuple[int, int]) : décalages (start, end) du placeholder dans la chaîne étendue
- “text” (str) : la chaîne de jetons de remplacement d’origine qui a été trouvée
- “replacement” (str) : la chaîne de caractères avec laquelle il a été remplacé
Remplacez les jetons de remplacement multimodaux dans un lot de chaînes de texte par leurs représentations étendues, et retournez les textes modifiés ainsi que les métadonnées de décalage.
Cette méthode constitue l'étape centrale de prétraitement côté texte pour les entrées multimodales. Elle parcourt chaque texte du lot à la recherche de jetons spéciaux (image, vidéo, audio) et les remplace, dans l'ordre, par les chaînes de remplacement précalculées produites par self.replace_image_token / self.replace_video_token / self.replace_audio_token.
Les remplacements sont consommés séquentiellement depuis la liste de chaque modalité, de sorte que la i-ème occurrence de, par exemple, self.image_token est remplacée par images_replacements[i].
Pour ajouter un nouveau processeur multimodal avec des jetons de substitution, vous devez définir un self.image_token correct, qui est le même jeton que celui intégré au texte d'entrée et également utilisé comme jeton de substitution et répété de nombreuses fois. Ensuite, vous devez surcharger self.replace_image_token pour retourner la chaîne de substitution correcte pour une image donnée à l'index i. Il en va de même pour toutes les autres modalités prises en charge.
create_mm_token_type_ids
< source >( input_ids: list ) → list[list[int]]
Paramètres
- input_ids (list[list[int]]) — Lot de séquences d’identifiants de jetons. Peut être non rembourré (longueur variable), de sorte qu’une simple liste Python de listes est attendue plutôt qu’un tenseur ou un tableau de forme uniforme.
Retourne
list[list[int]]
Une liste de la même structure que input_ids, où chaque entier est l'identifiant du type de modalité pour le jeton correspondant.
Construire les identifiants de type de modalité par jeton pour un lot de séquences de token_id.
Chaque position se voit attribuer un entier indiquant la modalité à laquelle elle appartient : 0 pour le texte régulier, 1 pour les jetons d'image, 2 pour les jetons de vidéo et 3 pour les jetons audio. L'appartenance est déterminée par comparaison avec self.image_token_ids, self.video_token_ids et self.audio_token_ids.
apply_chat_template
< source >( conversation: list[dict[str, str]] | list[list[dict[str, str]]]chat_template: str | None = Nonetools: list[dict] | None = Nonedocuments: list[dict[str, str]] | None = Noneadd_generation_prompt: bool = Falsecontinue_final_message: bool | str = Falsereturn_assistant_tokens_mask: bool = Falsetokenize: bool = Falsereturn_tensors: str | transformers.utils.generic.TensorType | None = 'auto'return_dict: bool = Falseload_audio_from_video: bool = Falseprocessor_kwargs: dict | None = None**kwargs )
De manière similaire à la méthode apply_chat_template des tokenizers, cette méthode applique un modèle Jinja aux conversations d'entrée pour les transformer en une seule chaîne tokenizable.
L’entrée est attendue au format suivant, où le contenu de chaque message est une liste composée de texte et, le cas échéant, d’entrées image ou vidéo. Il est également possible de fournir une image, une vidéo, une URL ou un chemin local, qui sera utilisé pour former pixel_values lorsque return_dict=True. En l’absence de cette information, seul le texte formaté, éventuellement tokenisé, sera renvoyé.
conversation = [ { “role”: “user”, “content”: [ {“type”: “image”, “url”: “https://www.ilankelman.org/stopsigns/australia.jpg”}, {“type”: “text”, “text”: “Please describe this image in detail.”}, ], }, ]
Traitement des kwargs
Les méthodes __call__ des classes Processor acceptent des arguments nommés organisés par modalité. Les classes TypedDict suivantes définissent les arguments nommés disponibles pour chaque modalité. Les processeurs spécifiques à un modèle peuvent sous-classes ces classes pour ajouter ou remplacer des champs.
Classe de base pour la transmission des kwargs aux processeurs.
Si un modèle possède des kwargs spécifiques qui ne sont pas présents dans la classe de base ou des valeurs par défaut pour des clés existantes,
il doit avoir sa propre classe ModelProcessorKwargs qui hérite de ProcessingKwargs afin de fournir :
1) Des clés typées supplémentaires que ce modèle requiert pour traiter les entrées.
2) Des valeurs par défaut pour les clés existantes sous l'attribut _defaults.
Les nouvelles clés doivent être définies comme suit pour s'assurer que l'annotation de types est effectuée correctement.
# adding a new image kwarg for this model
class ModelImagesKwargs(ImagesKwargs, total=False):
new_image_kwarg: Optional[bool]
class ModelProcessorKwargs(ProcessingKwargs, total=False):
images_kwargs: ModelImagesKwargs
_defaults = {
"images_kwargs: {
"new_image_kwarg": False,
}
"text_kwargs": {
"padding": "max_length",
},
}
Pour la compatibilité avec Python 3.8, lors de l'héritage de cette classe et de la surcharge de l'un des kwargs,
classe transformers.TextKwargs
< source >( )
Paramètres
- add_special_tokens (
bool, facultatif) — Indique s'il faut ou non ajouter des jetons spéciaux lors de l'encodage des séquences. - padding (
bool,strou PaddingStrategy, facultatif) — Active et contrôle le bourrage. - truncation (
bool,strou TruncationStrategy, facultatif) — Active et contrôle la troncature. - max_length (
int, facultatif) — Contrôle la longueur maximale à utiliser par l'un des paramètres de troncature/remplissage. - stride (
int, facultatif) — Si défini, les jetons en dépassement contiendront certains jetons de la fin de la séquence tronquée. - is_split_into_words (
bool, facultatif) — Indique si l'entrée est déjà pré-tokenisée. - pad_to_multiple_of (
int, facultatif) — Si défini, la séquence sera rembourdée jusqu'à un multiple de la valeur fournie. - return_token_type_ids (
bool, facultatif) — Indique s'il faut renvoyer les identifiants de type de jeton. - return_attention_mask (
bool, facultatif) — Indique s'il faut retourner le masque d'attention. - return_overflowing_tokens (
bool, facultatif) — Indique s'il faut ou non retourner les séquences de jetons en dépassement. - return_special_tokens_mask (
bool, facultatif) — Indique s'il faut ou non retourner les informations du masque des jetons spéciaux. - return_offsets_mapping (
bool, facultatif) — Indique s'il faut ou non retourner(char_start, char_end)pour chaque jeton. - return_length (
bool, facultatif) — Indique s'il faut ou non retourner les longueurs des entrées encodées. - verbose (
bool, facultatif) — Indique s'il faut afficher plus d'informations et d'avertissements. - padding_side (
str, facultatif) — Le côté sur lequel le bourrage sera appliqué. - return_mm_token_type_ids (
bool, facultatif) — Indique s'il faut retourner les identifiants de type de jeton multimodal indiquant les positions des jetons de substitution multimodaux. - return_text_replacement_offsets (
bool, facultatif) — Indique s'il faut retourner les décalages de caractères pour chaque emplacement réservé multimédia et son remplacement. - return_tensors (
strou TensorType, facultatif) — Si défini, renvoie des tenseurs d'un framework particulier. Les valeurs acceptées sont :'pt': Renvoie des objetstorch.Tensorde PyTorch.'np': Renvoie des objets NumPynp.ndarray.
Arguments de mots-clés pour le traitement du texte. Pour une documentation étendue, consultez les méthodes et les docstrings associées de tokenization_utils_base.
classe transformers.ImagesKwargs
< source >( )
Paramètres
- do_convert_rgb (
bool) — Indique s'il faut convertir l'image au format RGB. - do_resize (
bool, facultatif) — Indique s'il faut redimensionner l'image. - size (
dict[str, int], facultatif) — Redimensionner à l'aide de l'un des dictionnaires de taille pris en charge. Les limites de surface en pixels utilisent{"min_pixels": int, "max_pixels": int}. - default_to_square (
bool, facultatif, par défautself.default_to_square) — Indique s'il faut utiliser un carré par défaut lors du redimensionnement si la taille est un entier. - crop_size (
dict[str, int], facultatif) — Taille de sortie souhaitée lors de l'application d'un recadrage centré. - resample (
PILImageResampling, facultatif) — Filtre de rééchantillonnage à utiliser lors du redimensionnement de l'image. - do_rescale (
bool, facultatif) — Indique s'il faut redimensionner l'image selon l'échelle spécifiéerescale_factor. - rescale_factor (
intoufloat, facultatif) — Facteur d'échelle à utiliser lors du redimensionnement de l'image. - do_normalize (
bool, facultatif) — Indique s'il faut normaliser l'image. - image_mean (
floatoulist[float] or tuple[float, float, float], facultatif) — Moyenne à utiliser lors de la normalisation de l'image. - image_std (
floatoulist[float] or tuple[float, float, float], facultatif) — Écart-type à utiliser pour normaliser l'image. - do_pad (
bool, facultatif) — Indique s'il faut ajouter des rembourrage aux images du lot. - pad_size (
dict[str, int], facultatif) — La taille{"height": int, "width" int}à laquelle rembourder les images. - do_center_crop (
bool, facultatif) — Indique s'il faut effectuer un recadrage centré de l'image. - data_format (
ChannelDimensionoustr, facultatif) — Le format de la dimension des canaux pour l'image de sortie. - input_data_format (
ChannelDimensionoustr, facultatif) — Le format de la dimension des canaux pour l'image d'entrée. - device (
Union[str, torch.Tensor], facultatif) — L’appareil à utiliser pour le traitement (par ex. « cpu », « cuda »), uniquement pertinent pour l’arrière-plan torchvision. - return_tensors (
strou TensorType, facultatif) — Si défini, renvoie des tenseurs d'un framework particulier. Les valeurs acceptées sont :'pt': Renvoie des objetstorch.Tensorde PyTorch.'np': Renvoie des objets NumPynp.ndarray.
- disable_grouping (
bool, facultatif) — Indique s'il faut ou non regrouper les images par forme lors du traitement, uniquement pertinent pour l'arrière-plan torchvision. - image_seq_length (
int, facultatif) — Le nombre de jetons d’image à utiliser pour chaque image de l’entrée. Ajouté pour la compatibilité ascendante, mais cela devrait être défini comme un attribut du processeur dans les futurs modèles.
Arguments de mots-clés pour le traitement d'images. Pour une documentation étendue, consultez les méthodes et docstrings de la classe ImageProcessor appropriée.
classe transformers.VideosKwargs
< source >( )
Paramètres
- do_convert_rgb (
bool) — Indique s'il faut convertir la vidéo au format RGB. - do_resize (
bool) — Indique s'il faut redimensionner la vidéo. - size (
dict[str, int], facultatif) — Redimensionner le côté le plus court de l'entrée àsize["shortest_edge"]. - default_to_square (
bool, facultatif, par défautself.default_to_square) — Indique s'il faut utiliser un carré par défaut lors du redimensionnement si la taille est un entier. - resample (
PILImageResampling, facultatif) — Filtre de rééchantillonnage à utiliser lors du redimensionnement de la vidéo. - do_rescale (
bool, facultatif) — Indique s'il faut redimensionner la vidéo selon le facteur de redimensionnementrescale_factorspécifié. - rescale_factor (
intoufloat, facultatif) — Facteur d'échelle à utiliser lors du redimensionnement de la vidéo. - do_normalize (
bool, facultatif) — Indique s'il faut normaliser la vidéo. - image_mean (
floatoulist[float] or tuple[float, float, float], facultatif) — Moyenne à utiliser lors de la normalisation de la vidéo. - image_std (
floatoulist[float] or tuple[float, float, float], facultatif) — Écart-type à utiliser lors de la normalisation de la vidéo. - do_center_crop (
bool, facultatif) — Indique s'il faut effectuer un recadrage centré sur la vidéo. - do_pad (
bool, facultatif) — Indique s'il faut ajouter des rembourrage aux images du lot. - do_sample_frames (
bool, facultatif) — Indique s'il faut échantillonner des images de la vidéo avant le traitement ou traiter la vidéo entière. - video_metadata (
Union[VideoMetadata, dict], facultatif) — Métadonnées de la vidéo contenant des informations sur la durée totale, le fps et le nombre total d'images. - num_frames (
int, facultatif) — Nombre maximal de frames à échantillonner lorsquedo_sample_frames=True. - fps (
intoufloat, facultatif) — Nombre de cibles d'images à échantillonner par seconde lorsquedo_sample_frames=True. - crop_size (
dict[str, int], facultatif) — Taille de sortie souhaitée lors de l'application d'un recadrage centré. - data_format (
ChannelDimensionoustr, facultatif) — Le format de la dimension des canaux pour la vidéo de sortie. - input_data_format (
ChannelDimensionoustr, facultatif) — Le format de la dimension des canaux pour la vidéo d'entrée. - device (
Union[str, torch.Tensor], facultatif) — L’appareil à utiliser pour le traitement (par ex. « cpu », « cuda »), uniquement pertinent pour le traitement d’images rapide. - return_metadata (
bool, facultatif) — Indique s'il faut renvoyer les métadonnées de la vidéo ou non. - return_tensors (
strou TensorType, facultatif) — Si défini, renvoie des tenseurs d'un framework particulier. Les valeurs acceptées sont :'pt': Renvoie des objetstorch.Tensorde PyTorch.'np': Renvoie des objets NumPynp.ndarray.
Arguments de mots-clés pour le traitement vidéo.
classe transformers.AudioKwargs
< source >( )
Paramètres
- sampling_rate (
int, facultatif) — La fréquence d'échantillonnage à laquelle l'entréeraw_speecha été échantillonnée. - raw_speech (
np.ndarray,list[float],list[np.ndarray],list[list[float]]) — La séquence ou le lot de séquences à compléter. Chaque séquence peut être un tableau numpy, une liste de valeurs flottantes, une liste de tableaux numpy ou une liste de listes de valeurs flottantes. L’audio doit être en mono, pas en stéréo, c’est-à-dire un seul flottant par pas de temps. - padding (
bool,strou PaddingStrategy, facultatif) — Sélectionne une stratégie pour mettre en place le padding des séquences renvoyées (selon le côté de padding et l'index de padding du modèle) parmi les options suivantes :Trueou'longest': Ajuster à la séquence la plus longue du lot (ou aucun ajustement si une seule séquence est fournie).'max_length': Remplir jusqu'à une longueur maximale spécifiée par l'argumentmax_lengthou jusqu'à la longueur d'entrée maximale acceptable pour le modèle si cet argument n'est pas fourni.Falseou'do_not_pad'
- max_length (
int, facultatif) — Longueur maximale de la liste renvoyée et, le cas échéant, longueur du bourrage (voir ci-dessus). - truncation (
bool, facultatif) — Active la troncature pour couper les séquences d’entrée plus longues que max_length à max_length. - pad_to_multiple_of (
int, facultatif) — Si défini, la séquence sera rembourdée jusqu'à un multiple de la valeur fournie. - return_attention_mask (
bool, facultatif) — Indique si call() doit retournerattention_mask. - device (
stroutorch.device, facultatif) — L’appareil sur lequel calculer les caractéristiques audio (par ex. « cpu », « cuda »), uniquement pertinent pour les extracteurs de caractéristiques qui les calculent avec torch. - return_tensors (
strou TensorType, facultatif) — Si défini, renvoie des tenseurs d'un framework particulier. Les valeurs acceptées sont :'pt': Renvoie des objetstorch.Tensorde PyTorch.'np': Renvoie des objets NumPynp.ndarray.
- load_audio_backend (
str, facultatif) — Backend utilisé parload_audio()pour décoder/rééchantillonner l’audio référencé par URL/chemin dansapply_chat_template. L’un des"auto","torchcodec","librosa","torchaudio".
Arguments de mot-clé pour le traitement audio.