Mô-đun bộ tách token văn bản

Mô-đun bộ tách token văn bản chuyển chuỗi thành dãy ID token có thể đưa vào mô hình.
Lớp này chỉ xử lý việc tách token, mã hóa và giải mã ngược; không chạy suy luận. Quy trình thường dùng là mã hóa văn bản thành MLMultiArray hoặc onnxruntime.tensor, sau đó truyền kết quả vào yêu cầu CoreML hoặc ONNX Runtime tương ứng.

Mục tiêu hiện tại của mô-đun là “đủ tốt cho suy luận trên thiết bị”:

WordPiece có khả năng tương thích cao nhất và hoạt động tốt với các mô hình như BERT và CN-CLIP
BPE và SentencePiece sử dụng các triển khai nhẹ, chú trọng khả năng tương thích, phù hợp với phần lớn trường hợp mã hóa trên thiết bị
Mô-đun không cố đưa việc huấn luyện bộ tách token, lấy mẫu hoặc toàn bộ hệ sinh thái thượng nguồn vào thời gian chạy

Mô-đun này khả dụng trong các phiên bản phát hành sau 20260319

Tạo bộ tách token

`coreml.new_text_tokenizer(opts)`

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 = do_lower_case,
    vocab_limit = vocab_limit,
    clean_text = clean_text,
    add_bos = add_bos,
    add_eos = add_eos,
    bos_token = bos_token,
    eos_token = eos_token,
    pad_token = pad_token,
    unk_token = unk_token,
})

Giá trị của `type`

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

Mặc định là wordpiece.

Nếu đối số đầu tiên của coreml.new_text_tokenizer(...) không phải là bảng, lời gọi sẽ chuyển sang đường tắt WordPiece, tương đương với cách dùng như coreml.new_wordpiece_tokenizer(vocab_path).

Tham số chung

vocab_path
Kiểu chuỗi. Đường dẫn đến tệp từ vựng.
merges_path
Kiểu chuỗi. Đường dẫn đến tệp hợp nhất mà bộ tách token BPE sử dụng.
model_path
Kiểu chuỗi. Đường dẫn đến tệp .model dùng cho chế độ nhẹ tương thích SentencePiece.
pattern
Kiểu chuỗi. Biểu thức chính quy mà bộ tách token regex sử dụng.
context_length
Kiểu số nguyên, không bắt buộc. Độ dài dãy token đầu ra.
do_lower_case
Kiểu boolean, không bắt buộc. Có chuyển đầu vào thành chữ thường trước hay không.
vocab_limit
Kiểu số nguyên, không bắt buộc. Chủ yếu hữu ích với WordPiece để giới hạn kích thước từ vựng có hiệu lực.
clean_text
Kiểu boolean, không bắt buộc. Có thực hiện làm sạch văn bản cơ bản trước khi tách token hay không.
add_bos / add_eos Kiểu boolean, không bắt buộc. Có thêm token bắt đầu / kết thúc dãy vào đầu / cuối hay không.
bos_token / eos_token / pad_token / unk_token Kiểu chuỗi, không bắt buộc. Văn bản token dùng cho token đặc biệt tương ứng.

Không phải mọi loại bộ tách token đều hỗ trợ tất cả trường ở trên. Triển khai hiện tại hoạt động như sau:

wordpiece Chấp nhận chuỗi vocab_path hoặc bảng tùy chọn; yêu cầu vocab_path; mặc định là context_length = 52, do_lower_case = true và vocab_limit = 21128; từ vựng phải chứa [PAD], [UNK], [CLS] và [SEP]
bpe Chỉ nhận bảng; yêu cầu vocab_path và merges_path; mặc định là context_length = 77, do_lower_case = false, clean_text = false, add_bos = false và add_eos = false
sentencepiece Chỉ nhận bảng; yêu cầu ít nhất một trong hai trường vocab_path hoặc model_path; mặc định là context_length = 77, do_lower_case = false, clean_text = true, bos_token = "<s>", eos_token = "</s>", pad_token = "<pad>" và unk_token = "<unk>"
regex Chỉ nhận bảng; yêu cầu vocab_path và pattern; mặc định là context_length = 77, do_lower_case = false và clean_text = true
whitespace / character / byte Chỉ nhận bảng; yêu cầu vocab_path; mặc định là context_length = 77, do_lower_case = false và clean_text = true

Hướng dẫn lựa chọn:

