Transformers documentation
Tokenizadores
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.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")Una clase de tokenización específica de un modelo es un TokenizersBackend preconfigurado que utiliza la configuración exacta de tokenización (normalizador, pretokenizador, convenciones de tokens especiales, etc.) con la que se entrenó el modelo.
Use una clase específica del modelo para inicializar un tokenizador vacío para el entrenamiento o para pasar argumentos específicos del modelo como vocab o merges (consulte la guía Personalización de tokenizadores para aprender cómo hacerlo). Un tokenizador vacío es mínimo y solo contiene los tokens especiales de un modelo, como <pad>, <eos> o <bos>.
from transformers import GemmaTokenizer
tokenizer = GemmaTokenizer()
corpus = [
["Sphinx of black quartz, judge my vow."],
["Pack my box with five dozen liquor jugs."],
["How vexingly quick daft zebras jump!"],
]
new_tokenizer = tokenizer.train_new_from_iterator(corpus, vocab_size=1000)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.
| backend | implementation | descripción |
|---|---|---|
| TokenizersBackend | Tokenizers | predeterminado para la mayoría de los modelos |
| SentencePieceBackend | SentencePiece | modelos que requieren SentencePiece |
| PythonBackend | Python | modelos que requieren tokenizadores personalizados especializados |
| MistralCommonBackend | mistral-common | Modelos 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().
- Lee el archivo
tokenizer_config.jsonpara el campotokenizer_class. - El registro asocia
tokenizer_classcon 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 archivotokenizer.jsondescribe por completo el pipeline. GemmaTokenizer existe como subclase porque define configuraciones adicionales específicas del modelo en Python quetokenizer.jsonno 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.
| Motivo | Comportamiento | Ejemplos |
|---|---|---|
| Clase de tokenizador no dedicada | El 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 incorrecta | El 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ífico | Un 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
- La publicación Tokenization in Transformers v5 aborda la motivación detrás de los nuevos backends de tokenización.
- Consulte la guía de migración para obtener un resumen de los cambios en la tokenización.