# Tokenizadores

Um tokenizer converte texto em tensores, que são as entradas de um modelo. Ele normaliza e divide o texto, aplica o algoritmo de tokenização, adiciona tokens especiais e decodifica os ids de saída de volta para 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]])
}
```

Este guia aborda o carregamento, a codificação, a decodificação, o processamento em lote e os backends de tokenizer disponíveis.

## Carregar um tokenizer

Carregue um tokenizer com a classe [AutoTokenizer](/docs/transformers/main/pt/model_doc/auto#transformers.AutoTokenizer) ou com uma classe de tokenizer específica do modelo.

[AutoTokenizer.from_pretrained()](/docs/transformers/main/pt/model_doc/auto#transformers.AutoTokenizer.from_pretrained) lê a configuração do modelo, resolve a classe de tokenizer correta e retorna uma instância dela. Você não precisa conhecer a classe do tokenizer antecipadamente. A maioria dos tokenizers é resolvida para uma subclasse de [TokenizersBackend](/docs/transformers/main/pt/main_classes/tokenizer#transformers.TokenizersBackend), um tokenizer rápido baseado em Rust da biblioteca [Tokenizers](https://huggingface.co/docs/tokenizers/index).

Carregar com [AutoTokenizer](/docs/transformers/main/pt/model_doc/auto#transformers.AutoTokenizer) é a abordagem recomendada.

```py
from transformers import AutoTokenizer

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

Uma classe de tokenização específica de modelo é um [TokenizersBackend](/docs/transformers/main/pt/main_classes/tokenizer#transformers.TokenizersBackend) pré-configurado que utiliza a configuração exata de tokenização (normalizador, pré-tokenizador, convenções de tokens especiais, etc.) com a qual o modelo foi treinado.

Use uma classe específica do modelo para inicializar um tokenizer vazio para treinamento ou para passar argumentos específicos do modelo, como `vocab` ou `merges` (consulte o guia [Personalizando tokenizers](./custom_tokenizers) para saber como fazer isso). Um tokenizer vazio é mínimo e contém apenas os tokens especiais de um modelo, como `<pad>`, `<eos>` ou `<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 e decodificar

O método [TokenizersBackend.__call__()](/docs/transformers/main/pt/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__) codifica texto ou um lote de textos em `input_ids`, `attention_mask` e outras entradas do modelo. Ele também controla o preenchimento, a truncagem e a inserção de tokens especiais.

```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/main/pt/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) é semelhante, mas retorna apenas `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/main/pt/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.decode) converte uma única sequência ou um lote de `input_ids` tokenizados de volta para texto.

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

[TokenizersBackend.decode()](/docs/transformers/main/pt/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.decode) preserva o espaçamento exato da tokenização. Defina `clean_up_tokenization_spaces` para remover espaços antes de pontuação e `skip_special_tokens` para remover tokens especiais da saída.

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

## Tokens especiais

Os tokens especiais marcam fronteiras estruturais em uma sequência, como a posição de início da sequência ou as posições de preenchimento (padding). Cada modelo define seu próprio conjunto de tokens especiais. O tokenizer os adiciona quando você o chama.

```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 especiais nomeados adicionais com o argumento `extra_special_tokens`. Modelos multimodais os utilizam como marcadores para imagens, vídeos ou áudio.

```py
from transformers import AutoTokenizer

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

## Processamento em lote

O processamento em lote tokeniza múltiplas sequências em uma única chamada. [TokenizersBackend](/docs/transformers/main/pt/main_classes/tokenizer#transformers.TokenizersBackend) processa lotes grandes mais rapidamente porque seu backend baseado em Rust paraleliza o trabalho entre threads.

```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"
)
```

O processamento em lote exige que todas as sequências tenham o mesmo comprimento. O preenchimento (padding) e a truncagem são estratégias para lidar com sequências de comprimentos variados.

### Preenchimento

O padding adiciona tokens especiais para que sequências mais curtas tenham o mesmo comprimento da sequência mais longa do lote. A máscara de atenção marca as posições de padding como `0` para que o modelo as ignore. Defina `padding=True` para ajustar ao comprimento da sequência mais longa ou passe `max_length` para ajustar a um tamanho fixo.

```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]
> Os grandes modelos de linguagem aplicam padding no lado *esquerdo* para evitar interromper a geração, que prevê o próximo token a partir do lado *direito*.

### Truncamento

A truncação recorta tokens para que a sequência caiba dentro de um comprimento máximo. Defina `truncation=True` e especifique `max_length` para ativá-la.

O padding e a truncagem funcionam em conjunto. Sequências curtas recebem tokens de padding, enquanto sequências longas perdem tokens finais. Juntos, eles produzem um tensor retangular 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 tokenizer de modelo é definido em um único arquivo e suporta quatro backends de tokenização.