Nếu mô hình sử dụng vocab.txt + WordPiece, chọn wordpiece
Nếu mô hình sử dụng vocab.json + merges.txt, chọn bpe
Nếu mô hình sử dụng .vocab hoặc .model, chọn sentencepiece
Chỉ dùng regex, whitespace, character hoặc byte cho các trường hợp đơn giản dựa trên quy tắc

Giá trị trả về

tokenizer
Đối tượng bộ tách token văn bản, hoặc nil khi thất bại.
err
Kiểu chuỗi. nil khi thành công; thông báo lỗi khi thất bại.

Lưu ý

Nên tạo đối tượng bộ tách token một lần rồi tái sử dụng
Quá trình tạo chủ yếu quyết định ba yếu tố: thuật toán tách token, nguồn từ vựng và độ dài đầu ra cố định
Nếu hoạt động của mô hình có vẻ không đúng, trước tiên hãy kiểm tra loại bộ tách token, tệp từ vựng, cấu hình token đặc biệt và context_length
WordPiece hiện là lựa chọn đầy đủ và đáng tin cậy nhất
BPE và SentencePiece hướng đến khả năng tương thích thực tế trên thiết bị, không nhằm tái tạo chính xác từng bit mọi chi tiết triển khai thượng nguồn

Hàm tạo rút gọn

Các tiện ích sau là trình bao mỏng quanh coreml.new_text_tokenizer(...). Hãy dùng khi đã biết loại bộ tách token.

`coreml.new_wordpiece_tokenizer(opts)`

Tương đương với coreml.new_text_tokenizer({ type = "wordpiece", ... })
Phù hợp với BERT, CN-CLIP và các mô hình văn bản kiểu WordPiece khác
Cũng hỗ trợ truyền trực tiếp chuỗi đường dẫn từ vựng: coreml.new_wordpiece_tokenizer(vocab_path)

`coreml.new_bpe_tokenizer(opts)`

Tương đương với coreml.new_text_tokenizer({ type = "bpe", ... })
Cũng hỗ trợ các mô hình vocab.json + merges.txt kiểu GPT-2 và CLIP

`coreml.new_sentencepiece_tokenizer(opts)`

Tương đương với coreml.new_text_tokenizer({ type = "sentencepiece", ... })
Sử dụng triển khai nhẹ, chú trọng khả năng tương thích
Hỗ trợ cả .vocab và .model

`coreml.new_regex_tokenizer(opts)`

Tương đương với coreml.new_text_tokenizer({ type = "regex", ... })
Phù hợp để tách token theo quy tắc và tra cứu từ vựng đơn giản

`coreml.new_byte_tokenizer(opts)`

Tương đương với coreml.new_text_tokenizer({ type = "byte", ... })
Trước tiên chuyển văn bản thành các byte UTF-8, sau đó tra cứu token theo giá trị byte

`coreml.new_whitespace_tokenizer(opts)`

Tương đương với coreml.new_text_tokenizer({ type = "whitespace", ... })
Phù hợp để tách token theo khoảng trắng với thao tác tra cứu trực tiếp trong từ vựng

`coreml.new_character_tokenizer(opts)`

Tương đương với coreml.new_text_tokenizer({ type = "character", ... })
Phù hợp với các mô hình ở cấp ký tự

Kiểm tra kiểu

`coreml.is_text_tokenizer(value)`

is_tokenizer = coreml.is_text_tokenizer(value)

Kiểm tra một giá trị có phải là coreml_text_tokenizer_object hay không.

Phương thức đối tượng

`:encode(text[, opts])`

result, err = tokenizer:encode(text)

hoặc

result, err = tokenizer:encode(text, {
    output = "table" or "MLMultiArray" or "ort_tensor",
    data_type = data_type,
    pair_text = paired_text,
    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,
})

Mã hóa một chuỗi văn bản thành dãy token.

`:encode_batch(texts[, opts])`

result, err = tokenizer:encode_batch(texts)

hoặc

result, err = tokenizer:encode_batch(texts, {
    output = "table" or "MLMultiArray" or "ort_tensor",
    data_type = data_type,
    pair_text = paired_text_or_array,
    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,
})

Mã hóa nhiều văn bản cùng lúc và trả về các dãy token theo dạng lô.

`:decode(ids)`

text, err = tokenizer:decode(ids)

Giải mã ngược một dãy ID token thành văn bản.

