Tokeniseurs v1 : Encodage, décodage et échelle, mesurés

Tokeniseurs v1 : Encodage, décodage et échelle, mesurés

Une pile de services peut passer plus de temps à convertir du texte en entiers qu’à traiter le premier bloc transformateur. Cette affirmation est délibérément provocatrice et n’est pas toujours vraie — pour des prompts courts sur une GPU chaude, la tokenisation est généralement due à des erreurs d’arrondi. Mais elle l’est suffisamment souvent, dans suffisamment de charges de travail, pour que l’article du blog Hugging Face tokenisers v1 : encode, decode and scaling, measured (huggingface.co/blog/tokenizers-v1) vaille la peine d’être lu comme un document technique plutôt qu’une annonce. Cet article aborde les choses de cette manière : quel est réellement le coût de la frontière entre encodage et décodage, comment installer et utiliser la bibliothèque, et comment mesurer l’échelle sans se tromper soi-même.

Lorsque la source indique des chiffres spécifiques, considérez-les comme appartenant au matériel, à la distribution du texte et à la configuration de la source. Ce qui suit est la méthodologie et le code de travail nécessaires pour les reproduire ou les contredire sur votre propre machine.

Pourquoi l’encodage et le décodage méritent leurs propres chiffres

La tokenisation est la seule partie d’un pipeline de déduction moderne qui soit fondamentalement séquentielle par document et limitée par le CPU. L’attention est parallèle à travers la séquence ; le passage par des expressions régulières d’un pré-tokeniseur ne l’est pas. C’est cette asymétrie qui rend le comportement en termes d’échelle intéressant : ajouter des GPU ne rend pas le tokeniseur plus rapide, et augmenter la taille du lot n’aide que jusqu’au point où le pool de threads du noyau Rust se sature.

Trois quantités sont importantes en pratique :

• Coût d’encodage — texte en entrée, IDs entiers en sortie. Payé une fois par requête sur le chemin critique, et une fois par document lors du traitement de corpus hors ligne.
• Coût de décodage — IDs en sortie, texte restitué. Payé pour chaque token généré en flux si vous effectuez un détokenisation incrémentale, ce qui représente un coût courant et souvent non remarqué dans les interfaces de chat.
• Fertilité — tokens par unité de texte. Ce n’est pas une mesure de vitesse, mais elle indique combien de longueur de séquence vous obtenez par caractère, et donc quel est le coût en attention impliqué pour un corpus donné.

Dans ce cadre, l’échelle n’est pas une seule courbe. Il y en a au moins quatre : la longueur de la séquence, la taille du lot, le nombre de threads et le domaine texte. Un benchmark qui fixe trois d’entre eux et en varie un est utile. Un benchmark qui varie les quatre en même temps produit un chiffre principal sur lequel personne ne peut agir.

Exigences

Avant d’installer quoi que ce soit, assurez-vous de disposer de ce qui suit :

• Un interpréteur CPython 3.x pris en charge. Vérifiez sa version avec python --version et consultez les métadonnées du paquet pour la version que vous installez ; la plage prise en charge évolue avec le temps.
• pip, et de préférence un environnement virtuel afin que la bibliothèque de tokenisation ne entre pas en conflit avec d’autres dépendances fixées.
• Un fichier tokenizer.json, ou un corpus à partir duquel vous pouvez en créer un. La bibliothèque principale est délibérément agnostique quant à l’origine du vocabulaire.
• Une machine que vous pouvez laisser tranquille pendant les mesures. L’échelle de fréquence CPU, les quotas CPU des conteneurs et les voisins bruyants apparaîtront tous dans votre p95 avant que la bibliothèque ne le fasse.
• Optionnel : un outilchain Rust, uniquement si vous comptez compiler les bindings à partir de la source plutôt que d’installer un wheel.

Pour une étude d’échelle, décidez également à l’avance quel axe vous variez. Notez-le avant de lancer quoi que ce soit.

Installation étape par étape

Créez d’abord un environnement isolé, afin qu’un futur pip install ne puisse pas mettre à jour silencieusement une dépendance sur laquelle votre benchmark était calibré.

