Saltar al contenido principal

Módulo de tokenización de texto

El módulo de tokenización de texto convierte cadenas en secuencias de ID de tokens que pueden usar los modelos. Esta capa solo realiza tokenización, codificación y decodificación inversa; no ejecuta inferencias de modelos. El flujo habitual consiste en codificar primero el texto como MLMultiArray o onnxruntime.tensor y después pasar el resultado al ejecutor CoreML u ONNX Runtime correspondiente.

El objetivo de este módulo es ofrecer lo necesario para la inferencia en el dispositivo:

  • WordPiece ofrece la mayor compatibilidad y es adecuado para modelos como BERT y CN-CLIP
  • BPE y SentencePiece usan estrategias ligeras compatibles, adecuadas para la mayoría de los escenarios de codificación en el dispositivo
  • El tiempo de ejecución no incorpora el entrenamiento complejo de tokenizadores, el muestreo ni todo el comportamiento del ecosistema original

Disponible en versiones posteriores a 20260319

Crear un tokenizador​

coreml.new_text_tokenizer(opts)​

tokenizador, información_del_error = coreml.new_text_tokenizer({
    type = tipo,
    vocab_path = ruta_de_vocabulario,
    merges_path = ruta_de_merges,
    model_path = ruta_del_modelo_SentencePiece,
    pattern = expresión_regular,
    context_length = longitud_de_contexto,
    do_lower_case = convertir_a_minúsculas,
    vocab_limit = límite_del_vocabulario,
    clean_text = limpiar_el_texto,
    add_bos = añadir_token_inicial,
    add_eos = añadir_token_final,
    bos_token = texto_del_token_inicial,
    eos_token = texto_del_token_final,
    pad_token = texto_del_token_de_relleno,
    unk_token = texto_del_token_desconocido,
})

Valores de type​

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

El valor predeterminado es wordpiece.

Si el primer argumento de coreml.new_text_tokenizer(...) no es una tabla, se usa la construcción rápida de wordpiece, equivalente a coreml.new_wordpiece_tokenizer(vocab_path).

Parámetros habituales​

  • vocab_path: ruta del archivo de vocabulario.
  • merges_path: ruta del archivo merges para tokenizadores BPE.
  • model_path: ruta del archivo .model compatible con SentencePiece.
  • pattern: expresión regular del tokenizador Regex.
  • context_length: longitud de salida de tokens.
  • do_lower_case: booleano opcional; indica si se debe convertir primero a minúsculas.
  • clean_text: booleano opcional; indica si se debe realizar primero una limpieza básica del texto antes de tokenizarlo.
  • vocab_limit: límite opcional del vocabulario WordPiece.
  • add_bos / add_eos: booleanos opcionales; añaden tokens especiales inicial y final.
  • bos_token / eos_token / pad_token / unk_token: textos opcionales de los tokens especiales.

Requisitos y valores predeterminados:

  • wordpiece: admite una ruta de vocabulario directa o una tabla; exige vocab_path; context_length=52, do_lower_case=true, vocab_limit=21128 y los tokens [PAD], [UNK], [CLS], [SEP].
  • bpe: solo tabla; exige vocab_path y merges_path; longitud 77, sin minúsculas, limpieza, BOS ni EOS por defecto.
  • sentencepiece: solo tabla; exige vocab_path o model_path; longitud 77, limpieza activada y tokens <s>, </s>, <pad>, <unk>.
  • regex: solo tabla; exige vocab_path y pattern; longitud 77, sin minúsculas y con limpieza.
  • whitespace/character/byte: solo tabla; exige vocab_path; longitud 77, sin minúsculas y con limpieza.

Detalles adicionales de wordpiece: acepta vocab_path como cadena o dentro de una tabla, exige que exista, usa context_length = 52, do_lower_case = true y vocab_limit = 21128 de forma predeterminada, y necesita [PAD], [UNK], [CLS] y [SEP] en el vocabulario.

Detalles adicionales de bpe: solo acepta una tabla de opciones, exige vocab_path y merges_path, y usa context_length = 77, do_lower_case = false, clean_text = false, add_bos = false y add_eos = false de forma predeterminada.

Detalles adicionales de sentencepiece: solo acepta una tabla de opciones, exige vocab_path o model_path, y usa context_length = 77, do_lower_case = false, clean_text = true, bos_token = "<s>", eos_token = "</s>", pad_token = "<pad>" y unk_token = "<unk>" de forma predeterminada.

