# FalconMamba

[FalconMamba](https://huggingface.co/papers/2410.05355) — это большая языковая модель объёмом 7B, доступная в вариантах с предобучением и с обучением по инструкциям, основанная на архитектуре [Mamba](./mamba). Модель реализует чистый дизайн Mamba, ориентированный на вычислительную эффективность при сохранении высокого качества. FalconMamba значительно быстрее при инференсе и требует существенно меньше памяти для генерации длинных последовательностей. Модели предобучены на разнообразном наборе данных объёмом 5,8 трлн токенов, включающем [RefinedWeb](https://huggingface.co/datasets/tiiuae/falcon-refinedweb), технический контент, код и математические данные.

Официальные контрольные точки FalconMamba можно найти в коллекции [FalconMamba 7B](https://huggingface.co/collections/tiiuae/falconmamba-7b-66b9a580324dd1598b0f6d4a).

> [!TIP]
> Щёлкните по моделям FalconMamba в боковой панели справа, чтобы увидеть дополнительные примеры применения FalconMamba к различным языковым задачам.

Приведённые ниже примеры показывают, как генерировать текст с помощью [Pipeline](/docs/transformers/v5.23.0/ru/main_classes/pipelines#transformers.Pipeline), [AutoModel](/docs/transformers/v5.23.0/ru/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/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))
```

## Примечания

- Используйте левое выравнивание (left padding) для пакетной генерации. См. [Сторона выравнивания](../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/v5.23.0/src/transformers/models/falcon_mamba/configuration_falcon_mamba.py#L30)

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

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`, *необязательный*, по умолчанию `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` модели.

mixer_rms_eps (`float`, *optional*, по умолчанию 1e-06) : Значение epsilon для RMS norm, используемое в Mixer RMS norm для состояний B, C и dt.

Это класс конфигурации для хранения настроек модели FalconMambaModel. Он используется для создания модели Falcon Mamba в соответствии с указанными аргументами, определяя архитектуру модели. Создание конфигурации с параметрами по умолчанию даст конфигурацию, аналогичную конфигурации модели [tiiuae/falcon-mamba-7b](https://huggingface.co/tiiuae/falcon-mamba-7b)

Объекты конфигурации наследуются от [PreTrainedConfig](/docs/transformers/v5.23.0/ru/main_classes/configuration#transformers.PreTrainedConfig) и могут использоваться для управления выводами модели. Подробнее см. в документации [PreTrainedConfig](/docs/transformers/v5.23.0/ru/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/v5.23.0/src/transformers/models/falcon_mamba/modeling_falcon_mamba.py#L653)

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

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

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

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

Эта модель также является подклассом [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) в PyTorch. Используйте её как обычный модуль PyTorch и обращайтесь к документации 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/v5.23.0/src/transformers/models/falcon_mamba/modeling_falcon_mamba.py#L673)

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

input_ids (`torch.LongTensor` формы `(batch_size, sequence_length)`, *необязательно*) : Индексы токенов входной последовательности в словаре. По умолчанию заполнение (padding) игнорируется. Индексы можно получить с помощью [AutoTokenizer](/docs/transformers/v5.23.0/ru/model_doc/auto#transformers.AutoTokenizer). Подробности см. в [PreTrainedTokenizer.encode()](/docs/transformers/v5.23.0/ru/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) и [PreTrainedTokenizer.__call__()](/docs/transformers/v5.23.0/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_params (`Cache`, *optional*) : Если передано, модель использует предыдущее состояние во всех блоках (что даст вывод для переданных `input_ids`, как если бы модель добавила `state_input_ids + input_ids` в контекст).

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

output_hidden_states (`bool`, *необязательный*) : Нужно ли возвращать скрытые состояния всех слоёв. Подробнее о `hidden_states` в разделе возвращаемых тензоров.

return_dict (`bool`, *необязательный*) : Нужно ли возвращать [ModelOutput](/docs/transformers/v5.23.0/ru/main_classes/output#transformers.utils.ModelOutput) вместо обычного кортежа.

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

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

Объект `FalconMambaOutput` или кортеж из `torch.Tensor` (если передано `return_dict=False` или если `config.return_dict=False`), содержащий различные элементы в зависимости от конфигурации ([FalconMambaConfig](/docs/transformers/v5.23.0/ru/model_doc/falcon_mamba#transformers.FalconMambaConfig)) и входных данных.

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

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

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

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

## FalconMambaLMHeadModel[[transformers.FalconMambaForCausalLM]]

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

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

[Источник](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/falcon_mamba/modeling_falcon_mamba.py#L743)

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

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

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

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

Эта модель также является подклассом [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) в PyTorch. Используйте её как обычный модуль PyTorch и обращайтесь к документации 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.Tensor] = 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/v5.23.0/src/transformers/models/falcon_mamba/modeling_falcon_mamba.py#L784)

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

input_ids (`torch.LongTensor` формы `(batch_size, sequence_length)`, *необязательно*) : Индексы токенов входной последовательности в словаре. По умолчанию заполнение (padding) игнорируется. Индексы можно получить с помощью [AutoTokenizer](/docs/transformers/v5.23.0/ru/model_doc/auto#transformers.AutoTokenizer). Подробности см. в [PreTrainedTokenizer.encode()](/docs/transformers/v5.23.0/ru/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) и [PreTrainedTokenizer.__call__()](/docs/transformers/v5.23.0/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_params (`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/v5.23.0/ru/main_classes/output#transformers.utils.ModelOutput) вместо обычного кортежа.

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

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

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

Объект `FalconMambaCausalLMOutput` или кортеж из `torch.Tensor` (если передано `return_dict=False` или если `config.return_dict=False`), содержащий различные элементы в зависимости от конфигурации ([FalconMambaConfig](/docs/transformers/v5.23.0/ru/model_doc/falcon_mamba#transformers.FalconMambaConfig)) и входных данных.

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

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

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

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

Пример:

```python
```

