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.

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 ou com uma classe de tokenizer específica do modelo.

from transformers import AutoTokenizer

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

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

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() é semelhante, mas retorna apenas 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() converte uma única sequência ou um lote de input_ids tokenizados de volta para texto.

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

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

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.

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.

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 processa lotes grandes mais rapidamente porque seu backend baseado em Rust paraleliza o trabalho entre threads.

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.

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

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.

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.

Todos os backends herdam de 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 seleciona o backend disponível mais adequado quando você chama 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 herda de TokenizersBackend, e SiglipTokenizer herda de SentencePieceBackend. Alguns modelos, como o GLM, mapeiam diretamente para TokenizersBackend porque o arquivo tokenizer.json descreve completamente o pipeline. GemmaTokenizer existe como uma subclasse porque define configurações adicionais específicas do modelo em Python que tokenizer.json não captura. Quando um backend como mistral-common não está instalado, AutoTokenizer recorre a 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 lida com ambos os casos carregando o pipeline a partir do tokenizer.json por meio do 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 produz ids de tokens incorretos.

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

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.

O fallback é automático e não altera a forma como você chama 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.

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.

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 discute a motivação por trás dos novos backends de tokenização.
• Consulte o guia de migração para uma visão geral das alterações de tokenização.