テキストトークナイザーモジュール

テキストトークナイザーモジュールは、文字列をモデルで使用できる token ID シーケンスに変換します。
このレイヤーはトークン化、エンコード、デコードのみを行い、モデル推論は行いません。一般的な処理では、まずテキストを MLMultiArray または onnxruntime.tensor にエンコードし、その結果を対応する CoreML または ONNX Runtime 推論器に渡します。

現在のモジュールは「デバイス上の推論に必要十分」であることを目標としています。

WordPiece は最も高い互換性を備え、BERT、CN-CLIP などのモデルに適しています
BPE と SentencePiece は軽量な互換方式を採用し、デバイス上での多くのエンコード用途に適しています
複雑なトークナイザーの学習、サンプリング、上流エコシステムの完全な動作はランタイムへ持ち込みません

このモジュールは 20260319 以降のバージョンで使用できます

トークナイザーの作成

`coreml.new_text_tokenizer(opts)`

テキストトークナイザーオブジェクト, エラー情報 = coreml.new_text_tokenizer({
    type = トークナイザー種別,
    vocab_path = 語彙ファイルパス,
    merges_path = merges ファイルパス,
    model_path = SentencePiece モデルパス,
    pattern = 正規表現,
    context_length = コンテキスト長,
    do_lower_case = 小文字化するか,
    vocab_limit = 語彙上限,
    clean_text = 先にテキストをクリーニングするか,
    add_bos = 開始tokenを追加するか,
    add_eos = 終了tokenを追加するか,
    bos_token = 開始tokenテキスト,
    eos_token = 終了tokenテキスト,
    pad_token = パディング token テキスト,
    unk_token = 未知tokenテキスト,
})

`type` の値

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

デフォルトは wordpiece です。

coreml.new_text_tokenizer(...) の最初のパラメータが table でない場合は、wordpiece の簡易コンストラクターとして直接処理されます。つまり、coreml.new_wordpiece_tokenizer(vocab_path) のような使用方法と同等です。

一般的なパラメータ

vocab_path
文字列型。語彙ファイルのパスです。
merges_path
文字列型。BPE 系トークナイザーで使用する merges ファイルのパスです。
model_path
文字列型。SentencePiece 互換モードで使用できる .model ファイルのパスです。
pattern
文字列型。Regex トークナイザーで使用する正規表現です。
context_length
整数型の省略可能なパラメータ。出力 token シーケンスの長さです。
do_lower_case
ブール型の省略可能なパラメータ。先に小文字へ変換するかどうかを指定します。
vocab_limit
整数型の省略可能なパラメータ。主に WordPiece で使用し、語彙数の上限を制限します。
clean_text
ブール型の省略可能なパラメータ。トークン化の前に基本的なテキストクリーニングを行うかどうかを指定します。
add_bos / add_eos
ブール型の省略可能なパラメータ。エンコード結果の前後に開始 / 終了 token を追加するかどうかを指定します。
bos_token / eos_token / pad_token / unk_token
文字列型の省略可能なパラメータ。各特殊 token に対応する語彙内のテキストです。

すべてのトークナイザー型が上記のすべてのフィールドに対応するわけではありません。現在の実装における必須項目とデフォルト値は次のとおりです。

wordpiece vocab_path 文字列を直接渡す方法と table を渡す方法に対応します。vocab_path が必要です。デフォルトは context_length = 52、do_lower_case = true、vocab_limit = 21128 であり、語彙には [PAD]、[UNK]、[CLS]、[SEP] が必要です
bpe table のみ受け付けます。vocab_path と merges_path が必要です。デフォルトは context_length = 77、do_lower_case = false、clean_text = false、add_bos = false、add_eos = false です
sentencepiece table のみ受け付けます。vocab_path または model_path の少なくとも一方が必要です。デフォルトは context_length = 77、do_lower_case = false、clean_text = true、bos_token = "<s>"、eos_token = "</s>"、pad_token = "<pad>"、unk_token = "<unk>" です
regex table のみ受け付けます。vocab_path と pattern が必要です。デフォルトは context_length = 77、do_lower_case = false、clean_text = true です
whitespace / character / byte table のみ受け付けます。vocab_path が必要です。デフォルトは context_length = 77、do_lower_case = false、clean_text = true です

選択の目安：

