# Mamba 2

[Mamba 2](https://huggingface.co/papers/2405.21060) 基于状态空间对偶（SSD）框架，该框架将结构化状态空间模型（SSM）与注意力机制变体联系起来。它采用了一种更高效的 SSD 算法，速度比 Mamba 快 2 到 8 倍，并对架构进行了修改，以支持张量并行和分组值注意力（GVA）头结构。

您可以在 [State Space Models](https://huggingface.co/state-spaces) 组织下找到所有原始的 Mamba 2 检查点，但下文的示例使用的是 [mistralai/Mamba-Codestral-7B-v0.1](https://huggingface.co/mistralai/Mamba-Codestral-7B-v0.1)，因为 Hugging Face 目前尚不支持原始检查点。

其他基于 Mamba 2 的架构包括 [Bamba](./bamba)、[FalconH1](./falcon_h1) 和 [Zamba2](./zamba2)。

> [!TIP]
> 该模型由 [ArthurZ](https://huggingface.co/ArthurZ) 贡献。点击右侧边栏中的 Mamba 模型，以查看更多将 Mamba 应用于不同语言任务的示例。

以下示例演示了如何使用 [Pipeline](/docs/transformers/main/zh/main_classes/pipelines#transformers.Pipeline)、[AutoModel](/docs/transformers/main/zh/model_doc/auto#transformers.AutoModel) 以及命令行来生成文本。

```python
from transformers import pipeline

pipeline = pipeline(
    task="text-generation",
    model="mistralai/Mamba-Codestral-7B-v0.1",
    device=0
)
pipeline("Plants create energy through a process known as")
```

```python
from transformers import AutoModelForCausalLM, AutoTokenizer

tokenizer = AutoTokenizer.from_pretrained("mistralai/Mamba-Codestral-7B-v0.1")
model = AutoModelForCausalLM.from_pretrained("mistralai/Mamba-Codestral-7B-v0.1", 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/overview) 概述。

下面的示例使用 [torchao](../quantization/torchao) 仅将权重量化为 4 位整数。

```python
from transformers import AutoModelForCausalLM, AutoTokenizer, TorchAoConfig

quantization_config = TorchAoConfig("int4_weight_only", group_size=128)
tokenizer = AutoTokenizer.from_pretrained("mistralai/Mamba-Codestral-7B-v0.1")
model = AutoModelForCausalLM.from_pretrained("mistralai/Mamba-Codestral-7B-v0.1", 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))
```

## 备注

- Codestral Mamba 具有 `groups=8`，其作用类似于基于注意力的模型中的 kv 头数量。
- Codestral Mamba 具有两种不同的前向传播方式，`torch_forward` 或 `cuda_kernels_forward`，它们的预期结果会略有差异。
  - 未编译的 `torch_forward` 比 `cuda_kernels_forward` 快 3-4 倍。
  - `cuda_kernels_forward` 会在您的环境中使用原始的 CUDA 内核（如果可用）。由于较高的 CPU 开销，它在预填充（prefill）阶段需要一次“预热运行”，因此速度较慢（有关更多详细信息，请参阅 [这些](https://github.com/state-spaces/mamba/issues/389#issuecomment-2171755306) [评论](https://github.com/state-spaces/mamba/issues/355#issuecomment-2147597457)）。

- 该模型中没有位置嵌入，但存在 `attention_mask`，并且在批量生成的情况下，有两处特定的逻辑用于屏蔽隐藏状态（更多详情请参阅此 [评论](https://github.com/state-spaces/mamba/issues/66#issuecomment-1863563829)）。这（以及重新实现的 Mamba 2 内核的加入）导致批量生成与缓存生成之间存在轻微差异。

- SSM 算法严重依赖张量收缩，虽然张量收缩存在对应的矩阵乘法操作，但运算顺序略有不同。这使得在较低精度下，两者之间的差异更为显著。

- Padding 仅在左侧填充（left padding）的情况下经过测试。右侧填充（right padding）会用填充位置更新缓存，导致结果不可靠。对于批量生成，请设置 `tokenizer.padding_side="left"`。参见 [填充侧](../llm_tutorial#padding-side)。

- 以下示例演示了如何使用 [PEFT](https://huggingface.co/docs/peft) 对 Mamba 2 进行微调。

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

model_id = "mistralai/Mamba-Codestral-7B-v0.1"
dataset = load_dataset("Abirate/english_quotes", split="train")
training_args = SFTConfig(dataset_text_field="quote", gradient_checkpointing=True, per_device_train_batch_size=4)
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()
```

## Mamba2Config[[transformers.Mamba2Config]]

#### transformers.Mamba2Config[[transformers.Mamba2Config]]

```python
transformers.Mamba2Config(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, num_heads: int = 128, head_dim: int = 64, vocab_size: int = 32768, hidden_size: int = 4096, state_size: int = 128, num_hidden_layers: int = 64, layer_norm_epsilon: float = 1e-05, pad_token_id: int | None = 1, bos_token_id: int | None = 0, eos_token_id: int | list[int] | None = 2, expand: int = 2, conv_kernel: int = 4, n_groups: int = 8, 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_min: float = 0.001, time_step_max: float = 0.1, time_step_floor: float = 0.0001, time_step_limit: list[float] | tuple[float, ...] = (0.0, inf), rescale_prenorm_residual: bool = False, use_cache: bool = True, chunk_size: int = 256, tie_word_embeddings: bool = False)
```

[来源](https://github.com/huggingface/transformers/blob/main/src/transformers/models/mamba2/configuration_mamba2.py#L26)

**参数：**

num_heads (`int`，*可选*，默认为 `128`)：Transformer 解码器中每个注意力层的注意力头数量。

head_dim (`int`, *可选*, 默认为 `64`) : 注意力头维度。如果为 None，则默认为 hidden_size // num_attention_heads

vocab_size (`int`，*可选*，默认值为 `32768`)：模型的词汇表大小。定义了 `input_ids` 可以表示的不同 token 数量。

hidden_size (`int`，*可选*，默认为 `4096`)：隐藏表示的维度。

state_size (`int`，*可选*，默认为 `128`)：Mamba 层中 SSM 状态（潜在状态维度）的大小。

num_hidden_layers (`int`, *可选*, 默认为 `64`) : Transformer 解码器中的隐藏层数。

layer_norm_epsilon (`float`，*可选*，默认为 1e-05)：在层归一化层中使用的 epsilon 值。

pad_token_id (`int`，*可选*，默认为 `1`)：词表中用于填充的 token id。

bos_token_id (`int`，*可选*，默认为 `0`)：词汇表中用于表示流开始的 token id。

eos_token_id (`Union[int, list[int]]`，*可选*，默认为 `2`)：词汇表中用于表示流结束（end-of-stream）的 token id。

expand (`int`，*可选*，默认为 2)：用于确定中间大小的扩展因子。

conv_kernel (`int`, *可选*, 默认为 `4`) : 卷积核的大小。

n_groups (`int`，*可选*，默认为 8)：mamba 2 的演化矩阵的组数。

use_bias (`bool`, *可选*, 默认为 `False`) : 是否在 mixer 块的 ["in_proj", "out_proj"] 中使用偏置

use_conv_bias (`bool`，*可选*，默认为 `True`)：是否在 mixer 块的卷积层中使用偏置。

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_min (`float`，*可选*，默认为 `0.001`)：用于限制 `dt_proj.bias` 的最小 `time_step`。

time_step_max (`float`，*可选*，默认为 `0.1`)：用于限制 `dt_proj.bias` 的最大 `time_step`。

time_step_floor (`float`, *可选*，默认为 `0.0001`) : 经过 softplus 激活后，离散时间步 delta 允许的最小值。

time_step_limit (`Union[list[float], tuple[float, ...]]`，*可选*，默认为 `(0.0, inf)`)：用于钳制的步长值接受范围。

rescale_prenorm_residual (`bool`，*可选*，默认为 `False`)：是否在初始化时重新缩放 `out_proj` 的权重。

use_cache (`bool`，*可选*，默认为 `True`)：模型是否应返回最后的键/值注意力（并非所有模型都使用）。仅当 `config.is_decoder=True` 或模型为仅解码器生成模型时相关。

chunk_size (`int`，*可选*，默认为 256)：构成序列的块的大小。

tie_word_embeddings (`bool`，*可选*，默认为 `False`)：是否根据模型的 `tied_weights_keys` 映射来绑定权重嵌入。

这是用于存储 Mamba2Model 配置的类。它根据指定的参数实例化 Mamba2 模型，并定义模型架构。使用默认值实例化配置将生成与 [state-spaces/mamba2-2.8b](https://huggingface.co/state-spaces/mamba2-2.8b) 类似的配置。

配置对象继承自 [PreTrainedConfig](/docs/transformers/main/zh/main_classes/configuration#transformers.PreTrainedConfig)，可用于控制模型输出。有关更多信息，请参阅 [PreTrainedConfig](/docs/transformers/main/zh/main_classes/configuration#transformers.PreTrainedConfig) 的文档。

示例：

```python
>>> from transformers import Mamba2Config, Mamba2Model

>>> # Initializing a Mamba2 configuration
>>> configuration = Mamba2Config()

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

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

## Mamba2Model[[transformers.Mamba2Model]]

#### transformers.Mamba2Model[[transformers.Mamba2Model]]

```python
transformers.Mamba2Model(config: Mamba2Config)
```

[来源](https://github.com/huggingface/transformers/blob/main/src/transformers/models/mamba2/modeling_mamba2.py#L739)

**参数：**

config ([Mamba2Config](/docs/transformers/main/zh/model_doc/mamba2#transformers.Mamba2Config))：模型配置类，包含模型的所有参数。通过配置文件进行初始化时，不会加载与模型关联的权重，仅加载配置。请查看 [from_pretrained()](/docs/transformers/main/zh/main_classes/model#transformers.PreTrainedModel.from_pretrained) 方法以加载模型权重。

输出原始隐藏状态、顶部未添加任何特定头部的裸 Mamba2 模型。

该模型继承自 [PreTrainedModel](/docs/transformers/main/zh/main_classes/model#transformers.PreTrainedModel)。请查阅父类文档，了解该库为所有模型实现的通用方法（例如下载或保存、调整输入嵌入大小、剪枝头等）。

该模型也是 PyTorch [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) 的子类。请将其作为常规的 PyTorch Module 使用，有关通用用法和行为的所有事项，请参阅 PyTorch 文档。

#### forward[[transformers.Mamba2Model.forward]]

```python
forward(input_ids: typing.Optional[torch.LongTensor] = None, inputs_embeds: typing.Optional[torch.LongTensor] = None, cache: 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.Tensor] = None, **kwargs)
```

[来源](https://github.com/huggingface/transformers/blob/main/src/transformers/models/mamba2/modeling_mamba2.py#L764)

**参数：**

input_ids (`torch.LongTensor`，形状为 `(batch_size, sequence_length)`，*可选*)：输入序列中 token 在词汇表中的索引。默认情况下，填充（padding）将被忽略。可以使用 [AutoTokenizer](/docs/transformers/main/zh/model_doc/auto#transformers.AutoTokenizer) 获取索引。有关详细信息，请参阅 [PreTrainedTokenizer.encode()](/docs/transformers/main/zh/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) 和 [PreTrainedTokenizer.__call__()](/docs/transformers/main/zh/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__)。[什么是输入 ID？](../glossary#input-ids)

inputs_embeds (`torch.LongTensor`，形状为 `(batch_size, sequence_length, hidden_size)`，*可选*)：可选地，您可以选择直接传入嵌入表示，而不是传入 `input_ids`。如果您希望对将 `input_ids` 索引转换为相应向量的方式拥有比模型内部嵌入查找矩阵更多的控制权，这将非常有用。

cache (`Cache`，*可选*)：如果传入该参数，模型将在所有块中使用之前的状态（这将输出针对提供的 `input_ids` 的结果，就好像模型将 `state_input_ids + input_ids` 作为上下文添加一样）。

use_cache (`bool`, *可选*) : 如果设置为 `True`，则会返回 `cache`，可用于快速生成下一个 logits。

output_hidden_states (`bool`, *可选*) : 是否返回所有层的隐藏状态。有关更多详细信息，请参阅返回张量中的 `hidden_states`。

return_dict (`bool`, *可选*) : 是否返回 [ModelOutput](/docs/transformers/main/zh/main_classes/output#transformers.utils.ModelOutput) 而不是普通元组。

attention_mask (`torch.Tensor`，形状为 `(batch_size, sequence_length)`，*可选*)：用于避免对填充（padding）标记索引执行注意力机制的掩码。掩码值取自 `[0, 1]`： - 1 表示**未掩码**的标记， - 0 表示**已掩码**的标记。 [什么是注意力掩码？](../glossary#attention-mask)

**返回：** `Mamba2Output` 或 `tuple(torch.Tensor)`

`Mamba2Output` 或 `torch.Tensor` 元组（如果传入 `return_dict=False` 或 `config.return_dict=False`），其包含的元素取决于配置（`None`）和输入。

[Mamba2Model](/docs/transformers/main/zh/model_doc/mamba2#transformers.Mamba2Model) 的 forward 方法重写了 `__call__` 特殊方法。

尽管前向传播的实现需要在此函数中定义，但之后应调用 `Module` 实例，而不是直接调用此函数，因为前者会负责执行预处理和后处理步骤，而后者会静默地忽略这些步骤。

- **last_hidden_state**（形状为 `(batch_size, sequence_length, hidden_size)` 的 `torch.Tensor`，*可选*）-- 模型最后一层输出的隐藏状态序列。
- **cache** (`~cache_utils.Cache`, *可选*) -- 模型在上一个时间步的状态。可与下一个 `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)`。

  模型在每一层输出处的隐藏状态，以及可选的初始嵌入输出。

## Mamba2LMHeadModel[[transformers.Mamba2ForCausalLM]]

#### transformers.Mamba2ForCausalLM[[transformers.Mamba2ForCausalLM]]

```python
transformers.Mamba2ForCausalLM(config: Mamba2Config)
```

[来源](https://github.com/huggingface/transformers/blob/main/src/transformers/models/mamba2/modeling_mamba2.py#L843)

**参数：**

config ([Mamba2Config](/docs/transformers/main/zh/model_doc/mamba2#transformers.Mamba2Config))：模型配置类，包含模型的所有参数。通过配置文件进行初始化时，不会加载与模型关联的权重，仅加载配置。请查看 [from_pretrained()](/docs/transformers/main/zh/main_classes/model#transformers.PreTrainedModel.from_pretrained) 方法以加载模型权重。

带有语言建模头（线性层，其权重不与输入嵌入绑定）的 MAMBA2 模型 Transformer。

该模型继承自 [PreTrainedModel](/docs/transformers/main/zh/main_classes/model#transformers.PreTrainedModel)。请查阅父类文档，了解该库为所有模型实现的通用方法（例如下载或保存、调整输入嵌入大小、剪枝头等）。

该模型也是 PyTorch [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) 的子类。请将其作为常规的 PyTorch Module 使用，有关通用用法和行为的所有事项，请参阅 PyTorch 文档。

#### forward[[transformers.Mamba2ForCausalLM.forward]]

```python
forward(input_ids: typing.Optional[torch.LongTensor] = None, inputs_embeds: typing.Optional[torch.Tensor] = None, cache: 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, attention_mask: typing.Optional[torch.Tensor] = None, logits_to_keep: typing.Union[int, torch.Tensor] = 0, **kwargs)
```

[来源](https://github.com/huggingface/transformers/blob/main/src/transformers/models/mamba2/modeling_mamba2.py#L885)

**参数：**

input_ids (`torch.LongTensor`，形状为 `(batch_size, sequence_length)`，*可选*)：输入序列中 token 在词汇表中的索引。默认情况下，填充（padding）将被忽略。可以使用 [AutoTokenizer](/docs/transformers/main/zh/model_doc/auto#transformers.AutoTokenizer) 获取索引。有关详细信息，请参阅 [PreTrainedTokenizer.encode()](/docs/transformers/main/zh/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) 和 [PreTrainedTokenizer.__call__()](/docs/transformers/main/zh/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__)。[什么是输入 ID？](../glossary#input-ids)

inputs_embeds (`torch.Tensor`，形状为 `(batch_size, sequence_length, hidden_size)`，*可选*)：可选地，你可以选择直接传入嵌入表示，而不是传入 `input_ids`。如果你希望比模型内部的嵌入查找矩阵更精细地控制如何将 `input_ids` 索引转换为对应的向量，这将非常有用。

cache (`Cache`，*可选*)：如果传入该参数，模型将在所有块中使用之前的状态（这将输出针对提供的 `input_ids` 的结果，就好像模型将 `state_input_ids + input_ids` 作为上下文添加一样）。

labels (`torch.LongTensor`，形状为 `(batch_size, sequence_length)`，*可选*) : 用于语言建模的标签。请注意，模型内部会对标签进行**移位**，因此您可以设置 `labels = input_ids`。索引选自 `[-100, 0, ..., config.vocab_size]`。所有设置为 `-100` 的标签都会被忽略（被掩码），损失仅针对 `[0, ..., config.vocab_size]` 范围内的标签进行计算。

output_hidden_states (`bool`, *可选*) : 是否返回所有层的隐藏状态。有关更多详细信息，请参阅返回张量中的 `hidden_states`。

return_dict (`bool`, *可选*) : 是否返回 [ModelOutput](/docs/transformers/main/zh/main_classes/output#transformers.utils.ModelOutput) 而不是普通元组。

use_cache (`bool`, *可选*) : 如果设置为 `True`，则会返回 `cache`，可用于快速生成下一个 logits。

attention_mask (`torch.Tensor`，形状为 `(batch_size, sequence_length)`，*可选*)：用于避免对填充（padding）标记索引执行注意力机制的掩码。掩码值取自 `[0, 1]`： - 1 表示**未掩码**的标记， - 0 表示**已掩码**的标记。 [什么是注意力掩码？](../glossary#attention-mask)

logits_to_keep (`Union[int, torch.Tensor]`，*可选*，默认为 `0`)：如果为 `int`，则计算最后 `logits_to_keep` 个 token 的 logits。如果为 `0`，则计算所有 `input_ids` 的 logits（特殊情况）。生成过程只需要最后一个 token 的 logits，仅针对该 token 进行计算可以节省内存，对于长序列或大词汇量而言，这种节省相当可观。如果为 `torch.Tensor`，则必须是一维张量，对应于序列长度维度中需要保留的索引。这在使用打包张量格式（将批次和序列长度合并为单一维度）时非常有用。

**返回：** `Mamba2CausalLMOutput` 或 `tuple(torch.Tensor)`

`Mamba2CausalLMOutput` 或 `torch.Tensor` 元组（如果传入 `return_dict=False` 或 `config.return_dict=False`），其包含的元素取决于配置（`None`）和输入。

[Mamba2ForCausalLM](/docs/transformers/main/zh/model_doc/mamba2#transformers.Mamba2ForCausalLM) 的 forward 方法重写了 `__call__` 特殊方法。

尽管前向传播的实现需要在此函数中定义，但之后应调用 `Module` 实例，而不是直接调用此函数，因为前者会负责执行预处理和后处理步骤，而后者会静默地忽略这些步骤。

- **loss** (`torch.Tensor`，形状为 `(1,)`，*可选*，当提供 `labels` 时返回) -- 语言建模损失（用于下一个 token 预测）。
- **logits**（形状为 `(batch_size, sequence_length, config.vocab_size)` 的 `torch.Tensor`）-- 语言建模头的预测分数（SoftMax 之前每个词汇表 token 的分数）。
- **cache** (`~cache_utils.Cache`, *可选*) -- 模型在上一个时间步的状态。可与下一个 `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)`。

  模型在每一层输出处的隐藏状态，以及可选的初始嵌入输出。

