# xLSTM ## Aperçu Le modèle xLSTM a été proposé dans [xLSTM: Extended Long Short-Term Memory](https://huggingface.co/papers/2405.04517) par Maximilian Beck*, Korbinian Pöppel*, Markus Spanring, Andreas Auer, Oleksandra Prudnikova, Michael Kopp, Günter Klambauer, Johannes Brandstetter et Sepp Hochreiter. xLSTM met à jour l’architecture LSTM originale afin de rivaliser avec les modèles Transformer en introduisant un contrôle exponentiel, une extension de la mémoire matricielle, ainsi qu’un entraînement et une ingestion parallélisables. La variante [7B model](https://huggingface.co/NX-AI/xLSTM-7b) a été entraînée par l'équipe xLSTM : Maximilian Beck, Korbinian Pöppel, Phillip Lippe, Richard Kurle, Patrick Blies, Sebastian Böck et Sepp Hochreiter, chez NXAI. L'abstract de l'article est le suivant : *Dans les années 1990, le carrousel d'erreur constant et le gating ont été introduits comme idées centrales de la mémoire à court et long terme (LSTM). Depuis lors, les LSTM ont fait leurs preuves et ont contribué à de nombreuses réussites en deep learning, constituant notamment les premiers grands modèles de langage (LLM). Cependant, l'avènement de la technologie Transformer, dont le cœur est l'auto-attention parallélisable, a marqué l'aube d'une nouvelle ère, dépassant les LSTM à grande échelle. Nous posons désormais une question simple : jusqu'où peut-on aller en modélisation du langage en passant les LSTM à l'échelle de milliards de paramètres, en exploitant les dernières techniques des LLM modernes, tout en atténuant les limitations connues des LSTM ? Premièrement, nous introduisons un gating exponentiel avec des techniques de normalisation et de stabilisation appropriées. Deuxièmement, nous modifions la structure de mémoire du LSTM, obtenant : (i) sLSTM avec une mémoire scalaire, une mise à jour scalaire et un nouveau mélange de mémoire, (ii) mLSTM, entièrement parallélisable, avec une mémoire matricielle et une règle de mise à jour de covariance. L'intégration de ces extensions LSTM dans des squelettes de blocs résiduels produit des blocs xLSTM, qui sont ensuite empilés de manière résiduelle pour former des architectures xLSTM. Le gating exponentiel et les structures de mémoire modifiées renforcent les capacités des xLSTM, leur permettant de se comporter favorablement par rapport aux Transformers et aux modèles d'espace d'état de pointe, tant en termes de performance que de mise à l'échelle.* Ce modèle a été contribué par [NX-AI](https://huggingface.co/NX-AI). Le code d’origine est disponible [ici](https://github.com/NX-AI/xlstm). ## Notes - Utilisez le padding à gauche pour la génération par lots. Voir [Padding side](../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) ``` [Source](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/xlstm/configuration_xlstm.py#L58) **Paramètres :** vocab_size (`int`, *facultatif*, valeur par défaut `50304`) : Taille du vocabulaire du modèle. Définit le nombre de jetons différents qui peuvent être représentés par `input_ids`. hidden_size (`int`, *facultatif*, valeur par défaut `4096`) : Dimension des représentations cachées. embedding_dim (`int`, *facultatif*) : Dimension des embeddings et des états cachés. num_hidden_layers (`int`, *facultatif*, valeur par défaut `32`) : Nombre de couches cachées dans le décodeur Transformer. num_blocks (`int`, optionnel, *optionnel*, valeur par défaut : 32) : Nombre de blocs du modèle xLSTM. Si la valeur est None, utilisez num_hidden_layers. num_heads (`int`, optionnel, *optionnel*, par défaut 8) : Nombre de têtes pour la couche/cellule xLSTM. use_bias (`bool`, optionnel, *optionnel*, valeur par défaut `False`) : Indique s'il faut utiliser des biais dans le modèle xLSTM. norm_reduction_force_float32 (`bool`, facultatif, *facultatif*, valeur par défaut `True`) : Indique s'il faut forcer l'opérateur de réduction de la norme en float32 à s'exécuter en précision fp32. tie_word_embeddings (`bool`, *facultatif*, valeur par défaut `False`) : Indique s'il faut lier les embeddings de poids selon la correspondance `tied_weights_keys` du modèle. add_out_norm (`bool`, optionnel, *optionnel*, par défaut `True`) : Indique s'il faut ajouter une normalisation de sortie après les blocs, avant le LMHead. norm_eps (`float`, *facultatif*, par défaut `1e-06`) : L'épsilon utilisé par les couches de normalisation par couche. qk_dim_factor (`float`, optionnel, *optionnel*, valeur par défaut 0.5) : Facteur d'échelle pour la dimension des requêtes et des clés. v_dim_factor (`float`, optionnel, *optionnel*, valeur par défaut : 1.0) : Facteur d'échelle pour la dimension de valeur. chunkwise_kernel (`ChunkwiseKernelType`, optionnel, *optionnel*, par défaut `"chunkwise--native_autograd"`) : Type de noyau pour le mode de traitement par morceaux. sequence_kernel (`SequenceKernelType`, optionnel, *optionnel*, par défaut `"native_sequence__native"`) : Type de noyau pour le mode de traitement des séquences. step_kernel (`StepKernelType`, facultatif, *optional*, par défaut `"native"`) : Type de noyau pour le mode de traitement par étapes. mode (`BackendModeType`, facultatif, *facultatif*, valeur par défaut `"inference"`) : Mode de fonctionnement (l'inférence est requise pour la génération). chunk_size (`int`, optionnel, *optionnel*, valeur par défaut : 64) : Taille de bloc interne. return_last_states (`bool`, facultatif, *facultatif*, valeur par défaut `True`) : Indique s'il faut retourner les derniers états / le cache en interne. Doit être True pour la génération. autocast_kernel_dtype (`DtypeType`, optionnel, *optionnel*, par défaut `"bfloat16"`) : Dtype du noyau pour les états. eps (`float`, *facultatif*, par défaut `1e-06`) : L'épsilon utilisé par les couches de normalisation par couche. inference_state_dtype (`DtypeType`, facultatif, *facultatif*, valeur par défaut `"float32"`) : Dtype du noyau pour les états lors de l'inférence. ffn_proj_factor (`float`, optionnel, *optionnel*, valeur par défaut 2.667) : Facteur de taille du réseau Feed Forward à porte de la projection post-up. ffn_round_up_to_multiple_of (`int`, optionnel, *optionnel*, par défaut 64) : Facteur de taille de la valeur arrondie du réseau Feed Forward à porte après la projection post-up. gate_soft_cap (`float`, facultatif, *facultatif*, valeur par défaut : 15.0) : Échelle de la limite douce de la porte. output_logit_soft_cap (`float`, optionnel, *optionnel*, valeur par défaut : 30.0) : Échelle de la limite douce (soft cap) appliquée aux logits de sortie. weight_mode (`Literal`, *facultatif*, valeur par défaut `"single"`) : Indique si les couches linéaires parallèles sont séparées ou fusionnées (single). use_cache (`bool`, *facultatif*, valeur par défaut `True`) : Indique si le modèle doit retourner les dernières attentions clés/valeurs (non utilisé par tous les modèles). Pertinent uniquement si `config.is_decoder=True` ou si le modèle est un modèle génératif de type décodeur uniquement. pad_token_id (`int`, *facultatif*, valeur par défaut `1`) : Identifiant du jeton utilisé pour le bourrage dans le vocabulaire. bos_token_id (`int`, *facultatif*, valeur par défaut `0`) : Identifiant du jeton utilisé pour le début de flux dans le vocabulaire. eos_token_id (`Union[int, list[int]]`, *facultatif*, valeur par défaut `2`) : Identifiant de jeton utilisé pour la fin de flux dans le vocabulaire. max_inference_chunksize (`int`, optionnel, *optionnel*, valeur par défaut 16384) : Limite la taille des blocs pour l'inférence afin d'économiser de la mémoire. Il s'agit de la classe de configuration destinée à stocker la configuration d'un xLSTMModel. Elle est utilisée pour instancier un modèle Xlstm en fonction des arguments spécifiés, en définissant l'architecture du modèle. L'instanciation d'une configuration avec les valeurs par défaut produira une configuration similaire à celle de [NX-AI/xLSTM-7b](https://huggingface.co/NX-AI/xLSTM-7b) Les objets de configuration héritent de [PreTrainedConfig](/docs/transformers/v5.23.0/fr/main_classes/configuration#transformers.PreTrainedConfig) et peuvent être utilisés pour contrôler les sorties du modèle. Consultez la documentation de [PreTrainedConfig](/docs/transformers/v5.23.0/fr/main_classes/configuration#transformers.PreTrainedConfig) pour plus d’informations. Exemple : ```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) ``` [Source](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/xlstm/modeling_xlstm.py#L1394) **Paramètres :** config ([xLSTMConfig](/docs/transformers/v5.23.0/fr/model_doc/xlstm#transformers.xLSTMConfig)) : Classe de configuration du modèle contenant tous les paramètres du modèle. L'initialisation à partir d'un fichier de configuration ne charge pas les poids associés au modèle, uniquement la configuration. Consultez la méthode [from_pretrained()](/docs/transformers/v5.23.0/fr/main_classes/model#transformers.PreTrainedModel.from_pretrained) pour charger les poids du modèle. Le modèle Xlstm brut, qui produit des états cachés bruts sans aucune tête spécifique au sommet. Ce modèle hérite de [PreTrainedModel](/docs/transformers/v5.23.0/fr/main_classes/model#transformers.PreTrainedModel). Consultez la documentation de la classe parente pour les méthodes génériques que la bibliothèque implémente pour tous ses modèles (tels que le téléchargement ou l'enregistrement, le redimensionnement des embeddings d'entrée, l'élagage des têtes, etc.). Ce modèle est également une sous-classe de [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) de PyTorch. Utilisez-le comme un module PyTorch standard et consultez la documentation de PyTorch pour tout ce qui concerne l’utilisation et le comportement généraux. #### 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: *) ``` [Source](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/xlstm/modeling_xlstm.py#L1411) **Paramètres :** input_ids (`torch.LongTensor` de forme `(batch_size, sequence_length)`, *facultatif*) : Indices des jetons de la séquence d'entrée dans le vocabulaire. Le bourrage (padding) sera ignoré par défaut. Les indices peuvent être obtenus à l'aide de [AutoTokenizer](/docs/transformers/v5.23.0/fr/model_doc/auto#transformers.AutoTokenizer). Consultez [PreTrainedTokenizer.encode()](/docs/transformers/v5.23.0/fr/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) et [PreTrainedTokenizer.__call__()](/docs/transformers/v5.23.0/fr/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__) pour plus de détails. [Que sont les identifiants d'entrée ?](../glossary#input-ids) inputs_embeds (`torch.LongTensor` de forme `(batch_size, sequence_length, hidden_size)`, *facultatif*) : Facultativement, au lieu de passer `input_ids`, vous pouvez choisir de passer directement une représentation intégrée. Cela est utile si vous souhaitez un meilleur contrôle sur la manière de convertir les indices `input_ids` en vecteurs associés, par rapport à la matrice de recherche d'intégration interne du modèle. cache_params (`xLSTMCache`, *facultatif*) : le xLSTMCache qui transporte les états du RNN. use_cache (`bool`, *facultatif*) : Si défini sur `True`, les états clé-valeur de `past_key_values` sont renvoyés et peuvent être utilisés pour accélérer le décodage (voir `past_key_values`). **Retourne :** `xLSTMOutput` ou `tuple(torch.Tensor)` Un `xLSTMOutput` ou un tuple de `torch.Tensor` (si `return_dict=False` est passé ou lorsque `config.return_dict=False`) comprenant divers éléments selon la configuration ([xLSTMConfig](/docs/transformers/v5.23.0/fr/model_doc/xlstm#transformers.xLSTMConfig)) et les entrées. La méthode forward de [xLSTMModel](/docs/transformers/v5.23.0/fr/model_doc/xlstm#transformers.xLSTMModel) redéfinit la méthode spéciale `__call__`. Bien que la recette de la passe avant doive être définie dans cette fonction, il faut ensuite appeler l'instance `Module` plutôt que celle-ci, car la première gère l'exécution des étapes de prétraitement et de post-traitement, tandis que la seconde les ignore silencieusement. - **last_hidden_state** (`torch.Tensor` de forme `(batch_size, sequence_length, hidden_size)`, *facultatif*) -- Séquence d'états cachés à la sortie de la dernière couche du modèle. - **cache_params** (`~models.xlstm.modeling_xlstm.xLSTMCache`, *facultatif*) -- L'état du modèle à la dernière étape temporelle. Peut être utilisé dans une méthode forward avec les `input_ids` suivants pour éviter de fournir les anciens `input_ids`. - **hidden_states** (`tuple[torch.Tensor]`, *facultatif*, renvoyé lorsque `output_hidden_states=True` est passé ou lorsque `config.output_hidden_states=True`) -- Tuple de `torch.Tensor` (un pour la sortie des embeddings, si le modèle possède une couche d'embedding, + un pour la sortie de chaque couche) de forme `(batch_size, sequence_length, hidden_size)`. États cachés du modèle à la sortie de chaque couche, ainsi que les sorties d'incorporation initiales facultatives. ## xLSTMLMHeadModel[[transformers.xLSTMForCausalLM]] #### transformers.xLSTMForCausalLM[[transformers.xLSTMForCausalLM]] ```python transformers.xLSTMForCausalLM(config: xLSTMConfig) ``` [Source](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/xlstm/modeling_xlstm.py#L1517) **Paramètres :** config ([xLSTMConfig](/docs/transformers/v5.23.0/fr/model_doc/xlstm#transformers.xLSTMConfig)) : Classe de configuration du modèle contenant tous les paramètres du modèle. L'initialisation à partir d'un fichier de configuration ne charge pas les poids associés au modèle, uniquement la configuration. Consultez la méthode [from_pretrained()](/docs/transformers/v5.23.0/fr/main_classes/model#transformers.PreTrainedModel.from_pretrained) pour charger les poids du modèle. Le modèle Xlstm pour la modélisation causale de langage. Ce modèle hérite de [PreTrainedModel](/docs/transformers/v5.23.0/fr/main_classes/model#transformers.PreTrainedModel). Consultez la documentation de la classe parente pour les méthodes génériques que la bibliothèque implémente pour tous ses modèles (tels que le téléchargement ou l'enregistrement, le redimensionnement des embeddings d'entrée, l'élagage des têtes, etc.). Ce modèle est également une sous-classe de [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) de PyTorch. Utilisez-le comme un module PyTorch standard et consultez la documentation de PyTorch pour tout ce qui concerne l’utilisation et le comportement généraux. #### 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: *) ``` [Source](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/xlstm/modeling_xlstm.py#L1537) **Paramètres :** input_ids (`torch.LongTensor` de forme `(batch_size, sequence_length)`, *facultatif*) : Indices des jetons de la séquence d'entrée dans le vocabulaire. Le bourrage (padding) sera ignoré par défaut. Les indices peuvent être obtenus à l'aide de [AutoTokenizer](/docs/transformers/v5.23.0/fr/model_doc/auto#transformers.AutoTokenizer). Consultez [PreTrainedTokenizer.encode()](/docs/transformers/v5.23.0/fr/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) et [PreTrainedTokenizer.__call__()](/docs/transformers/v5.23.0/fr/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__) pour plus de détails. [Que sont les identifiants d'entrée ?](../glossary#input-ids) inputs_embeds (`torch.Tensor` de forme `(batch_size, sequence_length, hidden_size)`, *facultatif*) : Facultativement, au lieu de passer `input_ids`, vous pouvez choisir de passer directement une représentation intégrée. Cela est utile si vous souhaitez un meilleur contrôle sur la manière de convertir les indices `input_ids` en vecteurs associés, par rapport à la matrice de recherche d'intégration interne du modèle. cache_params (`xLSTMCache`, *facultatif*) : le xLSTMCache qui transporte les états du RNN. labels (`torch.LongTensor` de forme `(batch_size, sequence_length)`, *facultatif*) : Étiquettes pour le calcul de la perte de modélisation de langage causale. Les indices doivent être dans `[-100, 0, ..., config.vocab_size]` (voir la docstring de `input_ids`). Les jetons dont l'indice est défini sur `-100` sont ignorés (masqués) ; la perte n'est calculée que pour les jetons dont l'étiquette est dans `[0, ..., config.vocab_size]`. Les étiquettes sont **décalées en interne** de sorte que `labels[..., 1:]` sont utilisés pour prédire `logits[..., :-1, :]`. Transmettez des étiquettes non décalées correspondant à `input_ids` (c'est-à-dire `labels = input_ids`). Ne **décalez pas** vous-même les étiquettes avant de les transmettre. Si les étiquettes sont déjà décalées (par exemple avec le parallélisme de séquence), transmettez-les en tant qu'argument mot-clé `shift_labels` et elles seront utilisées telles quelles. Il faut toujours transmettre `labels` pour que la perte soit calculée. use_cache (`bool`, *facultatif*) : Si défini sur `True`, les états clé-valeur de `past_key_values` sont renvoyés et peuvent être utilisés pour accélérer le décodage (voir `past_key_values`). **Retourne :** `xLSTMCausalLMOutput` ou `tuple(torch.Tensor)` Un `xLSTMCausalLMOutput` ou un tuple de `torch.Tensor` (si `return_dict=False` est passé ou lorsque `config.return_dict=False`) comprenant divers éléments selon la configuration ([xLSTMConfig](/docs/transformers/v5.23.0/fr/model_doc/xlstm#transformers.xLSTMConfig)) et les entrées. La méthode forward de [xLSTMForCausalLM](/docs/transformers/v5.23.0/fr/model_doc/xlstm#transformers.xLSTMForCausalLM) redéfinit la méthode spéciale `__call__`. Bien que la recette de la passe avant doive être définie dans cette fonction, il faut ensuite appeler l'instance `Module` plutôt que celle-ci, car la première gère l'exécution des étapes de prétraitement et de post-traitement, tandis que la seconde les ignore silencieusement. - **loss** (`torch.Tensor` de forme `(1,)`, *facultatif*, renvoyé lorsque `labels` est fourni) -- Perte de modélisation du langage (pour la prédiction du jeton suivant). - **logits** (`torch.Tensor` de forme `(batch_size, sequence_length, config.vocab_size)`) -- Scores de prédiction de la tête de modélisation du langage (scores pour chaque jeton du vocabulaire avant SoftMax). - **cache_params** (`xLSTMCache`, *facultatif*, portant les états du RNN) -- L'état du modèle à la dernière étape temporelle. Peut être utilisé dans une méthode de propagation avant avec les `input_ids` suivants afin d'éviter de fournir les anciens `input_ids`. - **hidden_states** (`tuple[torch.Tensor]`, *facultatif*, renvoyé lorsque `output_hidden_states=True` est passé ou lorsque `config.output_hidden_states=True`) -- Tuple de `torch.Tensor` (un pour la sortie des embeddings, si le modèle possède une couche d'embedding, + un pour la sortie de chaque couche) de forme `(batch_size, sequence_length, hidden_size)`. États cachés du modèle à la sortie de chaque couche, ainsi que les sorties d'incorporation initiales facultatives. Exemple : ```python ```