Zum Hauptinhalt springen

Text-Tokenizer-Modul

Das Text-Tokenizer-Modul wandelt Zeichenketten in vom Modell verwendbare Token-ID-Sequenzen um.
Es übernimmt nur Tokenisierung, Kodierung und Dekodierung, nicht die Modellinferenz. Typischerweise wird der Text zunächst in ein MLMultiArray oder einen onnxruntime.tensor kodiert und das Ergebnis anschließend an den jeweiligen CoreML- oder ONNX-Runtime-Inferenz-Request übergeben.

Dieses Modul ist auf „ausreichende Inferenz auf dem Gerät“ ausgerichtet:

  • WordPiece bietet die höchste Kompatibilität und eignet sich für Modelle wie BERT und CN-CLIP.
  • BPE und SentencePiece verwenden eine leichte Kompatibilitätsstrategie und eignen sich für die meisten Kodierungsszenarien auf dem Gerät.
  • Komplexes Tokenizer-Training, Sampling oder das vollständige Verhalten der Upstream-Ökosysteme wird nicht in die Laufzeit übernommen.

Dieses Modul ist in Versionen nach 20260319 verfügbar

Tokenizer erstellen​

coreml.new_text_tokenizer(opts)​

SentencePiece_tokenizer, err = coreml.new_text_tokenizer({
    type = tokenizer_type,
    vocab_path = vocab_path,
    merges_path = merges_path,
    model_path = sentencepiece_model_path,
    pattern = regex_pattern,
    context_length = context_length,
    do_lower_case = use_lower_case,
    vocab_limit = vocab_limit,
    clean_text = clean_text,
    add_bos = add_bos,
    add_eos = add_eos,
    bos_token = bos_token_text,
    eos_token = eos_token_text,
    pad_token = pad_token_text,
    unk_token = unk_token_text, -- SentencePiece token text
})

Werte für type​

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

Standardwert ist wordpiece.

Wenn das erste Argument von coreml.new_text_tokenizer(...) keine Tabelle ist, wird direkt die wordpiece-Kurzform verwendet, entsprechend etwa coreml.new_wordpiece_tokenizer(vocab_path).

Häufige Parameter​

  • vocab_path
    Zeichenkette. Pfad zur Vokabulardatei.

  • merges_path
    Zeichenkette. Pfad zur von BPE-Tokenizern verwendeten Merges-Datei.

  • model_path
    Zeichenkette. Pfad zu einer .model-Datei für den SentencePiece-Kompatibilitätsmodus.

  • pattern
    Zeichenkette. Regulärer Ausdruck für den Regex-Tokenizer.

  • context_length
    Ganzzahl, optional. Länge der ausgegebenen Token-Sequenz.

  • do_lower_case
    Boolean, optional. Gibt an, ob zunächst in Kleinbuchstaben umgewandelt wird.

  • vocab_limit
    Ganzzahl, optional, hauptsächlich für WordPiece. Begrenzt die Größe des Vokabulars.

  • clean_text
    Boolean, optional. Gibt an, ob vor der Tokenisierung eine grundlegende Textbereinigung erfolgt.

  • add_bos / add_eos
    Boolean, optional. Gibt an, ob der Kodierung am Anfang bzw. Ende Start-/End-Token angefügt werden.

  • bos_token / eos_token / pad_token / unk_token
    Zeichenkette, optional. Der Text der jeweiligen Special-Token im Vokabular.

Nicht jeder Tokenizer-Typ unterstützt alle obigen Felder. Erforderliche Felder und Standardwerte der aktuellen Implementierung:

  • wordpiece Unterstützt die direkte Übergabe einer vocab_path-Zeichenkette oder einer Tabelle; vocab_path muss vorhanden sein. Standard sind context_length = 52, do_lower_case = true und vocab_limit = 21128; das Vokabular muss [PAD], [UNK], [CLS] und [SEP] enthalten.
  • bpe Akzeptiert nur eine Tabelle; vocab_path und merges_path sind erforderlich. Standard sind context_length = 77, do_lower_case = false, clean_text = false, add_bos = false und add_eos = false.
  • sentencepiece Akzeptiert nur eine Tabelle; mindestens vocab_path oder model_path ist erforderlich. Standard sind context_length = 77, do_lower_case = false, clean_text = true, bos_token = "<s>", eos_token = "</s>", pad_token = "<pad>" und unk_token = "<unk>".
  • regex Akzeptiert nur eine Tabelle; vocab_path und pattern sind erforderlich. Standard sind context_length = 77, do_lower_case = false und clean_text = true.
  • whitespace / character / byte Akzeptiert nur eine Tabelle; vocab_path ist erforderlich. Standard sind context_length = 77, do_lower_case = false und clean_text = true.

