Transformers documentation
xLSTM
Эта модель была опубликована в HF papers 07.05.2024 и добавлена в Hugging Face Transformers 25.07.2025.
xLSTM
Обзор
Модель xLSTM была предложена в работе xLSTM: Extended Long Short-Term Memory авторами Максимилианом Бекком, Корбинианом Пёппелем, Маркусом Шпанрингом, Андреасом Аурером, Олександрой Прудниковой, Михаэлем Коппом, Гюнтером Клямбауэром, Йоханнесом Брандштеттером и Сеппом Хохрайтером. xLSTM обновляет исходную архитектуру LSTM, делая её конкурентоспособной с моделями Transformer, за счёт введения экспоненциального гейтинга, расширения матричной памяти, а также параллелизуемых обучения и обработки входных данных.
Вариант модели 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. Исходный код можно найти здесь.
Примечания
- Используйте левое выравнивание (left padding) для пакетной генерации. См. Сторона выравнивания.
xLSTMConfig
класс transformers.xLSTMConfig
< source >( transformers_version: str | None = Nonearchitectures: list[str] | None = Noneoutput_hidden_states: bool | None = Falsereturn_dict: bool | None = Truedtype: str | torch.dtype | None = Nonechunk_size_feed_forward: int = 0is_encoder_decoder: bool = Falseid2label: dict[int, str] | dict[str, str] | None = Nonelabel2id: dict[str, int] | dict[str, str] | None = Noneproblem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = Nonevocab_size: int = 50304hidden_size: int = 4096embedding_dim: int | None = Nonenum_hidden_layers: int = 32num_blocks: int | None = Nonenum_heads: int = 8use_bias: bool = Falsenorm_reduction_force_float32: bool = Truetie_word_embeddings: bool = Falseadd_out_norm: bool = Truenorm_eps: float = 1e-06qk_dim_factor: float = 0.5v_dim_factor: float = 1.0chunkwise_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 = 64return_last_states: bool = Trueautocast_kernel_dtype: typing.Literal['float32', 'bfloat16', 'float16'] = 'bfloat16'eps: float = 1e-06inference_state_dtype: typing.Literal['float32', 'bfloat16', 'float16'] = 'float32'ffn_proj_factor: float = 2.667ffn_round_up_to_multiple_of: int = 64gate_soft_cap: float = 15.0output_logit_soft_cap: float = 30.0weight_mode: typing.Literal['single', 'fused'] = 'single'use_cache: bool = Truepad_token_id: int | None = 1bos_token_id: int | None = 0eos_token_id: int | list[int] | None = 2max_inference_chunksize: int = 16384 )
Параметры
- vocab_size (
int, необязательный, по умолчанию50304) — Размер словаря модели. Определяет количество различных токенов, которые могут быть представлены вinput_ids. - hidden_size (
int, необязательный, по умолчанию4096) — Размерность скрытых представлений. - embedding_dim (
int, необязательный) — Размерность эмбеддингов и скрытых состояний. - num_hidden_layers (
int, необязательный, по умолчанию32) — Количество скрытых слоев в декодере Transformer. - num_blocks (
int, optional, optional, по умолчанию 32) — Количество блоков модели xLSTM; если значение не задано, используется num_hidden_layers. - num_heads (
int, optional, необязательный, по умолчанию 8) — Количество головок для слоя/ячейки xLSTM. - use_bias (
bool, optional, optional, по умолчаниюFalse) — Использовать ли смещения (bias) в модели xLSTM. - norm_reduction_force_float32 (
bool, optional, optional, по умолчаниюTrue) — Определяет, следует ли выполнять операцию нормализации с приведением типов в точности 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, необязательный, по умолчанию"native_sequence__native") — Тип ядра для режима обработки последовательностей. - step_kernel (
StepKernelType, optional, optional, по умолчанию"native") — Тип ядра для режима обработки шагов. - mode (
BackendModeType, optional, необязательный, по умолчанию"inference") — Режим работы (режим inference необходим для генерации). - chunk_size (
int, optional, optional, по умолчанию 64) — Внутренний размер блока. - return_last_states (
bool, optional, optional, по умолчаниюTrue) — Возвращать ли последние состояния / кэш внутри. Для генерации должно быть установлено в True. - autocast_kernel_dtype (
DtypeType, optional, optional, по умолчанию"bfloat16") — Тип данных (dtype) для состояний ядра. - eps (
float, необязательный, по умолчанию1e-06) — Значение epsilon, используемое слоями нормализации. - inference_state_dtype (
DtypeType, optional, optional, по умолчанию"float32") — Тип данных ядра для состояний при инференсе. - ffn_proj_factor (
float, optional, optional, по умолчанию 2.667) — Коэффициент размера проекции post-up в gated 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) — Указывает, должен ли модель возвращать последние ключи/значения внимания (не используется во всех моделях). Актуально только еслиconfig.is_decoder=Trueили если модель является генеративной моделью только с декодером. - pad_token_id (
int, необязательный, по умолчанию1) — Идентификатор токена, используемого для дополнения (padding) в словаре. - 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
Объекты конфигурации наследуются от PreTrainedConfig и могут использоваться для управления выводами модели. Подробнее читайте в документации PreTrainedConfig.
Пример:
>>> 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.configxLSTMModel
класс transformers.xLSTMModel
< source >( config: xLSTMConfig )
Параметры
- config (xLSTMConfig) — Класс конфигурации модели, содержащий все параметры модели. Инициализация с помощью файла конфигурации не загружает веса, связанные с моделью, а только конфигурацию. Чтобы загрузить веса модели, используйте метод from_pretrained().
Модель Xlstm без дополнительных слоёв, выводящая необработанные скрытые состояния.
Эта модель наследуется от PreTrainedModel. См. документацию родительского класса для общих методов, которые библиотека реализует для всех своих моделей (например, загрузка или сохранение, изменение размера входных эмбеддингов, обрезка голов и т. д.)
Эта модель также является подклассом torch.nn.Module в PyTorch. Используйте её как обычный модуль PyTorch и обращайтесь к документации PyTorch по всем вопросам, связанным с общим использованием и поведением.
forward
< source >( input_ids: typing.Optional[torch.LongTensor] = Noneinputs_embeds: typing.Optional[torch.LongTensor] = Nonecache_params: transformers.models.xlstm.modeling_xlstm.xLSTMCache | None = Noneuse_cache: bool | None = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → xLSTMOutput or tuple(torch.Tensor)
Параметры
- input_ids (
torch.LongTensorформы(batch_size, sequence_length), , необязательный) — Индексы токенов входной последовательности в словаре. По умолчанию токены отсечки (padding) игнорируются.Индексы можно получить с помощью AutoTokenizer. Подробности см. в PreTrainedTokenizer.encode() и PreTrainedTokenizer.call().
- 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) и входных данных.
Метод forward класса 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
< source >( config: xLSTMConfig )
Параметры
- config (xLSTMConfig) — Класс конфигурации модели, содержащий все параметры модели. Инициализация с помощью файла конфигурации не загружает веса, связанные с моделью, а только конфигурацию. Чтобы загрузить веса модели, используйте метод from_pretrained().
Модель Xlstm для каузального моделирования языка.
Эта модель наследуется от PreTrainedModel. См. документацию родительского класса для общих методов, которые библиотека реализует для всех своих моделей (например, загрузка или сохранение, изменение размера входных эмбеддингов, обрезка голов и т. д.)
Эта модель также является подклассом torch.nn.Module в PyTorch. Используйте её как обычный модуль PyTorch и обращайтесь к документации PyTorch по всем вопросам, связанным с общим использованием и поведением.
forward
< source >( input_ids: typing.Optional[torch.LongTensor] = Noneinputs_embeds: typing.Optional[torch.Tensor] = Nonecache_params: transformers.models.xlstm.modeling_xlstm.xLSTMCache | None = Nonelabels: typing.Optional[torch.LongTensor] = Noneuse_cache: bool | None = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → xLSTMCausalLMOutput or tuple(torch.Tensor)
Параметры
- input_ids (
torch.LongTensorформы(batch_size, sequence_length), , необязательный) — Индексы токенов входной последовательности в словаре. По умолчанию токены отсечки (padding) игнорируются.Индексы можно получить с помощью AutoTokenizer. Подробности см. в PreTrainedTokenizer.encode() и PreTrainedTokenizer.call().
- 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), необязательный) — Метки для вычисления потерь маскированного языкового моделирования. Индексы должны находиться в диапазоне[0, ..., config.vocab_size]или быть равны -100 (см. docstringinput_ids). Токены с индексами, установленными в-100, игнорируются (маскируются); потери вычисляются только для токенов с метками в диапазоне[0, ..., config.vocab_size]. - 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) и входных данных.
Метод forward класса xLSTMForCausalLM переопределяет специальный метод __call__.
Хотя рецепт для прямого прохода должен быть определён внутри этой функции, после этого следует вызывать экземпляр
Module, а не эту функцию, поскольку первый вариант обеспечивает выполнение шагов предварительной и последующей обработки, тогда как второй молча их игнорирует.
loss (
torch.Tensorформы(1,), необязательный, возвращается, если заданlabels) — Потери языковой модели (для предсказания следующего токена).logits (
torch.Tensorформы(batch_size, sequence_length, config.vocab_size)) — Оценки предсказаний языковой модели (оценки для каждого токена словаря до применения SoftMax).cache_params (
xLSTMCache, optional, содержит состояния 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).Скрытые состояния модели на выходе каждого слоя, а также необязательные выходные значения начального слоя встраивания.