Transformers documentation
Autoformer
Ce modèle a été publié dans HF papers le 2021-06-24 et ajouté à Hugging Face Transformers le 2023-05-30.
Autoformer
Aperçu
Le modèle Autoformer a été proposé dans Autoformer: Decomposition Transformers with Auto-Correlation for Long-Term Series Forecasting par Haixu Wu, Jiehui Xu, Jianmin Wang, Mingsheng Long.
Ce modèle étend le Transformer en tant qu'architecture de décomposition profonde, capable de décomposer progressivement les composantes de tendance et saisonnières au cours du processus de prévision.
L'abstract de l'article est le suivant :
Étendre la période de prévision est un besoin essentiel pour les applications réelles, telles que l'alerte précoce sur les phénomènes météorologiques extrêmes et la planification à long terme de la consommation d'énergie. Cet article étudie le problème de la prévision à long terme des séries temporelles. Les modèles basés sur les Transformers adoptent divers mécanismes d'auto-attention pour découvrir les dépendances à longue portée. Cependant, les motifs temporels complexes du futur lointain empêchent le modèle de trouver des dépendances fiables. De plus, les Transformers doivent adopter des versions creuses des auto-attentions ponctuelles pour l'efficacité sur les longues séries, ce qui entraîne un goulot d'étranglement dans l'utilisation de l'information. En allant au-delà des Transformers, nous concevons Autoformer comme une nouvelle architecture de décomposition dotée d'un mécanisme d'Auto-Correlation. Nous rompons avec la convention de prétraitement de la décomposition des séries et la réinventons comme un bloc interne de base des modèles profonds. Cette conception confère à Autoformer des capacités de décomposition progressive pour les séries temporelles complexes. En outre, inspiré par la théorie des processus stochastiques, nous concevons le mécanisme d'Auto-Correlation basé sur la périodicité des séries, qui effectue la découverte des dépendances et l'agrégation des représentations au niveau des sous-séries. L'Auto-Correlation surpasse l'auto-attention en termes d'efficacité et de précision. En prévision à long terme, Autoformer atteint une précision de pointe, avec une amélioration relative de 38 % sur six benchmarks, couvrant cinq applications pratiques : énergie, trafic, économie, météo et maladie.
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.
- Consultez le billet de blog Autoformer sur le blog HuggingFace : Yes, Transformers are Effective for Time Series Forecasting (+ Autoformer)
AutoformerConfig
classe transformers.AutoformerConfig
< 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 = 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] | tuple[int, ...] = (1, 2, 3, 4, 5, 6, 7)scaling: bool | str = Truenum_time_features: int = 0num_dynamic_real_features: int = 0num_static_categorical_features: int = 0num_static_real_features: int = 0cardinality: list[int] | None = Noneembedding_dimension: list[int] | None = Noned_model: int = 64encoder_attention_heads: int = 2decoder_attention_heads: int = 2encoder_layers: int = 2decoder_layers: int = 2encoder_ffn_dim: int = 32decoder_ffn_dim: int = 32activation_function: str = 'gelu'dropout: float | int = 0.1encoder_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 = Truelabel_length: int = 10moving_average: int = 25autocorrelation_factor: int = 3 )
Paramètres
- is_encoder_decoder (
bool, facultatif, valeur par défautTrue) — 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. - context_length (
int, facultatif, par défautprediction_length) — La longueur de contexte pour l'encodeur. Si non définie, la longueur de contexte sera identique à laprediction_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êtedistribution_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. La valeur par défaut est[1, 2, 3, 4, 5, 6, 7]. - scaling (
bool, facultatif, par défautTrue) — Indique s'il faut mettre à l'échelle les cibles d'entrée. - num_time_features (
int, facultatif, valeur par défaut 0) — Le nombre de caractéristiques temporelles dans la série temporelle d'entrée. - num_dynamic_real_features (
int, facultatif, valeur par défaut 0) — Le nombre de caractéristiques dynamiques à valeurs réelles. - num_static_categorical_features (
int, facultatif, valeur par défaut 0) — Le nombre de caractéristiques catégorielles statiques. - num_static_real_features (
int, facultatif, valeur par défaut 0) — Le nombre de caractéristiques statiques à valeurs réelles. - 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 quenum_static_categorical_features. Ne peut pas êtreNonesinum_static_categorical_featuresest > 0. - embedding_dimension (
list[int], facultatif) — Dimension des embeddings et des états cachés. - d_model (
int, facultatif, par défaut64) — Taille des couches encodeur et de la couche pooler. - encoder_attention_heads (
int, facultatif, valeur par défaut2) — Nombre de têtes d'attention pour chaque couche d'attention dans l'encodeur Transformer. - decoder_attention_heads (
int, facultatif, valeur par défaut2) — Nombre de têtes d'attention pour chaque couche d'attention du décodeur Transformer. - encoder_layers (
int, facultatif, valeur par défaut2) — Nombre de couches cachées dans l'encodeur Transformer. Utilise la même valeur quenum_layerssi non défini. - decoder_layers (
int, facultatif, valeur par défaut2) — Nombre de couches cachées dans le décodeur Transformer. Utilise la même valeur quenum_layerssi non défini. - encoder_ffn_dim (
int, facultatif, valeur par défaut32) — Dimension de la couche « intermédiaire » (souvent appelée couche feed-forward) de l’encodeur. - decoder_ffn_dim (
int, facultatif, valeur par défaut32) — Dimension de la couche « intermédiaire » (souvent appelée couche feed-forward) du décodeur. - activation_function (
str, facultatif, par défautgelu) — 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éfaut0.1) — Le taux appliqué à toutes les couches de dropout. - encoder_layerdrop (
Union[float, int], facultatif, valeur par défaut0.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éfaut0.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éfaut0.1) — Le taux de dropout appliqué aux probabilités d'attention. - activation_dropout (
Union[float, int], facultatif, valeur par défaut0.1) — Le taux de dropout appliqué aux activations à l'intérieur de la couche entièrement connectée. - 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éfaut0.02) — L'écart-type de la truncated_normal_initializer utilisé pour initialiser toutes les matrices de poids. - 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. - label_length (
int, facultatif, valeur par défaut 10) — Longueur du jeton de départ du décodeur Autoformer, utilisée pour la prédiction multi-étapes directe (c.-à-d. la génération non autorégressive). - moving_average (
int, facultatif, par défaut 25) — La taille de la fenêtre de la moyenne mobile. En pratique, il s’agit de la taille du noyau dans AvgPool1d de la couche Decomposition. - autocorrelation_factor (
int, facultatif, valeur par défaut 3) — Facteur « Attention » (c’est-à-dire mécanisme AutoCorrelation) utilisé pour trouver les k retards d’auto-corrélation les plus élevés. L’article recommande de le définir à un nombre compris entre 1 et 5.
Ceci est la classe de configuration destinée à stocker la configuration d'un AutoformerModel. Elle est utilisée pour instancier un modèle Autoformer 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/autoformer-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 AutoformerConfig, AutoformerModel
>>> # Initializing a default Autoformer configuration
>>> configuration = AutoformerConfig()
>>> # Randomly initializing a model (with random weights) from the configuration
>>> model = AutoformerModel(configuration)
>>> # Accessing the model configuration
>>> configuration = model.configAutoformerModel
classe transformers.AutoformerModel
< source >( config: AutoformerConfig )
Paramètres
- config (AutoformerConfig) — 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 Autoformer 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 >( 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'> ) → AutoformerModelOutput or tuple(torch.Tensor)
Paramètres
- past_values (
torch.Tensorde forme(batch_size, sequence_length)) — Valeurs passées de la série temporelle, servant de contexte pour prédire l'avenir. Ces valeurs peuvent contenir des retards (lags), c'est-à-dire des valeurs supplémentaires du passé ajoutées pour servir de « contexte supplémentaire ».past_valuesest l'entrée du codeur Transformer (avec des fonctionnalités supplémentaires facultatives, telles questatic_categorical_features,static_real_features,past_time_features).La longueur de la séquence ici est égale à
context_length+max(config.lags_sequence).Les valeurs manquantes doivent être remplacées par des zéros.
- past_time_features (
torch.Tensorde forme(batch_size, sequence_length, num_features), facultatif) — Caractéristiques temporelles facultatives, que le modèle ajoutera en interne àpast_values. Il peut s'agir d'éléments tels que 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.Ces caractéristiques servent de « codages positionnels » pour les 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.
L'Autoformer n'apprend des embeddings supplémentaires que pour
static_categorical_features. - past_observed_mask (
torch.BoolTensorde forme(batch_size, sequence_length), facultatif) — Masque booléen indiquant quellespast_valuesont été observées et lesquelles étaient manquantes. 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.LongTensorde 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.Tensorde 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.Tensorde forme(batch_size, prediction_length)) — Valeurs futures de la série temporelle, servant d'étiquettes pour le modèle. Lefuture_valuesest ce que le Transformer doit apprendre à produire, étant donné lespast_values.Consultez le notebook de démonstration et les extraits de code pour plus de détails.
Les valeurs manquantes doivent être remplacées par des zéros.
- future_time_features (
torch.Tensorde forme(batch_size, prediction_length, num_features), facultatif) — Caractéristiques temporelles facultatives, que le modèle ajoutera en interne àfuture_values. Il peut s'agir d'éléments tels que 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.Ces caractéristiques servent de « codages positionnels » pour les 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 supplémentaires.
L'Autoformer n'apprend des embeddings supplémentaires que pour
static_categorical_features. - decoder_attention_mask (
torch.LongTensorde 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é delast_hidden_state,hidden_states(facultatif) etattentions(facultatif)last_hidden_statede 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 lapast_key_valuesretournée par le modèle à une étape antérieure du décodage, lorsqueuse_cache=Trueouconfig.use_cache=True.Seule une instance de Cache est autorisée en entrée, consultez notre guide du cache kv. Si aucun
past_key_valuesn'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_valuessont utilisés, l’utilisateur doit fournir uniquement lesinput_idsnon 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 lesinput_idsde forme(batch_size, sequence_length). - 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
AutoformerModelOutput ou tuple(torch.Tensor)
Un AutoformerModelOutput 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 (AutoformerConfig) et des entrées.
La méthode forward du modèle AutoformerModel surcharge 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)) — Séquence d'états cachés à la sortie de la dernière couche du décodeur du modèle.Si
past_key_valuesest utilisé, seule la dernière hidden-state des séquences de forme(batch_size, 1, hidden_size)est renvoyée.trend (
torch.Tensorde forme(batch_size, sequence_length, hidden_size)) — Tenseur de tendance pour chaque série temporelle.past_key_values (
Cache, facultatif, renvoyé lorsqueuse_cache=Trueest passé ou lorsqueconfig.use_cache=True) — Il s’agit d’une instance de Cache. 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é 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 décodeur à la sortie de chaque couche, plus les sorties de l'intégration initiale.
decoder_attentions (
tuple[torch.Tensor], facultatif, renvoyé lorsqueoutput_attentions=Trueest passé ou lorsqueconfig.output_attentions=True) — Tuple detorch.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é lorsqueoutput_attentions=Trueest passé ou lorsqueconfig.output_attentions=True) — Tuple detorch.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.Tensorde 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é 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 de l'encodeur à la sortie de chaque couche, plus les sorties des embeddings initiaux.
encoder_attentions (
tuple[torch.Tensor], facultatif, renvoyé lorsqueoutput_attentions=Trueest passé ou lorsqueconfig.output_attentions=True) — Tuple detorch.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.Tensorde 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.Tensorde 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 la magnitude d’origine. static_features : (torch.Tensorde 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.static_features (
torch.Tensorde 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 AutoformerModel
>>> file = hf_hub_download(
... repo_id="hf-internal-testing/tourism-monthly-batch", filename="train-batch.pt", repo_type="dataset"
... )
>>> batch = torch.load(file)
>>> model = AutoformerModel.from_pretrained("huggingface/autoformer-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"],
... future_values=batch["future_values"],
... future_time_features=batch["future_time_features"],
... )
>>> last_hidden_state = outputs.last_hidden_stateAutoformerForPrediction
classe transformers.AutoformerForPrediction
< source >( config: AutoformerConfig )
Paramètres
- config (AutoformerConfig) — 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 Autoformer avec une tête de distribution en tête 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
< source >( 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'> ) → Seq2SeqTSPredictionOutput or tuple(torch.Tensor)
Paramètres
- past_values (
torch.Tensorde forme(batch_size, sequence_length)) — Valeurs passées de la série temporelle, servant de contexte pour prédire l'avenir. Ces valeurs peuvent contenir des retards (lags), c'est-à-dire des valeurs supplémentaires du passé ajoutées pour servir de « contexte supplémentaire ».past_valuesest l'entrée du codeur Transformer (avec des fonctionnalités supplémentaires facultatives, telles questatic_categorical_features,static_real_features,past_time_features).La longueur de la séquence ici est égale à
context_length+max(config.lags_sequence).Les valeurs manquantes doivent être remplacées par des zéros.
- past_time_features (
torch.Tensorde forme(batch_size, sequence_length, num_features), facultatif) — Caractéristiques temporelles facultatives, que le modèle ajoutera en interne àpast_values. Il peut s'agir d'éléments tels que 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.Ces caractéristiques servent de « codages positionnels » pour les 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.
L'Autoformer n'apprend des embeddings supplémentaires que pour
static_categorical_features. - past_observed_mask (
torch.BoolTensorde forme(batch_size, sequence_length), facultatif) — Masque booléen indiquant quellespast_valuesont été observées et lesquelles étaient manquantes. 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.LongTensorde 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.Tensorde 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.Tensorde forme(batch_size, prediction_length)) — Valeurs futures de la série temporelle, servant d'étiquettes pour le modèle. Lefuture_valuesest ce que le Transformer doit apprendre à produire, étant donné lespast_values.Consultez le notebook de démonstration et les extraits de code pour plus de détails.
Les valeurs manquantes doivent être remplacées par des zéros.
- future_time_features (
torch.Tensorde forme(batch_size, prediction_length, num_features), facultatif) — Caractéristiques temporelles facultatives, que le modèle ajoutera en interne àfuture_values. Il peut s'agir d'éléments tels que 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.Ces caractéristiques servent de « codages positionnels » pour les 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 supplémentaires.
L'Autoformer n'apprend des embeddings supplémentaires que pour
static_categorical_features. - future_observed_mask (
torch.BoolTensorde forme(batch_size, sequence_length)ou(batch_size, sequence_length, input_size), facultatif) — Masque booléen indiquant quelsfuture_valuesont é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.LongTensorde 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é delast_hidden_state,hidden_states(facultatif) etattentions(facultatif)last_hidden_statede 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 lapast_key_valuesretournée par le modèle à une étape antérieure du décodage, lorsqueuse_cache=Trueouconfig.use_cache=True.Seule une instance de Cache est autorisée en entrée, consultez notre guide du cache kv. Si aucun
past_key_valuesn'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_valuessont utilisés, l’utilisateur doit fournir uniquement lesinput_idsnon 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 lesinput_idsde forme(batch_size, sequence_length). - 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
Seq2SeqTSPredictionOutput ou tuple(torch.Tensor)
Un Seq2SeqTSPredictionOutput 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 (AutoformerConfig) et des entrées.
La méthode forward de AutoformerForPrediction 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é lorsqu'unfuture_valuesest fourni) — Perte distributionnelle.params (
torch.Tensorde forme(batch_size, num_samples, num_params)) — Paramètres de la distribution choisie.past_key_values (
EncoderDecoderCache, facultatif, renvoyé lorsqueuse_cache=Trueest passé ou lorsqueconfig.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é 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 décodeur à la sortie de chaque couche, plus les sorties de l'intégration initiale.
decoder_attentions (
tuple(torch.Tensor), facultatif, renvoyé lorsqueoutput_attentions=Trueest passé ou lorsqueconfig.output_attentions=True) — Tuple detorch.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é lorsqueoutput_attentions=Trueest passé ou lorsqueconfig.output_attentions=True) — Tuple detorch.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.Tensorde 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é 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 de l'encodeur à la sortie de chaque couche, plus les sorties des embeddings initiaux.
encoder_attentions (
tuple(torch.Tensor), facultatif, renvoyé lorsqueoutput_attentions=Trueest passé ou lorsqueconfig.output_attentions=True) — Tuple detorch.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.Tensorde 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.Tensorde 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.Tensorde 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 AutoformerForPrediction
>>> file = hf_hub_download(
... repo_id="hf-internal-testing/tourism-monthly-batch", filename="train-batch.pt", repo_type="dataset"
... )
>>> batch = torch.load(file)
>>> model = AutoformerForPrediction.from_pretrained("huggingface/autoformer-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"],
... 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"],
... future_time_features=batch["future_time_features"],
... )
>>> mean_prediction = outputs.sequences.mean(dim=1)AutoformerForPrediction peut également utiliser static_real_features. Pour ce faire, définissez num_static_real_features dans AutoformerConfig en fonction du nombre de telles caractéristiques dans le jeu de données (dans le cas du jeu de données tourism_monthly, il
est égal à 1), initialisez le modèle et appelez comme indiqué ci-dessous :
>>> from huggingface_hub import hf_hub_download >>> import torch >>> from transformers import AutoformerConfig, AutoformerForPrediction >>> file = hf_hub_download( ... repo_id="hf-internal-testing/tourism-monthly-batch", filename="train-batch.pt", repo_type="dataset" ... ) >>> batch = torch.load(file) >>> # check number of static real features >>> num_static_real_features = batch["static_real_features"].shape[-1] >>> # load configuration of pretrained model and override num_static_real_features >>> configuration = AutoformerConfig.from_pretrained( ... "huggingface/autoformer-tourism-monthly", ... num_static_real_features=num_static_real_features, ... ) >>> # we also need to update feature_size as it is not recalculated >>> configuration.feature_size += num_static_real_features >>> model = AutoformerForPrediction(configuration) >>> 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"], ... )