Detalles adicionales de regex: solo acepta una tabla de opciones, exige vocab_path y pattern, y usa context_length = 77, do_lower_case = false y clean_text = true de forma predeterminada.

Detalles adicionales de whitespace, character y byte: solo aceptan una tabla de opciones, exigen vocab_path y usan context_length = 77, do_lower_case = false y clean_text = true de forma predeterminada.

Sugerencias de selección:

  • Si el modelo usa vocab.txt + WordPiece, elige wordpiece
  • Si el modelo usa vocab.json + merges.txt, elige bpe
  • Si el modelo usa .vocab o .model, elige sentencepiece
  • Considera regex, whitespace, character y byte solo para necesidades de tokenización con reglas sencillas

Valor de retorno​

  • tokenizador de texto: objeto; si falla, devuelve nil.
  • información_del_error: texto; es nil cuando tiene éxito y contiene el error cuando falla.

Descripción​

  • Conviene crear el tokenizador una vez y reutilizarlo; no se recomienda reconstruirlo para cada codificación.
  • La creación fija el algoritmo, el origen del vocabulario y la longitud de salida.
  • Si el resultado del modelo es incorrecto, comprueba el tipo, el vocabulario, los tokens especiales y context_length.
  • WordPiece es la implementación más completa; BPE y SentencePiece priorizan la compatibilidad en el dispositivo.
  • BPE y SentencePiece priorizan la compatibilidad de codificación en el dispositivo y no prometen reproducir todos los detalles de las implementaciones originales.

Constructores rápidos​

Todas las funciones constructoras rápidas son esencialmente reenvíos a coreml.new_text_tokenizer(...); son útiles cuando ya se conoce el tipo de tokenizador que se necesita.

coreml.new_wordpiece_tokenizer(opts)​

  • Es un alias de coreml.new_text_tokenizer({ type = "wordpiece", ... }).
  • Es adecuado para modelos de texto de estilo WordPiece, como BERT y CN-CLIP.
  • También acepta directamente una ruta de vocabulario: coreml.new_wordpiece_tokenizer(vocab_path).

coreml.new_bpe_tokenizer(opts)​

  • Es un alias de coreml.new_text_tokenizer({ type = "bpe", ... }).
  • También cubre modelos gpt2_bpe y clip_bpe del tipo vocab.json + merges.txt.

coreml.new_sentencepiece_tokenizer(opts)​

  • Es un alias de coreml.new_text_tokenizer({ type = "sentencepiece", ... }).
  • Usa una implementación ligera compatible orientada a la inferencia en el dispositivo.
  • Admite .vocab y .model.

coreml.new_regex_tokenizer(opts)​

  • Es un alias de coreml.new_text_tokenizer({ type = "regex", ... }).
  • Es adecuado para tokenización basada en reglas y asignaciones sencillas de vocabulario.

coreml.new_byte_tokenizer(opts)​

  • Es un alias de coreml.new_text_tokenizer({ type = "byte", ... }).
  • Convierte primero el texto en un flujo de bytes UTF-8 y después busca cada byte en el vocabulario.

coreml.new_whitespace_tokenizer(opts)​

  • Es un alias de coreml.new_text_tokenizer({ type = "whitespace", ... }).
  • Es adecuado para modelos de texto ligeros que dividen por espacios y buscan directamente en el vocabulario.

coreml.new_character_tokenizer(opts)​

  • Es un alias de coreml.new_text_tokenizer({ type = "character", ... }).
  • Es adecuado para modelos de texto a nivel de caracteres.

Comprobar el tipo​

coreml.is_text_tokenizer(value)​

es_tokenizador = coreml.is_text_tokenizer(valor_a_comprobar)

Comprueba si un valor es un objeto coreml_text_tokenizer_object.

Métodos del objeto​

:encode(text[, opts])​

resultado_codificado, información_del_error = tokenizador:encode(texto)

o

resultado_codificado, información_del_error = tokenizador:encode(texto, {
    output = "table" o "MLMultiArray" o "ort_tensor",
    data_type = tipo_de_datos,
    pair_text = texto_par,
    max_length = longitud_máxima,
    padding = estrategia_de_relleno,
    truncation = estrategia_de_truncado,
    return_attention_mask = devolver_attention_mask,
    return_token_type_ids = devolver_token_type_ids,
    return_special_tokens_mask = devolver_special_tokens_mask,
})

Codifica un texto en una secuencia de tokens.

:encode_batch(texts[, opts])​

