Transformers documentation

Tokenizadores

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Tokenizadores

Un tokenizer convierte el texto en tensores, que son las entradas de un modelo. Normaliza y divide el texto, aplica el algoritmo de tokenización, añade tokens especiales y decodifica los ids de salida de vuelta a texto.

from transformers import AutoTokenizer

tokenizer = AutoTokenizer.from_pretrained("google/gemma-2-2b")
tokenizer("Sphinx of black quartz, judge my vow.", return_tensors="pt")
{
    'input_ids': tensor([[     2, 235277,  82913,    576,   2656,  30407, 235269,  11490,    970,  29871, 235265]]),
    'attention_mask': tensor([[1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1]])
}

Esta guía cubre la carga, codificación, decodificación, el procesamiento por lotes y los backends de tokenizador disponibles.

Cargar un tokenizador

Carga un tokenizador con la clase AutoTokenizer o con una clase de tokenizador específica del modelo.

AutoTokenizer
tokenizador específico del modelo

AutoTokenizer.from_pretrained() lee la configuración del modelo, resuelve la clase de tokenizador correcta y devuelve una instancia de la misma. No es necesario conocer la clase del tokenizador de antemano. La mayoría de los tokenizadores se resuelven a una subclase de TokenizersBackend, un tokenizador rápido basado en Rust de la biblioteca Tokenizers.

Cargar con AutoTokenizer es el enfoque recomendado.

from transformers import AutoTokenizer

tokenizer = AutoTokenizer.from_pretrained("google/gemma-2-2b")

Codificar y decodificar

El método TokenizersBackend.call() codifica texto o un lote de texto en input_ids, attention_mask y otras entradas del modelo. También controla el relleno, la truncación y la inserción de tokens especiales.

from transformers import AutoTokenizer

tokenizer = AutoTokenizer.from_pretrained("google/gemma-2-2b")
tokenizer("Sphinx of black quartz, judge my vow.", return_tensors="pt")
{
    'input_ids': tensor([[     2, 235277,  82913,    576,   2656,  30407, 235269,  11490,    970,  29871, 235265]]),
    'attention_mask': tensor([[1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1]])
}

TokenizersBackend.encode() es similar, pero solo devuelve input_ids.

from transformers import AutoTokenizer

tokenizer = AutoTokenizer.from_pretrained("google/gemma-2-2b")
input_ids = tokenizer.encode("Sphinx of black quartz, judge my vow.")
[2, 235277, 82913, 576, 2656, 30407, 235269, 11490, 970, 29871, 235265]

TokenizersBackend.decode() convierte una secuencia única o un lote de input_ids tokenizados de vuelta a texto.

tokenizer.decode(input_ids)
'<bos>Sphinx of black quartz, judge my vow.'

TokenizersBackend.decode() preserva el espaciado exacto de la tokenización. Establezca clean_up_tokenization_spaces para eliminar los espacios antes de la puntuación y skip_special_tokens para quitar los tokens especiales de la salida.

tokenizer.decode(input_ids, skip_special_tokens=True)
'Sphinx of black quartz, judge my vow.'

Tokens especiales

Los tokens especiales marcan límites estructurales en una secuencia, como la posición de inicio de secuencia o las posiciones de relleno. Cada modelo define su propio conjunto de tokens especiales. El tokenizador los agrega cuando lo invocas.

input_ids = tokenizer.encode("Sphinx of black quartz, judge my vow.")
[2, 235277, 82913, 576, 2656, 30407, 235269, 11490, 970, 29871, 235265]
tokenizer.decode(input_ids)
'<bos>Sphinx of black quartz, judge my vow.'

Registre tokens especiales adicionales con nombre mediante el argumento extra_special_tokens. Los modelos multimodales los utilizan como marcadores de posición para imágenes, video o audio.

from transformers import AutoTokenizer

tokenizer = AutoTokenizer.from_pretrained(
    "google/gemma-3-4b-pt",
    extra_special_tokens={"image_token": "<image>"}
)

Procesamiento por lotes

El procesamiento por lotes tokeniza múltiples secuencias en una sola llamada. TokenizersBackend procesa lotes grandes más rápido porque su backend basado en Rust paraleliza el trabajo entre hilos.

from transformers import AutoTokenizer

tokenizer = AutoTokenizer.from_pretrained("google/gemma-2-2b")
tokenizer(
    [
        "Sphinx of black quartz, judge my vow.",
        "Pack my box with five dozen liquor jugs.",
        "How vexingly quick daft zebras jump!"
    ],
    return_tensors="pt"
)

El procesamiento por lotes requiere que todas las secuencias compartan la misma longitud. El relleno y la truncación son estrategias para manejar secuencias de longitud variable.

Relleno

El padding añade tokens especiales para que las secuencias más cortas coincidan con la secuencia más larga de un lote. La máscara de atención marca las posiciones de padding como 0 para que el modelo las ignore. Establece padding=True para rellenar hasta la secuencia más larga o pasa max_length para rellenar hasta un tamaño fijo.

from transformers import AutoTokenizer

tokenizer = AutoTokenizer.from_pretrained("google/gemma-2-2b")
tokenizer(
    [
        "Sphinx of black quartz, judge my vow.",
        "Pack my box with five dozen liquor jugs.",
        "How vexingly quick daft zebras jump!"
    ],
    return_tensors="pt",
    padding=True,
)
{
    'input_ids': tensor([
        [     2, 235277,  82913,    576,   2656,  30407, 235269,  11490,    970,  29871, 235265],
        [     0,      2,   6519,    970,   3741,    675,   4105,  25955,  42184, 225789, 235265],
        [     0,      2,   2299,  73378,  17844,   4320, 224463,   4949,  48977,  9902, 235341]
    ]),
    'attention_mask': tensor([
        [1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1],
        [0, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1],
        [0, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1]
    ])
}

