Transformers documentation
xLSTM
Este modelo foi publicado no HF papers em 2024-05-07 e contribuído para o Hugging Face Transformers em 2025-07-25.
xLSTM
Visão geral
O modelo xLSTM foi proposto em xLSTM: Extended Long Short-Term Memory 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 portões exponenciais, expansão de memória matricial e treinamento e ingestão paralelizáveis.
A variante modelo 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. O código original pode ser encontrado aqui.
Observações
- Use padding à esquerda para geração em lote. Consulte Lado do padding.
xLSTMConfig
classe transformers.xLSTMConfig
< source >( transformers_version: str | None = Nonearchitectures: list[str] | None = Noneoutput_hidden_states: bool | None = Falsereturn_dict: bool | None = Truedtype: str | torch.dtype | None = Nonechunk_size_feed_forward: int = 0is_encoder_decoder: bool = Falseid2label: dict[int, str] | dict[str, str] | None = Nonelabel2id: dict[str, int] | dict[str, str] | None = Noneproblem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = Nonevocab_size: int = 50304hidden_size: int = 4096embedding_dim: int | None = Nonenum_hidden_layers: int = 32num_blocks: int | None = Nonenum_heads: int = 8use_bias: bool = Falsenorm_reduction_force_float32: bool = Truetie_word_embeddings: bool = Falseadd_out_norm: bool = Truenorm_eps: float = 1e-06qk_dim_factor: float = 0.5v_dim_factor: float = 1.0chunkwise_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 = 64return_last_states: bool = Trueautocast_kernel_dtype: typing.Literal['float32', 'bfloat16', 'float16'] = 'bfloat16'eps: float = 1e-06inference_state_dtype: typing.Literal['float32', 'bfloat16', 'float16'] = 'float32'ffn_proj_factor: float = 2.667ffn_round_up_to_multiple_of: int = 64gate_soft_cap: float = 15.0output_logit_soft_cap: float = 30.0weight_mode: typing.Literal['single', 'fused'] = 'single'use_cache: bool = Truepad_token_id: int | None = 1bos_token_id: int | None = 0eos_token_id: int | list[int] | None = 2max_inference_chunksize: int = 16384 )
Parâmetros
- vocab_size (
int, opcional, padrão50304) — Tamanho do vocabulário do modelo. Define o número de tokens diferentes que podem ser representados pelosinput_ids. - hidden_size (
int, opcional, padrão4096) — Dimensão das representações ocultas. - embedding_dim (
int, opcional) — Dimensão dos embeddings e dos estados ocultos. - num_hidden_layers (
int, opcional, padrão32) — 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ãoFalse) — Indica se devem ser usadas viés no modelo xLSTM. - norm_reduction_force_float32 (
bool, opcional, opcional, padrãoTrue) — Se deve forçar a operação de redução de norma float32 a ser executada em precisão fp32. - tie_word_embeddings (
bool, opcional, padrãoFalse) — Se deve vincular as embeddings de pesos de acordo com o mapeamentotied_weights_keysdo modelo. - add_out_norm (
bool, opcional, opcional, padrãoTrue) — Se deve adicionar uma normalização de saída após os blocos, antes do LMHead. - norm_eps (
float, opcional, padrão1e-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 chunk. - return_last_states (
bool, opcional, opcional, padrãoTrue) — 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ão1e-06) — O epsilon utilizado 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 projeção pós-up da rede Feed Forward com gate. - ffn_round_up_to_multiple_of (
int, opcional, opcional, padrão 64) — Fator de arredondamento do valor da projeção pós-up da rede Feed Forward com gate. - 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) dos 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ãoTrue) — Se o modelo deve ou não retornar as últimas chaves/valores de atenção (não usado por todos os modelos). Relevante apenas seconfig.is_decoder=Trueou quando o modelo for um modelo generativo somente decodificador. - pad_token_id (
int, opcional, padrão1) — ID do token usado para preenchimento no vocabulário. - bos_token_id (
int, opcional, padrão0) — ID do token usado para o início do fluxo no vocabulário. - eos_token_id (
Union[int, list[int]], opcional, padrão2) — 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, a fim de 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
Os objetos de configuração herdam de PreTrainedConfig e podem ser usados para controlar as saídas do modelo. Consulte a documentação de PreTrainedConfig para mais informações.
Exemplo:
>>> 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.configxLSTMModel
classe transformers.xLSTMModel
< source >( config: xLSTMConfig )
Parâmetros
- config (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() 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. 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 do PyTorch. Use-o como um Módulo PyTorch regular e consulte a documentação do PyTorch para todos os assuntos relacionados ao uso geral e ao comportamento.
forward
< source >( input_ids: typing.Optional[torch.LongTensor] = Noneinputs_embeds: typing.Optional[torch.LongTensor] = Nonecache_params: transformers.models.xlstm.modeling_xlstm.xLSTMCache | None = Noneuse_cache: bool | None = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → xLSTMOutput or tuple(torch.Tensor)
Parâmetros
- input_ids (
torch.LongTensorde forma(batch_size, sequence_length), opcional) — Índices dos tokens da sequência de entrada no vocabulário. O padding será ignorado por padrão.Os índices podem ser obtidos usando AutoTokenizer. Consulte PreTrainedTokenizer.encode() e PreTrainedTokenizer.call() para mais detalhes.
- inputs_embeds (
torch.LongTensorde forma(batch_size, sequence_length, hidden_size), opcional) — Opcionalmente, em vez de passarinput_ids, você pode escolher passar diretamente uma representação incorporada. Isso é útil se você quiser ter mais controle sobre como converter os índices deinput_idsnos 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 comoTrue, os estados de chave-valorpast_key_valuessão retornados e podem ser usados para acelerar a decodificação (vejapast_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) e das entradas.
O método forward do 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
Moduleem 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.Tensorde forma(batch_size, sequence_length, hidden_size), opcional) — Sequência de estados ocultos 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óximoinput_idspara evitar fornecer osinput_idsantigos.hidden_states (
tuple[torch.Tensor], opcional, retornado quandooutput_hidden_states=Trueé passado ou quandoconfig.output_hidden_states=True) — Tupla detorch.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
classe transformers.xLSTMForCausalLM
< source >( config: xLSTMConfig )
Parâmetros
- config (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() para carregar os pesos do modelo.
O Modelo Xlstm para modelagem de linguagem causal.
Este modelo herda de 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 do PyTorch. Use-o como um Módulo PyTorch regular e consulte a documentação do PyTorch para todos os assuntos relacionados ao uso geral e ao comportamento.
forward
< source >( input_ids: typing.Optional[torch.LongTensor] = Noneinputs_embeds: typing.Optional[torch.Tensor] = Nonecache_params: transformers.models.xlstm.modeling_xlstm.xLSTMCache | None = Nonelabels: typing.Optional[torch.LongTensor] = Noneuse_cache: bool | None = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → xLSTMCausalLMOutput or tuple(torch.Tensor)
Parâmetros
- input_ids (
torch.LongTensorde forma(batch_size, sequence_length), opcional) — Índices dos tokens da sequência de entrada no vocabulário. O padding será ignorado por padrão.Os índices podem ser obtidos usando AutoTokenizer. Consulte PreTrainedTokenizer.encode() e PreTrainedTokenizer.call() para mais detalhes.
- inputs_embeds (
torch.Tensorde forma(batch_size, sequence_length, hidden_size), opcional) — Opcionalmente, em vez de passarinput_ids, você pode escolher passar diretamente uma representação incorporada. Isso é útil se você quiser ter mais controle sobre como converter os índices deinput_idsnos 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.LongTensorde forma(batch_size, sequence_length), opcional) — Rótulos para o cálculo da perda de modelagem de linguagem mascarada. Os índices devem estar em[0, ..., config.vocab_size]ou ser -100 (veja a docstring deinput_ids). Tokens com índices definidos como-100são ignorados (mascarados); a perda é calculada apenas para os tokens com rótulos em[0, ..., config.vocab_size]. - use_cache (
bool, opcional) — Se definido comoTrue, os estados de chave-valorpast_key_valuessão retornados e podem ser usados para acelerar a decodificação (vejapast_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) e das entradas.
O método forward de 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
Moduleem 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.Tensorde forma(1,), opcional, retornado quandolabelsé fornecido) — Perda de modelagem de linguagem (para previsão do próximo token).logits (
torch.Tensorde 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 de forward com o próximoinput_idspara evitar fornecer osinput_idsantigos.hidden_states (
tuple[torch.Tensor], opcional, retornado quandooutput_hidden_states=Trueé passado ou quandoconfig.output_hidden_states=True) — Tupla detorch.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.