# Tokenizers Un tokenizer convertit le texte en tenseurs, qui constituent les entrées d'un modèle. Il normalise et découpe le texte, applique l'algorithme de tokenisation, ajoute des jetons spéciaux et décode les identifiants de sortie en texte. ```py from transformers import AutoTokenizer tokenizer = AutoTokenizer.from_pretrained("google/gemma-2-2b") tokenizer("Sphinx of black quartz, judge my vow.", return_tensors="pt") { 'input_ids': tensor([[ 2, 235277, 82913, 576, 2656, 30407, 235269, 11490, 970, 29871, 235265]]), 'attention_mask': tensor([[1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1]]) } ``` Ce guide couvre le chargement, l'encodage, le décodage, le traitement par lots et les backends de tokenizer disponibles. ## Charger un tokenizer Chargez un tokenizer avec la classe [AutoTokenizer](/docs/transformers/v5.23.0/fr/model_doc/auto#transformers.AutoTokenizer) ou une classe de tokenizer spécifique au modèle. [AutoTokenizer.from_pretrained()](/docs/transformers/v5.23.0/fr/model_doc/auto#transformers.AutoTokenizer.from_pretrained) lit la configuration du modèle, détermine la classe de tokenizer appropriée et en retourne une instance. Il n'est pas nécessaire de connaître la classe du tokenizer à l'avance. La plupart des tokenizers résolvent vers une sous-classe de [TokenizersBackend](/docs/transformers/v5.23.0/fr/main_classes/tokenizer#transformers.TokenizersBackend), un tokenizer rapide basé sur Rust issu de la bibliothèque [Tokenizers](https://huggingface.co/docs/tokenizers/index). Le chargement avec [AutoTokenizer](/docs/transformers/v5.23.0/fr/model_doc/auto#transformers.AutoTokenizer) est l'approche recommandée. ```py from transformers import AutoTokenizer tokenizer = AutoTokenizer.from_pretrained("google/gemma-2-2b") ``` Une classe de tokenisation spécifique à un modèle est un [TokenizersBackend](/docs/transformers/v5.23.0/fr/main_classes/tokenizer#transformers.TokenizersBackend) préconfiguré qui utilise la configuration de tokenisation exacte (normaliseur, pré-tokeniseur, conventions de jetons spéciaux, etc.) avec laquelle le modèle a été entraîné. Utilisez une classe spécifique au modèle pour initialiser un tokenizer vide destiné à l'entraînement ou pour passer des arguments spécifiques au modèle tels que `vocab` ou `merges` (consultez le guide [Personnalisation des tokenizers](./custom_tokenizers) pour en savoir plus). Un tokenizer vide est minimal et ne contient que les jetons spéciaux d'un modèle, comme ``, `` ou ``. ```py from transformers import GemmaTokenizer tokenizer = GemmaTokenizer() corpus = [ ["Sphinx of black quartz, judge my vow."], ["Pack my box with five dozen liquor jugs."], ["How vexingly quick daft zebras jump!"], ] new_tokenizer = tokenizer.train_new_from_iterator(corpus, vocab_size=1000) ``` ## Encoder et décoder La méthode [TokenizersBackend.__call__()](/docs/transformers/v5.23.0/fr/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__) encode le texte ou un lot de textes en `input_ids`, `attention_mask` et autres entrées du modèle. Elle contrôle également le bourrage, la troncature et l'insertion des jetons spéciaux. ```py from transformers import AutoTokenizer tokenizer = AutoTokenizer.from_pretrained("google/gemma-2-2b") tokenizer("Sphinx of black quartz, judge my vow.", return_tensors="pt") { 'input_ids': tensor([[ 2, 235277, 82913, 576, 2656, 30407, 235269, 11490, 970, 29871, 235265]]), 'attention_mask': tensor([[1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1]]) } ``` [TokenizersBackend.encode()](/docs/transformers/v5.23.0/fr/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) est similaire mais ne renvoie que les `input_ids`. ```py from transformers import AutoTokenizer tokenizer = AutoTokenizer.from_pretrained("google/gemma-2-2b") input_ids = tokenizer.encode("Sphinx of black quartz, judge my vow.") [2, 235277, 82913, 576, 2656, 30407, 235269, 11490, 970, 29871, 235265] ``` [TokenizersBackend.decode()](/docs/transformers/v5.23.0/fr/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.decode) convertit une seule séquence ou un lot de `input_ids` tokenisés en texte. ```py tokenizer.decode(input_ids) 'Sphinx of black quartz, judge my vow.' ``` [TokenizersBackend.decode()](/docs/transformers/v5.23.0/fr/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.decode) conserve l’espacement exact de la tokenization. Définissez `clean_up_tokenization_spaces` pour supprimer les espaces avant la ponctuation, et `skip_special_tokens` pour retirer les jetons spéciaux de la sortie. ```py tokenizer.decode(input_ids, skip_special_tokens=True) 'Sphinx of black quartz, judge my vow.' ``` ## Jetons spéciaux Les jetons spéciaux marquent les limites structurelles d'une séquence, comme la position de début de séquence ou les positions de bourrage. Chaque modèle définit son propre ensemble de jetons spéciaux. Le tokeniseur les ajoute lorsque vous l'appelez. ```py input_ids = tokenizer.encode("Sphinx of black quartz, judge my vow.") [2, 235277, 82913, 576, 2656, 30407, 235269, 11490, 970, 29871, 235265] tokenizer.decode(input_ids) 'Sphinx of black quartz, judge my vow.' ``` Enregistrez des jetons spéciaux nommés supplémentaires avec l'argument `extra_special_tokens`. Les modèles multimodaux les utilisent comme jetons de remplacement pour les images, les vidéos ou l'audio. ```py from transformers import AutoTokenizer tokenizer = AutoTokenizer.from_pretrained( "google/gemma-3-4b-pt", extra_special_tokens={"image_token": ""} ) ``` ## Traitement par lots Le traitement par lots tokenise plusieurs séquences en un seul appel. [TokenizersBackend](/docs/transformers/v5.23.0/fr/main_classes/tokenizer#transformers.TokenizersBackend) gère les grands lots plus rapidement car son backend basé sur Rust parallélise le travail sur plusieurs threads. ```py from transformers import AutoTokenizer tokenizer = AutoTokenizer.from_pretrained("google/gemma-2-2b") tokenizer( [ "Sphinx of black quartz, judge my vow.", "Pack my box with five dozen liquor jugs.", "How vexingly quick daft zebras jump!" ], return_tensors="pt" ) ``` Le traitement par lots exige que toutes les séquences partagent la même longueur. Le bourrage (padding) et la troncature sont des stratégies pour gérer les séquences de longueurs variables. ### Remplissage Le padding ajoute des jetons spéciaux afin que les séquences plus courtes correspondent à la séquence la plus longue d'un lot. Le masque d'attention marque les positions de padding comme `0` pour que le modèle les ignore. Définissez `padding=True` pour ajuster à la séquence la plus longue ou passez `max_length` pour ajuster à une taille fixe. ```py from transformers import AutoTokenizer tokenizer = AutoTokenizer.from_pretrained("google/gemma-2-2b") tokenizer( [ "Sphinx of black quartz, judge my vow.", "Pack my box with five dozen liquor jugs.", "How vexingly quick daft zebras jump!" ], return_tensors="pt", padding=True, ) { 'input_ids': tensor([ [ 2, 235277, 82913, 576, 2656, 30407, 235269, 11490, 970, 29871, 235265], [ 0, 2, 6519, 970, 3741, 675, 4105, 25955, 42184, 225789, 235265], [ 0, 2, 2299, 73378, 17844, 4320, 224463, 4949, 48977, 9902, 235341] ]), 'attention_mask': tensor([ [1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1], [0, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1], [0, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1] ]) } ``` > [!NOTE] > Les grands modèles de langage ajoutent des jetons de bourrage (padding) sur le côté *gauche* afin de ne pas perturber la génération, qui prédit le jeton suivant à partir du côté *droit*. ### Troncature La troncature supprime des jetons pour qu'une séquence tienne dans une longueur maximale. Définissez `truncation=True` et spécifiez `max_length` pour l'activer. Le bourrage et la troncature fonctionnent de concert. Les séquences courtes reçoivent des jetons de bourrage tandis que les séquences longues perdent leurs jetons de fin. Ensemble, ils produisent un tenseur rectangulaire compact. ```py from transformers import AutoTokenizer tokenizer = AutoTokenizer.from_pretrained("google/gemma-2-2b") tokenizer( [ "Sphinx of black quartz, judge my vow.", "Pack my box with five dozen liquor jugs.", "How vexingly quick daft zebras jump!" ], return_tensors="pt", padding=True, truncation=True, max_length=5 ) { 'input_ids': tensor([ [ 2, 235277, 82913, 576, 2656], [ 2, 6519, 970, 3741, 675], [ 2, 2299, 73378, 17844, 4320] ]), 'attention_mask': tensor([ [1, 1, 1, 1, 1], [1, 1, 1, 1, 1], [1, 1, 1, 1, 1] ]) } ``` ## Backends Chaque tokenizer de modèle est défini dans un fichier unique et prend en charge quatre backends de tokenization. | backend | implémentation | description | | ------------------------ | ------------------------------------------------------------- | ---------------------------------------------- | | [TokenizersBackend](/docs/transformers/v5.23.0/fr/main_classes/tokenizer#transformers.TokenizersBackend) | [Tokenizers](https://huggingface.co/docs/tokenizers) | par défaut pour la plupart des modèles | | [SentencePieceBackend](/docs/transformers/v5.23.0/fr/main_classes/tokenizer#transformers.SentencePieceBackend) | [SentencePiece](https://github.com/google/sentencepiece) | modèles nécessitant SentencePiece | | [PythonBackend](/docs/transformers/v5.23.0/fr/main_classes/tokenizer#transformers.PythonBackend) | Python | les modèles nécessitant des tokenizers personnalisés spécialisés | | [MistralCommonBackend](/docs/transformers/v5.23.0/fr/model_doc/mistral#transformers.MistralCommonBackend) | [mistral-common](https://mistralai.github.io/mistral-common/) | Modèles Mistral et Pixtral | Tous les backends héritent de [PreTrainedTokenizerBase](/docs/transformers/v5.23.0/fr/internal/tokenization_utils#transformers.PreTrainedTokenizerBase) et partagent les mêmes API pour l'encodage, le décodage, le padding, la troncature, la sauvegarde et le chargement. La différence réside dans le pipeline de tokenisation qui s'exécute en arrière-plan. [AutoTokenizer](/docs/transformers/v5.23.0/fr/model_doc/auto#transformers.AutoTokenizer) sélectionne le meilleur backend disponible lorsque vous appelez [from_pretrained()](/docs/transformers/v5.23.0/fr/model_doc/auto#transformers.AutoTokenizer.from_pretrained). 1. Il lit le fichier `tokenizer_config.json` pour le champ `tokenizer_class`. 2. Le registre associe `tokenizer_class` à un nom de classe. La classe résolue hérite de l'un des quatre backends. Par exemple, [GemmaTokenizer](/docs/transformers/v5.23.0/fr/model_doc/gemma#transformers.GemmaTokenizer) hérite de [TokenizersBackend](/docs/transformers/v5.23.0/fr/main_classes/tokenizer#transformers.TokenizersBackend), et [SiglipTokenizer](/docs/transformers/v5.23.0/fr/model_doc/siglip#transformers.SiglipTokenizer) hérite de [SentencePieceBackend](/docs/transformers/v5.23.0/fr/main_classes/tokenizer#transformers.SentencePieceBackend). Certains modèles, comme GLM, sont directement associés à [TokenizersBackend](/docs/transformers/v5.23.0/fr/main_classes/tokenizer#transformers.TokenizersBackend) car le fichier `tokenizer.json` décrit entièrement le pipeline. [GemmaTokenizer](/docs/transformers/v5.23.0/fr/model_doc/gemma#transformers.GemmaTokenizer) existe en tant que sous-classe car il définit des paramètres spécifiques au modèle en Python que `tokenizer.json` ne prend pas en compte. Lorsqu'un backend comme mistral-common n'est pas installé, [AutoTokenizer](/docs/transformers/v5.23.0/fr/model_doc/auto#transformers.AutoTokenizer) bascule sur [TokenizersBackend](/docs/transformers/v5.23.0/fr/main_classes/tokenizer#transformers.TokenizersBackend). ### Repli sur TokenizersBackend Certains modèles ne disposent pas d'une classe de tokenizer dédiée, et certains points de contrôle ont un `tokenizer_class` qui ne correspond pas à leur fichier `tokenizer.json` réel. [AutoTokenizer](/docs/transformers/v5.23.0/fr/model_doc/auto#transformers.AutoTokenizer) gère les deux cas en chargeant le pipeline depuis `tokenizer.json` via le [TokenizersBackend](/docs/transformers/v5.23.0/fr/main_classes/tokenizer#transformers.TokenizersBackend) générique. Il accorde la priorité au tokenizer sérialisé par rapport au nom de classe issu du Hub, ce qui corrige les problèmes tels que ceux causés par un `tokenizer_class` incohérent qui génère des identifiants de jetons incorrects. Un point de contrôle se résout en un `TokenizersBackend` générique pour l'une des trois raisons suivantes. | Raison | Comportement | Exemples | | ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ | | Aucune classe de tokenizer dédiée | Le type de modèle correspond directement à `TokenizersBackend` car `tokenizer.json` décrit entièrement le pipeline. | GLM, Granite, OLMo 2, GPT BigCode | | Classe de tokenizer du Hub connue comme incorrecte | Le `tokenizer_class` enregistré sur le Hub est incorrect pour le type de modèle, de sorte que `AutoTokenizer` l’ignore et charge `tokenizer.json` à la place. | DeepSeek V3, LLaVA, Qwen2, ModernBERT | | Remplacement spécifique du point de contrôle | Un point de contrôle dont la configuration Hub nécessite encore une correction est identifié par son identifiant de modèle et forcé sur le backend. | `deepseek-ai/DeepSeek-R1-Distill-*`, `Salesforce/blip2-*`, `google/umt5-small` | Les types de modèles et points de contrôle concernés évoluent au fur et à mesure que les configurations sont corrigées sur le Hub. Pour l’ensemble actuel, consultez les définitions de `MODELS_WITH_INCORRECT_HUB_TOKENIZER_CLASS` et `MODEL_IDS_TO_TOKENIZERS_BACKEND` dans [tokenization_auto.py](https://github.com/huggingface/transformers/blob/main/src/transformers/models/auto/tokenization_auto.py). Le repli est automatique et ne modifie pas la façon dont vous appelez [from_pretrained()](/docs/transformers/v5.23.0/fr/model_doc/auto#transformers.AutoTokenizer.from_pretrained). Le tokenizer résultant encode et décode exactement comme spécifié par `tokenizer.json`. Vérifiez le backend utilisé par un tokenizer à l'aide de la propriété `backend`. ```py from transformers import AutoTokenizer tokenizer = AutoTokenizer.from_pretrained("google/gemma-2-2b") tokenizer.backend 'tokenizers' ``` ## Inspecter l'architecture du tokenizer Inspectez les composants internes d'un tokenizer (normalizer, pre-tokenizer, model, decoder) à l'aide de l'attribut `_tokenizer`. ```py from transformers import AutoTokenizer tokenizer = AutoTokenizer.from_pretrained("google/gemma-2-2b") print(tokenizer._tokenizer.normalizer) print(tokenizer._tokenizer.pre_tokenizer) print(tokenizer._tokenizer.model) print(tokenizer._tokenizer.decoder) ``` ## Ressources - L'article [Tokenization in Transformers v5](https://huggingface.co/blog/tokenizers) aborde la motivation derrière les nouveaux backends de tokenization. - Consultez le [guide de migration](https://github.com/huggingface/transformers/blob/main/MIGRATION_GUIDE_V5.md#tokenization) pour un aperçu des modifications apportées à la tokenization.