# FalconMamba

[FalconMamba](https://huggingface.co/papers/2410.05355) é um modelo de linguagem grande de 7B, disponível em variantes pré-treinadas e ajustadas por instrução, baseado no [Mamba](./mamba). Este modelo implementa um design puramente Mamba que se concentra na eficiência computacional, mantendo um desempenho robusto. O FalconMamba é significativamente mais rápido na inferência e requer substancialmente menos memória para a geração de sequências longas. Os modelos foram pré-treinados em um conjunto de dados diversificado de 5,8T tokens, incluindo [RefinedWeb](https://huggingface.co/datasets/tiiuae/falcon-refinedweb), conteúdo técnico, código e dados matemáticos.

Você pode encontrar os checkpoints oficiais do FalconMamba na coleção [FalconMamba 7B](https://huggingface.co/collections/tiiuae/falconmamba-7b-66b9a580324dd1598b0f6d4a).

> [!TIP]
> Clique nos modelos FalconMamba na barra lateral à direita para ver mais exemplos de como aplicar o FalconMamba a diferentes tarefas de linguagem.

Os exemplos abaixo demonstram como gerar texto com [Pipeline](/docs/transformers/main/pt/main_classes/pipelines#transformers.Pipeline), [AutoModel](/docs/transformers/main/pt/model_doc/auto#transformers.AutoModel) e pela linha de comando.

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

A quantização reduz a carga de memória de modelos grandes ao representar os pesos em uma precisão menor. Consulte a visão geral de [Quantização](../quantization/overview) para mais backends de quantização disponíveis.

O exemplo abaixo usa [bitsandbytes](../quantization/bitsandbytes) para quantizar os pesos em 4 bits.

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

## Observações

- Use padding à esquerda para geração em lote. Consulte [Lado do 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)
```

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

**Parâmetros:**

vocab_size (`int`, *opcional*, padrão `50280`) : Tamanho do vocabulário do modelo. Define o número de tokens diferentes que podem ser representados pelos `input_ids`.

hidden_size (`int`, *opcional*, padrão `768`) : Dimensão das representações ocultas.

state_size (`int`, *opcional*, padrão `16`) : Tamanho do estado do SSM (dimensão do estado latente) nas camadas Mamba.

num_hidden_layers (`int`, *opcional*, padrão `32`) : Número de camadas ocultas no decodificador do Transformer.

layer_norm_epsilon (`float`, *opcional*, padrão `1e-05`) : O epsilon usado pelas camadas de normalização de camada.

pad_token_id (`int`, *opcional*, padrão `0`) : ID do token usado para preenchimento no vocabulário.

bos_token_id (`int`, *opcional*, padrão `0`) : ID do token usado para o início do fluxo no vocabulário.

eos_token_id (`Union[int, list[int]]`, *opcional*, padrão `0`) : ID do token usado para o fim do fluxo no vocabulário.

expand (`int`, *opcional*, padrão 2) : Fator de expansão usado para determinar o tamanho intermediário.

conv_kernel (`int`, *opcional*, padrão 4) : Tamanho do kernel de convolução.

use_bias (`bool`, *opcional*, padrão `False`) : Se deve ou não usar viés em ["in_proj", "out_proj"] do bloco mixer

use_conv_bias (`bool`, *opcional*, padrão `True`) : Indica se deve ou não usar viés na camada de convolução do bloco mixer.

hidden_act (`str`, *opcional*, padrão `silu`) : A função de ativação não linear (função ou string) no decodificador. Por exemplo, `"gelu"`, `"relu"`, `"silu"`, etc.

initializer_range (`float`, *opcional*, padrão `0.1`) : O desvio padrão do truncated_normal_initializer para inicializar todas as matrizes de pesos.

residual_in_fp32 (`bool`, *opcional*, padrão `True`) : Indica se os resíduos devem estar em `float32`. Se definido como `False`, os resíduos manterão o mesmo `dtype` do restante do modelo

time_step_rank (`Union[str, int]`, *opcional*, padrão `auto`) : Rango da projeção do delta (passo de tempo). Pode ser `"auto"` para configurá-lo automaticamente.

time_step_scale (`float`, *opcional*, padrão `1.0`) : Escala aplicada ao delta do passo de tempo antes da discretização.

time_step_min (`float`, *opcional*, padrão `0.001`) : `time_step` mínimo usado para limitar `dt_proj.bias`.

time_step_max (`float`, *opcional*, padrão `0.1`) : `time_step` máximo usado para limitar `dt_proj.bias`.

time_step_init_scheme (`str`, *opcional*, padrão `random`) : Esquema de inicialização para o delta do passo de tempo. Pode ser `"random"` ou `"uniform"`.

time_step_floor (`float`, *opcional*, padrão `0.0001`) : Valor mínimo permitido para o passo de tempo discreto delta após a ativação softplus.

rescale_prenorm_residual (`bool`, *opcional*, padrão `False`) : Se as pesos de `out_proj` devem ser reescalados durante a inicialização.

use_cache (`bool`, *opcional*, padrão `True`) : Indica se o modelo deve retornar as últimas atenções de chave/valor (não utilizado por todos os modelos). Relevante apenas se `config.is_decoder=True` ou quando o modelo for um modelo generativo somente de decodificador.

use_mambapy (`bool`, *opcional*, padrão `False`) : Define a estratégia de fallback durante o treinamento caso a implementação oficial baseada em CUDA do Mamba não esteja disponível. Se `True`, a implementação mamba.py é utilizada. Se `False`, a implementação ingênua e mais lenta é utilizada. Considere alternar para a versão ingênua se a memória for limitada.

use_associative_scan (`bool`, *opcional*, padrão `True`) : Indica se deve-se usar o `torch._higher_order_ops.associative_scan` do PyTorch para o scan paralelo em vez da implementação sequencial simples. O scan associativo é ativo apenas durante o tracing do `torch.compile` e requer torch >= 2.9.0. Ambos os caminhos são testados para produzir resultados numericamente idênticos (veja `test_associative_scan_matches_sequential`). Defina como `False` para usar o loop sequencial.

tie_word_embeddings (`bool`, *opcional*, padrão `True`) : Se deve vincular as embeddings de pesos de acordo com o mapeamento `tied_weights_keys` do modelo.

mixer_rms_eps (`float`, *opcional*, padrão 1e-06) : O valor de epsilon da normalização RMS usado na normalização RMS do Mixer para os estados B, C e dt.

Esta é a classe de configuração para armazenar a configuração de um FalconMambaModel. Ela é usada para instanciar um modelo Falcon Mamba de acordo com os argumentos especificados, definindo a arquitetura do modelo. Instanciar uma configuração com os padrões resultará em uma configuração semelhante à do [tiiuae/falcon-mamba-7b](https://huggingface.co/tiiuae/falcon-mamba-7b)

Os objetos de configuração herdam de [PreTrainedConfig](/docs/transformers/main/pt/main_classes/configuration#transformers.PreTrainedConfig) e podem ser usados para controlar as saídas do modelo. Leia a documentação de [PreTrainedConfig](/docs/transformers/main/pt/main_classes/configuration#transformers.PreTrainedConfig) para mais informações.

Exemplo:

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

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

**Parâmetros:**

config ([FalconMambaConfig](/docs/transformers/main/pt/model_doc/falcon_mamba#transformers.FalconMambaConfig)) : Classe de configuração do modelo com todos os parâmetros do modelo. A inicialização com um arquivo de configuração não carrega os pesos associados ao modelo, apenas a configuração. Consulte o método [from_pretrained()](/docs/transformers/main/pt/main_classes/model#transformers.PreTrainedModel.from_pretrained) para carregar os pesos do modelo.

O modelo Falcon Mamba básico, que produz estados ocultos brutos sem nenhum cabeçalho específico no topo.

Este modelo herda de [PreTrainedModel](/docs/transformers/main/pt/main_classes/model#transformers.PreTrainedModel). Consulte a documentação da classe pai para os métodos genéricos que a biblioteca implementa para todos os seus modelos (como download ou salvamento, redimensionamento dos embeddings de entrada, poda de cabeças, etc.).

Este modelo também é uma subclasse de [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) do PyTorch. Use-o como um Módulo PyTorch regular e consulte a documentação do PyTorch para todos os assuntos relacionados ao uso e comportamento gerais.

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

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/falcon_mamba/modeling_falcon_mamba.py#L673)

**Parâmetros:**

input_ids (`torch.LongTensor` de forma `(batch_size, sequence_length)`, *opcional*) : Índices dos tokens da sequência de entrada no vocabulário. O preenchimento (padding) será ignorado por padrão. Os índices podem ser obtidos usando [AutoTokenizer](/docs/transformers/main/pt/model_doc/auto#transformers.AutoTokenizer). Consulte [PreTrainedTokenizer.encode()](/docs/transformers/main/pt/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) e [PreTrainedTokenizer.__call__()](/docs/transformers/main/pt/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__) para mais detalhes. [O que são IDs de entrada?](../glossary#input-ids)

inputs_embeds (`torch.LongTensor` de forma `(batch_size, sequence_length, hidden_size)`, *opcional*) : Opcionalmente, em vez de passar `input_ids`, você pode escolher passar diretamente uma representação incorporada. Isso é útil se você quiser ter mais controle sobre como converter os índices de `input_ids` nos vetores associados do que a matriz de busca de incorporação interna do modelo.

cache_params (`Cache`, *opcional*) : Se for passado, o modelo usa o estado anterior em todos os blocos (o que resultará na saída para os `input_ids` fornecidos, como se o modelo adicionasse `state_input_ids + input_ids` como contexto).

use_cache (`bool`, *opcional*) : Se definido como `True`, o `cache_params` é retornado e pode ser usado para gerar rapidamente os próximos logits.

output_hidden_states (`bool`, *opcional*) : Indica se os estados ocultos de todas as camadas devem ser retornados. Consulte `hidden_states` em tensores retornados para mais detalhes.

return_dict (`bool`, *opcional*) : Se deve ou não retornar um [ModelOutput](/docs/transformers/main/pt/main_classes/output#transformers.utils.ModelOutput) em vez de uma tupla simples.

attention_mask (`torch.LongTensor` de forma `(batch_size, sequence_length)`, *opcional*) : Máscara para evitar a execução de atenção nos índices de tokens de preenchimento. Valores de máscara selecionados em `[0, 1]`:  - 1 para tokens que **não estão mascarados**, - 0 para tokens que **estão mascarados**.  [O que são máscaras de atenção?](../glossary#attention-mask)

**Retorna:** `FalconMambaOutput` ou `tuple(torch.Tensor)`

Um `FalconMambaOutput` ou uma tupla de `torch.Tensor` (se `return_dict=False` for passado ou quando `config.return_dict=False`) contendo vários elementos, dependendo da configuração ([FalconMambaConfig](/docs/transformers/main/pt/model_doc/falcon_mamba#transformers.FalconMambaConfig)) e das entradas.

O método forward do [FalconMambaModel](/docs/transformers/main/pt/model_doc/falcon_mamba#transformers.FalconMambaModel) sobrescreve o método especial `__call__`.

Embora a receita para a passagem direta precise ser definida dentro desta função, deve-se chamar a instância de `Module` em seguida, em vez desta, pois a primeira cuida da execução das etapas de pré e pós-processamento, enquanto a segunda as ignora silenciosamente.

- **last_hidden_state** (`torch.Tensor` de forma `(batch_size, sequence_length, hidden_size)`, *opcional*) -- Sequência de hidden-states na saída da última camada do modelo.
- **cache_params** (`~cache_utils.Cache`, *opcional*) -- O estado do modelo no último passo de tempo. Pode ser usado em um método forward com o próximo `input_ids` para evitar fornecer os `input_ids` antigos.

  Inclui tanto as matrizes de estado do modelo de espaço de estados após o scan seletivo quanto os estados convolucionais
- **hidden_states** (`tuple[torch.Tensor]`, *opcional*, retornado quando `output_hidden_states=True` é passado ou quando `config.output_hidden_states=True`) -- Tupla de `torch.Tensor` (um para a saída dos embeddings, se o modelo tiver uma camada de embedding, + um para a saída de cada camada) de forma `(batch_size, sequence_length, hidden_size)`.

  Estados ocultos do modelo na saída de cada camada, além das saídas opcionais do embedding inicial.

## FalconMambaLMHeadModel[[transformers.FalconMambaForCausalLM]]

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

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

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

**Parâmetros:**

config ([FalconMambaConfig](/docs/transformers/main/pt/model_doc/falcon_mamba#transformers.FalconMambaConfig)) : Classe de configuração do modelo com todos os parâmetros do modelo. A inicialização com um arquivo de configuração não carrega os pesos associados ao modelo, apenas a configuração. Consulte o método [from_pretrained()](/docs/transformers/main/pt/main_classes/model#transformers.PreTrainedModel.from_pretrained) para carregar os pesos do modelo.

O transformer do modelo FALCON_MAMBA com uma cabeça de modelagem de linguagem no topo (camada linear com pesos vinculados aos embeddings de entrada).

Este modelo herda de [PreTrainedModel](/docs/transformers/main/pt/main_classes/model#transformers.PreTrainedModel). Consulte a documentação da classe pai para os métodos genéricos que a biblioteca implementa para todos os seus modelos (como download ou salvamento, redimensionamento dos embeddings de entrada, poda de cabeças, etc.).

Este modelo também é uma subclasse de [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) do PyTorch. Use-o como um Módulo PyTorch regular e consulte a documentação do PyTorch para todos os assuntos relacionados ao uso e comportamento gerais.

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

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/falcon_mamba/modeling_falcon_mamba.py#L784)

**Parâmetros:**

input_ids (`torch.LongTensor` de forma `(batch_size, sequence_length)`, *opcional*) : Índices dos tokens da sequência de entrada no vocabulário. O preenchimento (padding) será ignorado por padrão. Os índices podem ser obtidos usando [AutoTokenizer](/docs/transformers/main/pt/model_doc/auto#transformers.AutoTokenizer). Consulte [PreTrainedTokenizer.encode()](/docs/transformers/main/pt/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) e [PreTrainedTokenizer.__call__()](/docs/transformers/main/pt/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__) para mais detalhes. [O que são IDs de entrada?](../glossary#input-ids)

attention_mask (`torch.LongTensor` de forma `(batch_size, sequence_length)`, *opcional*) : Máscara para evitar a execução de atenção nos índices de tokens de preenchimento. Valores de máscara selecionados em `[0, 1]`:  - 1 para tokens que **não estão mascarados**, - 0 para tokens que **estão mascarados**.  [O que são máscaras de atenção?](../glossary#attention-mask)

inputs_embeds (`torch.Tensor` de forma `(batch_size, sequence_length, hidden_size)`, *opcional*) : Opcionalmente, em vez de passar `input_ids`, você pode escolher passar diretamente uma representação incorporada. Isso é útil se você quiser ter mais controle sobre como converter os índices de `input_ids` nos vetores associados do que a matriz de busca de incorporação interna do modelo.

cache_params (`Cache`, *opcional*) : Se for passado, o modelo usa o estado anterior em todos os blocos (o que resultará na saída para os `input_ids` fornecidos, como se o modelo adicionasse `state_input_ids + input_ids` como contexto).

labels (`torch.LongTensor` de forma `(batch_size, sequence_length)`, *opcional*) : Rótulos para modelagem de linguagem. Observe que os rótulos **são deslocados** dentro do modelo, ou seja, você pode definir `labels = input_ids` Os índices são selecionados em `[-100, 0, ..., config.vocab_size]` Todos os rótulos definidos como `-100` são ignorados (mascarados); a perda é calculada apenas para rótulos em `[0, ..., config.vocab_size]`

output_hidden_states (`bool`, *opcional*) : Indica se os estados ocultos de todas as camadas devem ser retornados. Consulte `hidden_states` em tensores retornados para mais detalhes.

return_dict (`bool`, *opcional*) : Se deve ou não retornar um [ModelOutput](/docs/transformers/main/pt/main_classes/output#transformers.utils.ModelOutput) em vez de uma tupla simples.

use_cache (`bool`, *opcional*) : Se definido como `True`, o `cache_params` é retornado e pode ser usado para gerar rapidamente os próximos logits.

logits_to_keep (`Union[int, torch.Tensor]`, *opcional*, padrão `0`) : Se for um `int`, calcula os logits para os últimos `logits_to_keep` tokens. Se for `0`, calcula os logits para todos os `input_ids` (caso especial). Apenas os logits do último token são necessários para a geração, e calculá-los apenas para esse token pode economizar memória, o que se torna bastante significativo para sequências longas ou tamanho de vocabulário grande. Se for um `torch.Tensor`, deve ser 1D, correspondendo aos índices a serem mantidos na dimensão de comprimento da sequência. Isso é útil ao usar o formato de tensor empacotado (uma única dimensão para lote e comprimento da sequência).

**Retorna:** `FalconMambaCausalLMOutput` ou `tuple(torch.Tensor)`

Um `FalconMambaCausalLMOutput` ou uma tupla de `torch.Tensor` (se `return_dict=False` for passado ou quando `config.return_dict=False`) contendo vários elementos, dependendo da configuração ([FalconMambaConfig](/docs/transformers/main/pt/model_doc/falcon_mamba#transformers.FalconMambaConfig)) e das entradas.

O método forward de [FalconMambaForCausalLM](/docs/transformers/main/pt/model_doc/falcon_mamba#transformers.FalconMambaForCausalLM) substitui o método especial `__call__`.

Embora a receita para a passagem direta precise ser definida dentro desta função, deve-se chamar a instância de `Module` em seguida, em vez desta, pois a primeira cuida da execução das etapas de pré e pós-processamento, enquanto a segunda as ignora silenciosamente.

- **loss** (`torch.Tensor` de forma `(1,)`, *opcional*, retornado quando `labels` é fornecido) -- Perda de modelagem de linguagem (para previsão do próximo token).
- **logits** (`torch.Tensor` de forma `(batch_size, sequence_length, config.vocab_size)`) -- Pontuações de previsão da cabeça de modelagem de linguagem (pontuações para cada token do vocabulário antes do SoftMax).
- **cache_params** (`~cache_utils.Cache`, *opcional*) -- O estado do modelo no último passo de tempo. Pode ser usado em um método forward com o próximo `input_ids` para evitar fornecer os `input_ids` antigos.

  Inclui tanto as matrizes de estado do modelo de espaço de estados após o scan seletivo quanto os estados convolucionais
- **hidden_states** (`tuple[torch.Tensor]`, *opcional*, retornado quando `output_hidden_states=True` é passado ou quando `config.output_hidden_states=True`) -- Tupla de `torch.Tensor` (um para a saída dos embeddings, se o modelo tiver uma camada de embedding, + um para a saída de cada camada) de forma `(batch_size, sequence_length, hidden_size)`.

  Estados ocultos do modelo na saída de cada camada, além das saídas opcionais do embedding inicial.

Exemplo:

```python
```