Transformers documentation
xLSTM
Ce modèle a été publié dans HF papers le 2024-05-07 et ajouté à Hugging Face Transformers le 2025-07-25.
xLSTM
Aperçu
Le modèle xLSTM a été proposé dans xLSTM: Extended Long Short-Term Memory 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 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. Le code d'origine peut être trouvé ici.
Notes
- Utilisez le padding à gauche pour la génération par lots. Voir Padding side.
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 )
Paramètres
- vocab_size (
int, facultatif, par défaut50304) — Taille du vocabulaire du modèle. Définit le nombre de jetons différents qui peuvent être représentés parinput_ids. - hidden_size (
int, facultatif, par défaut4096) — Dimension des représentations cachées. - embedding_dim (
int, facultatif) — Dimension des embeddings et des états cachés. - num_hidden_layers (
int, facultatif, par défaut32) — 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, num_hidden_layers est utilisé. - num_heads (
int, facultatif, facultatif, valeur par défaut : 8) — Nombre de têtes pour la couche/cellule xLSTM. - use_bias (
bool, optionnel, optionnel, par défautFalse) — Indique s'il faut utiliser des biais dans le modèle xLSTM. - norm_reduction_force_float32 (
bool, optionnel, optionnel, valeur par défautTrue) — Indique s'il faut forcer l'opérateur de réduction de la norme à être effectué en précision fp32. - tie_word_embeddings (
bool, facultatif, valeur par défautFalse) — Indique s'il faut lier les embeddings de poids selon la correspondancetied_weights_keysdu modèle. - add_out_norm (
bool, optionnel, optionnel, valeur par défautTrue) — Indique s'il faut ajouter une normalisation de sortie après les blocs, avant le LMHead. - norm_eps (
float, facultatif, par défaut1e-06) — L'épsilon utilisé par les couches de normalisation de 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 la valeur. - chunkwise_kernel (
ChunkwiseKernelType, facultatif, facultatif, 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, optionnel, optionnel, par défaut"native") — Type de noyau pour le mode de traitement par étapes. - mode (
BackendModeType, optionnel, optionnel, par défaut"inference") — Mode d'opération (le mode d'inférence est requis pour la génération). - chunk_size (
int, facultatif, facultatif, valeur par défaut : 64) — Taille de bloc interne. - return_last_states (
bool, optionnel, optionnel, par défautTrue) — Indique s'il faut retourner les derniers états / le cache en interne. Doit être défini sur True pour la génération. - autocast_kernel_dtype (
DtypeType, optionnel, optionnel, par défaut"bfloat16") — Type de données du noyau pour les états. - eps (
float, facultatif, par défaut1e-06) — L'épsilon utilisé par les couches de normalisation par couche. - inference_state_dtype (
DtypeType, optionnel, optionnel, par défaut"float32") — Type de données 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 de la projection post-up du réseau Feed Forward à porte. - ffn_round_up_to_multiple_of (
int, optionnel, optionnel, valeur par défaut : 64) — Facteur de taille pour l'arrondi de la valeur de la projection post-up du réseau Feed Forward à porte. - gate_soft_cap (
float, optionnel, optionnel, 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 des 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éfautTrue) — Indique si le modèle doit retourner les dernières attentions clés/valeurs (non utilisé par tous les modèles). N’est pertinent que siconfig.is_decoder=Trueou si le modèle est un modèle génératif uniquement décodeur. - pad_token_id (
int, facultatif, par défaut1) — Identifiant du jeton utilisé pour le bourrage dans le vocabulaire. - bos_token_id (
int, facultatif, par défaut0) — Identifiant du jeton utilisé pour le début de flux dans le vocabulaire. - eos_token_id (
Union[int, list[int]], facultatif, par défaut2) — Identifiant du 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.
Ceci est 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
Les objets de configuration héritent de PreTrainedConfig et peuvent être utilisés pour contrôler les sorties du modèle. Consultez la documentation de PreTrainedConfig pour plus d’informations.
Exemple :
>>> 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 )
Paramètres
- config (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() 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. 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, la taille des têtes, etc.)
Ce modèle est également une sous-classe de 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
< 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)
Paramètres
- input_ids (
torch.LongTensorde 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. Consultez PreTrainedTokenizer.encode() et PreTrainedTokenizer.call() pour plus de détails.
- inputs_embeds (
torch.LongTensorde forme(batch_size, sequence_length, hidden_size), facultatif) — Facultativement, au lieu de passerinput_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 indicesinput_idsen vecteurs associés que 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 surTrue, les états clé-valeurpast_key_valuessont renvoyés et peuvent être utilisés pour accélérer le décodage (voirpast_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 en fonction de la configuration (xLSTMConfig) et des entrées.
La méthode forward de 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
Moduleplutô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.Tensorde 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 lesinput_idssuivants pour éviter de fournir les anciensinput_ids.hidden_states (
tuple[torch.Tensor], facultatif, renvoyé lorsqueoutput_hidden_states=Trueest passé ou lorsqueconfig.output_hidden_states=True) — Tuple detorch.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
classe transformers.xLSTMForCausalLM
< source >( config: xLSTMConfig )
Paramètres
- config (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() 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. 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, la taille des têtes, etc.)
Ce modèle est également une sous-classe de 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
< 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)
Paramètres
- input_ids (
torch.LongTensorde 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. Consultez PreTrainedTokenizer.encode() et PreTrainedTokenizer.call() pour plus de détails.
- inputs_embeds (
torch.Tensorde forme(batch_size, sequence_length, hidden_size), facultatif) — Facultativement, au lieu de passerinput_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 indicesinput_idsen vecteurs associés que 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.LongTensorde forme(batch_size, sequence_length), facultatif) — Étiquettes pour le calcul de la perte de modélisation de langage masquée. Les indices doivent être dans[0, ..., config.vocab_size]ou -100 (voir la docstring deinput_ids). Les jetons dont l'indice est défini sur-100sont ignorés (masqués), la perte n'est calculée que pour les jetons dont l'étiquette est dans[0, ..., config.vocab_size]. - use_cache (
bool, facultatif) — Si défini surTrue, les états clé-valeurpast_key_valuessont renvoyés et peuvent être utilisés pour accélérer le décodage (voirpast_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 en fonction de la configuration (xLSTMConfig) et des entrées.
La méthode forward de 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
Moduleplutô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.Tensorde forme(1,), facultatif, renvoyé lorsquelabelsest fourni) — Perte de modélisation du langage (pour la prédiction du jeton suivant).logits (
torch.Tensorde 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 forward avec lesinput_idssuivants pour éviter de fournir les anciensinput_ids.hidden_states (
tuple[torch.Tensor], facultatif, renvoyé lorsqueoutput_hidden_states=Trueest passé ou lorsqueconfig.output_hidden_states=True) — Tuple detorch.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.