python -m venv .venv
source .venv/bin/activate    # Windows: .venv\Scripts\activate

Mettez à jour les outils de packaging, car des versions plus anciennes de pip résolvent parfois les wheels de manière suboptimale.

python -m pip install --upgrade pip

Installez la bibliothèque de tokenisation. Les wheels précompilés constituent la voie normale et évitent le besoin d’un compilateur Rust.

pip install tokenizers

Vérifiez l’importation et notez précisément la version dans vos notes — un benchmark sans chaîne de version n’est pas reproductible.

python -c "import tokenizers; print(tokenizers.__version__)"

Si vous devez compiler à partir de la source — par exemple, pour tester un changement non encore publié ou une plateforme sans wheels — installez l’outilchain Rust et un backend de compilation, puis compilez les bindings Python à partir d’une copie du répertoire tokenizers de Hugging Face.

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
pip install maturin

git clone https://github.com/huggingface/tokenizers
cd tokenizers/bindings/python
pip install -e .

NOTE DE CONFIGURATION IMPORTANTE POUR LES MESURES. Premièrement, l’encodage par lots est implémenté en Rust et peut utiliser un pool de threads de prélèvement de travail ; le système d’exécution respecte une variable d’environnement telle que RAYON_NUM_THREADS, assurez-vous donc qu’elle soit fixée afin que l’axe du comptage des threads corresponde bien à la variable prévue. Deuxièmement, certaines déploiements exposent TOKENIZERS_PARALLELISM pour contrôler le fait de diviser le travail en tâches parallèles ; définissez-le explicitement et de manière identique lors de chaque exécution dans une comparaison, plutôt que de le laisser prendre des valeurs différentes selon l’environnement.

Encodage et décodage en pratique

Un objet Encoding est plus riche qu’une liste d’entiers. Il contient :

• ids — les indices du vocabulaire consommés par le modèle.
• tokens — les chaînes de surface correspondantes, qui sont ce dont vous avez besoin pour déboguer une séparation.
• offsets — les segments de caractères dans le texte original, utiles pour l’highlighting, l’attribution ou l’étiquetage des segments.
• attention_mask, type_ids et special_tokens_mask — les tenseurs auxiliaires nécessaires à un cycle d’entraînement.
• overflowing — les encodages générés lorsque une séquence dépasse votre limite de troncature et que vous souhaitez conserver le reste.

Le décodage est l’opération inverse, non l’fonction inverse. La normalisation est souvent perdante : le pliage des majuscules/minuscules, la normalisation Unicode, le regroupement des espaces blancs et le remapping au niveau des octets peuvent tous faire en sorte que decode(encode(x)) diffère de x en tant que chaîne. Le test pertinent est l’idempotence — encoder la sortie décodée doit produire les mêmes IDs — et non l’égalité de chaînes avec l’entrée.

Exemples d’utilisation

Exemple 1 — un aller-retour minimal

Chargez un tokenizer à partir d’une définition JSON sauvegardée et examinez ce qui est renvoyé.

from tokenizers import Tokenizer

tok = Tokenizer.from_file("tokenizer.json")

text = "Tokenizers sit between raw text and model weights."
enc = tok.encode(text)

print(enc.tokens)                 # surface pieces
print(enc.ids)                    # model-facing integers
print(tok.decode(enc.ids))        # reconstructed text
print(enc.offsets[:5])            # character spans

L’idempotence est le critère qui résiste à la normalisation perdante : re-encodez la chaîne décodée et vérifiez que les IDs correspondent.

ids_once = tok.encode(text).ids
ids_twice = tok.encode(tok.decode(ids_once)).ids
print(ids_once == ids_twice)      # should be True; a False here means instability

Exemple 2 — encodage par lots avec remplissage et troncature

Configurez le tokenizer une fois, puis passez-lui une liste. Les méthodes par lots sont là où le noyau Rust montre tout son intérêt, car elles permettent de paralléliser les traitements sur plusieurs documents.

tok.enable_truncation(max_length=512)
tok.enable_padding(length=512)

