Este modelo se publicó en HF papers el 2023-10-14 y se contribuyó a Hugging Face Transformers el 2026-02-27.

TimesFM 2.5

Resumen

TimesFM 2.5 (Time Series Foundation Model) es un modelo de base preentrenado para series de tiempo propuesto en A decoder-only foundation model for time-series forecasting por Abhimanyu Das, Weihao Kong, Rajat Sen y Yichen Zhou. Se basa en la arquitectura original de TimesFM con atención rotativa, normalización QK, escalado de atención por dimensión y predicción de cuantiles continua.

El resumen del artículo es el siguiente:

Inspirados por los avances recientes en modelos de lenguaje de gran escala para el Procesamiento del Lenguaje Natural (NLP), diseñamos un modelo de base para series temporales de predicción cuyo rendimiento zero-shot, listo para usar, en una variedad de conjuntos de datos públicos se acerca a la precisión de los modelos de predicción supervisados de última generación para cada conjunto de datos individual. Nuestro modelo se basa en el preentrenamiento de un modelo de atención de estilo decodificador con parcheo de entrada, utilizando un gran corpus de series temporales que comprende tanto conjuntos de datos del mundo real como sintéticos. Los experimentos en un conjunto diverso de conjuntos de datos de predicción previamente no vistos sugieren que el modelo puede generar predicciones zero-shot precisas en diferentes dominios, horizontes de predicción y granularidades temporales.

Este modelo fue aportado por kashif. El código original se puede encontrar aquí.

Puedes encontrar el punto de control en google/timesfm-2.5-200m-transformers.

Ejemplo de uso

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

clase 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 )

Parámetros

patch_length (int, opcional, valor predeterminado 32) — La longitud de un parche en la secuencia de entrada.
context_length (int, opcional, valor predeterminado 16384) — La longitud del contexto de entrada.
horizon_length (int, opcional, valor predeterminado 128) — La longitud del horizonte de predicción.
num_hidden_layers (int, opcional, valor predeterminado 20) — Número de capas ocultas en el decodificador del Transformer.
hidden_size (int, opcional, valor predeterminado 1280) — Dimensión de las representaciones ocultas.
intermediate_size (int, opcional, valor predeterminado 1280) — Dimensión de las representaciones del MLP.
head_dim (int, opcional, valor predeterminado 80) — La dimensión de la cabeza de atención. Si es None, se establecerá en hidden_size // num_attention_heads
num_attention_heads (int, opcional, valor predeterminado 16) — Número de cabezas de atención para cada capa de atención en el decodificador Transformer.
rms_norm_eps (float, opcional, valor predeterminado 1e-06) — El epsilon utilizado por las capas de normalización rms.
quantiles (list[float], opcional, valor predeterminado [0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9]) — Los cuantiles a predecir.
attention_dropout (Union[float, int], opcional, valor predeterminado 0.0) — La proporción de dropout para las probabilidades de atención.
initializer_range (float, opcional, valor predeterminado 0.02) — La desviación estándar del truncated_normal_initializer para inicializar todas las matrices de pesos.
num_key_value_heads (int, opcional, valor predeterminado 16) — Este es el número de cabezas key_value que se deben utilizar para implementar Grouped Query Attention. Si num_key_value_heads=num_attention_heads, el modelo utilizará Multi Head Attention (MHA); si num_key_value_heads=1, el modelo utilizará Multi Query Attention (MQA); en caso contrario, se utilizará GQA. Al convertir un checkpoint multi-head en un checkpoint GQA, cada cabeza de clave y valor del grupo debe construirse mediante el promediado (meanpooling) de todas las cabezas originales dentro de ese grupo. Para más detalles, consulta este artículo. Si no se especifica, el valor predeterminado será num_attention_heads.
attention_bias (bool, opcional, valor predeterminado False) — Si se debe usar un sesgo en las capas de proyección de consulta, clave, valor y salida durante la autoatención.
output_quantile_len (int, opcional, valor predeterminado 1024) — Longitud de la dimensión de la proyección de salida de cuantiles.
decode_index (int, opcional, valor predeterminado 5) — Índice en la dimensión de cuantiles utilizado para extraer la predicción de punto (mediana).
use_bias (bool, opcional, valor predeterminado False) — Si se usa sesgo en las capas lineales de MLP y transformer.
activation (str, opcional, valor predeterminado swish) — La función de activación no lineal (función o cadena) en el decodificador. Por ejemplo, "gelu", "relu", "silu", etc.
use_continuous_quantile_head (bool, opcional, valor predeterminado True) — Si se debe utilizar la cabeza de cuantiles continuos para las predicciones de cuantiles no mediana.
force_flip_invariance (bool, opcional, valor predeterminado True) — Si se aplica el promedio de invariancia a la inversión durante la predicción.
infer_is_positive (bool, opcional, valor predeterminado True) — Si se deben limitar las predicciones a valores no negativos cuando el mínimo de la entrada es no negativo.
max_position_embeddings (int, opcional, valor predeterminado 16384) — La longitud máxima de secuencia con la que podría utilizarse este modelo.
rope_parameters (Union[~modeling_rope_utils.RopeParameters, dict], opcional) — Diccionario que contiene los parámetros de configuración para las incrustaciones RoPE. El diccionario debe contener un valor para rope_theta y, opcionalmente, parámetros utilizados para el escalado en caso de que desee usar RoPE con max_position_embeddings más largos.

