# Mamba

[Mamba](https://huggingface.co/papers/2312.00752)は、長文脈の処理におけるTransformersの計算効率の低さを回避するために設計された、選択型構造化状態空間モデル（SSM）です。完全にアテンション機構を排除したアーキテクチャであり、H3とゲート付きMLPブロック（Mambaブロック）の組み合わせで構成されています。Mambaの「コンテンツベースの推論」により、現在のトークンに応じて入力の特定の部分に焦点を当てることができます。また、Mambaは畳み込み演算の欠如を補うために、新しいハードウェア対応の並列アルゴリズムを採用しています。その結果、Mambaは高速な推論を実現し、非常に長いシーケンスにもスケーリングできます。

すべてのオリジナルの Mamba チェックポイントは、[State Space Models](https://huggingface.co/state-spaces) 組織の下で確認できます。

> [!TIP]
> このモデルは [Molbap](https://huggingface.co/Molbap) と [AntonV](https://huggingface.co/AntonV) によって提供されました。Mamba をさまざまな言語タスクに適用する方法の例については、右側のサイドバーにある Mamba モデルをクリックしてください。

以下の例では、[Pipeline](/docs/transformers/main/ja/main_classes/pipelines#transformers.Pipeline)、[AutoModel](/docs/transformers/main/ja/model_doc/auto#transformers.AutoModel)、およびコマンドラインからテキストを生成する方法を示しています。

```python
from transformers import pipeline

pipeline = pipeline(
    task="text-generation",
    model="state-spaces/mamba-130m-hf",
    device=0
)
pipeline("Plants create energy through a process known as")
```

```python
from transformers import AutoModelForCausalLM, AutoTokenizer

tokenizer = AutoTokenizer.from_pretrained("state-spaces/mamba-130m-hf")
model = AutoModelForCausalLM.from_pretrained("state-spaces/mamba-130m-hf", device_map="auto")
input_ids = tokenizer("Plants create energy through a process known as", return_tensors="pt").to(model.device)

output = model.generate(**input_ids)
print(tokenizer.decode(output[0], skip_special_tokens=True))
```

Quantization は、重みを低精度で表現することで、大規模モデルのメモリ負荷を軽減します。利用可能な Quantization バックエンドの詳細については、[Quantization](../quantization/overview) の概要を参照してください。

以下の例では、[torchao](../quantization/torchao)を使用して、重みを4ビット整数にのみ量子化しています。

```python
from torchao.quantization import Int4WeightOnlyConfig

from transformers import AutoModelForCausalLM, AutoTokenizer, TorchAoConfig

quantization_config = Int4WeightOnlyConfig(group_size=128)
quantization_config = TorchAoConfig(quant_type=quant_config)
tokenizer = AutoTokenizer.from_pretrained("state-spaces/mamba-2.8b-hf")
model = AutoModelForCausalLM.from_pretrained("state-spaces/mamba-2.8b-hf", quantization_config=quantization_config, device_map="auto")
input_ids = tokenizer("Plants create energy through a process known as", return_tensors="pt").to(model.device)

output = model.generate(**input_ids)
print(tokenizer.decode(output[0], skip_special_tokens=True))
```

## 注記

- 現在の実装では、元のCUDAカーネルを使用しています。FlashAttentionに相当する実装は、[mamba-ssm](https://github.com/state-spaces/mamba)および[causal_conv1d](https://github.com/Dao-AILab/causal-conv1d)リポジトリにホストされています。ハードウェアが対応している場合は、これらをインストールしてください。
- Mambaスタックは、`Attention`レイヤーと同等の`mixer`レイヤーを積み重ねています。Mambaの主要なロジックは`MambaMixer`クラスにあります。
- 以下の例では、[PEFT](https://huggingface.co/docs/peft)を使用してMambaをファインチューニングする方法を示します。

  ```py
  from datasets import load_dataset
  from trl import SFTConfig, SFTTrainer
  from peft import LoraConfig

  model_id = "state-spaces/mamba-130m-hf"
  dataset = load_dataset("Abirate/english_quotes", split="train")
  training_args = SFTConfig(dataset_text_field="quote")
  lora_config =  LoraConfig(target_modules=["x_proj", "embeddings", "in_proj", "out_proj"])
  trainer = SFTTrainer(
      model=model_id,
      args=training_args,
      train_dataset=dataset,
      peft_config=lora_config,
  )
  trainer.train()
   ```

- バッチ生成には左パディングを使用します。[Padding side](../llm_tutorial#padding-side)を参照してください。

## MambaConfig[[transformers.MambaConfig]]

#### transformers.MambaConfig[[transformers.MambaConfig]]

```python
transformers.MambaConfig(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 = 50280, hidden_size: int = 768, state_size: int = 16, num_hidden_layers: int = 32, layer_norm_epsilon: float = 1e-05, pad_token_id: int | None = 0, bos_token_id: int | None = 0, eos_token_id: int | list[int] | None = 0, expand: int = 2, conv_kernel: int = 4, use_bias: bool = False, use_conv_bias: bool = True, hidden_act: str = 'silu', initializer_range: float = 0.1, residual_in_fp32: bool = True, time_step_rank: str | int = 'auto', time_step_scale: float = 1.0, time_step_min: float = 0.001, time_step_max: float = 0.1, time_step_init_scheme: str = 'random', time_step_floor: float = 0.0001, rescale_prenorm_residual: bool = False, use_cache: bool = True, use_mambapy: bool = False, use_associative_scan: bool = True, tie_word_embeddings: bool = True)
```

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/models/mamba/configuration_mamba.py#L26)

**パラメータ:**

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

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

state_size (`int`、*任意*、デフォルトは`16`) : Mamba レイヤーにおける SSM 状態（潜在状態次元）のサイズ。

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

layer_norm_epsilon (`float`、*optional*、デフォルトは 1e-05) : Layer Normalization 層で使用する epsilon。

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

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

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

expand (`int`、*任意*、デフォルトは 2) : 中間サイズを決定するために使用される拡張係数。

conv_kernel (`int`、*任意*、デフォルトは`4`) : 畳み込みカーネルのサイズ。

use_bias (`bool`, *任意*, デフォルトは `False`) : mixer ブロックの ["in_proj", "out_proj"] でバイアスを使用するかどうか

use_conv_bias (`bool`, *任意*, デフォルトは `True`) : ミキサーブロックの畳み込み層でバイアスを使用するかどうか。

hidden_act (`str`、*任意*、デフォルトは`silu`) : デコーダーで使用する非線形活性化関数（関数または文字列）。例えば、`"gelu"`、`"relu"`、`"silu"`など。

initializer_range (`float`、*任意*、デフォルトは`0.1`) : 全重み行列の初期化に使用されるtruncated_normal_initializerの標準偏差です。

residual_in_fp32 (`bool`、*任意*、デフォルトは`True`) : 残差を`float32`にするかどうか。`False`に設定すると、残差はモデルの他の部分と同じ`dtype`を維持します。

time_step_rank (`Union[str, int]`、*任意*、デフォルトは`auto`) : デルタ（タイムステップ）射影のランク。`"auto"`を指定すると自動的に設定されます。

time_step_scale (`float`、*任意*、デフォルトは`1.0`) : 離散化の前にタイムステップの差分に適用されるスケーリング係数。

time_step_min (`float`、*任意*、デフォルトは `0.001`) : `dt_proj.bias` を制限するために使用される `time_step` の最小値。

time_step_max (`float`、*任意*、デフォルトは `0.1`) : `dt_proj.bias` を制限するために使用される `time_step` の最大値。

time_step_init_scheme (`str`、*任意*、デフォルトは`random`) : 時間ステップのデルタの初期化スキーム。`"random"`または`"uniform"`を指定できます。

time_step_floor (`float`、*任意*、デフォルトは `0.0001`) : softplus 活性化後の離散タイムステップ delta に許可される最小値。

rescale_prenorm_residual (`bool`, *任意*, デフォルトは `False`) : 初期化時に `out_proj` の重みをリスケールするかどうか。

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

use_mambapy (`bool`, *任意*, デフォルトは `False`) : Mamba の CUDA ベースの公式実装が利用できない場合の、学習時のフォールバック戦略を決定します。`True` の場合、mamba.py の実装が使用されます。`False` の場合、単純で遅い実装が使用されます。メモリが限られている場合は、単純なバージョンへの切り替えを検討してください。

use_associative_scan (`bool`、*任意*、デフォルトは`True`) : 単純な逐次実装の代わりに、並列スキャンに PyTorch の `torch._higher_order_ops.associative_scan` を使用するかどうかを指定します。associative scan は `torch.compile` のトレース中のみ有効であり、torch >= 2.9.0 が必要です。両方のパスが数値的に同一の結果を生成することがテストで確認されています（`test_associative_scan_matches_sequential` を参照）。`False` に設定すると、逐次ループにフォールバックします。

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

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

設定オブジェクトは [PreTrainedConfig](/docs/transformers/main/ja/main_classes/configuration#transformers.PreTrainedConfig) を継承し、モデルの出力を制御するために使用できます。詳細については、[PreTrainedConfig](/docs/transformers/main/ja/main_classes/configuration#transformers.PreTrainedConfig) のドキュメントを参照してください。

例:

```python
>>> from transformers import MambaConfig, MambaModel

>>> # Initializing a Mamba configuration
>>> configuration = MambaConfig()

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

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

## MambaModel[[transformers.MambaModel]]

#### transformers.MambaModel[[transformers.MambaModel]]

```python
transformers.MambaModel(config: MambaConfig)
```

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/models/mamba/modeling_mamba.py#L614)

**パラメータ:**

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

特定のヘッドを付加せず、生の隠れ状態を出力する素のMambaモデル。

このモデルは [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.MambaModel.forward]]

```python
forward(input_ids: typing.Optional[torch.LongTensor] = None, inputs_embeds: typing.Optional[torch.LongTensor] = None, cache_params: transformers.cache_utils.Cache | None = None, use_cache: bool | None = None, output_hidden_states: bool | None = None, return_dict: bool | None = None, attention_mask: typing.Optional[torch.LongTensor] = None, **kwargs)
```

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/models/mamba/modeling_mamba.py#L639)

**パラメータ:**

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 (`Cache`、*任意*) : 指定された場合、モデルはすべてのブロックで前回の状態を使用します（`input_ids` に対して、モデルが `state_input_ids + input_ids` をコンテキストとして追加したかのような出力が得られます）。

use_cache (`bool`, *任意*) : `True`に設定すると、`cache_params`が返され、次のlogitsを高速に生成するために使用できます。

output_hidden_states (`bool`, *任意*) : 全レイヤーの hidden states を返すかどうかを指定します。詳細は、返されるテンソルの `hidden_states` を参照してください。

return_dict (`bool`, *任意*) : プレーンなタプルではなく [ModelOutput](/docs/transformers/main/ja/main_classes/output#transformers.utils.ModelOutput) を返すかどうか。

attention_mask (`torch.LongTensor`、shape `(batch_size, sequence_length)`、*任意*) : padding トークンインデックスに対する attention を行わないためのマスク。`[0, 1]` から選択されるマスク値:  - **マスクされない**トークンは 1、- **マスクされる**トークンは 0。  [attention マスクとは?](../glossary#attention-mask)

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

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

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

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

- **last_hidden_state** (`torch.FloatTensor`、shape `(batch_size, sequence_length, hidden_size)`、*optional*) -- モデルの最終層の出力における隠れ状態のシーケンス。
- **cache_params** (`~cache_utils.Cache`、*任意*) -- 最終タイムステップにおけるモデルの状態。次の `input_ids` と組み合わせて forward メソッドで使用することで、古い `input_ids` を提供することを回避できます。

  選択的スキャン後のState space modelの状態行列と、Convolutional statesの両方を含みます
- **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、および任意の初期埋め込み出力。

## MambaLMHeadModel[[transformers.MambaForCausalLM]]

#### transformers.MambaForCausalLM[[transformers.MambaForCausalLM]]

```python
transformers.MambaForCausalLM(config: MambaConfig)
```

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/models/mamba/modeling_mamba.py#L709)

**パラメータ:**

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

MAMBA Modelのtransformerで、その上に言語モデリングヘッド（入力埋め込みの重みと共有される線形層）が配置されています。

このモデルは [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.MambaForCausalLM.forward]]

```python
forward(input_ids: typing.Optional[torch.LongTensor] = None, attention_mask: typing.Optional[torch.LongTensor] = None, inputs_embeds: typing.Optional[torch.FloatTensor] = None, cache_params: transformers.cache_utils.Cache | None = None, labels: typing.Optional[torch.LongTensor] = None, output_hidden_states: bool | None = None, return_dict: bool | None = None, use_cache: bool | None = None, logits_to_keep: typing.Union[int, torch.Tensor] = 0, **kwargs)
```

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/models/mamba/modeling_mamba.py#L750)

**パラメータ:**

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)

attention_mask (`torch.LongTensor`、shape `(batch_size, sequence_length)`、*任意*) : padding トークンインデックスに対する attention を行わないためのマスク。`[0, 1]` から選択されるマスク値:  - **マスクされない**トークンは 1、- **マスクされる**トークンは 0。  [attention マスクとは?](../glossary#attention-mask)

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

cache_params (`Cache`、*任意*) : 指定された場合、モデルはすべてのブロックで前回の状態を使用します（`input_ids` に対して、モデルが `state_input_ids + input_ids` をコンテキストとして追加したかのような出力が得られます）。

labels (`torch.LongTensor`、shape `(batch_size, sequence_length)`、*任意*) : 言語モデリング用のラベル。モデル内部でラベルは**シフト**されるため、`labels = input_ids` と設定できます。インデックスは `[-100, 0, ..., config.vocab_size]` から選択されます。`-100` に設定されたすべてのラベルは無視（マスク）され、損失は `[0, ..., config.vocab_size]` 内のラベルに対してのみ計算されます。

output_hidden_states (`bool`, *任意*) : 全レイヤーの hidden states を返すかどうかを指定します。詳細は、返されるテンソルの `hidden_states` を参照してください。

return_dict (`bool`, *任意*) : プレーンなタプルではなく [ModelOutput](/docs/transformers/main/ja/main_classes/output#transformers.utils.ModelOutput) を返すかどうか。

use_cache (`bool`, *任意*) : `True`に設定すると、`cache_params`が返され、次のlogitsを高速に生成するために使用できます。

logits_to_keep (`Union[int, torch.Tensor]`、*任意*、デフォルトは `0`) : `int` の場合、最後の `logits_to_keep` トークンについて logits を計算します。`0` の場合、すべての `input_ids` について logits を計算します（特殊ケース）。生成には最後のトークンの logits だけで十分であり、そのトークンのみについて計算することでメモリを節約できます。これは、長いシーケンスや大規模な語彙サイズの場合に特に顕著な効果があります。`torch.Tensor` の場合、シーケンス長次元で保持するインデックスに対応する 1 次元である必要があります。これは、パックされたテンソル形式（バッチとシーケンス長を単一の次元にまとめる形式）を使用する場合に有用です。

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

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

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

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

- **loss** (`torch.FloatTensor`、shape `(1,)`、*optional*、`labels` が指定された場合に返されます) -- 言語モデリングの損失(次のトークンの予測用)。
- **logits** (`torch.FloatTensor`、shape `(batch_size, sequence_length, config.vocab_size)`) -- 言語モデリングヘッドの予測スコア（SoftMax 適用前の各語彙トークンのスコア）。
- **cache_params** (`~cache_utils.Cache`、*任意*) -- 最終タイムステップにおけるモデルの状態。次の `input_ids` と組み合わせて forward メソッドで使用することで、古い `input_ids` を提供することを回避できます。

  選択的スキャン後のState space modelの状態行列と、Convolutional statesの両方を含みます
- **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
```