텍스트 토크나이저 모듈

텍스트 토크나이저 모듈은 문자열을 모델에서 사용할 수 있는 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 = 시작 토큰 추가 여부,
    add_eos = 종료 토큰 추가 여부,
    bos_token = 시작 토큰 텍스트,
    eos_token = 종료 토큰 텍스트,
    pad_token = 패딩 토큰 텍스트,
    unk_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​

구조화된 반환​

예제​