# 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.

```py
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](/docs/transformers/v5.23.0/es/model_doc/auto#transformers.AutoTokenizer) o con una clase de tokenizador específica del modelo.

[AutoTokenizer.from_pretrained()](/docs/transformers/v5.23.0/es/model_doc/auto#transformers.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](/docs/transformers/v5.23.0/es/main_classes/tokenizer#transformers.TokenizersBackend), un tokenizador rápido basado en Rust de la biblioteca [Tokenizers](https://huggingface.co/docs/tokenizers/index).

Cargar con [AutoTokenizer](/docs/transformers/v5.23.0/es/model_doc/auto#transformers.AutoTokenizer) es el enfoque recomendado.

```py
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](/docs/transformers/v5.23.0/es/main_classes/tokenizer#transformers.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](./custom_tokenizers) 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>`.

```py
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__()](/docs/transformers/v5.23.0/es/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__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.

```py
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()](/docs/transformers/v5.23.0/es/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) es similar, pero solo devuelve `input_ids`.

```py
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()](/docs/transformers/v5.23.0/es/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.decode) convierte una secuencia única o un lote de `input_ids` tokenizados de vuelta a texto.

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

[TokenizersBackend.decode()](/docs/transformers/v5.23.0/es/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.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.

```py
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.

```py
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.

```py
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](/docs/transformers/v5.23.0/es/main_classes/tokenizer#transformers.TokenizersBackend) procesa lotes grandes más rápido porque su backend basado en Rust paraleliza el trabajo entre hilos.

```py
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.

```py
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]
    ])
}
```

> [!NOTE]
> 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.

```py
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](/docs/transformers/v5.23.0/es/main_classes/tokenizer#transformers.TokenizersBackend)    | [Tokenizers](https://huggingface.co/docs/tokenizers)          | predeterminado para la mayoría de los modelos                        |
| [SentencePieceBackend](/docs/transformers/v5.23.0/es/main_classes/tokenizer#transformers.SentencePieceBackend) | [SentencePiece](https://github.com/google/sentencepiece)      | modelos que requieren SentencePiece                 |
| [PythonBackend](/docs/transformers/v5.23.0/es/main_classes/tokenizer#transformers.PythonBackend)        | Python                                                        | modelos que requieren tokenizadores personalizados especializados |
| [MistralCommonBackend](/docs/transformers/v5.23.0/es/model_doc/mistral#transformers.MistralCommonBackend) | [mistral-common](https://mistralai.github.io/mistral-common/) | Modelos Mistral y Pixtral                     |

Todos los backends heredan de [PreTrainedTokenizerBase](/docs/transformers/v5.23.0/es/internal/tokenization_utils#transformers.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](/docs/transformers/v5.23.0/es/model_doc/auto#transformers.AutoTokenizer) selecciona el mejor backend disponible cuando se llama a [from_pretrained()](/docs/transformers/v5.23.0/es/model_doc/auto#transformers.AutoTokenizer.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](/docs/transformers/v5.23.0/es/model_doc/gemma#transformers.GemmaTokenizer) hereda de [TokenizersBackend](/docs/transformers/v5.23.0/es/main_classes/tokenizer#transformers.TokenizersBackend), y [SiglipTokenizer](/docs/transformers/v5.23.0/es/model_doc/siglip#transformers.SiglipTokenizer) hereda de [SentencePieceBackend](/docs/transformers/v5.23.0/es/main_classes/tokenizer#transformers.SentencePieceBackend). Algunos modelos, como GLM, se mapean directamente a [TokenizersBackend](/docs/transformers/v5.23.0/es/main_classes/tokenizer#transformers.TokenizersBackend) porque el archivo `tokenizer.json` describe por completo el pipeline. [GemmaTokenizer](/docs/transformers/v5.23.0/es/model_doc/gemma#transformers.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](/docs/transformers/v5.23.0/es/model_doc/auto#transformers.AutoTokenizer) recurre a [TokenizersBackend](/docs/transformers/v5.23.0/es/main_classes/tokenizer#transformers.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](/docs/transformers/v5.23.0/es/model_doc/auto#transformers.AutoTokenizer) maneja ambos casos cargando el pipeline desde `tokenizer.json` a través del [TokenizersBackend](/docs/transformers/v5.23.0/es/main_classes/tokenizer#transformers.TokenizersBackend) genérico. Prioriza el tokenizador serializado sobre el nombre de 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](https://github.com/huggingface/transformers/blob/main/src/transformers/models/auto/tokenization_auto.py).

El mecanismo de respaldo es automático y no modifica la forma en que se llama a [from_pretrained()](/docs/transformers/v5.23.0/es/model_doc/auto#transformers.AutoTokenizer.from_pretrained). El tokenizador resultante codifica y decodifica exactamente como especifica `tokenizer.json`.

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

```py
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`.

```py
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](https://huggingface.co/blog/tokenizers) aborda la motivación detrás de los nuevos backends de tokenización.
- Consulte la [guía de migración](https://github.com/huggingface/transformers/blob/main/MIGRATION_GUIDE_V5.md#tokenization) para obtener un resumen de los cambios en la tokenización.