Esta es la clase de configuración para almacenar la configuración de un TimesFm2_5Model. Se utiliza para instanciar un modelo Timesfm2 5 según los argumentos especificados, definiendo la arquitectura del modelo. Instanciar una configuración con los valores predeterminados producirá una configuración similar a la de google/timesfm-2.5-200m-transformers

Los objetos de configuración heredan de PreTrainedConfig y se pueden usar para controlar las salidas del modelo. Lea la documentación de PreTrainedConfig para obtener más información.

Ejemplo:

>>> from transformers import TimesFm2_5Config, TimesFm2_5ModelForPrediction

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

TimesFm2_5Model

clase transformers.TimesFm2_5Model

< source >

( config: TimesFm2_5Config )

forward

< source >

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

Parámetros

past_values (torch.Tensor de forma (batch_size, sequence_length)) — Valores pasados de la serie temporal utilizados como entrada del modelo.
past_values_padding (torch.LongTensor de forma (batch_size, sequence_length), opcional) — Máscara de relleno para la entrada. 1 indica pasos de tiempo rellenados (enmascarados), 0 indica valores válidos.

Devuelve

TimesFm2_5Output o tuple(torch.Tensor)

Un TimesFm2_5Output o una tupla de torch.Tensor (si se pasa return_dict=False o cuando config.return_dict=False) que comprende varios elementos según la configuración (TimesFm2_5Config) y las entradas.

El método forward de TimesFm2_5Model reemplaza el método especial __call__.

Aunque la receta para la pasada hacia adelante debe definirse dentro de esta función, se debe llamar a la instancia de Module después en lugar de a esta, ya que la primera se encarga de ejecutar los pasos de pre y postprocesamiento, mientras que la segunda los ignora silenciosamente.

last_hidden_state (torch.Tensor de forma (batch_size, sequence_length, hidden_size)) — Secuencia de estados ocultos en la salida de la última capa del modelo.
hidden_states (tuple(torch.Tensor), opcional, devuelto cuando se pasa output_hidden_states=True o cuando config.output_hidden_states=True) — Tupla de torch.Tensor (una para la salida de las incrustaciones, si el modelo tiene una capa de incrustaciones, + una para la salida de cada capa) de forma (batch_size, sequence_length, hidden_size).

Estados ocultos del modelo en la salida de cada capa más las salidas opcionales de la incrustación inicial.
attentions (tuple(torch.Tensor), opcional, se devuelve cuando se pasa output_attentions=True o cuando config.output_attentions=True) — Tupla de torch.Tensor (una por cada capa) de forma (batch_size, num_heads, sequence_length, sequence_length).

