# xLSTM

## 概要

xLSTMモデルは、Maximilian Beck*、Korbinian Pöppel*、Markus Spanring、Andreas Auer、Oleksandra Prudnikova、Michael Kopp、Günter Klambauer、Johannes Brandstetter、Sepp Hochreiter による [xLSTM: Extended Long Short-Term Memory](https://huggingface.co/papers/2405.04517) で提案されました。xLSTMは、指数ゲート、行列メモリ拡張、並列化可能な学習およびインジェストを導入することで、元のLSTMアーキテクチャをTransformerモデルと競合できるレベルに更新しています。

[7Bモデル](https://huggingface.co/NX-AI/xLSTM-7b)のバリアントは、NXAIのxLSTMチームであるMaximilian Beck、Korbinian Pöppel、Phillip Lippe、Richard Kurle、Patrick Blies、Sebastian Böck、Sepp Hochreiterによって学習されました。

論文の抄録は以下の通りです。

*1990年代、定数誤差カレセルとゲーティングは、Long Short-Term Memory (LSTM) の中心的なアイデアとして導入されました。以来、LSTM は時を経てその価値を証明し、数多くの深層学習の成功事例に貢献してきました。特に、最初の Large Language Models (LLMs) を構成するものとなりました。しかし、並列化可能な自己注意機構を核とする Transformer 技術の登場は、新たな時代の幕開けを告げ、大規模なスケールにおいて LSTM を凌駕しました。ここで、単純な問いを提起します。LSTM を数十億パラメータ規模までスケールさせ、最新の LLM の手法を活用しつつ、LSTM の既知の限界を緩和した場合、言語モデリングにおいてどこまで到達できるのでしょうか。まず、適切な正規化と安定化手法を備えた指数ゲーティングを導入します。次に、LSTM のメモリ構造を変更し、(i) スカラーメモリ、スカラー更新、および新しいメモリ混合を備えた sLSTM、(ii) 行列メモリと共分散更新ルールを備え、完全に並列化可能な mLSTM を得ます。これらの LSTM の拡張を残差ブロックの骨格に統合することで xLSTM ブロックが得られ、これらを残差スタックすることで xLSTM アーキテクチャが構築されます。指数ゲーティングと変更されたメモリ構造により、xLSTM の能力が向上し、性能とスケーリングの両面で、最先端の Transformer や State Space Models との比較において有利に機能します。*

このモデルは[NX-AI](https://huggingface.co/NX-AI)によって提供されました。元のコードは[こちら](https://github.com/NX-AI/xlstm)で確認できます。

## 注記

- バッチ生成には左パディングを使用します。[Padding side](../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/main/src/transformers/models/xlstm/configuration_xlstm.py#L58)

**パラメータ:**

vocab_size (`int`、*任意*、デフォルトは`50304`) : モデルの語彙サイズ。`input_ids`で表現できるトークンの種類数を定義します。

hidden_size (`int`、*任意*、デフォルトは`4096`) : 隠れ表現の次元数。

embedding_dim (`int`, *任意*) : 埋め込みおよび隠れ状態の次元数。

num_hidden_layers (`int`、*任意*、デフォルトは`32`) : Transformerデコーダーの隠れ層の数。

num_blocks (`int`、省略可能、*optional*、デフォルト値は 32) : xLSTM モデルのブロック数です。None の場合は num_hidden_layers が使用されます。

num_heads (`int`、任意、*optional*、デフォルトは 8) : xLSTM Layer/Cell のヘッド数。

use_bias (`bool`、任意、*optional*、デフォルトは`False`) : xLSTMモデルでバイアスを使用するかどうか。

norm_reduction_force_float32 (`bool`、省略可能、*optional*、デフォルトは`True`) : float32のnorm reduction演算をfp32精度で実行することを強制するかどうか。

tie_word_embeddings (`bool`, *任意*, デフォルトは `False`) : モデルの `tied_weights_keys` マッピングに従って重み埋め込みを共有するかどうか。

add_out_norm (`bool`、省略可能、*optional*、デフォルトは`True`) : LMHeadの前にブロックの後に出力正規化を追加するかどうか。

norm_eps (`float`、*任意*、デフォルトは`1e-06`) : Layer Normalization 層で使用する epsilon です。

qk_dim_factor (`float`、任意、*optional*、デフォルト値は 0.5) : クエリとキーの次元に対するスケーリング係数。

v_dim_factor (`float`、任意、*optional*、デフォルト値は 1.0) : 値次元のスケール係数。

chunkwise_kernel (`ChunkwiseKernelType`、任意、*optional*、デフォルトは`"chunkwise--native_autograd"`) : チャンクワイズ処理モード用のカーネルタイプ。

sequence_kernel (`SequenceKernelType`、任意、*optional*、デフォルトは`"native_sequence__native"`) : シーケンス処理モードのカーネルタイプ。

step_kernel (`StepKernelType`、任意、*optional*、デフォルトは`"native"`) : ステップ処理モードのカーネルタイプ。

mode (`BackendModeType`、任意、*optional*、デフォルトは`"inference"`) : 操作モード（生成には推論が必要です）。

chunk_size (`int`、任意、*optional*、デフォルト値は 64) : 内部チャンクサイズ。

return_last_states (`bool`、任意、*optional*、デフォルトは`True`) : 内部の最終状態/キャッシュを返すかどうか。生成にはTrueが必要です。

autocast_kernel_dtype (`DtypeType`、任意、*optional*、デフォルトは`"bfloat16"`) : 状態のカーネルのデータ型。

eps (`float`、*任意*、デフォルトは`1e-06`) : Layer Normalization 層で使用する epsilon です。

inference_state_dtype (`DtypeType`、任意、*optional*、デフォルトは`"float32"`) : 推論時のステートに使用するカーネルのdtype。

ffn_proj_factor (`float`、任意、*optional*、デフォルト値は 2.667) : 後段のアッププロジェクションを持つゲート付き Feed Forward ネットワークのサイズ係数。

ffn_round_up_to_multiple_of (`int`、任意、*optional*、デフォルトは 64) : 後段のアッププロジェクションを持つゲート付き Feed Forward ネットワークのサイズ係数の丸め値。

gate_soft_cap (`float`、任意、*optional*、デフォルト値は 15.0) : Gate のソフトキャップのスケール。

output_logit_soft_cap (`float`、任意、*optional*、デフォルト値は 3.0) : 出力 logits のソフトキャップのスケール。

weight_mode (`Literal`, *任意*、デフォルトは`"single"`) : 並列線形レイヤーを分離するか融合（single）するかを指定します。

use_cache (`bool`、*任意*、デフォルトは `True`) : モデルが最後のキー/バリューアテンションを返すかどうか（すべてのモデルで利用されるわけではありません）。`config.is_decoder=True` の場合、またはモデルがデコーダー専用の生成モデルである場合にのみ関連します。

pad_token_id (`int`, *任意*, デフォルトは `1`) : 語彙内でパディングに使用されるトークン ID。

bos_token_id (`int`, *optional*, デフォルトは `0`) : 語彙内でストリームの開始に使用されるトークン ID。

eos_token_id (`Union[int, list[int]]`、*任意*、デフォルトは`2`) : 語彙内でストリーム終了に使用されるトークン ID。

max_inference_chunksize (`int`、任意、*optional*、デフォルト値は 16384) : メモリを節約するために、推論時のチャンクサイズを制限します。

これはの設定を保存するための設定クラスです。指定された引数に基づいてXlstmモデルをインスタンス化し、モデルのアーキテクチャを定義するために使用されます。デフォルト値で設定をインスタンス化すると、[NX-AI/xLSTM-7b](https://huggingface.co/NX-AI/xLSTM-7b)と類似した設定が得られます。

設定オブジェクトは [PreTrainedConfig](/docs/transformers/main/ja/main_classes/configuration#transformers.PreTrainedConfig) を継承し、モデルの出力を制御するために使用できます。詳細については、[PreTrainedConfig](/docs/transformers/main/ja/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/main/src/transformers/models/xlstm/modeling_xlstm.py#L1394)

**パラメータ:**

config ([xLSTMConfig](/docs/transformers/main/ja/model_doc/xlstm#transformers.xLSTMConfig)) : モデルのパラメータをすべて含むモデル設定クラスです。設定ファイルで初期化しても、モデルに関連する重みは読み込まれず、設定のみが読み込まれます。モデルの重みをロードするには、[from_pretrained()](/docs/transformers/main/ja/main_classes/model#transformers.PreTrainedModel.from_pretrained) メソッドを確認してください。

Model は、特定のヘッドを付加せずに生の隠れ状態を出力する、素の Xlstm です。

このモデルは [PreTrainedModel](/docs/transformers/main/ja/main_classes/model#transformers.PreTrainedModel) を継承しています。ライブラリがすべてのモデルに対して実装している汎用的なメソッド（ダウンロードや保存、入力埋め込みのリサイズ、ヘッドのプルーニングなど）については、スーパークラスのドキュメントを参照してください。

このモデルは、PyTorchの[torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module)のサブクラスでもあります。通常のPyTorch Moduleとして使用し、一般的な使用方法や動作に関する詳細については、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/main/src/transformers/models/xlstm/modeling_xlstm.py#L1411)

**パラメータ:**

input_ids (`torch.LongTensor`、shape `(batch_size, sequence_length)`、*任意*) : 語彙における入力シーケンスのトークンインデックスです。デフォルトでは、パディングは無視されます。インデックスは [AutoTokenizer](/docs/transformers/main/ja/model_doc/auto#transformers.AutoTokenizer) を使用して取得できます。詳細については、[PreTrainedTokenizer.encode()](/docs/transformers/main/ja/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) および [PreTrainedTokenizer.__call__()](/docs/transformers/main/ja/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__) を参照してください。 [入力IDとは何ですか？](../glossary#input-ids)

inputs_embeds (`torch.LongTensor`、shape `(batch_size, sequence_length, hidden_size)`、*任意*) : `input_ids` を渡す代わりに、埋め込み表現を直接渡すこともできます。これは、モデル内部の埋め込みルックアップ行列よりも、`input_ids` のインデックスを対応するベクトルに変換する方法をより細かく制御したい場合に便利です。

cache_params (`xLSTMCache`, *任意*) : RNNの状態を保持するxLSTMCacheです。

use_cache (`bool`, *任意*) : `True`に設定すると、`past_key_values`のキーバリュー状態が返され、デコーディングの高速化に利用できます（`past_key_values`を参照）。

**戻り値:** `xLSTMOutput` または `tuple(torch.FloatTensor)`

`xLSTMOutput`、または`torch.FloatTensor`のタプル（`return_dict=False`が渡された場合、または`config.return_dict=False`の場合）。設定（[xLSTMConfig](/docs/transformers/main/ja/model_doc/xlstm#transformers.xLSTMConfig)）や入力に応じて、さまざまな要素で構成されます。

[xLSTMModel](/docs/transformers/main/ja/model_doc/xlstm#transformers.xLSTMModel)のforwardメソッドは、`__call__`特殊メソッドをオーバーライドします。

この関数内でフォワードパスの手順を定義する必要がありますが、その後、この関数ではなく`Module`インスタンスを呼び出すべきです。前者は前処理と後処理の実行を適切に処理するのに対し、後者はそれらを無視してしまいます。

- **last_hidden_state** (`torch.FloatTensor`、shape `(batch_size, sequence_length, hidden_size)`、*optional*) -- モデルの最終層の出力における隠れ状態のシーケンス。
- **cache_params** (`~models.xlstm.modeling_xlstm.xLSTMCache`, *任意*) -- 最終タイムステップにおけるモデルの状態。次の`input_ids`と組み合わせて forward メソッドで使用することで、古い`input_ids`を指定することを回避できます。
- **hidden_states** (`tuple[torch.FloatTensor]`、*optional*、`output_hidden_states=True` が渡された場合または `config.output_hidden_states=True` の場合に返されます) -- `torch.FloatTensor` のタプル（モデルに埋め込み層がある場合はその出力用 + 各層の出力用）で、形状は `(batch_size, sequence_length, hidden_size)` です。

  各層の出力におけるモデルのHidden-states、および任意の初期埋め込み出力。

## xLSTMLMHeadModel[[transformers.xLSTMForCausalLM]]

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

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

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/models/xlstm/modeling_xlstm.py#L1517)

**パラメータ:**

config ([xLSTMConfig](/docs/transformers/main/ja/model_doc/xlstm#transformers.xLSTMConfig)) : モデルのパラメータをすべて含むモデル設定クラスです。設定ファイルで初期化しても、モデルに関連する重みは読み込まれず、設定のみが読み込まれます。モデルの重みをロードするには、[from_pretrained()](/docs/transformers/main/ja/main_classes/model#transformers.PreTrainedModel.from_pretrained) メソッドを確認してください。

因果言語モデリング用のXlstmモデル。

このモデルは [PreTrainedModel](/docs/transformers/main/ja/main_classes/model#transformers.PreTrainedModel) を継承しています。ライブラリがすべてのモデルに対して実装している汎用的なメソッド（ダウンロードや保存、入力埋め込みのリサイズ、ヘッドのプルーニングなど）については、スーパークラスのドキュメントを参照してください。

このモデルは、PyTorchの[torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module)のサブクラスでもあります。通常のPyTorch Moduleとして使用し、一般的な使用方法や動作に関する詳細については、PyTorchのドキュメントを参照してください。

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

```python
forward(input_ids: typing.Optional[torch.LongTensor] = None, inputs_embeds: typing.Optional[torch.FloatTensor] = 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/main/src/transformers/models/xlstm/modeling_xlstm.py#L1537)

**パラメータ:**

input_ids (`torch.LongTensor`、shape `(batch_size, sequence_length)`、*任意*) : 語彙における入力シーケンスのトークンインデックスです。デフォルトでは、パディングは無視されます。インデックスは [AutoTokenizer](/docs/transformers/main/ja/model_doc/auto#transformers.AutoTokenizer) を使用して取得できます。詳細については、[PreTrainedTokenizer.encode()](/docs/transformers/main/ja/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) および [PreTrainedTokenizer.__call__()](/docs/transformers/main/ja/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__) を参照してください。 [入力IDとは何ですか？](../glossary#input-ids)

inputs_embeds (`torch.FloatTensor`、shape `(batch_size, sequence_length, hidden_size)`、*任意*) : `input_ids` を渡す代わりに、埋め込み表現を直接渡すこともできます。これは、モデル内部の埋め込み参照行列よりも、`input_ids` のインデックスを対応するベクトルに変換する方法をより細かく制御したい場合に有用です。

cache_params (`xLSTMCache`, *任意*) : RNNの状態を保持するxLSTMCacheです。

labels (`torch.LongTensor`、形状 `(batch_size, sequence_length)`、*任意*) : マスク言語モデリング損失を計算するためのラベル。インデックスは `[0, ..., config.vocab_size]` の範囲内であるか、-100 である必要があります（`input_ids` のドキュメント文字列を参照）。インデックスが `-100` に設定されたトークンは無視（マスク）され、損失は `[0, ..., config.vocab_size]` の範囲内のラベルを持つトークンに対してのみ計算されます。

use_cache (`bool`, *任意*) : `True`に設定すると、`past_key_values`のキーバリュー状態が返され、デコーディングの高速化に利用できます（`past_key_values`を参照）。

**戻り値:** `xLSTMCausalLMOutput` または `tuple(torch.FloatTensor)`

`xLSTMCausalLMOutput`、または`torch.FloatTensor`のタプル（`return_dict=False`が渡された場合、または`config.return_dict=False`の場合）。設定（[xLSTMConfig](/docs/transformers/main/ja/model_doc/xlstm#transformers.xLSTMConfig)）と入力に応じて、さまざまな要素で構成されます。

[xLSTMForCausalLM](/docs/transformers/main/ja/model_doc/xlstm#transformers.xLSTMForCausalLM) の forward メソッドは、`__call__` という特殊メソッドをオーバーライドします。

この関数内でフォワードパスの手順を定義する必要がありますが、その後、この関数ではなく`Module`インスタンスを呼び出すべきです。前者は前処理と後処理の実行を適切に処理するのに対し、後者はそれらを無視してしまいます。

- **loss** (`torch.FloatTensor`、shape `(1,)`、*optional*、`labels` が指定された場合に返されます) -- 言語モデリングの損失(次のトークンの予測用)。
- **logits** (`torch.FloatTensor`、shape `(batch_size, sequence_length, config.vocab_size)`) -- 言語モデリングヘッドの予測スコア（SoftMax 適用前の各語彙トークンのスコア）。
- **cache_params** (`xLSTMCache`、*optional*、RNNの状態を保持) -- 最後のタイムステップにおけるモデルの状態。次の`input_ids`と組み合わせてforwardメソッドで使用することで、古い`input_ids`を指定することを回避できます。
- **hidden_states** (`tuple[torch.FloatTensor]`、*optional*、`output_hidden_states=True` が渡された場合または `config.output_hidden_states=True` の場合に返されます) -- `torch.FloatTensor` のタプル（モデルに埋め込み層がある場合はその出力用 + 各層の出力用）で、形状は `(batch_size, sequence_length, hidden_size)` です。

  各層の出力におけるモデルのHidden-states、および任意の初期埋め込み出力。

例:

```python
```