ids có thể là mảng Lua, MLMultiArray hoặc userdata dạng tensor như tensor ORT
ids cũng có thể là bất kỳ userdata dạng tensor nào triển khai cả shape() và to_table()
Truyền dữ liệu theo lô sẽ gây lỗi; hãy dùng decode_batch() trong trường hợp đó

`:decode_batch(batch_ids)`

texts, err = tokenizer:decode_batch(batch_ids)

Giải mã ngược một lô dãy ID token thành mảng chuỗi Lua.

batch_ids có thể là mảng Lua lồng nhau, MLMultiArray hoặc userdata dạng tensor như tensor ORT
batch_ids cũng có thể là bất kỳ userdata dạng tensor nào triển khai cả shape() và to_table()

`:vocab_size()`

size = tokenizer:vocab_size()

Trả về kích thước từ vựng khả dụng.

`:context_length()`

length = tokenizer:context_length()

Trả về độ dài đầu ra cố định của bộ tách token.

Lưu ý về mã hóa và giá trị trả về

output mặc định là "MLMultiArray", thuận tiện khi kết quả được đưa thẳng vào mô hình CoreML
output = "table" hữu ích khi gỡ lỗi, xem ID token hoặc hỗ trợ các tập lệnh cũ
output = "ort_tensor" hữu ích khi cần đưa kết quả trực tiếp vào mô hình văn bản ONNX Runtime
output = "ort_tensor" yêu cầu gọi require("onnxruntime") trước, vì cầu nối ORT được thêm vào tại thời điểm đó
output = "ort_tensor" phụ thuộc vào ONNX Runtime nên yêu cầu iOS 13 trở lên
Để tương thích với tập lệnh cũ, trường cũ multi_array_output vẫn được đọc; mã mới nên ưu tiên output

Quy tắc `data_type`

Với output = "MLMultiArray", data_type có thể là "int32", "float32", "float16" hoặc "double"; "float64" được chấp nhận làm bí danh của "double"
Với output = "MLMultiArray", data_type mặc định là "int32"
Với output = "ort_tensor", data_type có thể là "float16", "float32", "uint8", "int8", "int32", "int64", "double" hoặc "bool"
Với output = "ort_tensor", data_type mặc định là "int64"

`padding` / `truncation`

padding có thể là boolean hoặc chuỗi
- true ánh xạ thành "max_length"
- false ánh xạ thành "do_not_pad"
truncation có thể là boolean hoặc chuỗi
- true ánh xạ thành "longest_first"
- false ánh xạ thành "do_not_truncate"

`pair_text`

encode() chấp nhận một pair_text
encode_batch() chấp nhận một pair_text dùng chung hoặc một mảng văn bản ghép cặp có kích thước khớp với lô

Giá trị trả về có cấu trúc

Khi bất kỳ tùy chọn nào sau đây là true, encode() / encode_batch() trả về bảng kết quả có cấu trúc thay vì một dãy token đơn thuần:

return_attention_mask
return_token_type_ids
return_special_tokens_mask

Các trường thường gặp trong kết quả có cấu trúc:

input_ids
length
attention_mask
token_type_ids
special_tokens_mask

Với mã hóa theo lô:

Với output = "table", mỗi mẫu giữ nguyên độ dài tự nhiên
Với output = "MLMultiArray" hoặc "ort_tensor", lô được đệm thành dạng chữ nhật trước khi trả về

Ví dụ

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("các vì sao", {
    output = "MLMultiArray",
    data_type = "int32",
}))

local structured = assert(tokenizer:encode("các vì sao", {
    output = "table",
    return_attention_mask = true,
    return_token_type_ids = true,
}))

local ort = require("onnxruntime")

local input_ids = assert(tokenizer:encode("các vì sao", {
    output = "ort_tensor",
    data_type = "int64",
}))

local batch = assert(tokenizer:encode_batch({
    "các vì sao",
    "mặt trăng",
}, {
    output = "ort_tensor",
}))

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

Tạo bộ tách token​

coreml.new_text_tokenizer(opts)​

Giá trị của type​

Tham số chung​

Giá trị trả về​

Lưu ý​

Hàm tạo rút gọn​

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

Kiểm tra kiểu​

coreml.is_text_tokenizer(value)​

Phương thức đối tượng​

:encode(text[, opts])​

:encode_batch(texts[, opts])​

:decode(ids)​

:decode_batch(batch_ids)​

:vocab_size()​

:context_length()​

Lưu ý về mã hóa và giá trị trả về​

Quy tắc data_type​

padding / truncation​

pair_text​

Giá trị trả về có cấu trúc​

Ví dụ​