Transformers documentation

Informer

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Ce modèle a été publié dans HF papers le 2020-12-14 et ajouté à Hugging Face Transformers le 2023-03-08.

Informer

Aperçu

Le modèle Informer a été proposé dans Informer: Beyond Efficient Transformer for Long Sequence Time-Series Forecasting par Haoyi Zhou, Shanghang Zhang, Jieqi Peng, Shuai Zhang, Jianxin Li, Hui Xiong et Wancai Zhang.

Cette méthode introduit un mécanisme d’attention probabiliste afin de sélectionner les requêtes « actives » plutôt que les requêtes « paresseuses », et fournit ainsi un Transformer creux, ce qui atténue les exigences de calcul et de mémoire quadratiques de l’attention standard.

L'abstract de l'article est le suivant :

De nombreuses applications réelles nécessitent la prédiction de séries temporelles de longue séquence, comme la planification de la consommation d’électricité. La prévision de séries temporelles de longue séquence (LSTF) exige une forte capacité de prédiction du modèle, c’est-à-dire la capacité à capturer efficacement le couplage précis des dépendances à longue portée entre la sortie et l’entrée. Des études récentes ont montré le potentiel du Transformer pour augmenter cette capacité de prédiction. Cependant, le Transformer présente plusieurs problèmes majeurs qui l’empêchent d’être directement applicable à la LSTF, notamment une complexité temporelle quadratique, une forte consommation mémoire et la limitation inhérente de l’architecture encodeur-décodeur. Pour résoudre ces problèmes, nous concevons un modèle efficace basé sur le Transformer pour la LSTF, nommé Informer, doté de trois caractéristiques distinctes : (i) un mécanisme d’auto-attention ProbSparse, qui atteint une complexité temporelle et une utilisation mémoire de O(L logL), et offre des performances comparables en termes d’alignement des dépendances des séquences. (ii) la distillation d’auto-attention met en évidence l’attention dominante en réduisant de moitié l’entrée de la couche en cascade, et gère efficacement les séquences d’entrée extrêmement longues. (iii) le décodeur de style génératif, bien que conceptuellement simple, prédit les séquences de séries temporelles longues en une seule opération de propagation avant plutôt que de manière étape par étape, ce qui améliore considérablement la vitesse d’inférence des prédictions de longue séquence. Des expériences étendues sur quatre jeux de données à grande échelle démontrent qu’Informer surpasse significativement les méthodes existantes et offre une nouvelle solution au problème de la LSTF.

Ce modèle a été contribué par elisim et kashif. Le code d'origine peut être trouvé ici.

Ressources

Une liste de ressources officielles Hugging Face et de la communauté (indiquées par 🌎) pour vous aider à démarrer. Si vous souhaitez soumettre une ressource pour qu'elle soit incluse ici, n'hésitez pas à ouvrir une Pull Request et nous la examinerons ! La ressource devrait idéalement démontrer quelque chose de nouveau plutôt que de dupliquer une ressource existante.

InformerConfig

classe transformers.InformerConfig

< >

( 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 = 0id2label: 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 = Noneis_encoder_decoder: bool = Trueprediction_length: int | None = Nonecontext_length: int | None = Nonedistribution_output: str = 'student_t'loss: str = 'nll'input_size: int = 1lags_sequence: list[int] | None = Nonescaling: str | bool | None = 'mean'num_dynamic_real_features: int = 0num_static_real_features: int = 0num_static_categorical_features: int = 0num_time_features: int = 0cardinality: list[int] | None = Noneembedding_dimension: list[int] | None = Noned_model: int = 64encoder_ffn_dim: int = 32decoder_ffn_dim: int = 32encoder_attention_heads: int = 2decoder_attention_heads: int = 2encoder_layers: int = 2decoder_layers: int = 2activation_function: str = 'gelu'dropout: float | int = 0.05encoder_layerdrop: float | int = 0.1decoder_layerdrop: float | int = 0.1attention_dropout: float | int = 0.1activation_dropout: float | int = 0.1num_parallel_samples: int = 100init_std: float = 0.02use_cache: bool = Trueattention_type: str = 'prob'sampling_factor: int = 5distil: bool = True )

