Module tokenizer de texte

Le module tokenizer de texte convertit les chaînes en séquences d’identifiants token utilisables par les modèles.
Cette couche ne fait que la tokenisation, l’encodage et le décodage inverse ; elle n’effectue pas l’inférence du modèle. Le flux typique consiste à encoder d’abord le texte en MLMultiArray ou onnxruntime.tensor, puis à transmettre le résultat à l’inféreur CoreML ou ONNX Runtime correspondant.

L’objectif de cette implémentation est de fournir les fonctions nécessaires à l’inférence sur appareil :

WordPiece offre la compatibilité la plus complète et convient aux modèles tels que BERT et CN-CLIP
BPE et SentencePiece utilisent une stratégie de compatibilité légère adaptée à la plupart des scénarios d’encodage sur appareil
L’entraînement complexe des tokenizers, l’échantillonnage et l’ensemble du comportement de l’écosystème amont ne sont pas intégrés à l’environnement d’exécution

Ce module est disponible à partir des versions postérieures au 20260319

Créer un tokenizer

`coreml.new_text_tokenizer(opts)`

objet_tokenizer, message_erreur = coreml.new_text_tokenizer({
    type = type_tokenizer,
    vocab_path = chemin_vocabulaire,
    merges_path = chemin_fichier_merges,
    model_path = chemin_modele_SentencePiece,
    pattern = expression_reguliere,
    context_length = longueur_contexte,
    do_lower_case = convertir_en_minuscules,
    vocab_limit = limite_vocabulaire,
    clean_text = nettoyer_le_texte,
    add_bos = ajouter_token_de_debut,
    add_eos = ajouter_token_de_fin,
    bos_token = texte_token_debut,
    eos_token = texte_token_de_fin,
    pad_token = texte_token_remplissage,
    unk_token = texte_token_inconnu,
})

Valeurs de `type`

wordpiece / bert / cn_clip
bpe / gpt2_bpe / clip_bpe
sentencepiece / spm
regex / pattern
byte / bytes
whitespace / space
character / char

wordpiece est la valeur par défaut.

Si le premier paramètre de coreml.new_text_tokenizer(...) n’est pas une table, il est traité directement comme une construction abrégée wordpiece, ce qui équivaut à un appel tel que coreml.new_wordpiece_tokenizer(vocab_path).

Paramètres courants

vocab_path
type texte, chemin du fichier de vocabulaire.
merges_path
type texte, chemin du fichier merges utilisé par les tokenizers de la famille BPE.
model_path
type texte, chemin du fichier .model utilisable par le mode compatible SentencePiece.
pattern
type texte, expression régulière utilisée par le tokenizer Regex.
context_length
type entier, paramètre facultatif, longueur de la séquence de tokens renvoyée.
do_lower_case
type booléen, paramètre facultatif, indique s’il faut convertir préalablement le texte en minuscules.
vocab_limit
type entier, paramètre facultatif, principalement utilisé avec WordPiece pour limiter la taille du vocabulaire.
clean_text
type booléen, paramètre facultatif, indique s’il faut effectuer un nettoyage élémentaire du texte avant la tokenisation.
add_bos / add_eos
type booléen, paramètre facultatif, indique s’il faut ajouter un token de début / de fin avant ou après le résultat encodé.
bos_token / eos_token / pad_token / unk_token
type texte, paramètre facultatif, texte des tokens spéciaux correspondants dans le vocabulaire.

Tous les types de tokenizer ne prennent pas en charge tous les champs ci-dessus. Les champs obligatoires et les valeurs par défaut de l’implémentation actuelle sont les suivants :

wordpiece Accepte directement une chaîne vocab_path ou une table ; vocab_path doit exister ; par défaut, context_length = 52, do_lower_case = true, vocab_limit = 21128, et le vocabulaire doit contenir [PAD], [UNK], [CLS] et [SEP].
bpe Accepte uniquement une table ; vocab_path et merges_path sont obligatoires ; par défaut, context_length = 77, do_lower_case = false, clean_text = false, add_bos = false et add_eos = false.
sentencepiece Accepte uniquement une table ; au moins vocab_path ou model_path est obligatoire ; par défaut, context_length = 77, do_lower_case = false, clean_text = true, bos_token = "<s>", eos_token = "</s>", pad_token = "<pad>" et unk_token = "<unk>".
regex Accepte uniquement une table ; vocab_path et pattern sont obligatoires ; par défaut, context_length = 77, do_lower_case = false et clean_text = true.
whitespace / character / byte Acceptent uniquement une table ; vocab_path est obligatoire ; par défaut, context_length = 77, do_lower_case = false et clean_text = true.

Conseils de sélection :

Si le modèle utilise vocab.txt + WordPiece, choisissez wordpiece
Si le modèle utilise vocab.json + merges.txt, choisissez bpe
Si le modèle utilise .vocab ou .model, choisissez sentencepiece
Pour un besoin de découpage selon des règles simples, envisagez ensuite regex, whitespace, character ou byte

