Transformers documentation
TimesFM
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
< source >( transformers_version: str | None = Nonearchitectures: list[str] | None = Noneoutput_hidden_states: bool | None = Falsereturn_dict: bool | None = Truedtype: str | torch.dtype | None = Nonechunk_size_feed_forward: int = 0is_encoder_decoder: bool = Falseid2label: dict[int, str] | dict[str, str] | None = Nonelabel2id: dict[str, int] | dict[str, str] | None = Noneproblem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = 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éfaut50) — Nombre de couches cachées dans le décodeur Transformer. - hidden_size (
int, facultatif, par défaut1280) — Dimension des représentations cachées. - intermediate_size (
int, facultatif, par défaut1280) — Dimension des représentations MLP. - head_dim (
int, facultatif, valeur par défaut80) — 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éfaut16) — 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éfaut1e-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éfautFalse) — Indique s'il faut ajouter des embeddings positionnels. - initializer_range (
float, facultatif, par défaut0.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
< source >( 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
< source >( past_values: Tensorpast_values_padding: LongTensorfreq: Tensor**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → TimesFmOutput or tuple(torch.Tensor)
Paramètres
- past_values (
torch.Tensorde forme(batch_size, sequence_length)) — Valeurs passées de la série temporelle servant d'entrée au modèle. - past_values_padding (
torch.LongTensorde forme(batch_size, sequence_length)) — Indicateur de bourrage de la série temporelle. - freq (
torch.LongTensorde 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
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 modèle.hidden_states (
tuple(torch.Tensor), facultatif, renvoyé lorsqueoutput_hidden_states=Trueest passé ou lorsqueconfig.output_hidden_states=True) — Tuple detorch.Tensor(un pour la sortie des embeddings, si le modèle possède une couche d’embedding, + un pour la sortie de chaque couche) de forme(batch_size, sequence_length, hidden_size).États cachés du modèle à la sortie de chaque couche, ainsi que les sorties d'incorporation initiales facultatives.
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 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.Tensorde forme(batch_size, )) — La moyenne des séries temporelles d'entrée.scale (
torch.Tensorde forme(batch_size,)) — L'échelle des entrées de la série temporelle.
TimesFmModelForPrediction
Modèle TimesFM pour la prédiction des quantiles et de la moyenne.
forward
< source >( 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.Tensorde forme(batch_size, sequence_length)) — Valeurs passées de la série temporelle servant d'entrée au modèle. - freq (
torch.LongTensorde 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
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 modèle.hidden_states (
tuple(torch.Tensor), facultatif, renvoyé lorsqueoutput_hidden_states=Trueest passé ou lorsqueconfig.output_hidden_states=True) — Tuple detorch.Tensor(un pour la sortie des embeddings, si le modèle possède une couche d’embedding, + un pour la sortie de chaque couche) de forme(batch_size, sequence_length, hidden_size).États cachés du modèle à la sortie de chaque couche, ainsi que les sorties d'incorporation initiales facultatives.
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 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.Tensorde forme(batch_size, sequence_length)) — Les prédictions moyennes de la série temporelle.full_predictions (
torch.Tensorde forme(batch_size, sequence_length)) — Les prédictions complètes de la série temporelle, incluant la moyenne et les quantiles.loss (
torch.Tensorde forme(1,), facultatif, renvoyé lorsquefuture_valuesest 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