Este modelo foi publicado no HF papers em 2023-10-14 e contribuído para o Hugging Face Transformers em 2026-02-27.

TimesFM 2.5

Visão geral

TimesFM 2.5 (Time Series Foundation Model) é um modelo de fundação pré-treinado para séries temporais proposto em A decoder-only foundation model for time-series forecasting por Abhimanyu Das, Weihao Kong, Rajat Sen e Yichen Zhou. Ele se baseia na arquitetura original do TimesFM, com atenção rotativa, normalização QK, escalonamento de atenção por dimensão e previsão contínua de quantis.

O resumo do artigo é o seguinte:

Inspirados pelos avanços recentes em modelos de linguagem de grande escala para Processamento de Linguagem Natural (NLP), projetamos um modelo de fundação para séries temporais voltado à previsão, cujo desempenho zero-shot pronto para uso em uma variedade de conjuntos de dados públicos se aproxima da precisão dos modelos de previsão supervisionados de estado da arte para cada conjunto de dados individual. Nosso modelo é baseado no pré-treinamento de um modelo de atenção em estilo decodificador com patching de entrada, utilizando um grande corpus de séries temporais que inclui conjuntos de dados tanto do mundo real quanto sintéticos. Experimentos em um conjunto diversificado de conjuntos de dados de previsão anteriormente não vistos sugerem que o modelo pode gerar previsões zero-shot precisas em diferentes domínios, horizontes de previsão e granularidades temporais.

Este modelo foi contribuído por kashif. O código original pode ser encontrado aqui.

Você pode encontrar o checkpoint em google/timesfm-2.5-200m-transformers.

Exemplo 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

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 )

Parâmetros

patch_length (int, opcional, padrão 32) — O comprimento de um patch na sequência de entrada.
context_length (int, opcional, padrão 16384) — O comprimento do contexto de entrada.
horizon_length (int, opcional, padrão 128) — O comprimento do horizonte de previsão.
num_hidden_layers (int, opcional, padrão 20) — Número de camadas ocultas no decodificador do Transformer.
hidden_size (int, opcional, padrão 1280) — Dimensão das representações ocultas.
intermediate_size (int, opcional, padrão 1280) — Dimensão das representações do MLP.
head_dim (int, opcional, padrão 80) — A dimensão da cabeça de atenção. Se for None, o valor padrão será hidden_size // num_attention_heads
num_attention_heads (int, opcional, padrão 16) — Número de cabeças de atenção para cada camada de atenção no decodificador do Transformer.
rms_norm_eps (float, opcional, padrão 1e-06) — O epsilon usado pelas camadas de normalização rms.
quantiles (list[float], opcional, padrão [0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9]) — Os quantis a prever.
attention_dropout (Union[float, int], opcional, padrão 0.0) — A taxa de dropout para as probabilidades de atenção.
initializer_range (float, opcional, padrão 0.02) — O desvio padrão do truncated_normal_initializer para inicializar todas as matrizes de pesos.
num_key_value_heads (int, opcional, padrão 16) — Este é o número de cabeças de key_value que devem ser usadas para implementar Grouped Query Attention. Se num_key_value_heads=num_attention_heads, o modelo usará Multi Head Attention (MHA); se num_key_value_heads=1, o modelo usará Multi Query Attention (MQA); caso contrário, será usado GQA. Ao converter um checkpoint multi-head para um checkpoint GQA, cada grupo de cabeças de key e value deve ser construído por meio do meanpooling de todas as cabeças originais dentro desse grupo. Para mais detalhes, consulte este artigo. Se não for especificado, o valor padrão será num_attention_heads.
attention_bias (bool, opcional, padrão False) — Indica se deve ser usado um viés nas camadas de projeção de query, key, value e output durante a autoatenção.
output_quantile_len (int, opcional, padrão 1024) — Comprimento da dimensão da projeção de saída do quantil.
decode_index (int, opcional, padrão 5) — Índice na dimensão de quantil usado para extrair a previsão pontual (mediana).
use_bias (bool, opcional, padrão False) — Se deve usar viés nas camadas lineares do MLP e do transformer.
activation (str, opcional, padrão swish) — A função de ativação não linear (função ou string) no decodificador. Por exemplo, "gelu", "relu", "silu", etc.
use_continuous_quantile_head (bool, opcional, padrão True) — Se deve usar a cabeça de quantil contínuo para previsões de quantis não mediana.
force_flip_invariance (bool, opcional, padrão True) — Se deve aplicar a média de invariância a flip durante a previsão.
infer_is_positive (bool, opcional, padrão True) — Se deve limitar as previsões a valores não negativos quando o mínimo da entrada for não negativo.
max_position_embeddings (int, opcional, padrão 16384) — O comprimento máximo de sequência com o qual este modelo pode ser utilizado.
rope_parameters (Union[~modeling_rope_utils.RopeParameters, dict], opcional) — Dicionário contendo os parâmetros de configuração para os embeddings RoPE. O dicionário deve conter um valor para rope_theta e, opcionalmente, parâmetros usados para escalonamento, caso você queira usar RoPE com max_position_embeddings maiores.

Esta é a classe de configuração para armazenar a configuração de um TimesFm2_5Model. Ela é usada para instanciar um modelo Timesfm2 5 de acordo com os argumentos especificados, definindo a arquitetura do modelo. Instanciar uma configuração com os padrões resultará em uma configuração semelhante à do google/timesfm-2.5-200m-transformers

Os objetos de configuração herdam de PreTrainedConfig e podem ser usados para controlar as saídas do modelo. Consulte a documentação de PreTrainedConfig para mais informações.

Exemplo:

>>> from transformers import TimesFm2_5Config, TimesFm2_5ModelForPrediction

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

