Transformers documentation

TimesFM 2.5

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 2026-02-27.

FlashAttention SDPA

TimesFM 2.5

Aperçu

TimesFM 2.5 (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'appuie sur l'architecture originale de TimesFM, en y intégrant l'attention rotative, la normalisation QK, le mise à l'échelle de l'attention par dimension et la prédiction de quantiles continus.

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 « prêtes à l’emploi » 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 décodeur avec patching d’entrée, en utilisant un large corpus de séries temporelles comprenant à la fois des jeux de données réels et synthétiques. Des expériences sur un ensemble diversifié de jeux de données de prévision inédits suggèrent que le modèle peut produire des prévisions zero-shot précises à travers différents domaines, horizons de prévision et granularités temporelles.

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

Vous pouvez trouver le point de contrôle à l’adresse google/timesfm-2.5-200m-transformers.

Exemple d'utilisation

import numpy as np
import torch

from transformers import TimesFm2_5ModelForPrediction


model = TimesFm2_5ModelForPrediction.from_pretrained(
    "google/timesfm-2.5-200m-transformers",
    device_map="auto",
)

forecast_input = [
    np.sin(np.linspace(0, 20, 100)),
    np.sin(np.linspace(0, 20, 200)),
    np.sin(np.linspace(0, 20, 400)),
]
forecast_input_tensor = [torch.tensor(ts, dtype=torch.float32, device=model.device) for ts in forecast_input]

with torch.no_grad():
    outputs = model(past_values=forecast_input_tensor, return_dict=True)
    point_forecast = outputs.mean_predictions
    quantile_forecast = outputs.full_predictions

TimesFm2_5Config

classe transformers.TimesFm2_5Config

< >

( 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 = 16384horizon_length: int = 128num_hidden_layers: int = 20hidden_size: int = 1280intermediate_size: int = 1280head_dim: int = 80num_attention_heads: int = 16rms_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)attention_dropout: float | int = 0.0initializer_range: float = 0.02num_key_value_heads: int = 16attention_bias: bool = Falseoutput_quantile_len: int = 1024decode_index: int = 5use_bias: bool = Falseactivation: str = 'swish'use_continuous_quantile_head: bool = Trueforce_flip_invariance: bool = Trueinfer_is_positive: bool = Truemax_position_embeddings: int = 16384rope_parameters: transformers.modeling_rope_utils.RopeParameters | dict | None = None )

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 16384) — La longueur du contexte d'entrée.
  • horizon_length (int, facultatif, par défaut 128) — La longueur de l'horizon de prédiction.
  • num_hidden_layers (int, facultatif, par défaut 20) — 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.
  • 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.
  • attention_dropout (Union[float, int], facultatif, valeur par défaut 0.0) — Le taux de dropout appliqué aux probabilités d'attention.
  • 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.
  • num_key_value_heads (int, facultatif, valeur par défaut 16) — Ceci est le nombre de têtes key_value à utiliser pour implémenter l'attention Grouped Query. Si num_key_value_heads=num_attention_heads, le modèle utilisera l'attention Multi Head (MHA), si num_key_value_heads=1 le modèle utilisera l'attention Multi Query (MQA), sinon l'attention GQA est utilisée. Lors de la conversion d'un checkpoint multi-têtes en checkpoint GQA, chaque tête clé et valeur de groupe doit être construite en effectuant un meanpooling de toutes les têtes d'origine au sein de ce groupe. Pour plus de détails, consultez ce papier. S'il n'est pas spécifié, la valeur par défaut sera num_attention_heads.
  • attention_bias (bool, facultatif, par défaut False) — Indique s'il faut utiliser un biais dans les couches de projection des requêtes, des clés, des valeurs et de la sortie lors de l'auto-attention.
  • output_quantile_len (int, facultatif, valeur par défaut : 1024) — Longueur de la dimension de projection de la sortie des quantiles.
  • decode_index (int, facultatif, valeur par défaut : 5) — Index dans la dimension des quantiles utilisé pour extraire la prédiction ponctuelle (médiane).
  • use_bias (bool, facultatif, par défaut False) — Indique s'il faut utiliser un biais dans les couches linéaires des MLP et des transformeurs.
  • activation (str, facultatif, par défaut swish) — La fonction d'activation non linéaire (fonction ou chaîne de caractères) dans le décodeur. Par exemple, "gelu", "relu", "silu", etc.
  • use_continuous_quantile_head (bool, facultatif, valeur par défaut True) — Indique s'il faut utiliser la tête de quantile continue pour les prédictions de quantiles non médians.
  • force_flip_invariance (bool, facultatif, valeur par défaut True) — Indique s'il faut appliquer une moyenne d'invariance par retournement lors des prévisions.
  • infer_is_positive (bool, facultatif, valeur par défaut True) — Indique s'il faut limiter les prévisions à des valeurs non négatives lorsque le minimum de l'entrée est non négatif.
  • max_position_embeddings (int, facultatif, par défaut 16384) — La longueur de séquence maximale avec laquelle ce modèle pourrait être utilisé.
  • rope_parameters (Union[~modeling_rope_utils.RopeParameters, dict], facultatif) — Dictionnaire contenant les paramètres de configuration pour les embeddings RoPE. Le dictionnaire doit contenir une valeur pour rope_theta et, le cas échéant, les paramètres utilisés pour le mise à l’échelle si vous souhaitez utiliser RoPE avec des max_position_embeddings plus longs.

