Pular para o conteúdo principal

Módulo de tokenizador de texto

O módulo de tokenizador de texto converte strings em sequências de IDs de token utilizáveis pelo modelo.
Esta camada faz apenas tokenização, codificação e decodificação reversa; não realiza inferência do modelo. O fluxo típico é primeiro codificar o texto em MLMultiArray ou onnxruntime.tensor e então passar o resultado codificado ao request CoreML ou ONNX Runtime correspondente.

O objetivo deste módulo é oferecer o suficiente para “inferência no dispositivo”:

  • WordPiece tem a maior compatibilidade e é adequado para modelos como BERT e CN-CLIP.
  • BPE e SentencePiece usam estratégias leves de compatibilidade, adequadas à maioria dos cenários de codificação no dispositivo.
  • O treinamento de tokenizadores complexos, a amostragem e todo o comportamento do ecossistema upstream não são incorporados ao runtime.

Este módulo só está disponível em versões posteriores a 20260319

Criar um tokenizador​

coreml.new_text_tokenizer(opts)​

objeto_tokenizador_de_texto, mensagem_de_erro = coreml.new_text_tokenizer({
    type = tipo_de_tokenizador,
    vocab_path = caminho_do_vocabulário,
    merges_path = caminho_do_arquivo_de_merges,
    model_path = caminho_do_modelo_SentencePiece,
    pattern = expressão_regular,
    context_length = comprimento_de_contexto,
    do_lower_case = converter_para_minúsculas,
    vocab_limit = limite_do_vocabulário,
    clean_text = limpar_o_texto_antes,
    add_bos = adicionar_token_inicial,
    add_eos = adicionar_token_final,
    bos_token = texto_do_token_inicial,
    eos_token = texto_do_token_final,
    pad_token = texto_do_token_de_preenchimento,
    unk_token = texto_do_token_desconhecido,
})

Valores de type​

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

O padrão é wordpiece.

Se o primeiro argumento de coreml.new_text_tokenizer(...) não for uma table, ele será tratado diretamente como uma construção rápida wordpiece, equivalente ao uso de coreml.new_wordpiece_tokenizer(vocab_path).

Parâmetros comuns​

  • vocab_path
    Texto: caminho do arquivo de vocabulário.

  • merges_path
    Texto: caminho do arquivo de merges usado pelos tokenizadores da família BPE.

  • model_path
    Texto: caminho do arquivo .model que pode ser usado pelo modo compatível com SentencePiece.

  • pattern
    Texto: expressão regular usada pelo tokenizador Regex.

  • context_length
    Inteiro opcional que define o comprimento da sequência de tokens de saída.

  • do_lower_case
    Booleano opcional que define se o texto deve ser convertido primeiro para minúsculas.

  • vocab_limit
    Inteiro opcional, usado principalmente por WordPiece para limitar o tamanho do vocabulário.

  • clean_text
    Booleano opcional que define se uma limpeza básica do texto deve ser feita antes da tokenização.

  • add_bos / add_eos
    Booleanos opcionais que definem se tokens inicial / final serão anexados antes / depois do resultado codificado.

  • bos_token / eos_token / pad_token / unk_token
    Texto opcional correspondente ao texto desses tokens especiais no vocabulário.

Nem todo tipo de tokenizador aceita todos os campos acima. Os campos obrigatórios e valores padrão da implementação atual são:

  • wordpiece
    Aceita receber diretamente uma string vocab_path ou uma table; exige que vocab_path exista; o padrão é context_length = 52, do_lower_case = true, vocab_limit = 21128, e o vocabulário deve conter [PAD], [UNK], [CLS] e [SEP].
  • bpe
    Aceita somente table; exige vocab_path e merges_path; o padrão é context_length = 77, do_lower_case = false, clean_text = false, add_bos = false e add_eos = false.
  • sentencepiece
    Aceita somente table; exige pelo menos um entre vocab_path e model_path; o padrão é context_length = 77, do_lower_case = false, clean_text = true, bos_token = "<s>", eos_token = "</s>", pad_token = "<pad>" e unk_token = "<unk>".
  • regex
    Aceita somente table; exige vocab_path e pattern; o padrão é context_length = 77, do_lower_case = false e clean_text = true.
  • whitespace / character / byte
    Aceita somente table; exige vocab_path; o padrão é context_length = 77, do_lower_case = false e clean_text = true.

