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.

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 ou une classe de tokenizer spécifique au modèle.

from transformers import AutoTokenizer

tokenizer = AutoTokenizer.from_pretrained("google/gemma-2-2b")

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() 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.

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() est similaire mais ne renvoie que les input_ids.

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() convertit une seule séquence ou un lot de input_ids tokenisés en texte.

tokenizer.decode(input_ids)
'<bos>Sphinx of black quartz, judge my vow.'

TokenizersBackend.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.

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.

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)
'<bos>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.

from transformers import AutoTokenizer

tokenizer = AutoTokenizer.from_pretrained(
    "google/gemma-3-4b-pt",
    extra_special_tokens={"image_token": "<image>"}
)

Traitement par lots

Le traitement par lots tokenise plusieurs séquences en un seul appel. TokenizersBackend gère les grands lots plus rapidement car son backend basé sur Rust parallélise le travail sur plusieurs threads.

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.

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]
    ])
}

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.

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.

Tous les backends héritent de 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 sélectionne le meilleur backend disponible lorsque vous appelez 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 hérite de TokenizersBackend, et SiglipTokenizer hérite de SentencePieceBackend. Certains modèles, comme GLM, sont mappés directement sur TokenizersBackend car le fichier tokenizer.json décrit entièrement le pipeline. 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 capture pas. Lorsqu’un backend comme mistral-common n’est pas installé, AutoTokenizer bascule sur 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 gère les deux cas en chargeant le pipeline depuis tokenizer.json via le TokenizersBackend générique. Il privilégie le tokenizer sérialisé par rapport au nom de classe 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.

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.

Le repli est automatique et ne modifie pas la façon dont vous appelez 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.

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) avec l'attribut _tokenizer.

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 aborde la motivation derrière les nouveaux backends de tokenization.
• Consultez le guide de migration pour un aperçu des modifications apportées à la tokenization.