モデルが vocab.txt + WordPiece を使用することが分かっている場合は、wordpiece を選択します
モデルが vocab.json + merges.txt を使用することが分かっている場合は、bpe を選択します
モデルが .vocab または .model を使用することが分かっている場合は、sentencepiece を選択します
単純な規則に基づくトークン化のみが必要な場合は、regex、whitespace、character、byte を検討します

戻り値

テキストトークナイザーオブジェクト
オブジェクト型。作成に失敗した場合は nil を返します。
エラーメッセージ
文字列型。成功した場合は nil、失敗した場合はエラーメッセージを返します。

説明

トークナイザーオブジェクトは一度作成して再利用するのに適しており、エンコードのたびに作成し直すことは推奨しません
作成時には主に、トークン化アルゴリズム、語彙の取得元、固定出力長を決定します
モデルの結果が明らかに正しくない場合は、トークナイザー型、語彙ファイル、special token の構成、context_length が学習時と一致しているかを優先して確認してください
WordPiece は現在最も完全で安定した方式です
BPE と SentencePiece はデバイス上のエンコードとの互換性を目標としており、すべての上流実装の詳細を完全に再現することは保証しません

簡易コンストラクター

以下の簡易関数は、いずれも実質的に coreml.new_text_tokenizer(...) へ処理を転送します。使用するトークナイザー型が決まっている場合に直接使用できます。

`coreml.new_wordpiece_tokenizer(opts)`

coreml.new_text_tokenizer({ type = "wordpiece", ... }) と同等です
BERT、CN-CLIP などの WordPiece 形式のテキストモデルに適しています
語彙パスの文字列を直接渡す方法にも対応します：coreml.new_wordpiece_tokenizer(vocab_path)

`coreml.new_bpe_tokenizer(opts)`

coreml.new_text_tokenizer({ type = "bpe", ... }) と同等です
gpt2_bpe、clip_bpe などの vocab.json + merges.txt モデルにも対応します

`coreml.new_sentencepiece_tokenizer(opts)`

coreml.new_text_tokenizer({ type = "sentencepiece", ... }) と同等です
デバイス上の推論向けに軽量な互換実装を使用します
.vocab と .model に対応します

`coreml.new_regex_tokenizer(opts)`

coreml.new_text_tokenizer({ type = "regex", ... }) と同等です
規則に基づくトークン化と単純な語彙マッピングに適しています

`coreml.new_byte_tokenizer(opts)`

coreml.new_text_tokenizer({ type = "byte", ... }) と同等です
最初にテキストを UTF-8 バイト列へ変換し、その後バイト単位で語彙を検索します

`coreml.new_whitespace_tokenizer(opts)`

coreml.new_text_tokenizer({ type = "whitespace", ... }) と同等です
空白でのトークン化と語彙の直接検索を行う軽量なテキストモデルに適しています

`coreml.new_character_tokenizer(opts)`

coreml.new_text_tokenizer({ type = "character", ... }) と同等です
文字単位のテキストモデルに適しています

型判定

`coreml.is_text_tokenizer(value)`

テキストトークナイザーか = coreml.is_text_tokenizer(判定対象値)

値が coreml_text_tokenizer_object かどうかを判定します。

オブジェクトメソッド

`:encode(text[, opts])`

エンコード結果, エラー情報 = テキストトークナイザーオブジェクト:encode(テキスト)

または

エンコード結果, エラー情報 = テキストトークナイザーオブジェクト:encode(テキスト, {
    output = "table" または "MLMultiArray" または "ort_tensor",
    data_type = データ型,
    pair_text = ペアテキスト,
    max_length = 最大長,
    padding = パディング方式,
    truncation = 切り詰め方式,
    return_attention_mask = attention maskを返すか,
    return_token_type_ids = token type idsを返すか,
    return_special_tokens_mask = special tokens maskを返すか,
})

単一のテキストを token シーケンスにエンコードします。

`:encode_batch(texts[, opts])`

エンコード結果, エラー情報 = テキストトークナイザーオブジェクト:encode_batch(テキスト配列)

または

エンコード結果, エラー情報 = テキストトークナイザーオブジェクト:encode_batch(テキスト配列, {
    output = "table" または "MLMultiArray" または "ort_tensor",
    data_type = データ型,
    pair_text = ペアテキストまたはペアテキスト配列,
    max_length = 最大長,
    padding = パディング方式,
    truncation = 切り詰め方式,
    return_attention_mask = attention maskを返すか,
    return_token_type_ids = token type idsを返すか,
    return_special_tokens_mask = special tokens maskを返すか,
})