texts = [open(p, encoding="utf-8").read() for p in ["a.txt", "b.txt", "c.txt"]]
encs = tok.encode_batch(texts)

print(len(encs), len(encs[0].ids), len(encs[0].attention_mask))

Si vous vous souciez du débit plutôt que des tenseurs à forme fixe, omettez complètement le remplissage et le troncement : le remplissage à une longueur fixe augmente le nombre de tokens et modifie discrètement la signification de votre valeur en tokens par seconde.

Exemple 3 — entraînement d’un tokenizer BPE au niveau des octets à partir d’un itérateur

Pour un travail spécifique à un corpus, entraînez plutôt que d’hériter. L’interface itérateur vous permet de traiter un grand corpus en flux sans le stocker en mémoire.

from tokenizers import Tokenizer, models, trainers, pre_tokenizers, decoders

tok = Tokenizer(models.BPE(unk_token="[UNK]"))
tok.pre_tokenizer = pre_tokenizers.ByteLevel(add_prefix_space=False)
tok.decoder = decoders.ByteLevel()

trainer = trainers.BpeTrainer(
    vocab_size=30000,
    special_tokens=["[UNK]", "[PAD]", "[CLS]", "[SEP]", "[MASK]"],
)

def corpus():
    with open("corpus.txt", encoding="utf-8") as f:
        for line in f:
            yield line

tok.train_from_iterator(corpus(), trainer=trainer)
tok.save("tokenizer.json")

Notez que modifier vocab_size, le pré-tokeniseur, ou la liste des tokens spéciaux modifie à la fois la qualité et la vitesse. Chaque telle modification rend invalides les mesures précédentes ; relancez plutôt que d’extrapoler.

Mesure de l’échelle : les axes qui ont réellement un impact

Quatre axes méritent d’être isolés dans des exécutions séparées.

Longueur de la séquence. Pour un budget total de tokens fixe, le débit varie en fonction de la manière dont ces tokens sont distribués. Un document de 8,000 tokens et huit documents de 1,000 tokens ne sont pas interchangeables, car les coûts d’initialisation par document s’amortissent différemment.

Taille du lot. L’encodage en lots améliore généralement le débit jusqu’au point où le pool de threads est saturé et où le trafic mémoire devient prédominant. Tracez la courbe ; ne supposez pas que le plus grand lot est le meilleur sur des chemins sensibles à la latence.

Nombre de threads. C’est l’axe le plus souvent laissé sans contrôle. Si la taille du pool de threads diffère entre deux exécutions, vous mesurez le planificateur de votre machine, et non le tokenizer.

Domaine du texte. La prose anglaise propre est le meilleur cas. Le code source, l’HTML avec des balises longues non fermées, les caractères CJK et les textes riches en emojis sollicitent différentes parties du pipeline — en particulier les règles de séparation du pré-tokeniseur. Rapportez des valeurs par domaine, ou indiquez le domaine.

Pour chaque combinaison, enregistrez le débit (tokens par seconde et séquences par seconde) et une distribution de latence. Rapportez p50 et p95. Une moyenne cache la partie qui détermine si votre service respecte un SLO.

Un outil de mesure reproductible

L’outil suivant mesure le débit d’encodage en état stationnaire, avec un phase d’échauffement, des exécutions répétées et un rapport de pourcentiles. Il est délibérément simple afin que vous puissiez l’auditer plutôt que de lui faire confiance.

import statistics
import time

from tokenizers import Tokenizer

tok = Tokenizer.from_file("tokenizer.json")

# Replace with a realistic sample from your own corpus.
texts = [open("sample.txt", encoding="utf-8").read()] * 512

# Warmup: excludes page faults and lazy initialization from the measurement.
for _ in range(3):
    tok.encode_batch(texts)

durations = []
token_counts = []

for _ in range(20):
    t0 = time.perf_counter()
    encs = tok.encode_batch(texts)
    elapsed = time.perf_counter() - t0
    durations.append(elapsed)
    token_counts.append(sum(len(e.ids) for e in encs))

durations.sort()
median = statistics.median(durations)
p95 = durations[int(0.95 * len(durations)) - 1]

