Transformers documentation
xLSTM
このモデルは2024年5月7日にHF papersで公開され、2025年7月25日にHugging Face Transformersに貢献されました。
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 に記載されています。 xLSTMは、指数ゲート、行列メモリ拡張、並列化可能な学習およびインジェストを導入することで、元のLSTMアーキテクチャをTransformerモデルと競合できるレベルに更新します。
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によって提供されました。 元のコードはこちらで確認できます。
注記
- バッチ生成には左パディングを使用します。Padding sideを参照してください。
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、デフォルト値は 32) — xLSTM モデルのブロック数。None の場合は num_hidden_layers を使用します。 - num_heads (
int、任意、optional、デフォルトは 8) — xLSTM Layer/Cell のヘッド数。 - use_bias (
bool, 任意, 任意, デフォルトはFalse) — xLSTM モデルでバイアスを使用するかどうか。 - norm_reduction_force_float32 (
bool、任意、optional、デフォルトはTrue) — float32 の norm 集約演算を fp32 精度で実行するかどうかを指定します。 - tie_word_embeddings (
bool、任意、デフォルトはFalse) — モデルのtied_weights_keysマッピングに従って重み埋め込みを共有するかどうかを指定します。 - add_out_norm (
bool, 任意, 任意, デフォルトはTrue) — LMHead の前にブロックの後に出力正規化を追加するかどうかを指定します。 - norm_eps (
float、任意、デフォルトは1e-06) — レイヤーノーマライゼーション層で使用する epsilon です。 - qk_dim_factor (
float、任意、任意、デフォルト値は 0.5) — クエリとキーの次元に対するスケーリング係数。 - v_dim_factor (
float、任意、optional、デフォルト値は 1.0) — value 次元のスケール係数。 - chunkwise_kernel (
ChunkwiseKernelType、省略可、optional、デフォルトは"chunkwise--native_autograd") — チャンクワイズ処理モード用のカーネルタイプ。 - sequence_kernel (
SequenceKernelType、省略可、省略可、デフォルトは"native_sequence__native") — シーケンス処理モード用のカーネルタイプです。 - step_kernel (
StepKernelType、省略可、任意、デフォルトは"native") — ステップ処理モードのカーネルタイプです。 - mode (
BackendModeType、任意、任意、デフォルトは"inference") — 操作モード（生成には推論が必要です）。 - chunk_size (
int、任意、optional、デフォルト値は 64) — 内部チャンクサイズ。 - return_last_states (
bool、任意、optional、デフォルトはTrue) — 内部の最終状態 / キャッシュを返すかどうか。生成には True が必要です。 - autocast_kernel_dtype (
DtypeType、任意、optional、デフォルトは"bfloat16") — ステート用のカーネルのデータ型です。 - eps (
float、任意、デフォルトは1e-06) — レイヤーノーマライゼーション層で使用する epsilon です。 - inference_state_dtype (
DtypeType、任意、optional、デフォルトは"float32") — 推論時のステートに使用するカーネルのデータ型です。 - ffn_proj_factor (
float、任意、任意、デフォルトは 2.667) — アップ投影後のゲート付き Feed Forward ネットワークのサイズ係数。 - ffn_round_up_to_multiple_of (
int、任意、optional、デフォルト値は 64) — アップ投影後のゲート付き Feed Forward ネットワークのサイズ係数の丸め値。 - gate_soft_cap (
float、任意、optional、デフォルト値は 15.0) — ゲートのソフトキャップのスケール。 - output_logit_soft_cap (
float、任意、任意、デフォルトは 30.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、任意、デフォルトは0) — 語彙におけるストリーム開始に使用されるトークン ID。 - eos_token_id (
Union[int, list[int]]、任意、デフォルトは2) — 語彙内でストリーム終了に使用されるトークン ID。 - max_inference_chunksize (
int、任意、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() メソッドを参照してください。
Model は、特定のヘッドを付加せずに生の隠れ状態を出力する、素の Xlstm です。
このモデルは PreTrainedModel を継承しています。すべてのモデルに実装されている汎用的なメソッド（ダウンロードや保存、入力埋め込みのリサイズ、ヘッドのプルーニングなど）については、スーパークラスのドキュメントを参照してください。
このモデルは、PyTorchのtorch.nn.Moduleのサブクラスでもあります。 通常のPyTorch Moduleとして使用し、一般的な使用方法や動作に関する詳細については、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.FloatTensor)
パラメータ
- input_ids (
torch.LongTensorの形状(batch_size, sequence_length), 、省略可) — 語彙における入力シーケンスのトークンインデックスです。デフォルトではパディングは無視されます。インデックスはAutoTokenizerを使用して取得できます。詳細については、PreTrainedTokenizer.encode()およびPreTrainedTokenizer.call()を参照してください。
- 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)や入力に応じて、さまざまな要素で構成されます。
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のタプル（埋め込み層を持つモデルの場合、埋め込みの出力用が 1 つ、各層の出力用が 1 つずつ）で、形状は(batch_size, sequence_length, hidden_size)です。各層の出力におけるモデルのHidden-states、および任意の初期埋め込み出力。
xLSTMLMHeadModel
クラス transformers.xLSTMForCausalLM
< source >( config: xLSTMConfig )
パラメータ
- config (xLSTMConfig) — モデルのパラメータをすべて含むモデル設定クラスです。設定ファイルで初期化しても、モデルに関連する重みは読み込まれず、設定のみが読み込まれます。モデルの重みをロードするには、from_pretrained() メソッドを参照してください。
因果言語モデリング用のXlstmモデル。
このモデルは PreTrainedModel を継承しています。すべてのモデルに実装されている汎用的なメソッド（ダウンロードや保存、入力埋め込みのリサイズ、ヘッドのプルーニングなど）については、スーパークラスのドキュメントを参照してください。
このモデルは、PyTorchのtorch.nn.Moduleのサブクラスでもあります。 通常のPyTorch Moduleとして使用し、一般的な使用方法や動作に関する詳細については、PyTorchのドキュメントを参照してください。
forward
< source >( input_ids: typing.Optional[torch.LongTensor] = Noneinputs_embeds: typing.Optional[torch.FloatTensor] = 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.FloatTensor)
パラメータ
- input_ids (
torch.LongTensorの形状(batch_size, sequence_length), 、省略可) — 語彙における入力シーケンスのトークンインデックスです。デフォルトではパディングは無視されます。インデックスはAutoTokenizerを使用して取得できます。詳細については、PreTrainedTokenizer.encode()およびPreTrainedTokenizer.call()を参照してください。
- inputs_embeds (
torch.FloatTensor、形状(batch_size, sequence_length, hidden_size)、任意) —input_idsを渡す代わりに、埋め込み表現を直接渡すこともできます。これは、モデル内部の埋め込みルックアップ行列よりも、input_idsのインデックスを対応するベクトルに変換する方法をより細かく制御したい場合に有用です。 - cache_params (
xLSTMCache、任意) — RNN の状態を保持する xLSTMCache です。 - labels (
torch.LongTensor、shape(batch_size, sequence_length)、任意) — マスク言語モデリング損失を計算するためのラベルです。インデックスは[0, ..., config.vocab_size]の範囲内であるか、-100 である必要があります（input_idsの docstring を参照）。インデックスが-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）や入力に応じて、さまざまな要素で構成されます。
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のタプル（埋め込み層を持つモデルの場合、埋め込みの出力用が 1 つ、各層の出力用が 1 つずつ）で、形状は(batch_size, sequence_length, hidden_size)です。各層の出力におけるモデルのHidden-states、および任意の初期埋め込み出力。