複数のテキストをまとめてエンコードし、batch 形式の token シーケンスを返します。

`:decode(ids)`

テキスト, エラー情報 = テキストトークナイザーオブジェクト:decode(ids)

単一の token id シーケンスをテキストへデコードします。

ids には、Lua 配列、MLMultiArray、ORT tensor などの tensor-like userdata を使用できます
ids には、shape() と to_table() を実装した任意の tensor-like userdata も使用できます
batch データを渡した場合はエラーになり、decode_batch() を使用するように示されます

`:decode_batch(batch_ids)`

テキスト配列, エラー情報 = テキストトークナイザーオブジェクト:decode_batch(batch_ids)

batch token id シーケンスをテキスト配列へデコードします。

batch_ids には、ネストされた Lua 配列、MLMultiArray、ORT tensor などの tensor-like userdata を使用できます
batch_ids には、shape() と to_table() を実装した任意の tensor-like userdata も使用できます

`:vocab_size()`

語彙サイズ = テキストトークナイザーオブジェクト:vocab_size()

現在のトークナイザーで使用可能な語彙数を返します。

`:context_length()`

コンテキスト長 = テキストトークナイザーオブジェクト:context_length()

現在のトークナイザーの固定出力長、つまり各エンコードでパディングまたは切り詰めが行われる長さを返します。

エンコードと戻り値

output のデフォルトは "MLMultiArray" であり、CoreML モデルへ直接渡す場合に適しています
output = "table" は、デバッグ、token id の確認、従来のスクリプトとの互換性確保に適しています
output = "ort_tensor" は、ONNX Runtime テキストモデルへ直接渡す場合に適しています
output = "ort_tensor" を使用する前に require("onnxruntime") を実行して、ORT ブリッジインターフェースを追加する必要があります
output = "ort_tensor" は ONNX Runtime に依存するため、iOS 13+ のみ対応します
従来のスクリプトとの互換性のため、multi_array_output フィールドも引き続き読み取られます。ただし、新しいコードでは output の使用を推奨します

`data_type` の規則

output = "MLMultiArray" の場合、data_type には "int32"、"float32"、"float16"、"double" を指定できます。"float64" は "double" の別名として使用できます
output = "MLMultiArray" の場合、デフォルトは data_type = "int32" です
output = "ort_tensor" の場合、data_type には "float16"、"float32"、"uint8"、"int8"、"int32"、"int64"、"double"、"bool" を指定できます
output = "ort_tensor" の場合、デフォルトは data_type = "int64" です

`padding` / `truncation`

padding にはブール値または文字列を指定できます
- true は "max_length" にマッピングされます
- false は "do_not_pad" にマッピングされます
truncation にはブール値または文字列を指定できます
- true は "longest_first" にマッピングされます
- false は "do_not_truncate" にマッピングされます

`pair_text`

encode() では単一の pair_text を渡せます
encode_batch() では単一の pair_text、または batch サイズと一致する文字列配列を渡せます

構造化された戻り値

以下のいずれかのフィールドが true の場合、encode() / encode_batch() は token シーケンスだけでなく、構造化された結果テーブルを返します。

return_attention_mask
return_token_type_ids
return_special_tokens_mask

構造化された結果の一般的なフィールド：

input_ids
length
attention_mask
token_type_ids
special_tokens_mask

batch エンコードの場合：

output = "table" の場合は、各サンプル固有の長さを保持します
output = "MLMultiArray" / "ort_tensor" の場合は、batch を規則的な行列へパディングしてから返します

例

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

トークナイザーの作成​

coreml.new_text_tokenizer(opts)​

type の値​

一般的なパラメータ​

戻り値​

説明​

簡易コンストラクター​

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

型判定​

coreml.is_text_tokenizer(value)​

オブジェクトメソッド​

:encode(text[, opts])​

:encode_batch(texts[, opts])​

:decode(ids)​

:decode_batch(batch_ids)​

:vocab_size()​

:context_length()​

エンコードと戻り値​

data_type の規則​

padding / truncation​

pair_text​

構造化された戻り値​

例​