# Mamba

[Mamba](https://huggingface.co/papers/2312.00752) — это селективная структурированная модель пространства состояний (SSM), разработанная для обхода вычислительной неэффективности Transformers при работе с длинными последовательностями. Это полностью архитектура без механизма внимания, состоящая из комбинации блоков H3 и gated 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/ru/main_classes/pipelines#transformers.Pipeline), [AutoModel](/docs/transformers/main/ru/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/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 `mixer` эквивалентен слоям `Attention`. Основная логика Mamba реализована в классе `MambaMixer`.
- Приведённый ниже пример демонстрирует, как дообучить Mamba с помощью [PEFT](https://huggingface.co/docs/peft).

  ```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()
   ```

- Используйте левое выравнивание (left padding) для пакетной генерации. См. [Сторона выравнивания](../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`, *optional*, по умолчанию `768`) : Размерность скрытых представлений.

state_size (`int`, *optional*, по умолчанию `16`) : Размер состояния SSM (размерность латентного состояния) в слоях Mamba.

num_hidden_layers (`int`, *необязательный*, по умолчанию `32`) : Количество скрытых слоев в декодере Transformer.

layer_norm_epsilon (`float`, *optional*, по умолчанию 1e-05) : Значение epsilon, используемое в слоях нормализации по слоям.

pad_token_id (`int`, *необязательный*, по умолчанию `0`) : Идентификатор токена, используемый для выравнивания в словаре.

bos_token_id (`int`, *необязательный*, по умолчанию `0`) : Идентификатор токена, используемый для обозначения начала потока в словаре.

eos_token_id (`Union[int, list[int]]`, *необязательный*, по умолчанию `0`) : Идентификатор токена, используемого для обозначения конца потока в словаре.

expand (`int`, *optional*, по умолчанию 2) : Коэффициент расширения, используемый для определения промежуточного размера.

conv_kernel (`int`, *optional*, по умолчанию `4`) : Размер свёрточного ядра.

use_bias (`bool`, *необязательный*, по умолчанию `False`) : Использовать ли смещение (bias) в ["in_proj", "out_proj"] блока миксера

use_conv_bias (`bool`, *необязательный*, по умолчанию `True`) : Использовать ли смещение (bias) в слое свёртки блока миксера.

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`) : Минимальное значение `time_step`, используемое для ограничения `dt_proj.bias`.

time_step_max (`float`, *необязательный*, по умолчанию `0.1`) : Максимальное значение `time_step`, используемое для ограничения `dt_proj.bias`.

time_step_init_scheme (`str`, *необязательный*, по умолчанию `random`) : Схема инициализации для дельты шага времени. Может быть `"random"` или `"uniform"`.

time_step_floor (`float`, *необязательный*, по умолчанию `0.0001`) : Минимально допустимое значение дискретного шага времени delta после активации softplus.

rescale_prenorm_residual (`bool`, *необязательный*, по умолчанию `False`) : Нужно ли перемасштабировать веса `out_proj` при инициализации.

use_cache (`bool`, *необязательный*, по умолчанию `True`) : Следует ли модели возвращать последние значения внимания key/values (не используется во всех моделях). Актуально только при `config.is_decoder=True` или если модель является генеративной моделью только с декодером.

use_mambapy (`bool`, *необязательный*, по умолчанию `False`) : Определяет стратегию отката при обучении, если официальная реализация Mamba на базе CUDA недоступна. Если `True`, используется реализация из mamba.py. Если `False`, используется наивная и более медленная реализация. При ограниченной памяти рекомендуется переключиться на наивную версию.

use_associative_scan (`bool`, *optional*, по умолчанию `True`) : Использовать ли `torch._higher_order_ops.associative_scan` из PyTorch для параллельного сканирования вместо наивной последовательной реализации. Ассоциативное сканирование активно только во время трассировки `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/ru/main_classes/configuration#transformers.PreTrainedConfig) и могут использоваться для управления выводами модели. Подробнее см. в документации [PreTrainedConfig](/docs/transformers/main/ru/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#L616)

**Параметры:**

config ([MambaConfig](/docs/transformers/main/ru/model_doc/mamba#transformers.MambaConfig)) : Класс конфигурации модели со всеми параметрами модели. Инициализация с файлом конфигурации не загружает веса, связанные с моделью, только конфигурацию. Используйте метод [from_pretrained()](/docs/transformers/main/ru/main_classes/model#transformers.PreTrainedModel.from_pretrained) для загрузки весов модели.

Модель Mamba без дополнительных компонентов, выводящая необработанные скрытые состояния без какого-либо специализированного слоя.

Эта модель наследуется от [PreTrainedModel](/docs/transformers/main/ru/main_classes/model#transformers.PreTrainedModel). Общие методы, которые библиотека реализует для всех своих моделей (например, загрузка или сохранение, изменение размера входных эмбеддингов, обрезка головок и т. д.), описаны в документации родительского класса.

Эта модель также является подклассом [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) в PyTorch. Используйте её как обычный модуль PyTorch и обращайтесь к документации PyTorch по всем вопросам, связанным с общим использованием и поведением.

#### forward[[transformers.MambaModel.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.LongTensor] = None, **kwargs)
```

[Источник](https://github.com/huggingface/transformers/blob/main/src/transformers/models/mamba/modeling_mamba.py#L641)

**Параметры:**

input_ids (`torch.LongTensor` формы `(batch_size, sequence_length)`, *необязательно*) : Индексы токенов входной последовательности в словаре. По умолчанию заполнение (padding) игнорируется. Индексы можно получить с помощью [AutoTokenizer](/docs/transformers/main/ru/model_doc/auto#transformers.AutoTokenizer). Подробности см. в [PreTrainedTokenizer.encode()](/docs/transformers/main/ru/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) и [PreTrainedTokenizer.__call__()](/docs/transformers/main/ru/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__). [Что такое входные идентификаторы?](../glossary#input-ids)

inputs_embeds (`torch.LongTensor` формы `(batch_size, sequence_length, hidden_size)`, *необязательно*) : По желанию, вместо передачи `input_ids` можно напрямую передать встроенное представление. Это полезно, если требуется больший контроль над тем, как индексы `input_ids` преобразуются в соответствующие векторы, чем это обеспечивает внутренняя матрица поиска встраиваний модели.

cache (`Cache`, *optional*) : Если передано, модель использует предыдущее состояние во всех блоках (что даст вывод для переданных `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/ru/main_classes/output#transformers.utils.ModelOutput) вместо обычного кортежа.

attention_mask (`torch.LongTensor` формы `(batch_size, sequence_length)`, *необязательный*) : Маска для предотвращения применения внимания к индексам токенов отсечки. Значения маски выбираются из `[0, 1]`:  - 1 для токенов, которые **не замаскированы**, - 0 для токенов, которые **замаскированы**.  [Что такое маски внимания?](../glossary#attention-mask)

**Возвращает:** `MambaOutput` или `tuple(torch.Tensor)`

`MambaOutput` или кортеж `torch.Tensor` (если передано `return_dict=False` или при `config.return_dict=False`), содержащий различные элементы в зависимости от конфигурации (`None`) и входных данных.

Метод forward класса [MambaModel](/docs/transformers/main/ru/model_doc/mamba#transformers.MambaModel) переопределяет специальный метод `__call__`.

Хотя рецепт для прямого прохода должен быть определён внутри этой функции, после этого следует вызывать экземпляр `Module`, а не эту функцию, поскольку первый выполняет шаги предварительной и постобработки, тогда как второй молча их игнорирует.

- **last_hidden_state** (`torch.Tensor` формы `(batch_size, sequence_length, hidden_size)`, *необязательный*) -- Последовательность скрытых состояний на выходе последнего слоя модели.
- **cache** (`~cache_utils.Cache`, *необязательный*) -- Состояние модели на последнем шаге. Может использоваться в forward-методе вместе с новыми `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)`.

  Скрытые состояния модели на выходе каждого слоя, а также необязательные выходные значения начального слоя встраивания.

## 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#L712)

**Параметры:**

config ([MambaConfig](/docs/transformers/main/ru/model_doc/mamba#transformers.MambaConfig)) : Класс конфигурации модели со всеми параметрами модели. Инициализация с файлом конфигурации не загружает веса, связанные с моделью, только конфигурацию. Используйте метод [from_pretrained()](/docs/transformers/main/ru/main_classes/model#transformers.PreTrainedModel.from_pretrained) для загрузки весов модели.

Трансформер модели MAMBA с головой для моделирования языка сверху (линейный слой с весами, связанными со входными эмбеддингами).

Эта модель наследуется от [PreTrainedModel](/docs/transformers/main/ru/main_classes/model#transformers.PreTrainedModel). Общие методы, которые библиотека реализует для всех своих моделей (например, загрузка или сохранение, изменение размера входных эмбеддингов, обрезка головок и т. д.), описаны в документации родительского класса.

Эта модель также является подклассом [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) в PyTorch. Используйте её как обычный модуль PyTorch и обращайтесь к документации 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.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, logits_to_keep: typing.Union[int, torch.Tensor] = 0, **kwargs)
```

[Источник](https://github.com/huggingface/transformers/blob/main/src/transformers/models/mamba/modeling_mamba.py#L754)

**Параметры:**

input_ids (`torch.LongTensor` формы `(batch_size, sequence_length)`, *необязательно*) : Индексы токенов входной последовательности в словаре. По умолчанию заполнение (padding) игнорируется. Индексы можно получить с помощью [AutoTokenizer](/docs/transformers/main/ru/model_doc/auto#transformers.AutoTokenizer). Подробности см. в [PreTrainedTokenizer.encode()](/docs/transformers/main/ru/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) и [PreTrainedTokenizer.__call__()](/docs/transformers/main/ru/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__). [Что такое входные идентификаторы?](../glossary#input-ids)

attention_mask (`torch.LongTensor` формы `(batch_size, sequence_length)`, *необязательный*) : Маска для предотвращения применения внимания к индексам токенов отсечки. Значения маски выбираются из `[0, 1]`:  - 1 для токенов, которые **не замаскированы**, - 0 для токенов, которые **замаскированы**.  [Что такое маски внимания?](../glossary#attention-mask)

inputs_embeds (`torch.Tensor` формы `(batch_size, sequence_length, hidden_size)`, *необязательно*) : По желанию, вместо передачи `input_ids` можно напрямую передать встроенное представление. Это полезно, если требуется больший контроль над тем, как индексы `input_ids` преобразуются в соответствующие векторы, чем это обеспечивает внутренняя матрица поиска встраиваний модели.

cache (`Cache`, *optional*) : Если передано, модель использует предыдущее состояние во всех блоках (что даст вывод для переданных `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/ru/main_classes/output#transformers.utils.ModelOutput) вместо обычного кортежа.

use_cache (`bool`, *необязательный*) : Если установлено в `True`, `cache` возвращается и может использоваться для быстрого генерирования следующих logits.

logits_to_keep (`Union[int, torch.Tensor]`, *необязательный*, по умолчанию `0`) : Если передано значение типа `int`, вычисляются logits для последних `logits_to_keep` токенов. Если передано `0`, logits вычисляются для всех `input_ids` (специальный случай). Для генерации нужны logits только последнего токена, и вычисление их только для этого токена позволяет сэкономить память, что становится весьма значимым для длинных последовательностей или большого размера словаря. Если передано значение типа `torch.Tensor`, оно должно быть одномерным и соответствовать индексам, которые нужно сохранить в измерении длины последовательности. Это полезно при использовании упакованного формата тензоров (одно измерение для batch и длины последовательности).

**Возвращает:** `MambaCausalLMOutput` или `tuple(torch.Tensor)`

`MambaCausalLMOutput` или кортеж `torch.Tensor` (если передано `return_dict=False` или если `config.return_dict=False`), содержащий различные элементы в зависимости от конфигурации (`None`) и входных данных.

Метод forward класса [MambaForCausalLM](/docs/transformers/main/ru/model_doc/mamba#transformers.MambaForCausalLM) переопределяет специальный метод `__call__`.

Хотя рецепт для прямого прохода должен быть определён внутри этой функции, после этого следует вызывать экземпляр `Module`, а не эту функцию, поскольку первый выполняет шаги предварительной и постобработки, тогда как второй молча их игнорирует.

- **loss** (`torch.Tensor` формы `(1,)`, *необязательный*, возвращается, если задан `labels`) -- Потеря языковой модели (для предсказания следующего токена).
- **logits** (`torch.Tensor` формы `(batch_size, sequence_length, config.vocab_size)`) — Оценки предсказаний языковой модели (оценки для каждого токена словаря до применения SoftMax).
- **cache** (`~cache_utils.Cache`, *необязательный*) -- Состояние модели на последнем шаге. Может использоваться в forward-методе вместе с новыми `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)`.

  Скрытые состояния модели на выходе каждого слоя, а также необязательные выходные значения начального слоя встраивания.