tokens = statistics.mean(token_counts)
print(f"median batch time: {median:.4f} s")
print(f"p95 batch time:    {p95:.4f} s")
print(f"tokens per batch:  {tokens:.0f}")
print(f"tokens/second:     {tokens / median:.0f}")

Répétez cela en changeant un axe à la fois. Lorsque vous comparez deux exécutions, conservez le fichier de tokenisation, l’interpréteur, les paramètres des threads et l’échantillon de texte de manière identique au niveau des octets ; ne changez rien d’autre que la variable étudiée.

Une extension vaut la peine d’efforts : relancez le même ensemble de fonctionnalités à l’intérieur de votre boucle de service réelle, avec la GPU en activité. La tokenisation qui semble gratuite en isolation peut s’avérer coûteuse lorsqu’elle concurrence les mêmes cœurs CPU qui alimentent l’accélérateur.

Lire les chiffres sans se tromper soi-même

Une valeur de débit est une affirmation concernant une configuration. Avant de la reproduire, demandez-vous :

• La mesure était-elle en état stationnaire ou au démarrage ? Le chargement du modèle et l’initialisation lors de la première appel doivent faire l’objet d’une valeur distincte.
• Le padding et le troncature étaient-ils activés ? Le padding augmente le nombre de tokens et donc le numérateur.
• Quel était le domaine du texte ? Une valeur obtenue à partir de prose propre ne peut pas être transposée à du HTML extrait.
• Le pool de threads était-il fixé ? Sinon, le résultat n’est pas portable sur une machine ayant un nombre différent de cœurs.
• La statistique rapportée est-elle une moyenne ? Dans ce cas, la partie finale n’est pas mesurée.

La contribution de l’article de référence réside dans le cadre défini — l’encodage, le décodage et l’échelle sont trois questions différentes qui méritent trois mesures distinctes — ainsi que dans un ensemble de mesures prises dans des conditions spécifiées. Utilisez-le pour calibrer vos attentes et choisir ce à mesurer. Ne l’utilisez pas comme substitut à la mesure de votre propre corpus, car c’est votre corpus que votre service servira.

Ce que la source peut et ne peut pas affirmer

Ce qu’elle peut confirmer : le fait que la frontière entre encodage/décodage est mesurable et mérite d’être mesurée ; que le comportement d’échelle dépend de plus d’une variable d’entrée ; et que la méthodologie de rapportage est aussi importante que la valeur principale affichée.

Ce qu’elle ne peut pas confirmer : une garantie que n’importe quelle valeur spécifique sera transférable à votre matériel, à votre vocabulaire ou à votre distribution de texte. Chaque chiffre dépend de la machine, de la configuration des threads, du fichier de tokenisation et de l’échantillon. Toute comparaison qui modifie deux de ces éléments en même temps n’est pas une vraie comparaison.

Limites ouvertes. La conception du vocabulaire, le choix du pré-tokeniseur et le domaine du corpus interagissent de manières que une référence générale ne peut pas entièrement décomposer. Si votre charge de travail est dominée par un domaine non couvert par la référence — code, caractères CJK, journaux structurés, longs documents juridiques — considérez les chiffres publiés comme une hypothèse de départ et reproduisez l’expérience localement.

Conclusion

Les tokeniseurs v1, tels que présentés dans l’article de Hugging Face, doivent être interprétés avant tout comme une invitation à mesurer plutôt que comme un ensemble de chiffres à citer. Le flux de travail pratique est simple : installez la bibliothèque dans un environnement isolé, fixez sa version, chargez ou entraînez un tokeniseur, vérifiez l’idempotence de l’encodage/décodage, puis modifiez un seul paramètre à la fois — longueur de la séquence, taille du lot, nombre de threads ou domaine du texte — en rapportant des distributions plutôt que des moyennes.

Commencez avec l’outil ci-dessus et un échantillon de votre corpus réel. Quinze minutes de mesures systématiques vous en apprendront davantage sur vos coûts de traitement que n’importe quelle référence publiée, y compris celle-ci.