Valeur renvoyée

objet_tokenizer
type objet, renvoie nil si la création échoue.
message_erreur
type texte, vaut nil en cas de réussite et contient le message d’erreur en cas d’échec.

Description

Il est recommandé de créer l’objet tokenizer une seule fois puis de le réutiliser, plutôt que de le recréer à chaque encodage
La création détermine principalement trois éléments : l’algorithme de tokenisation, la source du vocabulaire et la longueur de sortie fixe
Si les résultats du modèle sont manifestement incorrects, vérifiez en priorité le type de tokenizer, le fichier de vocabulaire, la configuration des tokens spéciaux et la concordance de context_length avec l’entraînement
WordPiece est actuellement la famille la plus complète et la plus stable
BPE et SentencePiece visent la compatibilité de l’encodage sur appareil et ne garantissent pas de reproduire tous les détails des implémentations amont

Constructeurs abrégés

Les fonctions abrégées suivantes transmettent essentiellement leurs paramètres à coreml.new_text_tokenizer(...). Elles conviennent lorsque le type de tokenizer est déjà connu.

`coreml.new_wordpiece_tokenizer(opts)`

Équivaut à coreml.new_text_tokenizer({ type = "wordpiece", ... })
Convient aux modèles de texte de style WordPiece, tels que BERT et CN-CLIP
Accepte aussi directement un chemin de vocabulaire : coreml.new_wordpiece_tokenizer(vocab_path)

`coreml.new_bpe_tokenizer(opts)`

Équivaut à coreml.new_text_tokenizer({ type = "bpe", ... })
Couvre également les modèles gpt2_bpe et clip_bpe de type vocab.json + merges.txt

`coreml.new_sentencepiece_tokenizer(opts)`

Équivaut à coreml.new_text_tokenizer({ type = "sentencepiece", ... })
Utilise une implémentation légère compatible destinée à l’inférence sur appareil
Accepte .vocab et .model

`coreml.new_regex_tokenizer(opts)`

Équivaut à coreml.new_text_tokenizer({ type = "regex", ... })
Convient au découpage selon des règles et aux mappages simples de vocabulaire

`coreml.new_byte_tokenizer(opts)`

Équivaut à coreml.new_text_tokenizer({ type = "byte", ... })
Convertit d’abord le texte en flux d’octets UTF-8, puis recherche les tokens par octet dans le vocabulaire

`coreml.new_whitespace_tokenizer(opts)`

Équivaut à coreml.new_text_tokenizer({ type = "whitespace", ... })
Convient aux modèles de texte légers qui découpent sur les espaces et recherchent directement dans le vocabulaire

`coreml.new_character_tokenizer(opts)`

Équivaut à coreml.new_text_tokenizer({ type = "character", ... })
Convient aux modèles de texte au niveau des caractères

Détermination du type

`coreml.is_text_tokenizer(value)`

est_tokenizer_texte = coreml.is_text_tokenizer(valeur_a_tester)

Détermine si une valeur est un coreml_text_tokenizer_object.

Méthodes de l’objet

`:encode(text[, opts])`

resultat_encodage, message_erreur = objet_tokenizer:encode(texte)

resultat_encodage, message_erreur = objet_tokenizer:encode(texte, {
    output = "table" ou "MLMultiArray" ou "ort_tensor",
    data_type = type_donnees,
    pair_text = texte_paire,
    max_length = longueur_maximale,
    padding = strategie_remplissage,
    truncation = strategie_troncature,
    return_attention_mask = renvoyer_attention_mask,
    return_token_type_ids = renvoyer_token_type_ids,
    return_special_tokens_mask = renvoyer_special_tokens_mask,
})

Encode un texte unique en séquence de tokens.

`:encode_batch(texts[, opts])`

resultat_encodage, message_erreur = objet_tokenizer:encode_batch(tableau_textes)

resultat_encodage, message_erreur = objet_tokenizer:encode_batch(tableau_textes, {
    output = "table" ou "MLMultiArray" ou "ort_tensor",
    data_type = type_donnees,
    pair_text = texte_paire ou tableau_textes_paires,
    max_length = longueur_maximale,
    padding = strategie_remplissage,
    truncation = strategie_troncature,
    return_attention_mask = renvoyer_attention_mask,
    return_token_type_ids = renvoyer_token_type_ids,
    return_special_tokens_mask = renvoyer_special_tokens_mask,
})

Encode plusieurs textes en une fois et renvoie les séquences de tokens sous forme de batch.

`:decode(ids)`

texte, message_erreur = objet_tokenizer:decode(ids)

Décode une séquence unique d’identifiants token en texte.

ids peut être un tableau Lua, un MLMultiArray ou un userdata tensor-like tel qu’un tenseur ORT
ids peut également être n’importe quel userdata tensor-like qui implémente shape() et to_table()
Si des données de batch sont transmises, une erreur est renvoyée et indique d’utiliser decode_batch()