Recomendações de escolha:

  • Se o modelo usa vocab.txt + WordPiece, escolha wordpiece.
  • Se o modelo usa vocab.json + merges.txt, escolha bpe.
  • Se o modelo usa .vocab ou .model, escolha sentencepiece.
  • Considere regex, whitespace, character ou byte somente quando precisar de uma tokenização baseada em regras simples.

Valores retornados​

  • objeto tokenizador de texto
    Tipo objeto; retorna nil se a criação falhar.

  • mensagem de erro
    Tipo texto; é nil em caso de sucesso e contém a mensagem de erro em caso de falha.

Observações​

  • É adequado criar o objeto tokenizador uma vez e reutilizá-lo; não é recomendável reconstruí-lo a cada codificação.
  • A criação determina principalmente três coisas: algoritmo de tokenização, origem do vocabulário e comprimento fixo da saída.
  • Se o resultado do modelo estiver claramente incorreto, verifique primeiro o tipo do tokenizador, o arquivo de vocabulário, a configuração de tokens especiais e se context_length coincide com o usado no treinamento.
  • WordPiece é atualmente a opção mais completa e estável.
  • BPE e SentencePiece têm como objetivo a compatibilidade da codificação no dispositivo e não prometem reproduzir todos os detalhes de cada implementação upstream.

Construtores rápidos​

As funções rápidas abaixo são essencialmente encaminhamentos para coreml.new_text_tokenizer(...); use-as quando o tipo do tokenizador já estiver definido.

coreml.new_wordpiece_tokenizer(opts)​

  • Equivale a coreml.new_text_tokenizer({ type = "wordpiece", ... }).
  • É adequado para modelos de texto no estilo WordPiece, como BERT e CN-CLIP.
  • Também aceita diretamente uma string de caminho do vocabulário: coreml.new_wordpiece_tokenizer(vocab_path).

coreml.new_bpe_tokenizer(opts)​

  • Equivale a coreml.new_text_tokenizer({ type = "bpe", ... }).
  • Também abrange modelos gpt2_bpe e clip_bpe do tipo vocab.json + merges.txt.

coreml.new_sentencepiece_tokenizer(opts)​

  • Equivale a coreml.new_text_tokenizer({ type = "sentencepiece", ... }).
  • Usa uma implementação leve e compatível voltada à inferência no dispositivo.
  • Aceita .vocab e .model.

coreml.new_regex_tokenizer(opts)​

  • Equivale a coreml.new_text_tokenizer({ type = "regex", ... }).
  • É adequado a cenários de tokenização baseada em regras e mapeamento simples de vocabulário.

coreml.new_byte_tokenizer(opts)​

  • Equivale a coreml.new_text_tokenizer({ type = "byte", ... }).
  • Primeiro converte o texto em um fluxo de bytes UTF-8 e depois consulta o vocabulário por byte.

coreml.new_whitespace_tokenizer(opts)​

  • Equivale a coreml.new_text_tokenizer({ type = "whitespace", ... }).
  • É adequado para modelos de texto leves que tokenizam por espaço e consultam diretamente o vocabulário.

coreml.new_character_tokenizer(opts)​

  • Equivale a coreml.new_text_tokenizer({ type = "character", ... }).
  • É adequado para modelos de texto em nível de caractere.

Verificação de tipo​

coreml.is_text_tokenizer(value)​

é_tokenizador_de_texto = coreml.is_text_tokenizer(valor_a_verificar)

Verifica se um valor é um coreml_text_tokenizer_object.

Métodos do objeto​

:encode(text[, opts])​

resultado_codificado, mensagem_de_erro = objeto_tokenizador_de_texto:encode(texto)

ou

resultado_codificado, mensagem_de_erro = objeto_tokenizador_de_texto:encode(texto, {
    output = "table" ou "MLMultiArray" ou "ort_tensor",
    data_type = tipo_de_dado,
    pair_text = texto_em_par,
    max_length = comprimento_máximo,
    padding = estratégia_de_preenchimento,
    truncation = estratégia_de_truncamento,
    return_attention_mask = retornar_attention_mask,
    return_token_type_ids = retornar_token_type_ids,
    return_special_tokens_mask = retornar_special_tokens_mask,
})

Codifica um único texto em uma sequência de tokens.

:encode_batch(texts[, opts])​

