Токенизаторы

Токенизатор преобразует текст в тензоры, которые являются входными данными для модели. Он нормализует и разбивает текст, применяет алгоритм токенизации, добавляет специальные токены и декодирует выходные идентификаторы обратно в текст.

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

В этом руководстве рассматриваются загрузка, кодирование, декодирование, пакетная обработка и доступные бэкенды токенизаторов.

Загрузка токенизатора

Загрузите токенизатор с помощью класса AutoTokenizer или класса токенизатора, специфичного для модели.

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)

Кодирование и декодирование

Метод TokenizersBackend.call() кодирует текст или пакет текстов в input_ids, attention_mask и другие входные данные модели. Он также управляет выравниванием, усечением и вставкой специальных токенов.

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() похож, но возвращает только 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() преобразует одну последовательность или пакет токенизированных input_ids обратно в текст.

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

TokenizersBackend.decode() сохраняет точное пробельное форматирование токенизации. Установите clean_up_tokenization_spaces, чтобы удалить пробелы перед знаками препинания, и skip_special_tokens, чтобы исключить специальные токены из вывода.

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

Специальные токены

Специальные токены обозначают структурные границы в последовательности, например, позицию начала последовательности или позиции заполнения. Каждая модель определяет собственный набор специальных токенов. Токенизатор добавляет их при вызове.

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

Добавляйте дополнительные именованные специальные токены с помощью аргумента extra_special_tokens. Мультимодальные модели используют их в качестве плейсхолдеров для изображений, видео или аудио.

from transformers import AutoTokenizer

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

Пакетная обработка

Обработка пакетов токенизирует несколько последовательностей за один вызов. TokenizersBackend обрабатывает большие пакеты быстрее, так как его Rust-бэкенд параллелизирует работу между потоками.

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) и усечение (truncation) — это стратегии для работы с последовательностями разной длины.

Заполнение

Padding добавляет специальные токены, чтобы более короткие последовательности соответствовали самой длинной последовательности в батче. Attention mask помечает позиции padding как 0, чтобы модель игнорировала их. Установите padding=True, чтобы дополнить до самой длинной последовательности, или передайте max_length, чтобы дополнить до фиксированного размера.

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

Большие языковые модели дополняют последовательности нулями с левой стороны, чтобы не нарушать генерацию, которая предсказывает следующий токен, начиная с правой стороны.

Обрезка

Обрезка (truncation) укорачивает токены, чтобы последовательность уместилась в заданную максимальную длину. Для её включения установите truncation=True и укажите max_length.

Паддинг и усечение работают в связке. Короткие последовательности дополняются токенами-заполнителями, а длинные теряют хвостовые токены. Вместе они формируют упакованный прямоугольный тензор.

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

Бэкенды

Каждый токенизатор модели определяется в одном файле и поддерживает четыре бэкенда токенизации.

Все бэкенды наследуются от PreTrainedTokenizerBase и используют единые API для кодирования, декодирования, дополнения, усечения, сохранения и загрузки. Отличие состоит в том, какой конвейер токенизации выполняется под капотом.

AutoTokenizer выбирает оптимальный доступный бэкенд при вызове from_pretrained().

1. Он читает файл tokenizer_config.json для поля tokenizer_class.
2. Реестр сопоставляет tokenizer_class с именем класса. Разрешённый класс наследуется от одного из четырёх бэкендов. Например, GemmaTokenizer наследуется от TokenizersBackend, а SiglipTokenizer — от SentencePieceBackend. Некоторые модели, такие как GLM, напрямую отображаются на TokenizersBackend, поскольку файл tokenizer.json полностью описывает конвейер. Класс GemmaTokenizer существует как подкласс, так как он определяет дополнительные специфичные для модели настройки на Python, которые не отражены в tokenizer.json. Если бэкенд, например mistral-common, не установлен, AutoTokenizer переключается на TokenizersBackend.

Откат на TokenizersBackend

Некоторые модели не имеют выделенного класса токенизатора, а в некоторых контрольных точках tokenizer_class не соответствует их фактическому файлу tokenizer.json. AutoTokenizer обрабатывает оба случая, загружая пайплайн из tokenizer.json через универсальный TokenizersBackend. Он отдаёт приоритет сериализованному токенизатору перед именем класса из Hub, что устраняет проблемы, например, когда несоответствующий tokenizer_class приводит к неверным идентификаторам токенов.

Чекпоинт приводит к общему TokenizersBackend по одной из трёх причин.

Список затронутых типов моделей и контрольных точек расширяется по мере исправления конфигураций на Hub. Актуальный набор см. в определениях MODELS_WITH_INCORRECT_HUB_TOKENIZER_CLASS и MODEL_IDS_TO_TOKENIZERS_BACKEND в файле tokenization_auto.py.

Откат происходит автоматически и не меняет способ вызова from_pretrained(). Полученный токенизатор кодирует и декодирует данные точно так, как указано в tokenizer.json.

Проверьте, какой бэкенд использует токенизатор, с помощью свойства backend.

from transformers import AutoTokenizer

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

Осмотр архитектуры токенизатора

Осмотрите внутренние компоненты токенизатора (нормализатор, претокенизатор, модель, декодер) с помощью атрибута _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)

Ресурсы

• В статье Tokenization in Transformers v5 обсуждаются мотивы создания новых бэкендов токенизации.
• Ознакомьтесь с руководством по миграции, чтобы получить обзор изменений в токенизации.