# xLSTM

## Visão geral

O modelo xLSTM foi proposto em [xLSTM: Extended Long Short-Term Memory](https://huggingface.co/papers/2405.04517) por Maximilian Beck*, Korbinian Pöppel*, Markus Spanring, Andreas Auer, Oleksandra Prudnikova, Michael Kopp, Günter Klambauer, Johannes Brandstetter e Sepp Hochreiter. O xLSTM atualiza a arquitetura original do LSTM para ser competitivo com os modelos Transformer, introduzindo gating exponencial, expansão de memória matricial e treinamento e ingestão paralelizáveis.

A variante [modelo 7B](https://huggingface.co/NX-AI/xLSTM-7b) foi treinada pela equipe xLSTM: Maximilian Beck, Korbinian Pöppel, Phillip Lippe, Richard Kurle, Patrick Blies, Sebastian Böck e Sepp Hochreiter, da NXAI.

O resumo do artigo é o seguinte:

*Na década de 1990, o carrossel de erro constante e o gating foram introduzidos como as ideias centrais do Long Short-Term Memory (LSTM). Desde então, os LSTMs resistiram ao teste do tempo e contribuíram para inúmeras histórias de sucesso no deep learning, em particular constituíram os primeiros Large Language Models (LLMs). No entanto, o advento da tecnologia Transformer, com o self-attention paralelizável em seu núcleo, marcou o início de uma nova era, superando os LSTMs em escala. Agora, levantamos uma pergunta simples: até onde chegamos no modelamento de linguagem ao escalar LSTMs para bilhões de parâmetros, aproveitando as técnicas mais recentes de LLMs modernos, mas mitigando as limitações conhecidas dos LSTMs? Em primeiro lugar, introduzimos o gating exponencial com técnicas adequadas de normalização e estabilização. Em segundo lugar, modificamos a estrutura de memória do LSTM, obtendo: (i) sLSTM com memória escalar, atualização escalar e nova mistura de memória, (ii) mLSTM totalmente paralelizável com memória matricial e regra de atualização de covariância. A integração dessas extensões de LSTM em espinhas dorsais de blocos residuais resulta em blocos xLSTM, que são então empilhados residualmente em arquiteturas xLSTM. O gating exponencial e as estruturas de memória modificadas aumentam as capacidades do xLSTM para realizar-se favoravelmente quando comparado a Transformers e State Space Models de última geração, tanto em desempenho quanto em escalabilidade.*

Este modelo foi contribuído por [NX-AI](https://huggingface.co/NX-AI). O código original pode ser encontrado [aqui](https://github.com/NX-AI/xlstm).

## Observações

- Use padding à esquerda para geração em lote. Consulte [Lado do padding](../llm_tutorial#padding-side).

## xLSTMConfig[[transformers.xLSTMConfig]]

#### transformers.xLSTMConfig[[transformers.xLSTMConfig]]

```python
transformers.xLSTMConfig(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 = 50304, hidden_size: int = 4096, embedding_dim: int | None = None, num_hidden_layers: int = 32, num_blocks: int | None = None, num_heads: int = 8, use_bias: bool = False, norm_reduction_force_float32: bool = True, tie_word_embeddings: bool = False, add_out_norm: bool = True, norm_eps: float = 1e-06, qk_dim_factor: float = 0.5, v_dim_factor: float = 1.0, chunkwise_kernel: typing.Literal['chunkwise--native_autograd', 'parallel--native_autograd'] = 'chunkwise--native_autograd', sequence_kernel: typing.Literal['native_sequence__native'] = 'native_sequence__native', step_kernel: typing.Literal['native'] = 'native', mode: typing.Literal['train', 'train_with_padding', 'inference'] = 'inference', chunk_size: int = 64, return_last_states: bool = True, autocast_kernel_dtype: typing.Literal['float32', 'bfloat16', 'float16'] = 'bfloat16', eps: float = 1e-06, inference_state_dtype: typing.Literal['float32', 'bfloat16', 'float16'] = 'float32', ffn_proj_factor: float = 2.667, ffn_round_up_to_multiple_of: int = 64, gate_soft_cap: float = 15.0, output_logit_soft_cap: float = 30.0, weight_mode: typing.Literal['single', 'fused'] = 'single', use_cache: bool = True, pad_token_id: int | None = 1, bos_token_id: int | None = 0, eos_token_id: int | list[int] | None = 2, max_inference_chunksize: int = 16384)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/xlstm/configuration_xlstm.py#L58)

**Parâmetros:**

vocab_size (`int`, *opcional*, padrão `50304`) : 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 `4096`) : Dimensão das representações ocultas.

embedding_dim (`int`, *opcional*) : Dimensionalidade dos embeddings e dos estados ocultos.

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

num_blocks (`int`, opcional, *opcional*, padrão 32) : Número de blocos do modelo xLSTM, use num_hidden_layers se for None.

num_heads (`int`, opcional, *opcional*, padrão 8) : Número de cabeças para a Camada/Célula xLSTM.

use_bias (`bool`, opcional, *opcional*, padrão `False`) : Se deve usar vieses no modelo xLSTM.

norm_reduction_force_float32 (`bool`, opcional, *opcional*, padrão `True`) : Se deve forçar a operação de redução da norma float32 a ser executada em precisão fp32.

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

add_out_norm (`bool`, opcional, *opcional*, padrão `True`) : Se deve adicionar uma normalização de saída após os blocos, antes do LMHead.

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

qk_dim_factor (`float`, opcional, *opcional*, padrão 0.5) : Fator de escala para a dimensão da query e da key.

v_dim_factor (`float`, opcional, *opcional*, padrão 1.0) : Fator de escala para a dimensão de valor.

chunkwise_kernel (`ChunkwiseKernelType`, opcional, *opcional*, padrão `"chunkwise--native_autograd"`) : Tipo de kernel para o modo de processamento por blocos.

sequence_kernel (`SequenceKernelType`, opcional, *opcional*, padrão `"native_sequence__native"`) : Tipo de kernel para o modo de processamento de sequência.

step_kernel (`StepKernelType`, opcional, *opcional*, padrão `"native"`) : Tipo de kernel para o modo de processamento de etapas.

mode (`BackendModeType`, opcional, *opcional*, padrão `"inference"`) : Modo de operação (o modo de inferência é necessário para a geração).

chunk_size (`int`, opcional, *opcional*, padrão é 64) : Tamanho interno do bloco.

return_last_states (`bool`, opcional, *opcional*, padrão `True`) : Se deve retornar os últimos estados / cache internamente. Necessário como True para geração.

autocast_kernel_dtype (`DtypeType`, opcional, *opcional*, padrão `"bfloat16"`) : dtype do kernel para os estados.

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

inference_state_dtype (`DtypeType`, opcional, *opcional*, padrão `"float32"`) : dtype do kernel para estados na inferência.

ffn_proj_factor (`float`, opcional, *opcional*, padrão 2.667) : Fator de tamanho da rede Feed Forward com gate de pós-projeção.

ffn_round_up_to_multiple_of (`int`, opcional, *opcional*, padrão 64) : Fator de arredondamento do tamanho da rede Feed Forward com gate da projeção pós-up.

gate_soft_cap (`float`, opcional, *opcional*, padrão 15.0) : Escala do limite suave do gate.

output_logit_soft_cap (`float`, opcional, *opcional*, padrão 30.0) : Escala do limite suave (soft cap) para os logits de saída.

weight_mode (`Literal`, *opcional*, padrão `"single"`) : Se as camadas lineares paralelas são separadas ou fundidas (single).

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.

pad_token_id (`int`, *opcional*, padrão `1`) : 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 `2`) : ID do token usado para o fim do fluxo no vocabulário.

max_inference_chunksize (`int`, opcional, *opcional*, padrão 16384) : Limita o tamanho do bloco para inferência para economizar memória.

Esta é a classe de configuração para armazenar a configuração de um xLSTMModel. Ela é usada para instanciar um modelo Xlstm 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 [NX-AI/xLSTM-7b](https://huggingface.co/NX-AI/xLSTM-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 xLSTMConfig, xLSTMModel

>>> # Initializing a xLSTM configuration
>>> configuration = xLSTMConfig()

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

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

## xLSTMModel[[transformers.xLSTMModel]]

#### transformers.xLSTMModel[[transformers.xLSTMModel]]

```python
transformers.xLSTMModel(config: xLSTMConfig)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/xlstm/modeling_xlstm.py#L1394)

**Parâmetros:**

config ([xLSTMConfig](/docs/transformers/main/pt/model_doc/xlstm#transformers.xLSTMConfig)) : 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 Xlstm puro, que produz estados ocultos brutos sem nenhum head 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.xLSTMModel.forward]]

```python
forward(input_ids: typing.Optional[torch.LongTensor] = None, inputs_embeds: typing.Optional[torch.LongTensor] = None, cache_params: transformers.models.xlstm.modeling_xlstm.xLSTMCache | None = None, use_cache: bool | None = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/xlstm/modeling_xlstm.py#L1411)

**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 (`xLSTMCache`, *opcional*) : O xLSTMCache que carrega os estados da RNN.

use_cache (`bool`, *opcional*) : Se definido como `True`, os estados de chave-valor de `past_key_values` são retornados e podem ser usados para acelerar a decodificação (veja `past_key_values`).

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

Um `xLSTMOutput` 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 ([xLSTMConfig](/docs/transformers/main/pt/model_doc/xlstm#transformers.xLSTMConfig)) e das entradas.

O método forward do [xLSTMModel](/docs/transformers/main/pt/model_doc/xlstm#transformers.xLSTMModel) 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.

- **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** (`~models.xlstm.modeling_xlstm.xLSTMCache`, *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 antigos `input_ids`.
- **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.

## xLSTMLMHeadModel[[transformers.xLSTMForCausalLM]]

#### transformers.xLSTMForCausalLM[[transformers.xLSTMForCausalLM]]

```python
transformers.xLSTMForCausalLM(config: xLSTMConfig)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/xlstm/modeling_xlstm.py#L1517)

**Parâmetros:**

config ([xLSTMConfig](/docs/transformers/main/pt/model_doc/xlstm#transformers.xLSTMConfig)) : 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 Xlstm para modelagem de linguagem causal.

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.xLSTMForCausalLM.forward]]

```python
forward(input_ids: typing.Optional[torch.LongTensor] = None, inputs_embeds: typing.Optional[torch.Tensor] = None, cache_params: transformers.models.xlstm.modeling_xlstm.xLSTMCache | None = None, labels: typing.Optional[torch.LongTensor] = None, use_cache: bool | None = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/xlstm/modeling_xlstm.py#L1537)

**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.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 (`xLSTMCache`, *opcional*) : O xLSTMCache que carrega os estados da RNN.

labels (`torch.LongTensor` de forma `(batch_size, sequence_length)`, *opcional*) : Rótulos para calcular a perda de modelagem de linguagem mascarada. Os índices devem estar em `[0, ..., config.vocab_size]` ou ser -100 (veja a docstring de `input_ids`). Tokens com índices definidos como `-100` são ignorados (mascarados); a perda é calculada apenas para os tokens com rótulos em `[0, ..., config.vocab_size]`.

use_cache (`bool`, *opcional*) : Se definido como `True`, os estados de chave-valor de `past_key_values` são retornados e podem ser usados para acelerar a decodificação (veja `past_key_values`).

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

Um `xLSTMCausalLMOutput` 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 ([xLSTMConfig](/docs/transformers/main/pt/model_doc/xlstm#transformers.xLSTMConfig)) e das entradas.

O método forward de [xLSTMForCausalLM](/docs/transformers/main/pt/model_doc/xlstm#transformers.xLSTMForCausalLM) 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** (`xLSTMCache`, *opcional*, contendo os estados da RNN) -- 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 antigos `input_ids`.
- **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
```