`:decode_batch(batch_ids)`

tableau_textes, message_erreur = objet_tokenizer:decode_batch(batch_ids)

Décode un batch de séquences d’identifiants token en tableau de textes.

batch_ids peut être un tableau Lua imbriqué, un MLMultiArray ou un userdata tensor-like tel qu’un tenseur ORT
batch_ids peut également être n’importe quel userdata tensor-like qui implémente shape() et to_table()

`:vocab_size()`

taille_vocabulaire = objet_tokenizer:vocab_size()

Renvoie la taille du vocabulaire utilisable par le tokenizer actuel.

`:context_length()`

longueur_contexte = objet_tokenizer:context_length()

Renvoie la longueur de sortie fixe du tokenizer, c’est-à-dire la longueur à laquelle chaque encodage est complété ou tronqué.

Règles d’encodage et de retour

output vaut par défaut "MLMultiArray", ce qui convient à une transmission directe à un modèle CoreML
output = "table" convient au débogage, à l’examen des identifiants token ou à la compatibilité avec les anciens scripts
output = "ort_tensor" convient à une transmission directe à un modèle de texte ONNX Runtime
Avant output = "ort_tensor", exécutez require("onnxruntime") afin d’injecter les interfaces de pont ORT
output = "ort_tensor" dépend d’ONNX Runtime et n’est donc disponible que sous iOS 13+
Pour assurer la compatibilité avec les anciens scripts, le champ multi_array_output est encore lu ; dans le nouveau code, il est recommandé d’utiliser uniformément output

Règles de `data_type`

Avec output = "MLMultiArray", data_type accepte "int32", "float32", "float16" et "double" ; "float64" est un alias de "double"
Avec output = "MLMultiArray", data_type = "int32" par défaut
Avec output = "ort_tensor", data_type accepte "float16", "float32", "uint8", "int8", "int32", "int64", "double" et "bool"
Avec output = "ort_tensor", data_type = "int64" par défaut

`padding` / `truncation`

padding peut être un booléen ou une chaîne
- true correspond à "max_length"
- false correspond à "do_not_pad"
truncation peut être un booléen ou une chaîne
- true correspond à "longest_first"
- false correspond à "do_not_truncate"

`pair_text`

encode() accepte un seul pair_text
encode_batch() accepte un seul pair_text ou un tableau de chaînes dont la taille correspond à celle du batch

Retour structuré

Lorsque l’un des champs suivants vaut true, encode() / encode_batch() renvoie une table de résultat structurée plutôt qu’une simple séquence de tokens :

return_attention_mask
return_token_type_ids
return_special_tokens_mask

Champs courants du résultat structuré :

input_ids
length
attention_mask
token_type_ids
special_tokens_mask

Pour l’encodage par batch :

Avec output = "table", la longueur propre à chaque échantillon est conservée
Avec output = "MLMultiArray" / "ort_tensor", le batch est complété en matrice régulière avant d’être renvoyé

Exemple

local tokenizer = assert(coreml.new_text_tokenizer({
    type = "wordpiece",
    vocab_path = XXT_HOME_PATH.."/models/demo/vocab.txt",
    context_length = 52,
}))

local ids = assert(tokenizer:encode("星星", {
    output = "MLMultiArray",
    data_type = "int32",
}))

local structured = assert(tokenizer:encode("星星", {
    output = "table",
    return_attention_mask = true,
    return_token_type_ids = true,
}))

local ort = require("onnxruntime")

local input_ids = assert(tokenizer:encode("星星", {
    output = "ort_tensor",
    data_type = "int64",
}))

local batch = assert(tokenizer:encode_batch({
    "星星",
    "月亮",
}, {
    output = "ort_tensor",
}))

print(tokenizer:decode(structured.input_ids))
print(tokenizer:vocab_size())
print(tokenizer:context_length())

Créer un tokenizer​

coreml.new_text_tokenizer(opts)​

Valeurs de type​

Paramètres courants​

Valeur renvoyée​

Description​

Constructeurs abrégés​

coreml.new_wordpiece_tokenizer(opts)​

coreml.new_bpe_tokenizer(opts)​

coreml.new_sentencepiece_tokenizer(opts)​

coreml.new_regex_tokenizer(opts)​

coreml.new_byte_tokenizer(opts)​

coreml.new_whitespace_tokenizer(opts)​

coreml.new_character_tokenizer(opts)​

Détermination du type​

coreml.is_text_tokenizer(value)​

Méthodes de l’objet​

:encode(text[, opts])​

:encode_batch(texts[, opts])​

:decode(ids)​

:decode_batch(batch_ids)​

:vocab_size()​

:context_length()​

Règles d’encodage et de retour​

Règles de data_type​

padding / truncation​

pair_text​

Retour structuré​

Exemple​