Transformers documentation

TimesFM

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v5.23.0).
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 les papiers HF le 2023-10-14 et contribué à Hugging Face Transformers le 2025-04-16.

TimesFM

Aperçu

TimesFM (Time Series Foundation Model) est un modèle de base préentraîné pour les séries temporelles, proposé dans A decoder-only foundation model for time-series forecasting par Abhimanyu Das, Weihao Kong, Rajat Sen et Yichen Zhou. Il s’agit d’un modèle de type decoder only qui prend en entrée des patches non chevauchants de données de séries temporelles et produit, de manière autorégressive, une prédiction d’une longueur de patch de sortie donnée.

L'abstract de l'article est le suivant :

Inspiré par les récentes avancées des grands modèles de langage pour le traitement automatique des langues (NLP), nous concevons un modèle de fondation pour séries temporelles destiné à la prévision, dont les performances zero-shot, sans aucune adaptation, sur une variété de jeux de données publics s'approchent de la précision des modèles de prévision supervisés de pointe pour chaque jeu de données individuel. Notre modèle repose sur la pré-entraînement d'un modèle d'attention de type patched-decoder sur un large corpus de séries temporelles, et fonctionne bien à travers différentes longueurs d'historique de prévision, longueurs de prédiction et granularités temporelles.

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

Pour utiliser le modèle :

import numpy as np
import torch

from transformers import TimesFmModelForPrediction


model = TimesFmModelForPrediction.from_pretrained(
    "google/timesfm-2.0-500m-pytorch",
    attn_implementation="sdpa",
    device_map="auto"
)


 # Create dummy inputs
forecast_input = [
    np.sin(np.linspace(0, 20, 100)),
    np.sin(np.linspace(0, 20, 200)),
    np.sin(np.linspace(0, 20, 400)),
]
frequency_input = [0, 1, 2]

# Convert inputs to sequence of tensors
forecast_input_tensor = [
    torch.tensor(ts).to(model.device)
    for ts in forecast_input
]
frequency_input_tensor = torch.tensor(frequency_input, dtype=torch.long).to(model.device)

# Get predictions from the pre-trained model
with torch.no_grad():
    outputs = model(past_values=forecast_input_tensor, freq=frequency_input_tensor, return_dict=True)
    point_forecast_conv = outputs.mean_predictions.float().cpu().numpy()
    quantile_forecast_conv = outputs.full_predictions.float().cpu().numpy()

TimesFmConfig

classe transformers.TimesFmConfig

< >

( 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 = Nonepatch_length: int = 32context_length: int = 512horizon_length: int = 128freq_size: int = 3num_hidden_layers: int = 50hidden_size: int = 1280intermediate_size: int = 1280head_dim: int = 80num_attention_heads: int = 16tolerance: float = 1e-06rms_norm_eps: float = 1e-06quantiles: list[float] | tuple[float, ...] = (0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9)pad_val: float = 1123581321.0attention_dropout: float | int = 0.0use_positional_embedding: bool = Falseinitializer_range: float = 0.02min_timescale: int = 1max_timescale: int = 10000 )

Paramètres

  • patch_length (int, facultatif, valeur par défaut : 32) — La longueur d'un patch dans la séquence d'entrée.
  • context_length (int, facultatif, par défaut 512) — La longueur du contexte d'entrée.
  • horizon_length (int, facultatif, par défaut 128) — La longueur de l'horizon de prédiction.
  • freq_size (int, facultatif, valeur par défaut : 3) — Le nombre d’embeddings de fréquence.
  • num_hidden_layers (int, facultatif, par défaut 50) — Nombre de couches cachées dans le décodeur Transformer.
  • hidden_size (int, facultatif, par défaut 1280) — Dimension des représentations cachées.
  • intermediate_size (int, facultatif, par défaut 1280) — Dimension des représentations MLP.
  • head_dim (int, facultatif, valeur par défaut 80) — La dimension des têtes d'attention. Si None, elle est définie par défaut sur hidden_size // num_attention_heads
  • num_attention_heads (int, facultatif, valeur par défaut 16) — Nombre de têtes d'attention pour chaque couche d'attention du décodeur Transformer.
  • tolerance (float, facultatif, par défaut 1e-06) — La tolérance pour la perte de quantile.
  • rms_norm_eps (float, facultatif, valeur par défaut 1e-06) — L'épsilon utilisé par les couches de normalisation rms.
  • quantiles (list[float], facultatif, par défaut [0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9]) — Les quantiles à prédire.
  • pad_val (float, facultatif, valeur par défaut : 1123581321.0) — La valeur utilisée pour compléter les prédictions.
  • attention_dropout (float, facultatif, valeur par défaut 0.0) — Probabilité de dropout appliquée aux scores d'attention.
  • use_positional_embedding (bool, facultatif, valeur par défaut False) — Indique s'il faut ajouter des embeddings positionnels.
  • initializer_range (float, facultatif, par défaut 0.02) — L'écart-type de la truncated_normal_initializer utilisé pour initialiser toutes les matrices de poids.
  • min_timescale (int, facultatif, valeur par défaut : 1) — Début de l'index positionnel géométrique. Détermine la périodicité du signal ajouté.
  • max_timescale (int, facultatif, valeur par défaut : 10000) — Fin de l'index positionnel géométrique. Détermine la fréquence du signal ajouté.

