# xLSTM

## Обзор

Модель xLSTM была предложена в работе [xLSTM: Extended Long Short-Term Memory](https://huggingface.co/papers/2405.04517) авторами Максимилианом Бекком*, Корбинианом Пёппелем*, Маркусом Шпанрингом, Андреасом Ауром, Олександрой Прудниковой, Михаэлем Коппом, Гюнтером Клямбауэром, Йоханнесом Брандштеттером и Сеппом Хохрайтером. xLSTM обновляет исходную архитектуру LSTM, чтобы сделать её конкурентоспособной с моделями Transformer, за счёт введения экспоненциального гейтинга, расширения матричной памяти, а также параллелизуемого обучения и обработки данных.

Вариант [модели 7B](https://huggingface.co/NX-AI/xLSTM-7b) был обучен командой xLSTM: Максимилианом Бекком, Корбинианом Пёппелем, Филлипом Липпе, Ричардом Курле, Патриком Блесом, Себастьяном Бёком и Сеппом Хохрайтером из NXAI.

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

*В 1990-х годах были введены постоянная ошибка карусели и гейтинг как центральные идеи Long Short-Term Memory (LSTM). С тех пор LSTMs выдержали испытание временем и внесли вклад в многочисленные успехи глубокого обучения, в частности, они составили основу первых Large Language Models (LLMs). Однако появление технологии Transformer с параллелизуемым self-attention в её ядре ознаменовало начало новой эры, в которой LSTMs уступают в масштабируемости. Теперь мы задаём простой вопрос: насколько далеко мы можем продвинуться в моделировании языка, масштабируя LSTMs до миллиардов параметров, используя новейшие методы современных LLM, но смягчая известные ограничения LSTMs? Во-первых, мы вводим экспоненциальный гейтинг с соответствующими методами нормализации и стабилизации. Во-вторых, мы модифицируем структуру памяти LSTM, получая: (i) sLSTM с скалярной памятью, скалярным обновлением и новым смешиванием памяти, (ii) mLSTM, полностью параллелизуемую, с матричной памятью и правилом обновления ковариации. Интеграция этих расширений LSTM в каркасы из остаточных блоков даёт блоки xLSTM, которые затем остаточно складываются в архитектуры xLSTM. Экспоненциальный гейтинг и модифицированные структуры памяти повышают возможности xLSTM, позволяя им демонстрировать результаты, сопоставимые с передовыми Transformers и State Space Models, как по производительности, так и по масштабируемости.*

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

## Примечания

- Используйте левое выравнивание (left padding) для пакетной генерации. См. [Сторона выравнивания](../llm_tutorial#padding-side).

## xLSTMConfig[[transformers.xLSTMConfig]]

#### transformers.xLSTMConfig[[transformers.xLSTMConfig]]

```python
transformers.xLSTMConfig(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 = 50304, hidden_size: int = 4096, embedding_dim: int | None = None, num_hidden_layers: int = 32, num_blocks: int | None = None, num_heads: int = 8, use_bias: bool = False, norm_reduction_force_float32: bool = True, tie_word_embeddings: bool = False, add_out_norm: bool = True, norm_eps: float = 1e-06, qk_dim_factor: float = 0.5, v_dim_factor: float = 1.0, chunkwise_kernel: typing.Literal['chunkwise--native_autograd', 'parallel--native_autograd'] = 'chunkwise--native_autograd', sequence_kernel: typing.Literal['native_sequence__native'] = 'native_sequence__native', step_kernel: typing.Literal['native'] = 'native', mode: typing.Literal['train', 'train_with_padding', 'inference'] = 'inference', chunk_size: int = 64, return_last_states: bool = True, autocast_kernel_dtype: typing.Literal['float32', 'bfloat16', 'float16'] = 'bfloat16', eps: float = 1e-06, inference_state_dtype: typing.Literal['float32', 'bfloat16', 'float16'] = 'float32', ffn_proj_factor: float = 2.667, ffn_round_up_to_multiple_of: int = 64, gate_soft_cap: float = 15.0, output_logit_soft_cap: float = 30.0, weight_mode: typing.Literal['single', 'fused'] = 'single', use_cache: bool = True, pad_token_id: int | None = 1, bos_token_id: int | None = 0, eos_token_id: int | list[int] | None = 2, max_inference_chunksize: int = 16384)
```

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

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

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

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

embedding_dim (`int`, *необязательный*) : Размерность эмбеддингов и скрытых состояний.

num_hidden_layers (`int`, *необязательный*, по умолчанию `32`) : Количество скрытых слоев в декодере Transformer.

num_blocks (`int`, optional, *optional*, по умолчанию 32) : Количество блоков модели xLSTM; если значение равно None, используется num_hidden_layers.

num_heads (`int`, optional, *optional*, по умолчанию 8) : Количество голов для слоя/ячейки xLSTM.

use_bias (`bool`, optional, *optional*, по умолчанию `False`) : Использовать ли смещения в модели xLSTM.

norm_reduction_force_float32 (`bool`, optional, *optional*, по умолчанию `True`) : Указывает, следует ли выполнять операцию нормализации с приведением к float32 в точности fp32.

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

add_out_norm (`bool`, optional, *optional*, по умолчанию `True`) : Добавлять ли нормализацию вывода после блоков перед LMHead.

norm_eps (`float`, *необязательный*, по умолчанию `1e-06`) : Значение epsilon, используемое слоями нормализации.

qk_dim_factor (`float`, optional, *optional*, по умолчанию 0.5) : Коэффициент масштабирования для размерности запроса и ключа.

v_dim_factor (`float`, optional, *optional*, по умолчанию 1.0) : Коэффициент масштабирования для размерности значений.

chunkwise_kernel (`ChunkwiseKernelType`, optional, *optional*, по умолчанию `"chunkwise--native_autograd"`) : Тип ядра для режима обработки по чанкам.

sequence_kernel (`SequenceKernelType`, optional, *optional*, по умолчанию `"native_sequence__native"`) : Тип ядра для режима обработки последовательностей.

step_kernel (`StepKernelType`, optional, *optional*, по умолчанию `"native"`) : Тип ядра для режима обработки шагов.

mode (`BackendModeType`, optional, *optional*, по умолчанию `"inference"`) : Режим работы (режим inference необходим для генерации).

chunk_size (`int`, optional, *optional*, по умолчанию 64) : Внутренний размер блока.

return_last_states (`bool`, optional, *optional*, по умолчанию `True`) : Если нужно возвращать последние состояния / кэш внутри. Для генерации требуется значение True.

autocast_kernel_dtype (`DtypeType`, optional, *optional*, по умолчанию `"bfloat16"`) : Тип данных ядра для состояний.

eps (`float`, *необязательный*, по умолчанию `1e-06`) : Значение epsilon, используемое слоями нормализации.

inference_state_dtype (`DtypeType`, optional, *optional*, по умолчанию `"float32"`) : Тип данных ядра для состояний при инференсе.

ffn_proj_factor (`float`, optional, *optional*, по умолчанию 2.667) : Коэффициент размера пост-ап проекции в гейтированной сети Feed Forward.

ffn_round_up_to_multiple_of (`int`, optional, *optional*, по умолчанию 64) : Множитель размера для округления значения пост-ап проекции в gated Feed Forward сети.

gate_soft_cap (`float`, optional, *optional*, по умолчанию 15.0) : Масштаб мягкого ограничения гейта.

output_logit_soft_cap (`float`, optional, *optional*, по умолчанию 30.0) : Масштаб мягкого ограничения для выходных логитов.

weight_mode (`Literal`, *необязательный*, по умолчанию `"single"`) : Разделяются ли параллельные линейные слои или объединяются (single).

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

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

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

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

max_inference_chunksize (`int`, optional, *optional*, по умолчанию 16384) : Ограничивает размер блока для инференса, чтобы сэкономить память.

Это класс конфигурации для хранения настроек модели xLSTMModel. Он используется для создания модели Xlstm в соответствии с указанными аргументами, определяя архитектуру модели. Создание конфигурации с параметрами по умолчанию даст конфигурацию, аналогичную конфигурации модели [NX-AI/xLSTM-7b](https://huggingface.co/NX-AI/xLSTM-7b)

Объекты конфигурации наследуются от [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 xLSTMConfig, xLSTMModel

>>> # Initializing a xLSTM configuration
>>> configuration = xLSTMConfig()

>>> # Initializing a model (with random weights) from the configuration
>>> model = xLSTMModel(configuration)

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

## xLSTMModel[[transformers.xLSTMModel]]

#### transformers.xLSTMModel[[transformers.xLSTMModel]]

```python
transformers.xLSTMModel(config: xLSTMConfig)
```

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

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

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

Модель Xlstm без дополнительных слоёв, выводящая необработанные скрытые состояния.

Эта модель наследуется от [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.xLSTMModel.forward]]

```python
forward(input_ids: typing.Optional[torch.LongTensor] = None, inputs_embeds: typing.Optional[torch.LongTensor] = None, cache_params: transformers.models.xlstm.modeling_xlstm.xLSTMCache | None = None, use_cache: bool | None = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

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

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

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)

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

cache_params (`xLSTMCache`, *необязательный*) : xLSTMCache, содержащий состояния RNN.

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

**Возвращает:** `xLSTMOutput` или `tuple(torch.Tensor)`

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

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

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

- **last_hidden_state** (`torch.Tensor` формы `(batch_size, sequence_length, hidden_size)`, *необязательный*) -- Последовательность скрытых состояний на выходе последнего слоя модели.
- **cache_params** (`~models.xlstm.modeling_xlstm.xLSTMCache`, *необязательный*) -- Состояние модели на последнем шаге времени. Может использоваться в forward-методе вместе с новыми `input_ids`, чтобы избежать передачи старых `input_ids`.
- **hidden_states** (`tuple[torch.Tensor]`, *необязательный*, возвращается, если передано `output_hidden_states=True` или если `config.output_hidden_states=True`) -- Кортеж `torch.Tensor` (один для вывода слоя встраиваний, если модель имеет слой встраиваний, + один для вывода каждого слоя) формы `(batch_size, sequence_length, hidden_size)`.

  Скрытые состояния модели на выходе каждого слоя, а также необязательные выходные значения начального слоя встраивания.

## xLSTMLMHeadModel[[transformers.xLSTMForCausalLM]]

#### transformers.xLSTMForCausalLM[[transformers.xLSTMForCausalLM]]

```python
transformers.xLSTMForCausalLM(config: xLSTMConfig)
```

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

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

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

Модель Xlstm для каузального моделирования языка.

Эта модель наследуется от [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.xLSTMForCausalLM.forward]]

```python
forward(input_ids: typing.Optional[torch.LongTensor] = None, inputs_embeds: typing.Optional[torch.Tensor] = None, cache_params: transformers.models.xlstm.modeling_xlstm.xLSTMCache | None = None, labels: typing.Optional[torch.LongTensor] = None, use_cache: bool | None = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

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

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

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)

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

cache_params (`xLSTMCache`, *необязательный*) : xLSTMCache, содержащий состояния RNN.

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

**Возвращает:** `xLSTMCausalLMOutput` или `tuple(torch.Tensor)`

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

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

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

- **loss** (`torch.Tensor` формы `(1,)`, *необязательный*, возвращается, если задан `labels`) -- Потеря языковой модели (для предсказания следующего токена).
- **logits** (`torch.Tensor` формы `(batch_size, sequence_length, config.vocab_size)`) — Оценки предсказаний языковой модели (оценки для каждого токена словаря до применения SoftMax).
- **cache_params** (`xLSTMCache`, *необязательный*, содержит состояния RNN) -- Состояние модели на последнем шаге времени. Может использоваться в forward-методе вместе с новыми `input_ids`, чтобы избежать передачи старых `input_ids`.
- **hidden_states** (`tuple[torch.Tensor]`, *необязательный*, возвращается, если передано `output_hidden_states=True` или если `config.output_hidden_states=True`) -- Кортеж `torch.Tensor` (один для вывода слоя встраиваний, если модель имеет слой встраиваний, + один для вывода каждого слоя) формы `(batch_size, sequence_length, hidden_size)`.

  Скрытые состояния модели на выходе каждого слоя, а также необязательные выходные значения начального слоя встраивания.

Пример:

```python
```