TimesFm2_5Model

classe 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 passados da série temporal usados como entrada para o modelo.
past_values_padding (torch.LongTensor de forma (batch_size, sequence_length), opcional) — Máscara de preenchimento para a entrada. 1 indica passos de tempo preenchidos (mascarados), 0 indica valores válidos.

Retorna

TimesFm2_5Output ou tuple(torch.Tensor)

Um TimesFm2_5Output ou uma tupla de torch.Tensor (se return_dict=False for passado ou quando config.return_dict=False) contendo vários elementos, dependendo da configuração (TimesFm2_5Config) e das entradas.

O método forward do TimesFm2_5Model substitui o método especial __call__.

Embora a receita para a passagem direta precise ser definida dentro desta função, deve-se chamar a instância de Module em seguida, em vez desta, pois a primeira cuida da execução das etapas de pré e pós-processamento, enquanto a segunda as ignora silenciosamente.

last_hidden_state (torch.Tensor de forma (batch_size, sequence_length, hidden_size)) — Sequência de estados ocultos na saída da última camada do modelo.
hidden_states (tuple(torch.Tensor), opcional, retornado quando output_hidden_states=True é passado ou quando config.output_hidden_states=True) — Tupla de torch.Tensor (um para a saída dos embeddings, se o modelo tiver uma camada de embedding, + um para a saída de cada camada) de forma (batch_size, sequence_length, hidden_size).

Estados ocultos do modelo na saída de cada camada, além das saídas opcionais do embedding inicial.
attentions (tuple(torch.Tensor), opcional, retornado quando output_attentions=True é passado ou quando config.output_attentions=True) — Tupla de torch.Tensor (um para cada camada) com forma (batch_size, num_heads, sequence_length, sequence_length).

Pesos de atenção após o softmax de atenção, usados para calcular a média ponderada nos cabeçalhos de autoatenção.
loc (torch.Tensor de forma (batch_size,) ou (batch_size, input_size), opcional) — Desloca os valores da janela de contexto de cada série temporal, o que é usado para fornecer ao modelo entradas da mesma magnitude e, em seguida, para desfazer o deslocamento e retornar à magnitude original.
scale (torch.Tensor de forma (batch_size,) ou (batch_size, input_size), opcional) — Valores de escala da janela de contexto de cada série temporal, usados para fornecer ao modelo entradas da mesma magnitude e, em seguida, para reescalar de volta à magnitude original.
context_mu (torch.Tensor de forma (batch_size, num_patches)) — Médias em execução calculadas por patch de entrada durante a normalização.
context_sigma (torch.Tensor de forma (batch_size, num_patches)) — Desvios padrão calculados por patch de entrada durante a normalização.

TimesFm2_5ModelForPrediction

classe transformers.TimesFm2_5ModelForPrediction

< source >

( config: TimesFm2_5Config )

Modelo TimesFm2_5 para previsão de quantis e média.

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 passados da série temporal que servem como entrada para o modelo. Cada tensor é uma série temporal unidimensional.
window_size (int, opcional) — Tamanho da janela para a decomposição em tendência + resíduo. Se None, a decomposição não é aplicada.
future_values (torch.Tensor, opcional) — Valores futuros opcionais usados para calcular a perda.
forecast_context_len (int, opcional) — Substituição opcional do comprimento do contexto usado durante a previsão.
truncate_negative (bool, opcional) — Se deve limitar as saídas a valores não negativos. Se None, o valor padrão é config.infer_is_positive.
force_flip_invariance (bool, opcional) — Se deve aplicar a combinação de invariância por inversão. Se None, o valor padrão é config.force_flip_invariance.

Retorna

TimesFm2_5OutputForPrediction ou tuple(torch.Tensor)

Um TimesFm2_5OutputForPrediction ou uma tupla de torch.Tensor (se return_dict=False for passado ou quando config.return_dict=False) contendo vários elementos, dependendo da configuração (TimesFm2_5Config) e das entradas.

O método forward do TimesFm2_5ModelForPrediction substitui o método especial __call__.

Embora a receita para a passagem direta precise ser definida dentro desta função, deve-se chamar a instância de Module em seguida, em vez desta, pois a primeira cuida da execução das etapas de pré e pós-processamento, enquanto a segunda as ignora silenciosamente.

last_hidden_state (torch.Tensor de forma (batch_size, sequence_length, hidden_size)) — Sequência de estados ocultos na saída da última camada do modelo.
hidden_states (tuple(torch.Tensor), opcional, retornado quando output_hidden_states=True é passado ou quando config.output_hidden_states=True) — Tupla de torch.Tensor (um para a saída dos embeddings, se o modelo tiver uma camada de embedding, + um para a saída de cada camada) de forma (batch_size, sequence_length, hidden_size).

Estados ocultos do modelo na saída de cada camada, além das saídas opcionais do embedding inicial.
attentions (tuple(torch.Tensor), opcional, retornado quando output_attentions=True é passado ou quando config.output_attentions=True) — Tupla de torch.Tensor (um para cada camada) com forma (batch_size, num_heads, sequence_length, sequence_length).

Pesos de atenção após o softmax de atenção, usados para calcular a média ponderada nos cabeçalhos de autoatenção.
mean_predictions (torch.Tensor de forma (batch_size, horizon_length)) — Previsões determinísticas após a desnornormalização.
full_predictions (torch.Tensor de forma (batch_size, horizon_length, quantiles)) — Previsões de quantis incluindo a mediana após a desnornalização.
loss (torch.Tensor de forma (1,), opcional, retornado quando future_values é fornecido) — Perda de treinamento que combina as perdas MSE e quantil quando os alvos são fornecidos.

Update on GitHub