Este modelo se publicó en HF papers el 2023-10-14 y se contribuyó a Hugging Face Transformers el 2025-04-16.

TimesFM

Resumen

TimesFM (Time Series Foundation Model) es un modelo de base preentrenado para series temporales propuesto en A decoder-only foundation model for time-series forecasting por Abhimanyu Das, Weihao Kong, Rajat Sen y Yichen Zhou. Es un modelo solo decodificador que utiliza como entrada parches no superpuestos de datos de series temporales y genera una predicción de longitud de parche de salida de manera autorregresiva.

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 parches en un gran corpus de series temporales, y puede funcionar bien a través de diferentes longitudes de historial de predicción, longitudes de predicción y granularidades temporales.

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

Para usar el modelo:

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

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

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 512) — La longitud del contexto de entrada.
horizon_length (int, opcional, valor predeterminado 128) — La longitud del horizonte de predicción.
freq_size (int, opcional, valor predeterminado 3) — El número de incrustaciones de frecuencia.
num_hidden_layers (int, opcional, valor predeterminado 50) — 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.
tolerance (float, opcional, valor predeterminado 1e-06) — La tolerancia para la pérdida de cuantiles.
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.
pad_val (float, opcional, valor predeterminado 1123581321.0) — El valor utilizado para rellenar las predicciones.
attention_dropout (float, opcional, valor predeterminado 0.0) — La probabilidad de dropout para las puntuaciones de atención.
use_positional_embedding (bool, opcional, valor predeterminado False) — Si se deben añadir embeddings posicionales.
initializer_range (float, opcional, valor predeterminado 0.02) — La desviación estándar del truncated_normal_initializer para inicializar todas las matrices de pesos.
min_timescale (int, opcional, valor predeterminado 1) — El inicio del índice posicional geométrico. Determina la periodicidad de la señal añadida.
max_timescale (int, opcional, valor predeterminado 10000) — El final del índice posicional geométrico. Determina la frecuencia de la señal añadida.

Esta es la clase de configuración para almacenar la configuración de un TimesFmModel. Se utiliza para instanciar un modelo Timesfm 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.0-500m-pytorch

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.

TimesFmModel

clase transformers.TimesFmModel

< source >

( config: TimesFmConfig )

Parámetros

config (TimesFmConfig) — Clase de configuración del modelo con todos los parámetros del modelo. Inicializar con un archivo de configuración no carga los pesos asociados con el modelo, solo la configuración. Consulte el método from_pretrained() para cargar los pesos del modelo.

El modelo Timesfm básico que emite estados ocultos sin ningún cabezal específico en la parte superior.

Este modelo hereda de PreTrainedModel. Consulta la documentación de la clase superior para los métodos genéricos que la biblioteca implementa para todos sus modelos (como la descarga o el guardado, el redimensionamiento de las incrustaciones de entrada, la poda de cabezas, etc.).

Este modelo también es una subclase de torch.nn.Module de PyTorch. Úsalo como un módulo de PyTorch regular y consulta la documentación de PyTorch para todo lo relacionado con el uso y el comportamiento generales.

forward

< source >

( past_values: Tensorpast_values_padding: LongTensorfreq: Tensor**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → TimesFmOutput or tuple(torch.Tensor)

Parámetros

past_values (torch.Tensor de forma (batch_size, sequence_length)) — Valores pasados de la serie temporal que sirven como entrada para el modelo.
past_values_padding (torch.LongTensor de forma (batch_size, sequence_length)) — El indicador de relleno de la serie temporal.
freq (torch.LongTensor de forma (batch_size,)) — Índices de frecuencia para los datos de la serie temporal.

Devuelve

TimesFmOutput o tuple(torch.Tensor)

Un TimesFmOutput 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 (TimesFmConfig) y las entradas.

El método forward de TimesFmModel 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, )) — La media de las entradas de la serie temporal.
scale (torch.Tensor de forma (batch_size,)) — La escala de las entradas de la serie temporal.

TimesFmModelForPrediction

clase transformers.TimesFmModelForPrediction

< source >

( config: TimesFmConfig )

Modelo TimesFM para predicción de cuantiles y media.

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)

Parámetros

past_values (torch.Tensor de forma (batch_size, sequence_length)) — Valores pasados de la serie temporal que sirven como entrada para el modelo.
freq (torch.LongTensor de forma (batch_size,)) — Índices de frecuencia para los datos de la serie temporal.
window_size (int, opcional) — Tamaño de la ventana de la descomposición en tendencia + residuo. Si es None, no se realiza la descomposición.
future_values (torch.Tensor, opcional) — Valores de la serie temporal futura opcionales que se utilizarán para el cálculo de la pérdida.
forecast_context_len (int, opcional) — Longitud de contexto máxima opcional.
return_forecast_on_context (bool, opcional) — True para devolver la predicción en el contexto cuando está disponible, es decir, después del primer parche de entrada.
truncate_negative (bool, opcional) — Trunca a solo valores no negativos si alguno de los contextos tiene valores no negativos; en caso contrario, no hace nada.

Devuelve

TimesFmOutputForPrediction o tuple(torch.Tensor)

Un TimesFmOutputForPrediction 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 (TimesFmConfig) y las entradas.

El método forward de TimesFmModelForPrediction 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, sequence_length)) — Las predicciones medias de la serie temporal.
full_predictions (torch.Tensor de forma (batch_size, sequence_length)) — Las predicciones completas de la serie temporal, incluyendo la media y los cuantiles.
loss (torch.Tensor de forma (1,), opcional, se devuelve cuando se proporciona future_values) — La pérdida del modelo TimesFM.

Ejemplo:

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