Ceci est la classe de configuration destinée à stocker la configuration d'un TimesFmModel. Elle est utilisée pour instancier un modèle Timesfm 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 google/timesfm-2.0-500m-pytorch

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.

TimesFmModel

classe transformers.TimesFmModel

< >

( config: TimesFmConfig )

Paramètres

  • config (TimesFmConfig) — 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 Timesfm 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_values_padding: LongTensorfreq: Tensor**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → TimesFmOutput or tuple(torch.Tensor)

Paramètres

  • past_values (torch.Tensor de forme (batch_size, sequence_length)) — Valeurs passées de la série temporelle servant d'entrée au modèle.
  • past_values_padding (torch.LongTensor de forme (batch_size, sequence_length)) — Indicateur de bourrage de la série temporelle.
  • freq (torch.LongTensor de forme (batch_size,)) — Indices de fréquence pour les données de séries temporelles.

Retourne

TimesFmOutput ou tuple(torch.Tensor)

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

La méthode forward du modèle TimesFmModel 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 modèle.

  • hidden_states (tuple(torch.Tensor), facultatif, renvoyé lorsque output_hidden_states=True est passé ou lorsque config.output_hidden_states=True) — Tuple de torch.Tensor (un pour la sortie des embeddings, si le modèle possède une couche d’embedding, + un pour la sortie de chaque couche) de forme (batch_size, sequence_length, hidden_size).

    États cachés du modèle à la sortie de chaque couche, ainsi que les sorties d'incorporation initiales facultatives.

  • 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 des attentions 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, )) — La moyenne des séries temporelles d'entrée.

  • scale (torch.Tensor de forme (batch_size,)) — L'échelle des entrées de la série temporelle.

TimesFmModelForPrediction

classe transformers.TimesFmModelForPrediction

< >

( config: TimesFmConfig )

Modèle TimesFM pour la prédiction des quantiles et de la moyenne.

forward

< >

( past_values: collections.abc.Sequence[torch.Tensor]freq: collections.abc.Sequence[typing.Union[torch.Tensor, int]] | None = Nonewindow_size: int | None = Nonefuture_values: typing.Optional[torch.Tensor] = Noneforecast_context_len: int | None = Nonereturn_forecast_on_context: bool = Falsetruncate_negative: bool = False**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → TimesFmOutputForPrediction or tuple(torch.Tensor)

Paramètres

  • past_values (torch.Tensor de forme (batch_size, sequence_length)) — Valeurs passées de la série temporelle servant d'entrée au modèle.
  • freq (torch.LongTensor de forme (batch_size,)) — Indices de fréquence pour les données de séries temporelles.
  • window_size (int, facultatif) — Taille de la fenêtre de la décomposition en tendance + résidu. Si la valeur est None, aucune décomposition n'est effectuée.
  • future_values (torch.Tensor, facultatif) — Valeurs futures de la série temporelle à utiliser pour le calcul de la perte.
  • forecast_context_len (int, facultatif) — Longueur de contexte maximale facultative.
  • return_forecast_on_context (bool, facultatif) — True pour renvoyer la prévision sur le contexte lorsqu'il est disponible, c'est-à-dire après le premier patch d'entrée.
  • truncate_negative (bool, facultatif) — Tronque pour ne conserver que les valeurs non négatives si l'un des contextes en contient, sinon ne fait rien.

Retourne

TimesFmOutputForPrediction ou tuple(torch.Tensor)

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

La méthode forward du modèle TimesFmModelForPrediction 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 modèle.

  • hidden_states (tuple(torch.Tensor), facultatif, renvoyé lorsque output_hidden_states=True est passé ou lorsque config.output_hidden_states=True) — Tuple de torch.Tensor (un pour la sortie des embeddings, si le modèle possède une couche d’embedding, + un pour la sortie de chaque couche) de forme (batch_size, sequence_length, hidden_size).

    États cachés du modèle à la sortie de chaque couche, ainsi que les sorties d'incorporation initiales facultatives.

  • 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 des attentions après le softmax d'attention, utilisés pour calculer la moyenne pondérée dans les têtes d'auto-attention.

  • mean_predictions (torch.Tensor de forme (batch_size, sequence_length)) — Les prédictions moyennes de la série temporelle.

  • full_predictions (torch.Tensor de forme (batch_size, sequence_length)) — Les prédictions complètes de la série temporelle, incluant la moyenne et les quantiles.

  • loss (torch.Tensor de forme (1,), facultatif, renvoyé lorsque future_values est fourni) — La perte du modèle TimesFM.

Exemple :

>>> from transformers import TimesFmModelForPrediction

>>> model = TimesFmModelForPrediction.from_pretrained("google/timesfm-2.0-500m-pytorch")

>>> forecast_input = [torch.linspace(0, 20, 100).sin(), torch.linspace(0, 20, 200).sin(), torch.linspace(0, 20, 400).sin()]
>>> frequency_input = torch.tensor([0, 1, 2], dtype=torch.long)

>>> # Generate
>>> with torch.no_grad():
>>>     outputs = model(past_values=forecast_input, freq=frequency_input, return_dict=True)
>>>     point_forecast_conv = outputs.mean_predictions
>>>     quantile_forecast_conv = outputs.full_predictions
Update on GitHub