# FalconMamba

[FalconMamba](https://huggingface.co/papers/2410.05355) は、[Mamba](./mamba) をベースにした 7B パラメータの大型言語モデルで、事前学習済みと指示チューニング済みのバリアントが利用可能です。このモデルは、強力な性能を維持しながら計算効率に焦点を当てた純粋な Mamba デザインを実装しています。FalconMamba は推論が大幅に高速であり、長いシーケンスの生成にははるかに少ないメモリを必要とします。これらのモデルは、[RefinedWeb](https://huggingface.co/datasets/tiiuae/falcon-refinedweb)、技術的なコンテンツ、コード、数学データを含む多様な 5.8T トークンのデータセットで事前学習されています。

FalconMambaの公式チェックポイントは、[FalconMamba 7B](https://huggingface.co/collections/tiiuae/falconmamba-7b-66b9a580324dd1598b0f6d4a)コレクションで確認できます。

> [!TIP]
> FalconMamba を異なる言語タスクに適用する方法のより多くの例については、右側のサイドバーにある FalconMamba モデルをクリックしてください。

以下の例では、[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(
    "text-generation",
    model="tiiuae/falcon-mamba-7b-instruct",
    device=0
)
pipeline(
    "Explain the difference between transformers and SSMs",
    max_length=100,
    do_sample=True,
    temperature=0.7
)
```

```python
from transformers import AutoModelForCausalLM, AutoTokenizer

tokenizer = AutoTokenizer.from_pretrained("tiiuae/falcon-mamba-7b-instruct")
model = AutoModelForCausalLM.from_pretrained(
    "tiiuae/falcon-mamba-7b-instruct",
    device_map="auto"
)

input_ids = tokenizer("Explain the difference between transformers and SSMs", return_tensors="pt").to(model.device)

output = model.generate(**input_ids, max_new_tokens=100, cache_implementation="static")
print(tokenizer.decode(output[0], skip_special_tokens=True))
```

```bash
transformers chat tiiuae/falcon-mamba-7b-instruct --dtype auto --device 0
```

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

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

```python
from transformers import AutoTokenizer, BitsAndBytesConfig, FalconMambaForCausalLM

quantization_config = BitsAndBytesConfig(
    load_in_4bit=True,
    bnb_4bit_quant_type="nf4",
    bnb_4bit_use_double_quant=True,
)

tokenizer = AutoTokenizer.from_pretrained("tiiuae/falcon-mamba-7b")
model = FalconMambaForCausalLM.from_pretrained(
    "tiiuae/falcon-mamba-7b",
    device_map="auto",
    quantization_config=quantization_config,
)

inputs = tokenizer("Explain the concept of state space models in simple terms", return_tensors="pt").to(model.device)
outputs = model.generate(**inputs, max_new_tokens=100)
print(tokenizer.decode(outputs[0], skip_special_tokens=True))
```

## 注記

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

## FalconMambaConfig[[transformers.FalconMambaConfig]]

#### transformers.FalconMambaConfig[[transformers.FalconMambaConfig]]

```python
transformers.FalconMambaConfig(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, mixer_rms_eps: float = 1e-06)
```

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/models/falcon_mamba/configuration_falcon_mamba.py#L30)

**パラメータ:**

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`、*任意*、デフォルトは`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`マッピングに従って重み埋め込みを共有するかどうか。

mixer_rms_eps (`float`、*optional*、デフォルト値は 1e-06) : B、C、dt 状態の Mixer RMS norm で使用される RMS norm の epsilon 値です。

これはFalconMambaModelの設定を保存するための設定クラスです。指定された引数に基づいてFalcon Mambaモデルをインスタンス化し、モデルのアーキテクチャを定義するために使用されます。デフォルト値で設定をインスタンス化すると、[tiiuae/falcon-mamba-7b](https://huggingface.co/tiiuae/falcon-mamba-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 FalconMambaConfig, FalconMambaModel

>>> # Initializing a FalconMamba configuration
>>> configuration = FalconMambaConfig()

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

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

## FalconMambaModel[[transformers.FalconMambaModel]]

#### transformers.FalconMambaModel[[transformers.FalconMambaModel]]

```python
transformers.FalconMambaModel(config: FalconMambaConfig)
```

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/models/falcon_mamba/modeling_falcon_mamba.py#L653)

**パラメータ:**

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

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

このモデルは [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.FalconMambaModel.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/falcon_mamba/modeling_falcon_mamba.py#L673)

**パラメータ:**

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)

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

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

[FalconMambaModel](/docs/transformers/main/ja/model_doc/falcon_mamba#transformers.FalconMambaModel)の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、および任意の初期埋め込み出力。

## FalconMambaLMHeadModel[[transformers.FalconMambaForCausalLM]]

#### transformers.FalconMambaForCausalLM[[transformers.FalconMambaForCausalLM]]

```python
transformers.FalconMambaForCausalLM(config: FalconMambaConfig)
```

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/models/falcon_mamba/modeling_falcon_mamba.py#L743)

**パラメータ:**

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

FALCON_MAMBA モデルの 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.FalconMambaForCausalLM.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/falcon_mamba/modeling_falcon_mamba.py#L784)

**パラメータ:**

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 次元である必要があります。これは、パックされたテンソル形式（バッチとシーケンス長を単一の次元にまとめる形式）を使用する場合に有用です。

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

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

[FalconMambaForCausalLM](/docs/transformers/main/ja/model_doc/falcon_mamba#transformers.FalconMambaForCausalLM)の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
```