Transformers documentation
TimesFM 2.5
Ce modèle a été publié dans les papiers HF le 2023-10-14 et contribué à Hugging Face Transformers le 2026-02-27.
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_predictionsTimesFm2_5Config
classe transformers.TimesFm2_5Config
< 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 = 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éfaut20) — 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. - 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. - attention_dropout (
Union[float, int], facultatif, valeur par défaut0.0) — Le taux de dropout appliqué aux probabilités d'attention. - initializer_range (
float, facultatif, par défaut0.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éfaut16) — Ceci est le nombre de têtes key_value à utiliser pour implémenter l'attention Grouped Query. Sinum_key_value_heads=num_attention_heads, le modèle utilisera l'attention Multi Head (MHA), sinum_key_value_heads=1le 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 seranum_attention_heads. - attention_bias (
bool, facultatif, par défautFalse) — 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éfautFalse) — Indique s'il faut utiliser un biais dans les couches linéaires des MLP et des transformeurs. - activation (
str, facultatif, par défautswish) — 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éfautTrue) — 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éfautTrue) — Indique s'il faut appliquer une moyenne d'invariance par retournement lors des prévisions. - infer_is_positive (
bool, facultatif, valeur par défautTrue) — 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éfaut16384) — 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 pourrope_thetaet, le cas échéant, les paramètres utilisés pour le mise à l’échelle si vous souhaitez utiliser RoPE avec desmax_position_embeddingsplus 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.
TimesFm2_5Model
forward
< source >( 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.Tensorde 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.LongTensorde forme(batch_size, sequence_length), facultatif) — Masque de bourrage pour l'entrée.1indique les pas de temps bourrés (masqués),0indique 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
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,)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.context_mu (
torch.Tensorde forme(batch_size, num_patches)) — Moyennes courantes calculées pour chaque patch d'entrée lors de la normalisation.context_sigma (
torch.Tensorde forme(batch_size, num_patches)) — Écarts-types courants calculés pour chaque patch d'entrée lors de la normalisation.
TimesFm2_5ModelForPrediction
Modèle TimesFm2_5 pour la prédiction des quantiles et de la moyenne.
forward
< source >( 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. SiNone, 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. SiNone, la valeur par défaut estconfig.infer_is_positive. - force_flip_invariance (
bool, facultatif) — Indique s'il faut appliquer la combinaison d'invariance par retournement. SiNone, la valeur par défaut estconfig.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
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, horizon_length)) — Prévisions déterministes après dénormalisation.full_predictions (
torch.Tensorde forme(batch_size, horizon_length, quantiles)) — Prévisions par quantiles, incluant la médiane, après dénormalisation.loss (
torch.Tensorde forme(1,), facultatif, renvoyé lorsquefuture_valuesest fourni) — Perte d'entraînement combinant les pertes MSE et quantile lorsque des cibles sont fournies.