Los modelos de lenguaje de gran tamaño rellenan en el lado izquierdo para evitar interrumpir la generación, que predice el siguiente token desde el lado derecho.

Truncamiento

La truncación recorta los tokens para que una secuencia quepa dentro de una longitud máxima. Establezca truncation=True y especifique max_length para activarla.

El relleno y la truncación funcionan de manera conjunta. Las secuencias cortas reciben tokens de relleno, mientras que las secuencias largas pierden tokens finales. Juntas, producen un tensor rectangular compacto.

from transformers import AutoTokenizer

tokenizer = AutoTokenizer.from_pretrained("google/gemma-2-2b")
tokenizer(
    [
        "Sphinx of black quartz, judge my vow.",
        "Pack my box with five dozen liquor jugs.",
        "How vexingly quick daft zebras jump!"
    ],
    return_tensors="pt",
    padding=True,
    truncation=True,
    max_length=5
)
{
    'input_ids': tensor([
        [     2, 235277,  82913,    576,   2656],
        [     2,   6519,    970,   3741,    675],
        [     2,   2299,  73378,  17844,   4320]
    ]),
    'attention_mask': tensor([
        [1, 1, 1, 1, 1],
        [1, 1, 1, 1, 1],
        [1, 1, 1, 1, 1]
    ])
}

Backends

Cada tokenizador de modelo se define en un único archivo y admite cuatro backends de tokenización.

backendimplementationdescripción
TokenizersBackendTokenizerspredeterminado para la mayoría de los modelos
SentencePieceBackendSentencePiecemodelos que requieren SentencePiece
PythonBackendPythonmodelos que requieren tokenizadores personalizados especializados
MistralCommonBackendmistral-commonModelos Mistral y Pixtral

Todos los backends heredan de PreTrainedTokenizerBase y comparten las mismas APIs para codificación, decodificación, relleno, truncamiento, guardado y carga. La diferencia radica en qué pipeline de tokenización se ejecuta en segundo plano.

AutoTokenizer selecciona el mejor backend disponible cuando se llama a from_pretrained().

  1. Lee el archivo tokenizer_config.json para el campo tokenizer_class.
  2. El registro asocia tokenizer_class con un nombre de clase. La clase resuelta hereda de uno de los cuatro backends. Por ejemplo, GemmaTokenizer hereda de TokenizersBackend, y SiglipTokenizer hereda de SentencePieceBackend. Algunos modelos, como GLM, se mapean directamente a TokenizersBackend porque el archivo tokenizer.json describe por completo el pipeline. GemmaTokenizer existe como subclase porque define configuraciones adicionales específicas del modelo en Python que tokenizer.json no captura. Cuando un backend como mistral-common no está instalado, AutoTokenizer recurre a TokenizersBackend.

Uso de TokenizersBackend como alternativa

Algunos modelos no tienen una clase de tokenizador dedicada y algunos puntos de control tienen un tokenizer_class que no coincide con su archivo tokenizer.json real. AutoTokenizer maneja ambos casos cargando el pipeline desde tokenizer.json a través del TokenizersBackend genérico. Prioriza el tokenizador serializado sobre el nombre de la clase del Hub, lo que corrige problemas como cuando un tokenizer_class no coincidente produce ids de tokens incorrectos.

Un checkpoint se resuelve en un TokenizersBackend genérico por una de tres razones.

MotivoComportamientoEjemplos
Clase de tokenizador no dedicadaEl tipo de modelo se corresponde directamente con TokenizersBackend porque tokenizer.json describe por completo el pipeline.GLM, Granite, OLMo 2, GPT BigCode
Clase de tokenizador del Hub incorrectaEl tokenizer_class registrado en el Hub es incorrecto para el tipo de modelo, por lo que AutoTokenizer lo ignora y carga tokenizer.json en su lugar.DeepSeek V3, LLaVA, Qwen2, ModernBERT
Sobrescritura de un punto de control específicoUn checkpoint cuya configuración de Hub aún necesita una corrección se coincide con su id de modelo y se fuerza a usar el backend.deepseek-ai/DeepSeek-R1-Distill-*, Salesforce/blip2-*, google/umt5-small

Los tipos de modelos y puntos de control afectados aumentan a medida que se corrigen las configuraciones en el Hub. Para el conjunto actual, consulte las definiciones de MODELS_WITH_INCORRECT_HUB_TOKENIZER_CLASS y MODEL_IDS_TO_TOKENIZERS_BACKEND en tokenization_auto.py.

El mecanismo de respaldo es automático y no cambia cómo se llama a from_pretrained(). El tokenizador resultante codifica y decodifica exactamente como especifica tokenizer.json.

Comprueba qué backend está utilizando un tokenizador con la propiedad backend.

from transformers import AutoTokenizer

tokenizer = AutoTokenizer.from_pretrained("google/gemma-2-2b")
tokenizer.backend
'tokenizers'

Inspeccionar la arquitectura del tokenizador

Inspecciona los componentes internos de un tokenizador (normalizador, pretokenizador, modelo, decodificador) con el atributo _tokenizer.

from transformers import AutoTokenizer

tokenizer = AutoTokenizer.from_pretrained("google/gemma-2-2b")
print(tokenizer._tokenizer.normalizer)
print(tokenizer._tokenizer.pre_tokenizer)
print(tokenizer._tokenizer.model)
print(tokenizer._tokenizer.decoder)

Recursos

Update on GitHub