Ceci est la classe de configuration destinée à stocker la configuration d'un TimesFm2_5Model. Elle est utilisée pour instancier un modèle Timesfm2 5 selon les 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.5-200m-transformers

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 TimesFm2_5Config, TimesFm2_5ModelForPrediction

>>> configuration = TimesFm2_5Config()
>>> model = TimesFm2_5ModelForPrediction(configuration)
>>> configuration = model.config

TimesFm2_5Model

classe transformers.TimesFm2_5Model

< >

( config: TimesFm2_5Config )

forward

< >

( past_values: Tensorpast_values_padding: typing.Optional[torch.LongTensor] = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → TimesFm2_5Output or tuple(torch.Tensor)

Paramètres

  • past_values (torch.Tensor de forme (batch_size, sequence_length)) — Valeurs passées de la série temporelle utilisées comme entrée du modèle.
  • past_values_padding (torch.LongTensor de forme (batch_size, sequence_length), facultatif) — Masque de bourrage pour l'entrée. 1 indique les pas de temps bourrés (masqués), 0 indique les valeurs valides.

Retourne

TimesFm2_5Output ou tuple(torch.Tensor)

Un TimesFm2_5Output ou un tuple de torch.Tensor (si return_dict=False est passé ou lorsque config.return_dict=False) comprenant divers éléments selon la configuration (TimesFm2_5Config) et les entrées.

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

  • context_mu (torch.Tensor de forme (batch_size, num_patches)) — Moyennes courantes calculées pour chaque patch d'entrée lors de la normalisation.

  • context_sigma (torch.Tensor de forme (batch_size, num_patches)) — Écarts-types courants calculés pour chaque patch d'entrée lors de la normalisation.

TimesFm2_5ModelForPrediction

classe transformers.TimesFm2_5ModelForPrediction

< >

( config: TimesFm2_5Config )

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

forward

< >

( past_values: collections.abc.Sequence[torch.Tensor]window_size: int | None = Nonefuture_values: typing.Optional[torch.Tensor] = Noneforecast_context_len: int | None = Nonetruncate_negative: bool | None = Noneforce_flip_invariance: bool | None = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → TimesFm2_5OutputForPrediction or tuple(torch.Tensor)

Paramètres

  • past_values (collections.abc.Sequence[torch.Tensor]) — Valeurs passées de la série temporelle servant d'entrée au modèle. Chaque tenseur est une série temporelle 1D.
  • window_size (int, facultatif) — Taille de la fenêtre de la décomposition en tendance + résidu. Si None, la décomposition n'est pas appliquée.
  • future_values (torch.Tensor, facultatif) — Valeurs futures facultatives utilisées pour calculer la perte.
  • forecast_context_len (int, facultatif) — Longueur de contexte facultative utilisée lors des prévisions.
  • truncate_negative (bool, facultatif) — Indique s'il faut limiter les sorties aux valeurs non négatives. Si None, la valeur par défaut est config.infer_is_positive.
  • force_flip_invariance (bool, facultatif) — Indique s'il faut appliquer la combinaison d'invariance par retournement. Si None, la valeur par défaut est config.force_flip_invariance.

Retourne

TimesFm2_5OutputForPrediction ou tuple(torch.Tensor)

Un TimesFm2_5OutputForPrediction ou un tuple de torch.Tensor (si return_dict=False est passé ou lorsque config.return_dict=False) comprenant divers éléments selon la configuration (TimesFm2_5Config) et les entrées.

La méthode forward du modèle TimesFm2_5ModelForPrediction 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, horizon_length)) — Prévisions déterministes après dénormalisation.

  • full_predictions (torch.Tensor de forme (batch_size, horizon_length, quantiles)) — Prévisions par quantiles, incluant la médiane, après dénormalisation.

  • loss (torch.Tensor de forme (1,), facultatif, renvoyé lorsque future_values est fourni) — Perte d'entraînement combinant les pertes MSE et quantile lorsque des cibles sont fournies.

Update on GitHub