Paramètres

  • is_encoder_decoder (bool, facultatif, valeur par défaut True) — Indique si le modèle est utilisé comme encodeur/décodeur ou non.
  • prediction_length (int, facultatif) — La longueur de prédiction pour le décodeur. Autrement dit, l’horizon de prédiction du modèle. Cette valeur est généralement dictée par le jeu de données et nous recommandons de la définir en conséquence.
  • context_length (int, facultatif, par défaut prediction_length) — La longueur de contexte pour l’encodeur. Si None, la longueur de contexte sera identique à la prediction_length.
  • distribution_output (string, facultatif, par défaut "student_t") — La tête d'émission de distribution du modèle. Peut être « student_t », « normal » ou « negative_binomial ».
  • loss (string, facultatif, par défaut "nll") — La fonction de perte du modèle correspondant à la tête distribution_output. Pour les distributions paramétriques, il s'agit de la log-vraisemblance négative (nll) - qui est actuellement la seule prise en charge.
  • input_size (int, facultatif, valeur par défaut 1) — La taille de la variable cible, qui est de 1 par défaut pour les cibles univariées. Elle est > 1 dans le cas de cibles multivariées.
  • lags_sequence (list[int], facultatif, par défaut [1, 2, 3, 4, 5, 6, 7]) — Les retards de la série temporelle d'entrée en tant que covariables, souvent dictés par la fréquence des données. La valeur par défaut est [1, 2, 3, 4, 5, 6, 7], mais nous recommandons de la modifier en fonction du jeu de données.
  • scaling (string ou bool, facultatif, par défaut "mean") — Indique si les cibles d’entrée doivent être mises à l’échelle via le scaler « mean », le scaler « std » ou aucun scaler si None. Si True, le scaler est défini sur « mean ».
  • num_dynamic_real_features (int, facultatif, valeur par défaut 0) — Le nombre de caractéristiques dynamiques à valeurs réelles.
  • num_static_real_features (int, facultatif, valeur par défaut 0) — Le nombre de caractéristiques statiques à valeurs réelles.
  • num_static_categorical_features (int, facultatif, valeur par défaut 0) — Le nombre de caractéristiques catégorielles statiques.
  • num_time_features (int, facultatif, valeur par défaut 0) — Le nombre de caractéristiques temporelles dans la série temporelle d'entrée.
  • cardinality (list[int], facultatif) — La cardinalité (nombre de valeurs distinctes) pour chacune des caractéristiques catégorielles statiques. Doit être une liste d'entiers, ayant la même longueur que num_static_categorical_features. Ne peut pas être None si num_static_categorical_features est > 0.
  • embedding_dimension (list[int], facultatif) — La dimension de l'embedding pour chacune des caractéristiques catégorielles statiques. Doit être une liste d'entiers, de la même longueur que num_static_categorical_features. Ne peut pas être None si num_static_categorical_features est > 0.
  • d_model (int, facultatif, par défaut 64) — Taille des couches encodeur et de la couche pooler.
  • encoder_ffn_dim (int, facultatif, valeur par défaut 32) — Dimension de la couche « intermédiaire » (souvent appelée couche feed-forward) de l’encodeur.
  • decoder_ffn_dim (int, facultatif, valeur par défaut 32) — Dimension de la couche « intermédiaire » (souvent appelée couche feed-forward) du décodeur.
  • encoder_attention_heads (int, facultatif, valeur par défaut 2) — Nombre de têtes d'attention pour chaque couche d'attention dans l'encodeur Transformer.
  • decoder_attention_heads (int, facultatif, valeur par défaut 2) — Nombre de têtes d'attention pour chaque couche d'attention du décodeur Transformer.
  • encoder_layers (int, facultatif, valeur par défaut 2) — Nombre de couches cachées dans l'encodeur Transformer. Utilise la même valeur que num_layers si non défini.
  • decoder_layers (int, facultatif, valeur par défaut 2) — Nombre de couches cachées dans le décodeur Transformer. Utilise la même valeur que num_layers si non défini.
  • activation_function (str, facultatif, par défaut gelu) — La fonction d'activation non linéaire (fonction ou chaîne de caractères) du décodeur. Par exemple, "gelu", "relu", "silu", etc.
  • dropout (Union[float, int], facultatif, par défaut 0.05) — Le taux appliqué à toutes les couches de dropout.
  • encoder_layerdrop (Union[float, int], facultatif, valeur par défaut 0.1) — Probabilité de LayerDrop pour l'encodeur. Voir l'article [LayerDrop](voir https://huggingface.co/papers/1909.11556) pour plus de détails.
  • decoder_layerdrop (Union[float, int], facultatif, valeur par défaut 0.1) — Probabilité de LayerDrop pour le décodeur. Consultez l’article [LayerDrop](voir https://huggingface.co/papers/1909.11556) pour plus de détails.
  • attention_dropout (Union[float, int], facultatif, valeur par défaut 0.1) — Le taux de dropout appliqué aux probabilités d'attention.
  • activation_dropout (float, facultatif, valeur par défaut 0.1) — La probabilité de dropout utilisée entre les deux couches des réseaux feed-forward.
  • num_parallel_samples (int, facultatif, valeur par défaut 100) — Le nombre d'échantillons à générer en parallèle pour chaque étape temporelle de l'inférence.
  • init_std (float, facultatif, valeur par défaut 0.02) — L'écart-type de la truncated_normal_initializer utilisé pour initialiser toutes les matrices de poids.
  • 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). N’est pertinent que si config.is_decoder=True ou si le modèle est un modèle génératif uniquement décodeur.
  • attention_type (str, facultatif, par défaut “prob”) — Attention utilisée dans l’encodeur. Peut être définie sur “prob” (ProbAttention d’Informer) ou “full” (auto-attention canonique du transformer standard).
  • sampling_factor (int, facultatif, valeur par défaut 5) — Facteur d'échantillonnage ProbSparse (n'a d'effet que si attention_type=“prob”). Il est utilisé pour contrôler la longueur d'entrée de la matrice de requêtes réduite (Q_reduce).
  • distil (bool, facultatif, par défaut True) — Indique s'il faut utiliser la distillation dans l'encodeur.

Ceci est la classe de configuration destinée à stocker la configuration d'un InformerModel. Elle est utilisée pour instancier un modèle Informer en fonction des arguments spécifiés, définissant ainsi l'architecture du modèle. L'instanciation d'une configuration avec les valeurs par défaut produira une configuration similaire à celle de huggingface/informer-tourism-monthly

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 InformerConfig, InformerModel

>>> # Initializing an Informer configuration with 12 time steps for prediction
>>> configuration = InformerConfig(prediction_length=12)

>>> # Randomly initializing a model (with random weights) from the configuration
>>> model = InformerModel(configuration)

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

InformerModel

classe transformers.InformerModel

< >

( config: InformerConfig )

Paramètres

  • config (InformerConfig) — 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 Informer 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

< >

( past_values: Tensorpast_time_features: Tensorpast_observed_mask: Tensorstatic_categorical_features: typing.Optional[torch.Tensor] = Nonestatic_real_features: typing.Optional[torch.Tensor] = Nonefuture_values: typing.Optional[torch.Tensor] = Nonefuture_time_features: typing.Optional[torch.Tensor] = Nonedecoder_attention_mask: typing.Optional[torch.LongTensor] = Noneencoder_outputs: list[torch.Tensor] | None = Nonepast_key_values: transformers.cache_utils.Cache | None = Noneuse_cache: bool | None = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → Seq2SeqTSModelOutput or tuple(torch.Tensor)

Paramètres

  • past_values (torch.Tensor de forme (batch_size, sequence_length) ou (batch_size, sequence_length, input_size)) — Valeurs passées de la série temporelle, servant de contexte pour prédire l'avenir. La taille de séquence de ce tenseur doit être supérieure à la context_length du modèle, car le modèle utilisera la taille plus grande pour construire des caractéristiques de décalage (lags), c'est-à-dire des valeurs supplémentaires du passé ajoutées pour servir de « contexte supplémentaire ».

    La sequence_length ici est égale à config.context_length + max(config.lags_sequence), ce qui, si aucune lags_sequence n'est configurée, est égal à config.context_length + 7 (car par défaut, l'indice de rétrovision le plus grand dans config.lags_sequence est 7). La propriété _past_length renvoie la longueur réelle du passé.

    past_values est ce que le Transformer encoder reçoit en entrée (avec des fonctionnalités supplémentaires facultatives, telles que static_categorical_features, static_real_features, past_time_features et les retards).

    Facultativement, les valeurs manquantes doivent être remplacées par des zéros et indiquées via le past_observed_mask.

    Pour les séries temporelles multivariées, la dimension input_size > 1 est requise et correspond au nombre de variables de la série temporelle par pas de temps.

  • past_time_features (torch.Tensor de forme (batch_size, sequence_length, num_features)) — Fonctions temporelles requises, que le modèle ajoutera en interne à past_values. Il peut s'agir d'éléments comme le « mois de l'année », le « jour du mois », etc., encodés sous forme de vecteurs (par exemple en tant que caractéristiques de Fourier). Il peut également s'agir de caractéristiques dites d'« âge », qui aident essentiellement le modèle à savoir « à quel stade de sa vie » se trouve une série temporelle. Les caractéristiques d'âge ont des valeurs faibles pour les pas de temps éloignés dans le passé et augmentent de manière monotone à mesure que l'on approche du pas de temps actuel. Les caractéristiques de jours fériés sont également un bon exemple de caractéristiques temporelles.

    Ces caractéristiques servent de « codages positionnels » des entrées. Contrairement à un modèle comme BERT, où les codages de position sont appris de zéro en interne en tant que paramètres du modèle, le Time Series Transformer nécessite de fournir des caractéristiques temporelles supplémentaires. Le Time Series Transformer n’apprend des plongements supplémentaires que pour static_categorical_features.

    Des covariables dynamiques réelles supplémentaires peuvent être concaténées à ce tenseur, à condition que ces caractéristiques soient connues au moment de la prédiction.

    Le num_features ici est égal à config.num_time_features+config.num_dynamic_real_features`.

  • past_observed_mask (torch.BoolTensor de forme (batch_size, sequence_length) ou (batch_size, sequence_length, input_size), facultatif) — Masque booléen indiquant quels past_values ont été observés et lesquels étaient manquants. Les valeurs du masque sont sélectionnées dans [0, 1]:
    • 1 pour les valeurs observées,
    • 0 pour les valeurs manquantes (c.-à-d. les NaN remplacés par des zéros).
  • static_categorical_features (torch.LongTensor de forme (batch_size, number of static categorical features), facultatif) — Caractéristiques catégorielles statiques facultatives pour lesquelles le modèle apprendra un embedding, qu'il ajoutera aux valeurs de la série temporelle.

    Les caractéristiques catégorielles statiques sont des caractéristiques qui ont la même valeur pour toutes les étapes temporelles (statiques dans le temps).

    Un exemple typique de caractéristique catégorielle statique est un identifiant de série temporelle.

  • static_real_features (torch.Tensor de forme (batch_size, number of static real features), facultatif) — Caractéristiques réelles statiques facultatives que le modèle ajoutera aux valeurs de la série temporelle. Les caractéristiques réelles statiques sont des caractéristiques qui ont la même valeur pour toutes les étapes temporelles (statiques dans le temps). Un exemple typique de caractéristique réelle statique est l'information de promotion.

    Les caractéristiques réelles statiques sont des caractéristiques qui ont la même valeur pour toutes les étapes temporelles (statiques dans le temps).

    Un exemple typique de caractéristique réelle statique est l'information de promotion.

  • future_values (torch.Tensor de forme (batch_size, prediction_length) ou (batch_size, prediction_length, input_size), facultatif) — Valeurs futures de la série temporelle, servant d'étiquettes pour le modèle. Les future_values sont ce que le Transformer doit apprendre à produire pendant l'entraînement, étant donné les past_values.

    La longueur de la séquence ici est égale à prediction_length.

    Consultez le notebook de démonstration et les extraits de code pour plus de détails.

    Optionnellement, pendant l’entraînement, toute valeur manquante doit être remplacée par zéro et indiquée via le future_observed_mask.

    Pour les séries temporelles multivariées, la dimension input_size > 1 est requise et correspond au nombre de variables de la série temporelle par pas de temps.

  • future_time_features (torch.Tensor de forme (batch_size, prediction_length, num_features)) — Fonctions temporelles requises pour la fenêtre de prédiction, que le modèle ajoutera en interne à future_values. Il peut s'agir d'éléments comme le « mois de l'année », le « jour du mois », etc., encodés sous forme de vecteurs (par exemple en tant que caractéristiques de Fourier). Il peut également s'agir de caractéristiques dites de « vieillissement » (age), qui aident essentiellement le modèle à savoir « à quel stade de sa vie » se trouve une série temporelle. Les caractéristiques de vieillissement ont des valeurs faibles pour les pas de temps éloignés dans le passé et augmentent de manière monotone à mesure que l'on approche du pas de temps actuel. Les caractéristiques de jours fériés sont également un bon exemple de caractéristiques temporelles.

    Ces caractéristiques servent de « codages positionnels » des entrées. Contrairement à un modèle comme BERT, où les codages de position sont appris de zéro en interne en tant que paramètres du modèle, le Time Series Transformer nécessite de fournir des caractéristiques temporelles supplémentaires. Le Time Series Transformer n’apprend des plongements supplémentaires que pour static_categorical_features.

    Des covariables dynamiques réelles supplémentaires peuvent être concaténées à ce tenseur, à condition que ces caractéristiques soient connues au moment de la prédiction.

    Ici, num_features est égal à config.num_time_features + config.num_dynamic_real_features.

  • decoder_attention_mask (torch.LongTensor de forme (batch_size, target_sequence_length), facultatif) — Masque pour éviter d’effectuer l’attention sur certains indices de jetons. Par défaut, un masque causal est utilisé afin de s’assurer que le modèle ne peut regarder que les entrées précédentes pour prédire le futur.
  • encoder_outputs (tuple(tuple(torch.Tensor), facultatif) — Le tuple est composé de last_hidden_state, hidden_states (facultatif) et attentions (facultatif) last_hidden_state de forme (batch_size, sequence_length, hidden_size) (facultatif) est une séquence d’états cachés à la sortie de la dernière couche de l’encodeur. Utilisé dans l’attention croisée du décodeur.
  • past_key_values (~cache_utils.Cache, facultatif) — États cachés précalculés (clés et valeurs dans les blocs d'auto-attention et d'attention croisée) qui peuvent être utilisés pour accélérer le décodage séquentiel. Cela consiste généralement en la past_key_values retournée par le modèle à une étape antérieure du décodage, lorsque use_cache=True ou config.use_cache=True.

    Seule une instance de Cache est autorisée en entrée, consultez notre guide du cache kv. Si aucun past_key_values n'est transmis, DynamicCache sera initialisé par défaut.

    Le modèle produira le même format de cache qui est fourni en entrée.

    Si past_key_values sont utilisés, l’utilisateur doit fournir uniquement les input_ids non traités (ceux pour lesquels les états de clés et de valeurs passées n’ont pas été fournis à ce modèle) de forme (batch_size, unprocessed_length) au lieu de tous les input_ids de forme (batch_size, sequence_length).

  • use_cache (bool, facultatif) — Si défini sur True, les états clé-valeur past_key_values sont renvoyés et peuvent être utilisés pour accélérer le décodage (voir past_key_values).

Retourne

Seq2SeqTSModelOutput ou tuple(torch.Tensor)

Un Seq2SeqTSModelOutput 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 (InformerConfig) et des entrées.

La méthode forward du modèle InformerModel 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)) — Séquence d'états cachés à la sortie de la dernière couche du décodeur du modèle.

    Si past_key_values est utilisé, seule la dernière hidden-state des séquences de forme (batch_size, 1, hidden_size) est renvoyée.

  • past_key_values (EncoderDecoderCache, facultatif, renvoyé lorsque use_cache=True est passé ou lorsque config.use_cache=True) — Il s’agit d’une instance de EncoderDecoderCache. Pour plus de détails, consultez notre guide sur le cache kv.

    Contient des états cachés précalculés (clés et valeurs dans les blocs d'auto-attention et dans les blocs d'attention croisée) qui peuvent être utilisés (voir l'entrée past_key_values) pour accélérer le décodage séquentiel.

  • decoder_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 décodeur à la sortie de chaque couche, plus les sorties d'incorporation initiale facultatives.

  • decoder_attentions (tuple(torch.Tensor), facultatif, renvoyé lorsque output_attentions=True est passé ou lorsque config.output_attentions=True) — Tuple de torch.Tensor (un par couche) de forme (batch_size, num_heads, sequence_length, sequence_length).

    Poids d'attention du décodeur, après le softmax d'attention, utilisés pour calculer la moyenne pondérée dans les têtes d'auto-attention.

  • cross_attentions (tuple(torch.Tensor), facultatif, renvoyé lorsque output_attentions=True est passé ou lorsque config.output_attentions=True) — Tuple de torch.Tensor (un par couche) de forme (batch_size, num_heads, sequence_length, sequence_length).

    Poids d'attention de la couche d'attention croisée du décodeur, après le softmax d'attention, utilisés pour calculer la moyenne pondérée dans les têtes d'attention croisée.

  • encoder_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 de l'encodeur du modèle.

  • encoder_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 de l'encodeur à la sortie de chaque couche, plus les sorties d'incorporation initiales facultatives.

  • encoder_attentions (tuple(torch.Tensor), facultatif, renvoyé lorsque output_attentions=True est passé ou lorsque config.output_attentions=True) — Tuple de torch.Tensor (un par couche) de forme (batch_size, num_heads, sequence_length, sequence_length).

    Poids d'attention de l'encodeur, après le softmax d'attention, utilisés pour calculer la moyenne pondérée dans les têtes d'auto-attention.

  • loc (torch.Tensor de forme (batch_size,) ou (batch_size, input_size), facultatif) — Valeurs de décalage appliquées à la fenêtre de contexte de chaque série temporelle, utilisées pour fournir au modèle des entrées de même amplitude, puis pour revenir à l'amplitude d'origine.

  • scale (torch.Tensor de forme (batch_size,) ou (batch_size, input_size), facultatif) — Valeurs d'échelle de la fenêtre de contexte de chaque série temporelle, utilisées pour fournir au modèle des entrées de même magnitude, puis pour rétablir l'échelle d'origine.

  • static_features (torch.Tensor de forme (batch_size, feature size), facultatif) — Caractéristiques statiques de chaque série temporelle d’un lot, copiées dans les covariables lors de l’inférence.

Exemples :

>>> from huggingface_hub import hf_hub_download
>>> import torch
>>> from transformers import InformerModel

>>> file = hf_hub_download(
...     repo_id="hf-internal-testing/tourism-monthly-batch", filename="train-batch.pt", repo_type="dataset"
... )
>>> batch = torch.load(file)

>>> model = InformerModel.from_pretrained("huggingface/informer-tourism-monthly")

>>> # during training, one provides both past and future values
>>> # as well as possible additional features
>>> outputs = model(
...     past_values=batch["past_values"],
...     past_time_features=batch["past_time_features"],
...     past_observed_mask=batch["past_observed_mask"],
...     static_categorical_features=batch["static_categorical_features"],
...     static_real_features=batch["static_real_features"],
...     future_values=batch["future_values"],
...     future_time_features=batch["future_time_features"],
... )

>>> last_hidden_state = outputs.last_hidden_state

InformerForPrediction

classe transformers.InformerForPrediction

< >

( config: InformerConfig )

Paramètres

  • config (InformerConfig) — 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 Informer avec une tête de distribution au sommet pour la prévision de séries temporelles.

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

< >

( past_values: Tensorpast_time_features: Tensorpast_observed_mask: Tensorstatic_categorical_features: typing.Optional[torch.Tensor] = Nonestatic_real_features: typing.Optional[torch.Tensor] = Nonefuture_values: typing.Optional[torch.Tensor] = Nonefuture_time_features: typing.Optional[torch.Tensor] = Nonefuture_observed_mask: typing.Optional[torch.Tensor] = Nonedecoder_attention_mask: typing.Optional[torch.LongTensor] = Noneencoder_outputs: list[torch.Tensor] | None = Nonepast_key_values: transformers.cache_utils.Cache | None = Noneuse_cache: bool | None = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → Seq2SeqTSModelOutput or tuple(torch.Tensor)

Paramètres

  • past_values (torch.Tensor de forme (batch_size, sequence_length) ou (batch_size, sequence_length, input_size)) — Valeurs passées de la série temporelle, servant de contexte pour prédire l'avenir. La taille de séquence de ce tenseur doit être supérieure à la context_length du modèle, car le modèle utilisera la taille plus grande pour construire des caractéristiques de décalage (lags), c'est-à-dire des valeurs supplémentaires du passé ajoutées pour servir de « contexte supplémentaire ».

    La sequence_length ici est égale à config.context_length + max(config.lags_sequence), ce qui, si aucune lags_sequence n'est configurée, est égal à config.context_length + 7 (car par défaut, l'indice de rétrovision le plus grand dans config.lags_sequence est 7). La propriété _past_length renvoie la longueur réelle du passé.

    past_values est ce que le Transformer encoder reçoit en entrée (avec des fonctionnalités supplémentaires facultatives, telles que static_categorical_features, static_real_features, past_time_features et les retards).

    Facultativement, les valeurs manquantes doivent être remplacées par des zéros et indiquées via le past_observed_mask.

    Pour les séries temporelles multivariées, la dimension input_size > 1 est requise et correspond au nombre de variables de la série temporelle par pas de temps.

  • past_time_features (torch.Tensor de forme (batch_size, sequence_length, num_features)) — Fonctions temporelles requises, que le modèle ajoutera en interne à past_values. Il peut s'agir d'éléments comme le « mois de l'année », le « jour du mois », etc., encodés sous forme de vecteurs (par exemple en tant que caractéristiques de Fourier). Il peut également s'agir de caractéristiques dites d'« âge », qui aident essentiellement le modèle à savoir « à quel stade de sa vie » se trouve une série temporelle. Les caractéristiques d'âge ont des valeurs faibles pour les pas de temps éloignés dans le passé et augmentent de manière monotone à mesure que l'on approche du pas de temps actuel. Les caractéristiques de jours fériés sont également un bon exemple de caractéristiques temporelles.

    Ces caractéristiques servent de « codages positionnels » des entrées. Contrairement à un modèle comme BERT, où les codages de position sont appris de zéro en interne en tant que paramètres du modèle, le Time Series Transformer nécessite de fournir des caractéristiques temporelles supplémentaires. Le Time Series Transformer n’apprend des plongements supplémentaires que pour static_categorical_features.

    Des covariables dynamiques réelles supplémentaires peuvent être concaténées à ce tenseur, à condition que ces caractéristiques soient connues au moment de la prédiction.

    Le num_features ici est égal à config.num_time_features+config.num_dynamic_real_features`.

  • past_observed_mask (torch.BoolTensor de forme (batch_size, sequence_length) ou (batch_size, sequence_length, input_size), facultatif) — Masque booléen indiquant quels past_values ont été observés et lesquels étaient manquants. Les valeurs du masque sont sélectionnées dans [0, 1]:
    • 1 pour les valeurs observées,
    • 0 pour les valeurs manquantes (c.-à-d. les NaN remplacés par des zéros).
  • static_categorical_features (torch.LongTensor de forme (batch_size, number of static categorical features), facultatif) — Caractéristiques catégorielles statiques facultatives pour lesquelles le modèle apprendra un embedding, qu'il ajoutera aux valeurs de la série temporelle.

    Les caractéristiques catégorielles statiques sont des caractéristiques qui ont la même valeur pour toutes les étapes temporelles (statiques dans le temps).

    Un exemple typique de caractéristique catégorielle statique est un identifiant de série temporelle.

  • static_real_features (torch.Tensor de forme (batch_size, number of static real features), facultatif) — Caractéristiques réelles statiques facultatives que le modèle ajoutera aux valeurs de la série temporelle. Les caractéristiques réelles statiques sont des caractéristiques qui ont la même valeur pour toutes les étapes temporelles (statiques dans le temps). Un exemple typique de caractéristique réelle statique est l'information de promotion.

    Les caractéristiques réelles statiques sont des caractéristiques qui ont la même valeur pour toutes les étapes temporelles (statiques dans le temps).

    Un exemple typique de caractéristique réelle statique est l'information de promotion.

  • future_values (torch.Tensor de forme (batch_size, prediction_length) ou (batch_size, prediction_length, input_size), facultatif) — Valeurs futures de la série temporelle, servant d'étiquettes pour le modèle. Les future_values sont ce que le Transformer doit apprendre à produire pendant l'entraînement, étant donné les past_values.

    La longueur de la séquence ici est égale à prediction_length.

    Consultez le notebook de démonstration et les extraits de code pour plus de détails.

    Optionnellement, pendant l’entraînement, toute valeur manquante doit être remplacée par zéro et indiquée via le future_observed_mask.

    Pour les séries temporelles multivariées, la dimension input_size > 1 est requise et correspond au nombre de variables de la série temporelle par pas de temps.

  • future_time_features (torch.Tensor de forme (batch_size, prediction_length, num_features)) — Fonctions temporelles requises pour la fenêtre de prédiction, que le modèle ajoutera en interne à future_values. Il peut s'agir d'éléments comme le « mois de l'année », le « jour du mois », etc., encodés sous forme de vecteurs (par exemple en tant que caractéristiques de Fourier). Il peut également s'agir de caractéristiques dites de « vieillissement » (age), qui aident essentiellement le modèle à savoir « à quel stade de sa vie » se trouve une série temporelle. Les caractéristiques de vieillissement ont des valeurs faibles pour les pas de temps éloignés dans le passé et augmentent de manière monotone à mesure que l'on approche du pas de temps actuel. Les caractéristiques de jours fériés sont également un bon exemple de caractéristiques temporelles.

    Ces caractéristiques servent de « codages positionnels » des entrées. Contrairement à un modèle comme BERT, où les codages de position sont appris de zéro en interne en tant que paramètres du modèle, le Time Series Transformer nécessite de fournir des caractéristiques temporelles supplémentaires. Le Time Series Transformer n’apprend des plongements supplémentaires que pour static_categorical_features.

    Des covariables dynamiques réelles supplémentaires peuvent être concaténées à ce tenseur, à condition que ces caractéristiques soient connues au moment de la prédiction.

    Ici, num_features est égal à config.num_time_features + config.num_dynamic_real_features.

  • future_observed_mask (torch.BoolTensor de forme (batch_size, sequence_length) ou (batch_size, sequence_length, input_size), facultatif) — Masque booléen indiquant quels future_values ont été observés et lesquels étaient manquants. Les valeurs du masque sont sélectionnées dans [0, 1] : 1 pour les valeurs observées, 0 pour les valeurs manquantes (c'est-à-dire les NaN remplacés par des zéros). Ce masque est utilisé pour exclure les valeurs manquantes lors du calcul final de la perte. [0, 1]:
    • 1 pour les valeurs observées,
    • 0 pour les valeurs manquantes (c.-à-d. les NaN remplacés par des zéros).

    Ce masque est utilisé pour filtrer les valeurs manquantes lors du calcul de la perte finale.

  • decoder_attention_mask (torch.LongTensor de forme (batch_size, target_sequence_length), facultatif) — Masque pour éviter d’effectuer l’attention sur certains indices de jetons. Par défaut, un masque causal est utilisé afin de s’assurer que le modèle ne peut regarder que les entrées précédentes pour prédire le futur.
  • encoder_outputs (tuple(tuple(torch.Tensor), facultatif) — Le tuple est composé de last_hidden_state, hidden_states (facultatif) et attentions (facultatif) last_hidden_state de forme (batch_size, sequence_length, hidden_size) (facultatif) est une séquence d’états cachés à la sortie de la dernière couche de l’encodeur. Utilisé dans l’attention croisée du décodeur.
  • past_key_values (~cache_utils.Cache, facultatif) — États cachés précalculés (clés et valeurs dans les blocs d'auto-attention et d'attention croisée) qui peuvent être utilisés pour accélérer le décodage séquentiel. Cela consiste généralement en la past_key_values retournée par le modèle à une étape antérieure du décodage, lorsque use_cache=True ou config.use_cache=True.

    Seule une instance de Cache est autorisée en entrée, consultez notre guide du cache kv. Si aucun past_key_values n'est transmis, DynamicCache sera initialisé par défaut.

    Le modèle produira le même format de cache qui est fourni en entrée.

    Si past_key_values sont utilisés, l’utilisateur doit fournir uniquement les input_ids non traités (ceux pour lesquels les états de clés et de valeurs passées n’ont pas été fournis à ce modèle) de forme (batch_size, unprocessed_length) au lieu de tous les input_ids de forme (batch_size, sequence_length).

  • use_cache (bool, facultatif) — Si défini sur True, les états clé-valeur past_key_values sont renvoyés et peuvent être utilisés pour accélérer le décodage (voir past_key_values).

Retourne

Seq2SeqTSModelOutput ou tuple(torch.Tensor)

Un Seq2SeqTSModelOutput 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 (InformerConfig) et des entrées.

La méthode forward de InformerForPrediction 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)) — Séquence d'états cachés à la sortie de la dernière couche du décodeur du modèle.

    Si past_key_values est utilisé, seule la dernière hidden-state des séquences de forme (batch_size, 1, hidden_size) est renvoyée.

  • past_key_values (EncoderDecoderCache, facultatif, renvoyé lorsque use_cache=True est passé ou lorsque config.use_cache=True) — Il s’agit d’une instance de EncoderDecoderCache. Pour plus de détails, consultez notre guide sur le cache kv.

    Contient des états cachés précalculés (clés et valeurs dans les blocs d'auto-attention et dans les blocs d'attention croisée) qui peuvent être utilisés (voir l'entrée past_key_values) pour accélérer le décodage séquentiel.

  • decoder_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 décodeur à la sortie de chaque couche, plus les sorties d'incorporation initiale facultatives.

  • decoder_attentions (tuple(torch.Tensor), facultatif, renvoyé lorsque output_attentions=True est passé ou lorsque config.output_attentions=True) — Tuple de torch.Tensor (un par couche) de forme (batch_size, num_heads, sequence_length, sequence_length).

    Poids d'attention du décodeur, après le softmax d'attention, utilisés pour calculer la moyenne pondérée dans les têtes d'auto-attention.

  • cross_attentions (tuple(torch.Tensor), facultatif, renvoyé lorsque output_attentions=True est passé ou lorsque config.output_attentions=True) — Tuple de torch.Tensor (un par couche) de forme (batch_size, num_heads, sequence_length, sequence_length).

    Poids d'attention de la couche d'attention croisée du décodeur, après le softmax d'attention, utilisés pour calculer la moyenne pondérée dans les têtes d'attention croisée.

  • encoder_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 de l'encodeur du modèle.

  • encoder_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 de l'encodeur à la sortie de chaque couche, plus les sorties d'incorporation initiales facultatives.

  • encoder_attentions (tuple(torch.Tensor), facultatif, renvoyé lorsque output_attentions=True est passé ou lorsque config.output_attentions=True) — Tuple de torch.Tensor (un par couche) de forme (batch_size, num_heads, sequence_length, sequence_length).

    Poids d'attention de l'encodeur, après le softmax d'attention, utilisés pour calculer la moyenne pondérée dans les têtes d'auto-attention.

  • loc (torch.Tensor de forme (batch_size,) ou (batch_size, input_size), facultatif) — Valeurs de décalage appliquées à la fenêtre de contexte de chaque série temporelle, utilisées pour fournir au modèle des entrées de même amplitude, puis pour revenir à l'amplitude d'origine.

  • scale (torch.Tensor de forme (batch_size,) ou (batch_size, input_size), facultatif) — Valeurs d'échelle de la fenêtre de contexte de chaque série temporelle, utilisées pour fournir au modèle des entrées de même magnitude, puis pour rétablir l'échelle d'origine.

  • static_features (torch.Tensor de forme (batch_size, feature size), facultatif) — Caractéristiques statiques de chaque série temporelle d’un lot, copiées dans les covariables lors de l’inférence.

Exemples :

>>> from huggingface_hub import hf_hub_download
>>> import torch
>>> from transformers import InformerForPrediction

>>> file = hf_hub_download(
...     repo_id="hf-internal-testing/tourism-monthly-batch", filename="train-batch.pt", repo_type="dataset"
... )
>>> batch = torch.load(file)

>>> model = InformerForPrediction.from_pretrained(
...     "huggingface/informer-tourism-monthly"
... )

>>> # during training, one provides both past and future values
>>> # as well as possible additional features
>>> outputs = model(
...     past_values=batch["past_values"],
...     past_time_features=batch["past_time_features"],
...     past_observed_mask=batch["past_observed_mask"],
...     static_categorical_features=batch["static_categorical_features"],
...     static_real_features=batch["static_real_features"],
...     future_values=batch["future_values"],
...     future_time_features=batch["future_time_features"],
... )

>>> loss = outputs.loss
>>> loss.backward()

>>> # during inference, one only provides past values
>>> # as well as possible additional features
>>> # the model autoregressively generates future values
>>> outputs = model.generate(
...     past_values=batch["past_values"],
...     past_time_features=batch["past_time_features"],
...     past_observed_mask=batch["past_observed_mask"],
...     static_categorical_features=batch["static_categorical_features"],
...     static_real_features=batch["static_real_features"],
...     future_time_features=batch["future_time_features"],
... )

>>> mean_prediction = outputs.sequences.mean(dim=1)
Update on GitHub