Auswahlempfehlungen:

  • Wenn das Modell vocab.txt + WordPiece verwendet, wordpiece wählen.
  • Wenn das Modell vocab.json + merges.txt verwendet, bpe wählen.
  • Wenn das Modell .vocab oder .model verwendet, sentencepiece wählen.
  • regex, whitespace, character oder byte nur bei einfachen regelbasierten Tokenisierungsanforderungen erwägen.

Rückgabewerte​

  • tokenizer
    Objekt; bei einem Fehler nil.

  • err
    Zeichenkette; bei Erfolg nil, bei einem Fehler die Fehlermeldung.

Hinweise​

  • Das Tokenizerobjekt sollte einmal erstellt und wiederverwendet werden; eine Neuerstellung für jede Kodierung wird nicht empfohlen.
  • Beim Erstellen werden vor allem drei Dinge festgelegt: Tokenisierungsalgorithmus, Vokabularquelle und feste Ausgabelänge.
  • Bei deutlich falschen Modellergebnissen zuerst Tokenizer-Typ, Vokabulardatei, Special-Token-Konfiguration und die Übereinstimmung von context_length mit dem Training prüfen.
  • WordPiece ist derzeit die vollständigste und stabilste Variante.
  • BPE und SentencePiece zielen auf kompatible Kodierung auf dem Gerät und versprechen keine vollständige Reproduktion aller Upstream-Details.

Kurz-Tokenizer​

Die folgenden Kurzfunktionen leiten im Wesentlichen an coreml.new_text_tokenizer(...) weiter und eignen sich, wenn der Tokenizer-Typ bereits feststeht.

coreml.new_wordpiece_tokenizer(opts)​

  • Entspricht coreml.new_text_tokenizer({ type = "wordpiece", ... }).
  • Geeignet für Textmodelle im WordPiece-Stil wie BERT und CN-CLIP.
  • Unterstützt auch die direkte Übergabe eines Vokabularpfads: coreml.new_wordpiece_tokenizer(vocab_path).

coreml.new_bpe_tokenizer(opts)​

  • Entspricht coreml.new_text_tokenizer({ type = "bpe", ... }).
  • Deckt auch Modelle wie gpt2_bpe und clip_bpe mit vocab.json + merges.txt ab.

coreml.new_sentencepiece_tokenizer(opts)​

  • Entspricht coreml.new_text_tokenizer({ type = "sentencepiece", ... }).
  • Verwendet eine leichte, für Inferenz auf dem Gerät ausgelegte Kompatibilitätsimplementierung.
  • Unterstützt .vocab und .model.

coreml.new_regex_tokenizer(opts)​

  • Entspricht coreml.new_text_tokenizer({ type = "regex", ... }).
  • Geeignet für regelbasierte Tokenisierung und einfache Vokabularzuordnung.

coreml.new_byte_tokenizer(opts)​

  • Entspricht coreml.new_text_tokenizer({ type = "byte", ... }).
  • Wandelt den Text zunächst in einen UTF-8-Byte-Stream um und sucht anschließend byteweise im Vokabular.

coreml.new_whitespace_tokenizer(opts)​

  • Entspricht coreml.new_text_tokenizer({ type = "whitespace", ... }).
  • Geeignet für leichte Textmodelle mit Leerzeichen-Tokenisierung und direkter Vokabularsuche.

coreml.new_character_tokenizer(opts)​

  • Entspricht coreml.new_text_tokenizer({ type = "character", ... }).
  • Geeignet für zeichenbasierte Textmodelle.

Typprüfung​

coreml.is_text_tokenizer(value)​

is_tokenizer = coreml.is_text_tokenizer(value)

Prüft, ob ein Wert ein coreml_text_tokenizer_object ist.

Objektmethoden​

:encode(text[, opts])​

encoded_token, err = tokenizer:encode(text)

oder

encoded, err = tokenizer:encode(text, {
    output = "table" or "MLMultiArray" or "ort_tensor",
    data_type = data_type,
    pair_text = token_pair_text,
    max_length = max_length,
    padding = padding_strategy,
    truncation = truncation_strategy,
    return_attention_mask = return_attention_mask,
    return_token_type_ids = token_type_ids,
    return_special_tokens_mask = return_special_tokens_mask, -- token sequence
})

Kodiert einen einzelnen Text in eine Token-Sequenz.

:encode_batch(texts[, opts])​