resultado_codificado, mensagem_de_erro = objeto_tokenizador_de_texto:encode_batch(array_de_textos)

ou

resultado_codificado, mensagem_de_erro = objeto_tokenizador_de_texto:encode_batch(array_de_textos, {
    output = "table" ou "MLMultiArray" ou "ort_tensor",
    data_type = tipo_de_dado,
    pair_text = texto_em_par_ou_array_de_textos_em_par,
    max_length = comprimento_máximo,
    padding = estratégia_de_preenchimento,
    truncation = estratégia_de_truncamento,
    return_attention_mask = retornar_attention_mask,
    return_token_type_ids = retornar_token_type_ids,
    return_special_tokens_mask = retornar_special_tokens_mask,
})

Codifica vários textos de uma vez e retorna sequências de tokens em formato batch.

:decode(ids)​

texto, mensagem_de_erro = objeto_tokenizador_de_texto:decode(ids)

Decodifica reversamente uma sequência de IDs de token individual em texto.

  • ids pode ser um array Lua, MLMultiArray ou userdata semelhante a tensor, como um tensor ORT.
  • ids também pode ser qualquer userdata semelhante a tensor que implemente shape() e to_table().
  • Se os dados passados forem um batch, ocorrerá um erro solicitando o uso de decode_batch().

:decode_batch(batch_ids)​

array_de_textos, mensagem_de_erro = objeto_tokenizador_de_texto:decode_batch(batch_ids)

Decodifica reversamente sequências batch de IDs de token em um array de textos.

  • batch_ids pode ser um array Lua aninhado, MLMultiArray ou userdata semelhante a tensor, como um tensor ORT.
  • batch_ids também pode ser qualquer userdata semelhante a tensor que implemente shape() e to_table().

:vocab_size()​

tamanho_do_vocabulário = objeto_tokenizador_de_texto:vocab_size()

Retorna o tamanho do vocabulário disponível no tokenizador atual.

:context_length()​

comprimento_de_contexto = objeto_tokenizador_de_texto:context_length()

Retorna o comprimento fixo de saída do tokenizador atual, isto é, o comprimento ao qual cada codificação será preenchida ou truncada.

Observações sobre codificação e retorno​

  • O padrão de output é "MLMultiArray", adequado para ser passado diretamente a um modelo CoreML.
  • output = "table" é adequado para depuração, visualização de IDs de token ou compatibilidade com scripts antigos.
  • output = "ort_tensor" é adequado para ser passado diretamente a um modelo de texto ONNX Runtime.
  • Antes de output = "ort_tensor", é necessário executar require("onnxruntime") para que a interface de ponte ORT seja injetada.
  • output = "ort_tensor" depende do ONNX Runtime e, portanto, só é compatível com iOS 13+.
  • Para compatibilidade com scripts antigos, o campo multi_array_output continua sendo lido; em código novo, use output de maneira uniforme.

Regras de data_type​

  • Com output = "MLMultiArray", data_type aceita "int32", "float32", "float16" e "double"; "float64" pode ser usado como alias de "double".
  • Com output = "MLMultiArray", o padrão é data_type = "int32".
  • Com output = "ort_tensor", data_type aceita "float16", "float32", "uint8", "int8", "int32", "int64", "double" e "bool".
  • Com output = "ort_tensor", o padrão é data_type = "int64".

padding / truncation​

  • padding pode ser booleano ou string.
    • true é mapeado para "max_length".
    • false é mapeado para "do_not_pad".
  • truncation pode ser booleano ou string.
    • true é mapeado para "longest_first".
    • false é mapeado para "do_not_truncate".

pair_text​

  • encode() aceita um único pair_text.
  • encode_batch() aceita um único pair_text ou um array de strings com o mesmo tamanho do batch.

Retorno estruturado​

Quando qualquer um dos campos abaixo for true, encode() / encode_batch() retornará uma tabela estruturada, e não apenas uma sequência de tokens bruta:

  • return_attention_mask
  • return_token_type_ids
  • return_special_tokens_mask

Campos comuns do resultado estruturado:

  • input_ids
  • length
  • attention_mask
  • token_type_ids
  • special_tokens_mask

Para codificação em batch:

  • Com output = "table", o comprimento próprio de cada amostra é preservado.
  • Com output = "MLMultiArray" / "ort_tensor", o batch é preenchido até formar uma matriz regular antes de ser retornado.

Exemplo​

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