Pesos de atención tras el softmax de atención, utilizados para calcular la media ponderada en las cabezas de autoatención.
loc (torch.Tensor de forma (batch_size,) o (batch_size, input_size), opcional) — Desplaza los valores de la ventana de contexto de cada serie temporal, lo que se utiliza para proporcionar al modelo entradas de la misma magnitud y luego se utiliza para desplazar de vuelta a la magnitud original.
scale (torch.Tensor de forma (batch_size,) o (batch_size, input_size), opcional) — Valores de escalado de la ventana de contexto de cada serie temporal, que se utilizan para proporcionar al modelo entradas de la misma magnitud y luego para reescalar de vuelta a la magnitud original.
context_mu (torch.Tensor de forma (batch_size, num_patches)) — Medias móviles calculadas por parche de entrada durante la normalización.
context_sigma (torch.Tensor de forma (batch_size, num_patches)) — Desviaciones estándar móviles calculadas por parche de entrada durante la normalización.

TimesFm2_5ModelForPrediction

clase transformers.TimesFm2_5ModelForPrediction

< source >

( config: TimesFm2_5Config )

Modelo TimesFm2_5 para predicción de cuantiles y media.

forward

< source >

( past_values: Sequencewindow_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)

Parámetros

past_values (collections.abc.Sequence[torch.Tensor]) — Valores pasados de la serie temporal que sirven como entrada al modelo. Cada tensor es una serie temporal unidimensional.
window_size (int, opcional) — Tamaño de la ventana de la descomposición en tendencia + residual. Si es None, no se aplica la descomposición.
future_values (torch.Tensor, opcional) — Valores futuros opcionales utilizados para calcular la pérdida.
forecast_context_len (int, opcional) — Longitud de contexto opcional que se utiliza durante la predicción.
truncate_negative (bool, opcional) — Si se deben limitar las salidas a valores no negativos. Si es None, el valor predeterminado es config.infer_is_positive.
force_flip_invariance (bool, opcional) — Si se debe aplicar la combinación de invariancia por volteo. Si es None, el valor predeterminado es config.force_flip_invariance.

Devuelve

TimesFm2_5OutputForPrediction o tuple(torch.Tensor)

Un TimesFm2_5OutputForPrediction o una tupla de torch.Tensor (si se pasa return_dict=False o cuando config.return_dict=False) que comprende varios elementos según la configuración (TimesFm2_5Config) y las entradas.

El método forward de TimesFm2_5ModelForPrediction reemplaza el método especial __call__.

Aunque la receta para la pasada hacia adelante debe definirse dentro de esta función, se debe llamar a la instancia de Module después en lugar de a esta, ya que la primera se encarga de ejecutar los pasos de pre y postprocesamiento, mientras que la segunda los ignora silenciosamente.

last_hidden_state (torch.Tensor de forma (batch_size, sequence_length, hidden_size)) — Secuencia de estados ocultos en la salida de la última capa del modelo.
hidden_states (tuple(torch.Tensor), opcional, devuelto cuando se pasa output_hidden_states=True o cuando config.output_hidden_states=True) — Tupla de torch.Tensor (una para la salida de las incrustaciones, si el modelo tiene una capa de incrustaciones, + una para la salida de cada capa) de forma (batch_size, sequence_length, hidden_size).

Estados ocultos del modelo en la salida de cada capa más las salidas opcionales de la incrustación inicial.
attentions (tuple(torch.Tensor), opcional, se devuelve cuando se pasa output_attentions=True o cuando config.output_attentions=True) — Tupla de torch.Tensor (una por cada capa) de forma (batch_size, num_heads, sequence_length, sequence_length).

Pesos de atención tras el softmax de atención, utilizados para calcular la media ponderada en las cabezas de autoatención.
mean_predictions (torch.Tensor de forma (batch_size, horizon_length)) — Predicciones deterministas tras la desnormalización.
full_predictions (torch.Tensor de forma (batch_size, horizon_length, quantiles)) — Predicciones de cuantiles que incluyen la mediana después de la desnormalización.
loss (torch.Tensor de forma (1,), opcional, devuelta cuando se proporciona future_values) — Pérdida de entrenamiento que combina las pérdidas MSE y de cuantiles cuando se proporcionan objetivos.

Update on GitHub