# Byte Latent Transformer (BLT)

## Обзор

Модель BLT была предложена в статье [Byte Latent Transformer: Patches Scale Better Than Tokens](https://huggingface.co/papers/2412.09871) авторами Artidoro Pagnoni, Ram Pasunuru, Pedro Rodriguez, John Nguyen, Benjamin Muller, Margaret Li1, Chunting Zhou, Lili Yu, Jason Weston, Luke Zettlemoyer, Gargi Ghosh, Mike Lewis, Ari Holtzman†, Srinivasan Iyer. BLT — это LLM на уровне байтов, которая достигает производительности на уровне токенизации за счёт динамического патчинга на основе энтропии.

Аннотация из статьи следующая:

*Мы представляем Byte Latent Transformer (BLT) — новую байтовую архитектуру LLM, которая впервые достигает производительности LLM на основе токенизации при масштабном обучении, демонстрируя при этом значительное повышение эффективности и устойчивости инференса. BLT кодирует байты в патчи динамического размера, которые служат основными единицами вычислений. Патчи сегментируются на основе энтропии следующего байта, что позволяет распределять больше вычислительных ресурсов и ёмкости модели там, где повышенная сложность данных этого требует. Мы проводим первое исследование масштабирования байтовых моделей с контролем числа операций (FLOPs) до 8 млрд параметров и 4 трлн обучающих байтов. Наши результаты подтверждают возможность масштабирования моделей, обученных на «сырых» байтах без фиксированного словаря. Эффективность как обучения, так и инференса повышается за счёт динамического выбора длинных патчей, когда данные предсказуемы, а также за счёт качественных улучшений в рассуждениях и обобщении на «длинный хвост». В целом, при фиксированных затратах на инференс BLT демонстрирует значительно лучшее масштабирование, чем модели на основе токенизации, за счёт одновременного увеличения размера патчей и модели.*

## Советы по использованию

- **Архитектура с двумя моделями**: BLT состоит из двух отдельных обученных моделей:
  - **Patcher (модель энтропии)**: небольшая трансформерная модель, которая предсказывает байтовую энтропию для определения границ патчей и сегментации входных данных.
  - **Основная модель Transformer**: основная модель, которая обрабатывает патчи через локальный энкодер, глобальный Transformer и локальный декодер.

- **Динамическая подмена патчей**: модель использует динамическую подмену патчей на основе энтропии, при которой:
  - Области с высокой энтропией (сложные данные) получают более короткие патчи с большим вычислительным вниманием
  - Области с низкой энтропией (предсказуемые данные) получают более длинные патчи для повышения эффективности
  - Это позволяет модели распределять вычислительные ресурсы там, где они наиболее необходимы

- **Локальный энкодер**: обрабатывает последовательности байтов с использованием кросс-внимания к патч-эмбеддингам
- **Global Transformer**: обрабатывает представления на уровне патчей с полным вниманием между патчами
- **Локальный декодер**: генерирует вывод с использованием кросс-внимания к исходной последовательности байтов

- **Токенизатор байтового уровня**: в отличие от традиционных токенизаторов, использующих обученные словари, токенизатор BLT просто преобразует текст в байты UTF-8 и сопоставляет каждый байт с идентификатором токена. Словарь не требуется.

Модель можно загрузить с помощью:

```python
from transformers import AutoModelForCausalLM, AutoTokenizer

tokenizer = AutoTokenizer.from_pretrained("itazap/blt-1b-hf")
model = AutoModelForCausalLM.from_pretrained(
    "itazap/blt-1b-hf",
    device_map="auto",
)

inputs = tokenizer(prompt, return_tensors="pt").to(model.device)

prompt = "my name is"
generated_ids = model.generate(
    **inputs, max_new_tokens=NUM_TOKENS_TO_GENERATE, do_sample=False, use_cache=False
)

print(tokenizer.decode(generated_ids[0]))
```

Эта модель была добавлена пользователем [itazap](https://huggingface.co/). Исходный код можно найти [здесь]().

## BltConfig[[transformers.BltConfig]]

#### transformers.BltConfig[[transformers.BltConfig]]

```python
transformers.BltConfig(transformers_version: str | None = None, architectures: list[str] | None = None, output_hidden_states: bool | None = False, return_dict: bool | None = True, dtype: str | torch.dtype | None = None, chunk_size_feed_forward: int = 0, is_encoder_decoder: bool = False, id2label: dict[int, str] | dict[str, str] | None = None, label2id: dict[str, int] | dict[str, str] | None = None, problem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = None, vocab_size: int = 260, max_position_embeddings: int = 4096, patch_in_forward: bool | None = True, patch_size: int | None = 4, patching_mode: str | None = 'entropy', patching_threshold: float | None = 1.335442066192627, patching_batch_size: int | None = 1, max_patch_length: int | None = None, local_attention_window_len: int | None = 512, cross_attn_k: int | None = 2, encoder_hash_byte_group_size: list[int] | None = None, encoder_hash_byte_group_vocab: int | None = 500002, encoder_hash_byte_group_nb_functions: int | None = 1, patcher_config: dict | transformers.configuration_utils.PreTrainedConfig | None = None, encoder_config: dict | transformers.configuration_utils.PreTrainedConfig | None = None, decoder_config: dict | transformers.configuration_utils.PreTrainedConfig | None = None, global_config: dict | transformers.configuration_utils.PreTrainedConfig | None = None, tie_word_embeddings: bool = False, use_cache: bool = True, pad_token_id: int | None = None, bos_token_id: int | None = None, eos_token_id: int | list[int] | None = None, initializer_range: float = 0.02, rope_parameters: transformers.modeling_rope_utils.RopeParameters | dict | None = None)
```

[Источник](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/blt/configuration_blt.py#L167)

**Параметры:**

vocab_size (`int`, *необязательный*, по умолчанию `260`) : Размер словаря модели. Определяет количество различных токенов, которые могут быть представлены в `input_ids`.

max_position_embeddings (`int`, *необязательный*, по умолчанию `4096`) : Максимальная длина последовательности, с которой может использоваться данная модель.

patch_in_forward (`bool`, *необязательный*, по умолчанию `True`) : Выполнять ли патчинг во время прямого прохода.

patch_size (`int`, *optional*, по умолчанию 4) : Размер патчей, используемых в механизме патчинга.

patching_mode (`str`, *необязательный*, по умолчанию `"entropy"`) : Режим, используемый для патчинга, например, патчинг на основе энтропии.

patching_threshold (`float`, *optional*, по умолчанию 1.34) : Пороговое значение, используемое для определения момента применения патчей.

patching_batch_size (`int`, *необязательный*, по умолчанию 1) : Размер батча, используемый в процессе патчинга.

max_patch_length (`int`, *необязательный*) : Максимальная длина патчей, которые могут быть сгенерированы.

local_attention_window_len (`int`, *optional*, по умолчанию 512) : Размер локального окна внимания, используемого локальным энкодером и локальным декодером, соответствует `local_attention_window_len` в опубликованных чекпоинтах. Установите `None`, чтобы учитывать весь каузальный контекст.

cross_attn_k (`int`, *optional*, по умолчанию 2) : Количество головок кросс-внимания, используемых в модели.

encoder_hash_byte_group_size (`list`, *необязательный*) : Список размеров байтовых групп, используемых в хеш-функции кодировщика.

encoder_hash_byte_group_vocab (`int`, *optional*, по умолчанию 500002) : Размер словаря для групп байтов хэширования энкодера.

encoder_hash_byte_group_nb_functions (`int`, *optional*, по умолчанию 1) : Количество хеш-функций, используемых при группировке байтов в кодировщике.

patcher_config (`BltPatcherConfig`, *необязательный*) : Конфигурация для компонента patcher модели.

encoder_config (`Union[dict, ~configuration_utils.PreTrainedConfig]`, *необязательный*) : Объект конфигурации или словарь для базовой модели энкодера.

decoder_config (`Union[dict, ~configuration_utils.PreTrainedConfig]`, *необязательный*) : Объект конфигурации или словарь для декодерного бэкбона.

global_config (`BltGlobalTransformerConfig`, *необязательный*) : Конфигурация для глобального компонента трансформера модели.

tie_word_embeddings (`bool`, *необязательный*, по умолчанию `False`) : Связывать ли веса эмбеддингов согласно отображению `tied_weights_keys` модели.

use_cache (`bool`, *необязательный*, по умолчанию `True`) : Следует ли модели возвращать последние значения внимания key/values (не используется во всех моделях). Актуально только при `config.is_decoder=True` или если модель является генеративной моделью только с декодером.

pad_token_id (`int`, *необязательный*) : Идентификатор токена, используемый для выравнивания в словаре.

bos_token_id (`int`, *optional*) : Идентификатор токена, используемый для обозначения начала потока в словаре.

eos_token_id (`Union[int, list[int]]`, *необязательный*) : Идентификатор токена, используемый для обозначения конца потока в словаре.

initializer_range (`float`, *необязательный*, по умолчанию `0.02`) : Стандартное отклонение truncated_normal_initializer для инициализации всех матриц весов.

rope_parameters (`Union[~modeling_rope_utils.RopeParameters, dict]`, *optional*) : Словарь, содержащий параметры конфигурации для вложений RoPE. Словарь должен содержать значение для `rope_theta` и, при необходимости, параметры, используемые для масштабирования, если вы хотите использовать RoPE с более длинными `max_position_embeddings`.

Это класс конфигурации для хранения настроек модели BltModel. Он используется для создания модели Blt в соответствии с указанными аргументами, определяя архитектуру модели. Создание конфигурации с параметрами по умолчанию даст конфигурацию, аналогичную конфигурации [itazap/blt-1b-hf](https://huggingface.co/itazap/blt-1b-hf)

Объекты конфигурации наследуются от [PreTrainedConfig](/docs/transformers/v5.23.0/ru/main_classes/configuration#transformers.PreTrainedConfig) и могут использоваться для управления выводами модели. Подробнее см. в документации [PreTrainedConfig](/docs/transformers/v5.23.0/ru/main_classes/configuration#transformers.PreTrainedConfig).

Пример:
```python
>>> from transformers import BltModel, BltConfig

>>> # Initializing a Blt configuration
>>> configuration = BltConfig()

>>> # Initializing a model from the configuration
>>> model = BltModel(configuration)

>>> # Accessing the model configuration
>>> configuration = model.config
```

#### transformers.BltModel[[transformers.BltModel]]

```python
transformers.BltModel(config: BltConfig)
```

[Источник](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/blt/modeling_blt.py#L1144)

#### forward[[transformers.BltModel.forward]]

```python
forward(input_ids: typing.Optional[torch.LongTensor] = None, patch_lengths: typing.Optional[torch.Tensor] = None, attention_mask: typing.Optional[torch.Tensor] = None, position_ids: typing.Optional[torch.LongTensor] = None, past_key_values: transformers.cache_utils.Cache | None = None, inputs_embeds: typing.Optional[torch.Tensor] = None, use_cache: bool | None = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[Источник](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/blt/modeling_blt.py#L1165)

## BltForCausalLM[[transformers.BltForCausalLM]]

#### transformers.BltForCausalLM[[transformers.BltForCausalLM]]

```python
transformers.BltForCausalLM(config: BltConfig)
```

[Источник](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/blt/modeling_blt.py#L1327)

**Параметры:**

config ([BltConfig](/docs/transformers/v5.23.0/ru/model_doc/blt#transformers.BltConfig)) : Класс конфигурации модели со всеми параметрами модели. Инициализация с файлом конфигурации не загружает веса, связанные с моделью, только конфигурацию. Используйте метод [from_pretrained()](/docs/transformers/v5.23.0/ru/main_classes/model#transformers.PreTrainedModel.from_pretrained) для загрузки весов модели.

Модель Blt Text с головой для моделирования языка.

Эта модель наследуется от [PreTrainedModel](/docs/transformers/v5.23.0/ru/main_classes/model#transformers.PreTrainedModel). Общие методы, которые библиотека реализует для всех своих моделей (например, загрузка или сохранение, изменение размера входных эмбеддингов, обрезка головок и т. д.), описаны в документации родительского класса.

Эта модель также является подклассом [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) в PyTorch. Используйте её как обычный модуль PyTorch и обращайтесь к документации PyTorch по всем вопросам, связанным с общим использованием и поведением.

#### forward[[transformers.BltForCausalLM.forward]]

```python
forward(input_ids: typing.Optional[torch.LongTensor] = None, attention_mask: typing.Optional[torch.Tensor] = None, position_ids: typing.Optional[torch.LongTensor] = None, cross_attention_states: typing.Optional[torch.LongTensor] = None, cross_attention_mask: typing.Optional[torch.LongTensor] = None, full_text_row_masked_out_mask: tuple[torch.Tensor, torch.Tensor] | None = None, past_key_values: transformers.cache_utils.Cache | None = None, inputs_embeds: typing.Optional[torch.Tensor] = None, labels: typing.Optional[torch.LongTensor] = None, use_cache: bool | None = None, logits_to_keep: typing.Union[int, torch.Tensor] = 0, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[Источник](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/blt/modeling_blt.py#L1342)

**Параметры:**

input_ids (`torch.LongTensor` формы `(batch_size, sequence_length)`, *необязательно*) : Индексы токенов входной последовательности в словаре. По умолчанию заполнение (padding) игнорируется. Индексы можно получить с помощью [AutoTokenizer](/docs/transformers/v5.23.0/ru/model_doc/auto#transformers.AutoTokenizer). Подробности см. в [PreTrainedTokenizer.encode()](/docs/transformers/v5.23.0/ru/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) и [PreTrainedTokenizer.__call__()](/docs/transformers/v5.23.0/ru/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__). [Что такое входные идентификаторы?](../glossary#input-ids)

attention_mask (`torch.Tensor` формы `(batch_size, sequence_length)`, *необязательный*) : Маска для предотвращения применения внимания к индексам токенов отсечки. Значения маски выбираются из `[0, 1]`:  - 1 для токенов, которые **не замаскированы**, - 0 для токенов, которые **замаскированы**.  [Что такое маски внимания?](../glossary#attention-mask)

position_ids (`torch.LongTensor` формы `(batch_size, sequence_length)`, *необязательно*) : Индексы позиций токенов каждого входного последовательности в позиционных эмбеддингах. Выбираются из диапазона `[0, config.n_positions - 1]`.  [Что такое position IDs?](../glossary#position-ids)

cross_attention_states (`torch.Tensor`, *необязательный*) : Выход визуальной модели, используемый для кросс-внимания. Этот тензор содержит обработанные признаки изображения, на которые будет обращать внимание языковая модель.

cross_attention_mask (`torch.Tensor` формы `(batch_size, seq_length, max_num_images, max_num_tiles)`, *необязательный*) : Маска кросс-внимания для управления взаимодействием между текстовыми токенами и плитками изображения. Этот 4D-тензор определяет, к каким плиткам изображения должен обращаться каждый текстовый токен.  Для каждого текстового токена (в seq_length): - 1 означает, что токен **должен обращаться** к соответствующей плитке изображения - 0 означает, что токен **не должен обращаться** к соответствующей плитке изображения

full_text_row_masked_out_mask (`tuple[torch.Tensor, torch.Tensor]`, *optional*) : Кортеж, содержащий два тензора, которые маскируют строки в механизме кросс-внимания: - Первый тензор имеет форму `(batch_size, 1, seq_length, 1)` и содержит значения 0 или 1. Значение 0 указывает, что вся строка, соответствующая текстовому токену, в матрице кросс-внимания должна быть замаскирована (все визуальные токены игнорируются). - Второй тензор имеет ту же форму и используется внутренне для применения маскирования во время прямого прохода слоёв кросс-внимания. Эта маска выводится из cross_attention_mask и используется для обработки случаев, когда текстовый токен не должен обращать внимание ни на один визуальный токен.

past_key_values (`~cache_utils.Cache`, *необязательный*) : Предварительно вычисленные скрытые состояния (ключи и значения в блоках само-внимания и кросс-внимания), которые можно использовать для ускорения последовательного декодирования. Обычно это `past_key_values`, возвращаемые моделью на предыдущем этапе декодирования, когда `use_cache=True` или `config.use_cache=True`. В качестве входного значения допускается только экземпляр [Cache](/docs/transformers/v5.23.0/ru/internal/generation_utils#transformers.Cache), см. наше [руководство по kv cache](https://huggingface.co/docs/transformers/en/kv_cache). Если `past_key_values` не переданы, по умолчанию будет инициализирован [DynamicCache](/docs/transformers/v5.23.0/ru/internal/generation_utils#transformers.DynamicCache). Модель будет выводить тот же формат кэша, который был передан на вход. Если используются `past_key_values`, ожидается, что пользователь передаст только необработанные `input_ids` (те, для которых не заданы их прошлые состояния ключей и значений в этой модели) с формой `(batch_size, unprocessed_length)` вместо всех `input_ids` с формой `(batch_size, sequence_length)`.

inputs_embeds (`torch.Tensor` формы `(batch_size, sequence_length, hidden_size)`, *необязательно*) : По желанию, вместо передачи `input_ids` можно напрямую передать встроенное представление. Это полезно, если требуется больший контроль над тем, как индексы `input_ids` преобразуются в соответствующие векторы, чем это обеспечивает внутренняя матрица поиска встраиваний модели.

labels (`torch.LongTensor` формы `(batch_size, sequence_length)`, *необязательный*) : Метки для вычисления потерь каузального языкового моделирования. Индексы должны находиться в диапазоне `[-100, 0, ..., config.vocab_size]` (см. docstring для `input_ids`). Токены с индексами, установленными в `-100`, игнорируются (маскируются); потери вычисляются только для токенов с метками в диапазоне `[0, ..., config.vocab_size]`. Метки **внутренне сдвигаются**, так что `labels[..., 1:]` используются для предсказания `logits[..., :-1, :]`. Передавайте несдвинутые метки, соответствующие `input_ids` (т. е. `labels = input_ids`). Не **сдвигайте** метки самостоятельно перед передачей. Если метки уже сдвинуты (например, при параллелизме последовательностей), передайте их как аргумент `shift_labels`, и они будут использованы как есть. `labels` всё равно необходимо передать для вычисления потерь.

use_cache (`bool`, *необязательный*) : Если установлено в `True`, состояния ключей и значений `past_key_values` возвращаются и могут использоваться для ускорения декодирования (см. `past_key_values`).

logits_to_keep (`Union[int, torch.Tensor]`, *необязательный*, по умолчанию `0`) : Если передано значение типа `int`, вычисляются logits для последних `logits_to_keep` токенов. Если передано `0`, logits вычисляются для всех `input_ids` (специальный случай). Для генерации нужны logits только последнего токена, и вычисление их только для этого токена позволяет сэкономить память, что становится весьма значимым для длинных последовательностей или большого размера словаря. Если передано значение типа `torch.Tensor`, оно должно быть одномерным и соответствовать индексам, которые нужно сохранить в измерении длины последовательности. Это полезно при использовании упакованного формата тензоров (одно измерение для batch и длины последовательности).

**Возвращает:** [CausalLMOutputWithPast](/docs/transformers/v5.23.0/ru/main_classes/output#transformers.modeling_outputs.CausalLMOutputWithPast) или `tuple(torch.Tensor)`

Объект [CausalLMOutputWithPast](/docs/transformers/v5.23.0/ru/main_classes/output#transformers.modeling_outputs.CausalLMOutputWithPast) или кортеж `torch.Tensor` (если передано `return_dict=False` или если `config.return_dict=False`), содержащий различные элементы в зависимости от конфигурации ([BltConfig](/docs/transformers/v5.23.0/ru/model_doc/blt#transformers.BltConfig)) и входных данных.

Метод [BltForCausalLM](/docs/transformers/v5.23.0/ru/model_doc/blt#transformers.BltForCausalLM) forward переопределяет специальный метод `__call__`.

Хотя рецепт для прямого прохода должен быть определён внутри этой функции, после этого следует вызывать экземпляр `Module`, а не эту функцию, поскольку первый выполняет шаги предварительной и постобработки, тогда как второй молча их игнорирует.

- **loss** (`torch.Tensor` формы `(1,)`, *необязательный*, возвращается, если задан `labels`) -- Потеря языковой модели (для предсказания следующего токена).
- **logits** (`torch.Tensor` формы `(batch_size, sequence_length, config.vocab_size)`) — Оценки предсказаний языковой модели (оценки для каждого токена словаря до применения SoftMax).
- **past_key_values** (`Cache`, *необязательный*, возвращается при передаче `use_cache=True` или когда `config.use_cache=True`) -- это экземпляр [Cache](/docs/transformers/v5.23.0/ru/internal/generation_utils#transformers.Cache). Подробнее см. в нашем [руководстве по кэшированию kv](https://huggingface.co/docs/transformers/en/kv_cache).

  Содержит предварительно вычисленные скрытые состояния (ключи и значения в блоках само-внимания), которые можно использовать (см. вход `past_key_values`) для ускорения последовательного декодирования.
- **hidden_states** (`tuple(torch.Tensor)`, *необязательный*, возвращается при передаче `output_hidden_states=True` или когда `config.output_hidden_states=True`) -- Кортеж `torch.Tensor` (один для вывода слоя встраиваний, если модель имеет слой встраиваний, + один для вывода каждого слоя) формы `(batch_size, sequence_length, hidden_size)`.

  Скрытые состояния модели на выходе каждого слоя, а также необязательные выходные значения начального слоя встраивания.
- **attentions** (`tuple(torch.Tensor)`, *необязательный*, возвращается при передаче `output_attentions=True` или при `config.output_attentions=True`) -- Кортеж `torch.Tensor` (по одному на каждый слой) формы `(batch_size, num_heads, sequence_length, sequence_length)`.

  Веса внимания после softmax в механизме внимания, используемые для вычисления взвешенного среднего в головах само-внимания.

Пример:

```python
>>> from transformers import AutoTokenizer, BltForCausalLM

>>> model = BltForCausalLM.from_pretrained("itazap/blt-1b-hf")
>>> tokenizer = AutoTokenizer.from_pretrained("itazap/blt-1b-hf")

>>> prompt = "If I had to write a haiku, it would be:"
>>> inputs = tokenizer(prompt, return_tensors="pt")

>>> # Generate
>>> generate_ids = model.generate(inputs.input_ids, max_length=40, do_sample=True, temperature=0.6)
>>> result = tokenizer.batch_decode(generate_ids, skip_special_tokens=True, clean_up_tokenization_spaces=False)[0]
>>> print(result)
If I had to write a haiku, it would be: "Snowflakes gently fall" - simple, yet peaceful.
I love the idea of snowflakes gently falling, each one
```

