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

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

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

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

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

Загрузите токенизатор с помощью класса [AutoTokenizer](/docs/transformers/main/ru/model_doc/auto#transformers.AutoTokenizer) или класса токенизатора, специфичного для модели.

[AutoTokenizer.from_pretrained()](/docs/transformers/main/ru/model_doc/auto#transformers.AutoTokenizer.from_pretrained) reads the model config, resolves the correct tokenizer class, and returns an instance of it. You don't need to know the tokenizer class beforehand. Most tokenizers resolve to a subclass of [TokenizersBackend](/docs/transformers/main/ru/main_classes/tokenizer#transformers.TokenizersBackend), a fast Rust-based tokenizer from the [Tokenizers](https://huggingface.co/docs/tokenizers/index) library.

Загрузка с помощью [AutoTokenizer](/docs/transformers/main/ru/model_doc/auto#transformers.AutoTokenizer) — рекомендуемый подход.

```py
from transformers import AutoTokenizer

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

Класс токенизации, специфичный для модели, представляет собой предварительно настроенный [TokenizersBackend](/docs/transformers/main/ru/main_classes/tokenizer#transformers.TokenizersBackend), который использует точную конфигурацию токенизации (нормализатор, претокенизатор, соглашения о специальных токенах и т. д.), с которой обучалась модель.

Используйте класс, специфичный для модели, чтобы инициализировать пустой токенизатор для обучения или передать аргументы, специфичные для модели, такие как `vocab` или `merges` (см. руководство [Настройка токенизаторов](./custom_tokenizers), чтобы узнать, как это сделать). Пустой токенизатор является минимальным и содержит только специальные токены модели, такие как `<pad>`, `<eos>` или `<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)
```

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

Метод [TokenizersBackend.__call__()](/docs/transformers/main/ru/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__) кодирует текст или пакет текстов в `input_ids`, `attention_mask` и другие входные данные модели. Он также управляет выравниванием, усечением и вставкой специальных токенов.

```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/ru/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) похож, но возвращает только `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/ru/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.decode) преобразует одну последовательность или пакет токенизированных `input_ids` обратно в текст.

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

[TokenizersBackend.decode()](/docs/transformers/main/ru/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.decode) сохраняет точное пробельное форматирование токенизации. Установите `clean_up_tokenization_spaces`, чтобы удалить пробелы перед знаками препинания, и `skip_special_tokens`, чтобы исключить специальные токены из вывода.

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

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

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

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

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

```py
from transformers import AutoTokenizer

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

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

Обработка пакетов токенизирует несколько последовательностей за один вызов. [TokenizersBackend](/docs/transformers/main/ru/main_classes/tokenizer#transformers.TokenizersBackend) обрабатывает большие пакеты быстрее, так как его Rust-бэкенд параллелизирует работу между потоками.

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

### Заполнение

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

```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]
> Большие языковые модели дополняют последовательности нулями с *левой* стороны, чтобы не нарушать генерацию, которая предсказывает следующий токен, начиная с *правой* стороны.

### Обрезка

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

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

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

## Бэкенды

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

| backend                  | реализация                                                | Описание                                    |
| ------------------------ | ------------------------------------------------------------- | ---------------------------------------------- |
| [TokenizersBackend](/docs/transformers/main/ru/main_classes/tokenizer#transformers.TokenizersBackend)    | [Токенизаторы](https://huggingface.co/docs/tokenizers)          | по умолчанию для большинства моделей                        |
| [SentencePieceBackend](/docs/transformers/main/ru/main_classes/tokenizer#transformers.SentencePieceBackend) | [SentencePiece](https://github.com/google/sentencepiece)      | модели, требующие SentencePiece                 |
| [PythonBackend](/docs/transformers/main/ru/main_classes/tokenizer#transformers.PythonBackend)        | Python                                                        | модели, требующие специализированных пользовательских токенизаторов |
| [MistralCommonBackend](/docs/transformers/main/ru/model_doc/mistral#transformers.MistralCommonBackend) | [mistral-common](https://mistralai.github.io/mistral-common/) | Модели Mistral и Pixtral                     |

Все бэкенды наследуются от [PreTrainedTokenizerBase](/docs/transformers/main/ru/internal/tokenization_utils#transformers.PreTrainedTokenizerBase) и используют единые API для кодирования, декодирования, дополнения, усечения, сохранения и загрузки. Отличие состоит в том, какой конвейер токенизации выполняется под капотом.

[AutoTokenizer](/docs/transformers/main/ru/model_doc/auto#transformers.AutoTokenizer) выбирает оптимальный доступный бэкенд при вызове [from_pretrained()](/docs/transformers/main/ru/model_doc/auto#transformers.AutoTokenizer.from_pretrained).

1. Он читает файл `tokenizer_config.json` для поля `tokenizer_class`.
2. Реестр сопоставляет `tokenizer_class` с именем класса. Разрешённый класс наследуется от одного из четырёх бэкендов. Например, [GemmaTokenizer](/docs/transformers/main/ru/model_doc/gemma#transformers.GemmaTokenizer) наследуется от [TokenizersBackend](/docs/transformers/main/ru/main_classes/tokenizer#transformers.TokenizersBackend), а [SiglipTokenizer](/docs/transformers/main/ru/model_doc/siglip#transformers.SiglipTokenizer) — от [SentencePieceBackend](/docs/transformers/main/ru/main_classes/tokenizer#transformers.SentencePieceBackend). Некоторые модели, такие как GLM, напрямую отображаются на [TokenizersBackend](/docs/transformers/main/ru/main_classes/tokenizer#transformers.TokenizersBackend), поскольку файл `tokenizer.json` полностью описывает конвейер. Класс [GemmaTokenizer](/docs/transformers/main/ru/model_doc/gemma#transformers.GemmaTokenizer) существует как подкласс, так как он определяет дополнительные специфичные для модели настройки на Python, которые не отражены в `tokenizer.json`. Если бэкенд, например mistral-common, не установлен, [AutoTokenizer](/docs/transformers/main/ru/model_doc/auto#transformers.AutoTokenizer) переключается на [TokenizersBackend](/docs/transformers/main/ru/main_classes/tokenizer#transformers.TokenizersBackend).

### Откат на TokenizersBackend

Некоторые модели не имеют выделенного класса токенизатора, а в некоторых чекпоинтах значение `tokenizer_class` не соответствует фактическому файлу `tokenizer.json`. [AutoTokenizer](/docs/transformers/main/ru/model_doc/auto#transformers.AutoTokenizer) обрабатывает оба случая, загружая пайплайн из `tokenizer.json` через универсальный [TokenizersBackend](/docs/transformers/main/ru/main_classes/tokenizer#transformers.TokenizersBackend). Он отдаёт приоритет сериализованному токенизатору перед именем класса из Hub, что устраняет проблемы, например, когда несоответствующий `tokenizer_class` приводит к формированию неверных идентификаторов токенов.

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

| Причина                              | Поведение                                                                                                                                 | Примеры                                                                       |
| ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| Отсутствует отдельный класс токенизатора        | Тип модели напрямую соответствует `TokenizersBackend`, поскольку `tokenizer.json` полностью описывает конвейер.                               | GLM, Granite, OLMo 2, GPT BigCode                                              |
| Неверный класс токенизатора на Hub | Значение `tokenizer_class`, указанное на Hub, не соответствует типу модели, поэтому `AutoTokenizer` игнорирует его и загружает `tokenizer.json`. | DeepSeek V3, LLaVA, Qwen2, ModernBERT                                          |
| Переопределение конкретного контрольного пункта        | Чекпоинт, конфигурация которого в Hub всё ещё требует исправления, сопоставляется по идентификатору модели и принудительно переводится на целевой бэкенд.                                    | `deepseek-ai/DeepSeek-R1-Distill-*`, `Salesforce/blip2-*`, `google/umt5-small` |

Список затронутых типов моделей и контрольных точек расширяется по мере исправления конфигураций на Hub. Актуальный набор см. в определениях `MODELS_WITH_INCORRECT_HUB_TOKENIZER_CLASS` и `MODEL_IDS_TO_TOKENIZERS_BACKEND` в файле [tokenization_auto.py](https://github.com/huggingface/transformers/blob/main/src/transformers/models/auto/tokenization_auto.py).

Откат происходит автоматически и не меняет способ вызова [from_pretrained()](/docs/transformers/main/ru/model_doc/auto#transformers.AutoTokenizer.from_pretrained). Полученный токенизатор кодирует и декодирует данные точно так, как указано в `tokenizer.json`.

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

```py
from transformers import AutoTokenizer

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

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

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

## Ресурсы

- В статье [Tokenization in Transformers v5](https://huggingface.co/blog/tokenizers) обсуждаются мотивы создания новых бэкендов токенизации.
- Ознакомьтесь с [руководством по миграции](https://github.com/huggingface/transformers/blob/main/MIGRATION_GUIDE_V5.md#tokenization), чтобы получить обзор изменений в токенизации.