| backend                  | implementação                                                | descrição                                    |
| ------------------------ | ------------------------------------------------------------- | ---------------------------------------------- |
| [TokenizersBackend](/docs/transformers/main/pt/main_classes/tokenizer#transformers.TokenizersBackend)    | [Tokenizers](https://huggingface.co/docs/tokenizers)          | padrão para a maioria dos modelos                        |
| [SentencePieceBackend](/docs/transformers/main/pt/main_classes/tokenizer#transformers.SentencePieceBackend) | [SentencePiece](https://github.com/google/sentencepiece)      | modelos que exigem SentencePiece                 |
| [PythonBackend](/docs/transformers/main/pt/main_classes/tokenizer#transformers.PythonBackend)        | Python                                                        | modelos que exigem tokenizadores personalizados especializados |
| [MistralCommonBackend](/docs/transformers/main/pt/model_doc/mistral#transformers.MistralCommonBackend) | [mistral-common](https://mistralai.github.io/mistral-common/) | Modelos Mistral e Pixtral                     |

Todos os backends herdam de [PreTrainedTokenizerBase](/docs/transformers/main/pt/internal/tokenization_utils#transformers.PreTrainedTokenizerBase) e compartilham as mesmas APIs para codificação, decodificação, padding, truncamento, salvamento e carregamento. A diferença está em qual pipeline de tokenização é executado por baixo.

[AutoTokenizer](/docs/transformers/main/pt/model_doc/auto#transformers.AutoTokenizer) seleciona o backend disponível mais adequado quando você chama [from_pretrained()](/docs/transformers/main/pt/model_doc/auto#transformers.AutoTokenizer.from_pretrained).

1. Ele lê o arquivo `tokenizer_config.json` para o campo `tokenizer_class`.
2. O registro corresponde `tokenizer_class` a um nome de classe. A classe resolvida herda de um dos quatro backends. Por exemplo, [GemmaTokenizer](/docs/transformers/main/pt/model_doc/gemma#transformers.GemmaTokenizer) herda de [TokenizersBackend](/docs/transformers/main/pt/main_classes/tokenizer#transformers.TokenizersBackend), e [SiglipTokenizer](/docs/transformers/main/pt/model_doc/siglip#transformers.SiglipTokenizer) herda de [SentencePieceBackend](/docs/transformers/main/pt/main_classes/tokenizer#transformers.SentencePieceBackend). Alguns modelos, como o GLM, mapeiam diretamente para [TokenizersBackend](/docs/transformers/main/pt/main_classes/tokenizer#transformers.TokenizersBackend) porque o arquivo `tokenizer.json` descreve totalmente o pipeline. [GemmaTokenizer](/docs/transformers/main/pt/model_doc/gemma#transformers.GemmaTokenizer) existe como uma subclasse porque define configurações adicionais específicas do modelo em Python que o `tokenizer.json` não captura. Quando um backend como mistral-common não está instalado, o [AutoTokenizer](/docs/transformers/main/pt/model_doc/auto#transformers.AutoTokenizer) recorre ao [TokenizersBackend](/docs/transformers/main/pt/main_classes/tokenizer#transformers.TokenizersBackend).

### Fallback para TokenizersBackend

Alguns modelos não possuem uma classe de tokenizer dedicada, e alguns checkpoints possuem um `tokenizer_class` que não corresponde ao seu arquivo `tokenizer.json` real. O [AutoTokenizer](/docs/transformers/main/pt/model_doc/auto#transformers.AutoTokenizer) lida com ambos os casos carregando o pipeline a partir do `tokenizer.json` por meio do [TokenizersBackend](/docs/transformers/main/pt/main_classes/tokenizer#transformers.TokenizersBackend) genérico. Ele prioriza o tokenizer serializado em relação ao nome da classe do Hub, o que corrige problemas como quando um `tokenizer_class` incompatível gera ids de tokens incorretos.

Um checkpoint é resolvido para um `TokenizersBackend` genérico por um de três motivos.

| Motivo                              | Comportamento                                                                                                                                 | Exemplos                                                                       |
| ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| Na classe de tokenizer dedicada        | O tipo de modelo mapeia diretamente para `TokenizersBackend`, pois `tokenizer.json` descreve completamente o pipeline.                               | GLM, Granite, OLMo 2, GPT BigCode                                              |
| Classe de tokenizador do Hub conhecida como incorreta | O `tokenizer_class` registrado no Hub está incorreto para o tipo de modelo, portanto o `AutoTokenizer` o ignora e carrega o `tokenizer.json` em vez disso. | DeepSeek V3, LLaVA, Qwen2, ModernBERT                                          |
| Sobrescrita de checkpoint específico        | Um checkpoint cuja configuração no Hub ainda precisa de correção é identificado pelo seu id de modelo e forçado para o backend.                                    | `deepseek-ai/DeepSeek-R1-Distill-*`, `Salesforce/blip2-*`, `google/umt5-small` |

Os tipos de modelos e checkpoints afetados aumentam à medida que as configurações são corrigidas no Hub. Para o conjunto atual, consulte as definições de `MODELS_WITH_INCORRECT_HUB_TOKENIZER_CLASS` e `MODEL_IDS_TO_TOKENIZERS_BACKEND` em [tokenization_auto.py](https://github.com/huggingface/transformers/blob/main/src/transformers/models/auto/tokenization_auto.py).

O fallback é automático e não altera a forma como você chama [from_pretrained()](/docs/transformers/main/pt/model_doc/auto#transformers.AutoTokenizer.from_pretrained). O tokenizer resultante codifica e decodifica exatamente como especificado em `tokenizer.json`.

Verifique qual backend um tokenizer está usando com a propriedade `backend`.

```py
from transformers import AutoTokenizer

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

## Inspecionar a arquitetura do tokenizer

Inspecione os componentes internos de um tokenizer (normalizer, pre-tokenizer, model, decoder) com o 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

- O post [Tokenization in Transformers v5](https://huggingface.co/blog/tokenizers) discute a motivação por trás dos novos backends de tokenização.
- Consulte o [guia de migração](https://github.com/huggingface/transformers/blob/main/MIGRATION_GUIDE_V5.md#tokenization) para uma visão geral das alterações de tokenização.