resultados, información_del_error = tokenizador:encode_batch(textos, opciones)

o

resultados, información_del_error = tokenizador:encode_batch(textos, {
    output = "table" o "MLMultiArray" o "ort_tensor",
    data_type = tipo_de_datos,
    pair_text = texto_par_o_matriz_de_textos,
    max_length = longitud_máxima,
    padding = estrategia_de_relleno,
    truncation = estrategia_de_truncado,
    return_attention_mask = devolver_attention_mask,
    return_token_type_ids = devolver_token_type_ids,
    return_special_tokens_mask = devolver_special_tokens_mask,
})

Codifica varios textos y devuelve secuencias por lotes.

:decode(ids)​

texto, información_del_error = tokenizador:decode(ids)

Decodifica una sola secuencia de IDs.

  • ids puede ser una matriz Lua, MLMultiArray u objeto tensorial de ORT.
  • batch_ids también puede ser cualquier userdata que implemente shape() y to_table().
  • Si recibe datos por lotes, devuelve un error y solicita decode_batch().

:decode_batch(batch_ids)​

textos, información_del_error = tokenizador:decode_batch(batch_ids)

Decodifica un lote de secuencias en una matriz de textos.

  • batch_ids puede ser una matriz Lua anidada, MLMultiArray u objeto tensorial de ORT.
  • También puede ser cualquier userdata que implemente shape() y to_table().

:vocab_size()​

tamaño = tokenizador:vocab_size()

Devuelve el tamaño del vocabulario.

:context_length()​

longitud = tokenizador:context_length()

Devuelve la longitud fija de salida a la que se rellena o trunca cada codificación.

Codificación y resultados​

  • output es "MLMultiArray" por defecto y es adecuado para pasarlo directamente a un modelo CoreML.

  • output = "table" devuelve una tabla Lua para inspección o compatibilidad.

  • output = "MLMultiArray" devuelve un tensor nativo para CoreML.

  • output = "ort_tensor" devuelve un tensor para ONNX Runtime.

  • output = "ort_tensor" requiere require("onnxruntime").

  • output = "ort_tensor" solo está disponible en iOS 13+.

  • Para compatibilidad con scripts antiguos, el campo multi_array_output todavía se lee; el código nuevo debería usar output.

  • data_type para MLMultiArray admite "int32", "float32", "float16" y "double"; "float64" es un alias de "double" y el predeterminado es "int32". Para ort_tensor admite "float16", "float32", "uint8", "int8", "int32", "int64", "double" y "bool"; el predeterminado es "int64".

  • Para output = "MLMultiArray", el data_type "int32" es el valor predeterminado (data_type = "int32").

  • Para output = "MLMultiArray", también admite "float16" y "double".

  • Para output = "ort_tensor", data_type = "int64" es el valor predeterminado.

  • Para output = "ort_tensor", también admite "uint8", "int8" y "bool".

Reglas de data_type​

Los valores booleanos literales true y false se pueden usar donde se indique que se acepta un booleano.

padding y truncation aceptan booleanos o cadenas: true equivale respectivamente a "max_length" y "longest_first"; false equivale a "do_not_pad" y "do_not_truncate". pair_text puede ser un texto individual o, en lotes, una matriz del mismo tamaño.

padding / truncation​

padding y truncation aceptan valores booleanos o cadenas.

  • padding = true equivale a "max_length".
  • padding = false equivale a "do_not_pad".
  • truncation = true equivale a "longest_first".
  • truncation = false equivale a "do_not_truncate".

pair_text​

pair_text puede ser un texto individual o, en lotes, una matriz del mismo tamaño.

  • encode() acepta un solo pair_text.
  • encode_batch() acepta un solo pair_text o una matriz de textos del tamaño del lote.

Resultado estructurado​

  • return_attention_mask añade attention_mask al resultado.
  • return_token_type_ids añade token_type_ids al resultado.
  • return_special_tokens_mask añade special_tokens_mask al resultado.

Los resultados estructurados suelen incluir:

  • input_ids

  • length

  • attention_mask

  • token_type_ids

  • special_tokens_mask

  • Si return_attention_mask, return_token_type_ids o return_special_tokens_mask es true, encode()/encode_batch() devuelve una tabla de resultados estructurada, no solo la secuencia de tokens sin formato.

  • En la codificación por lotes, output = "table" conserva la longitud de cada muestra; output = "MLMultiArray"/"ort_tensor" rellena el lote hasta formar una matriz regular.

Ejemplo​

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