encoded, err = tokenizer:encode_batch(texts)

oder

encoded, err = tokenizer:encode_batch(texts, {
    output = "table" or "MLMultiArray" or "ort_tensor",
    data_type = data_type,
    pair_text = pair_text_or_texts,
    max_length = max_length,
    padding = padding_strategy,
    truncation = truncation_strategy,
    return_attention_mask = return_attention_mask,
    return_token_type_ids = return_token_type_ids,
    return_special_tokens_mask = return_special_tokens_mask, -- token output
})

Kodiert mehrere Texte auf einmal und gibt Token-Sequenzen im Batch-Format zurück.

:decode(ids)​

text, err = tokenizer:decode(ids)

Dekodiert eine einzelne Token-ID-Sequenz zurück in Text.

  • ids kann ein Lua-Array, ein MLMultiArray oder eine tensorähnliche ORT-Tensor-Userdata sein.
  • ids kann auch jede tensorähnliche Userdata sein, die shape() und to_table() implementiert.
  • Bei Batch-Daten wird ein Fehler ausgegeben und auf decode_batch() verwiesen.

:decode_batch(batch_ids)​

texts, err = tokenizer:decode_batch(batch_ids)

Dekodiert Batch-Token-ID-Sequenzen zurück in ein Textarray.

  • batch_ids kann ein verschachteltes Lua-Array, ein MLMultiArray oder eine tensorähnliche ORT-Tensor-Userdata sein.
  • batch_ids kann auch jede tensorähnliche Userdata sein, die shape() und to_table() implementiert.

:vocab_size()​

vocab_size = tokenizer:vocab_size()

Gibt die Größe des verfügbaren Vokabulars des aktuellen Tokenizers zurück.

:context_length()​

context_length = tokenizer:context_length()

Gibt die feste Ausgabelänge des aktuellen Tokenizers zurück, auf die eine einzelne Kodierung aufgefüllt oder gekürzt wird.

Hinweise zu Kodierung und Rückgabewerten​

  • output ist standardmäßig "MLMultiArray" und eignet sich zur direkten Übergabe an CoreML-Modelle.
  • output = "table" eignet sich für Debugging, die Anzeige von Token-IDs oder die Kompatibilität mit älteren Skripten.
  • output = "ort_tensor" eignet sich zur direkten Übergabe an ONNX-Runtime-Textmodelle.
  • Vor output = "ort_tensor" muss require("onnxruntime") ausgeführt werden, damit die ORT-Bridge-Schnittstelle eingefügt wird.
  • output = "ort_tensor" hängt von ONNX Runtime ab und unterstützt daher nur iOS 13+.
  • Zur Kompatibilität mit älteren Skripten wird das Feld multi_array_output weiterhin gelesen; in neuem Code sollte einheitlich output verwendet werden.

Regeln für data_type​

  • Bei output = "MLMultiArray" kann data_type "int32", "float32", "float16" oder "double" sein; "float64" ist ein Alias für "double".
  • Bei output = "MLMultiArray" ist data_type = "int32" der Standard.
  • Bei output = "ort_tensor" kann data_type "float16", "float32", "uint8", "int8", "int32", "int64", "double" oder "bool" sein.
  • Bei output = "ort_tensor" ist data_type = "int64" der Standard.

padding / truncation​

  • padding kann ein Boolean oder eine Zeichenkette sein.
    • true wird auf "max_length" abgebildet.
    • false wird auf "do_not_pad" abgebildet.
  • truncation kann ein Boolean oder eine Zeichenkette sein.
    • true wird auf "longest_first" abgebildet.
    • false wird auf "do_not_truncate" abgebildet.

pair_text​

  • In encode() kann ein einzelnes pair_text übergeben werden.
  • In encode_batch() kann ein einzelnes pair_text oder ein Zeichenkettenarray mit der Batchgröße übergeben werden.

Strukturierte Rückgabe​

Wenn eines der folgenden Felder true ist, geben encode() / encode_batch() eine strukturierte Ergebnistabelle statt nur einer rohen Token-Sequenz zurück:

  • return_attention_mask
  • return_token_type_ids
  • return_special_tokens_mask

Häufige Felder des strukturierten Ergebnisses:

  • input_ids
  • length
  • attention_mask
  • token_type_ids
  • special_tokens_mask

Bei Batch-Kodierung gilt:

  • Bei output = "table" bleibt die individuelle Länge jedes Beispiels erhalten.
  • Bei output = "MLMultiArray" / "ort_tensor" wird der Batch vor der Rückgabe zu einer regulären Matrix aufgefüllt.

Beispiel​

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