timesfm-forecasting

Previsão com TimesFM

Visão Geral

O TimesFM (Time Series Foundation Model) é um modelo fundacional pré-treinado com arquitetura decoder-only desenvolvido pelo Google Research para previsão de séries temporais. Ele funciona zero-shot — basta fornecer qualquer série temporal univariada e ele retorna previsões pontuais com intervalos de predição quantílicos calibrados, sem necessidade de treinamento.

Esta skill encapsula o TimesFM para inferência local segura e amigável para agentes de IA. Ela inclui um verificador de sistema obrigatório que verifica RAM, memória GPU e espaço em disco antes que o modelo seja carregado, garantindo que o agente nunca trave a máquina do usuário.

Números-chave: TimesFM 2.5 usa 200M parâmetros (~800 MB em disco, ~1.5 GB em RAM na CPU, ~1 GB VRAM na GPU). O modelo arquivado v1/v2 com 500M parâmetros precisa de ~32 GB RAM. Execute sempre o verificador de sistema primeiro.

Quando Usar Esta Skill

Use esta skill quando:

• For necessário prever qualquer série temporal univariada (vendas, demanda, sensores, sinais vitais, preços, clima)
• Você precisar de previsão zero-shot sem treinar um modelo personalizado
• Você quiser previsões probabilísticas com intervalos de predição calibrados (quantis)
• Você tiver séries temporais de qualquer comprimento (o modelo lida com 1–16.384 pontos de contexto)
• Você precisar prever centenas ou milhares de séries em lote de forma eficiente
• Você quiser uma abordagem de modelo fundacional em vez de ajustar manualmente parâmetros ARIMA/ETS

Não use esta skill quando:

• Você precisar de modelos estatísticos clássicos com interpretação de coeficientes → use statsmodels
• Você precisar de classificação ou agrupamento de séries temporais → use aeon
• Você precisar de autorregressão vetorial multivariada ou causalidade de Granger → use statsmodels
• Seus dados forem tabulares (não temporais) → use scikit-learn

Nota sobre Detecção de Anomalias: TimesFM não possui detecção de anomalias integrada, mas você pode usar as previsões quantílicas como intervalos de predição — valores fora do IC 90% (q10–q90) são estatisticamente incomuns. Consulte o diretório examples/anomaly-detection/ para um exemplo completo.

⚠️ Verificação Pré-voo Obrigatória: Requisitos de Sistema

CRÍTICO — SEMPRE execute o verificador de sistema antes de carregar o modelo pela primeira vez.

python scripts/check_system.py

Este script verifica:

1. RAM disponível — avisa se abaixo de 4 GB, bloqueia se abaixo de 2 GB
2. Disponibilidade de GPU — detecta dispositivos CUDA/MPS e VRAM
3. Espaço em disco — verifica espaço para o download do modelo de ~800 MB
4. Versão do Python — requer 3.10+
5. Instalação existente — verifica se timesfm e torch estão instalados

Nota: Os pesos do modelo NÃO estão armazenados neste repositório. Os pesos do TimesFM (~800 MB) são baixados sob demanda do HuggingFace no primeiro uso e armazenados em cache em ~/.cache/huggingface/. O verificador de pré-voo garante recursos suficientes antes que qualquer download seja iniciado.

flowchart TD
    accTitle: Verificação de Sistema Pré-voo
    accDescr: Fluxograma de decisão mostrando as verificações de requisitos de sistema que devem ser aprovadas antes de carregar o TimesFM.

    start["🚀 Executar check_system.py"] --> ram{"RAM ≥ 4 GB?"}
    ram -->|"Sim"| gpu{"GPU disponível?"}
    ram -->|"Não (2-4 GB)"| warn_ram["⚠️ Aviso: RAM limitada<br/>Apenas CPU, lotes pequenos"]
    ram -->|"Não (< 2 GB)"| block["🛑 BLOQUEADO<br/>Memória insuficiente"]
    warn_ram --> disk
    gpu -->|"CUDA / MPS"| vram{"VRAM ≥ 2 GB?"}
    gpu -->|"Apenas CPU"| cpu_ok["✅ Modo CPU<br/>Mais lento, mas funciona"]
    vram -->|"Sim"| gpu_ok["✅ Modo GPU<br/>Inferência rápida"]
    vram -->|"Não"| cpu_ok
    gpu_ok --> disk{"Disco ≥ 2 GB livres?"}
    cpu_ok --> disk
    disk -->|"Sim"| ready["✅ PRONTO<br/>Seguro para carregar o modelo"]
    disk -->|"Não"| block_disk["🛑 BLOQUEADO<br/>Espaço necessário para pesos"]

    classDef ok fill:#dcfce7,stroke:#16a34a,stroke-width:2px,color:#14532d
    classDef warn fill:#fef9c3,stroke:#ca8a04,stroke-width:2px,color:#713f12
    classDef block fill:#fee2e2,stroke:#dc2626,stroke-width:2px,color:#7f1d1d
    classDef neutral fill:#f3f4f6,stroke:#6b7280,stroke-width:2px,color:#1f2937

    class ready,gpu_ok,cpu_ok ok
    class warn_ram warn
    class block,block_disk block
    class start,ram,gpu,vram,disk neutral

Requisitos de Hardware por Versão do Modelo

Modelo	Parâmetros	RAM (CPU)	VRAM (GPU)	Disco	Contexto
TimesFM 2.5 (recomendado)	200M	≥ 4 GB	≥ 2 GB	~800 MB	até 16.384
TimesFM 2.0 (arquivado)	500M	≥ 16 GB	≥ 8 GB	~2 GB	até 2.048
TimesFM 1.0 (arquivado)	200M	≥ 8 GB	≥ 4 GB	~800 MB	até 2.048

Recomendação: Sempre use TimesFM 2.5, a menos que você tenha um motivo específico para usar um checkpoint mais antigo. Ele é menor, mais rápido e suporta contexto 8× maior.

🔧 Instalação

Passo 1: Verificar o Sistema (sempre primeiro)

python scripts/check_system.py

Passo 2: Instalar TimesFM

# Usando uv (recomendado por este repositório)
uv pip install timesfm[torch]

# Para backend JAX/Flax (mais rápido em TPU/GPU)
uv pip install timesfm[flax]

Passo 3: Instalar PyTorch para Seu Hardware

# CUDA 12.1 (GPU NVIDIA)
uv pip install torch>=2.0.0 --index-url https://download.pytorch.org/whl/cu121

# Apenas CPU
uv pip install torch>=2.0.0 --index-url https://download.pytorch.org/whl/cpu

# Apple Silicon (MPS)
uv pip install torch>=2.0.0  # Suporte MPS é integrado

Passo 4: Verificar Instalação

import timesfm
import numpy as np
print(f"Versão do TimesFM: {timesfm.__version__}")
print("Instalação OK")

🎯 Início Rápido

Exemplo Mínimo (5 Linhas)

import torch, numpy as np, timesfm

torch.set_float32_matmul_precision("high")

model = timesfm.TimesFM_2p5_200M_torch.from_pretrained(
    "google/timesfm-2.5-200m-pytorch"
)
model.compile(timesfm.ForecastConfig(
    max_context=1024, max_horizon=256, normalize_inputs=True,
    use_continuous_quantile_head=True, force_flip_invariance=True,
    infer_is_positive=True, fix_quantile_crossing=True,
))

point, quantiles = model.forecast(horizon=24, inputs=[
    np.sin(np.linspace(0, 20, 200)),  # qualquer array 1-D
])
# point.shape == (1, 24)        — previsão mediana
# quantiles.shape == (1, 24, 10) — bandas do percentil 10º ao 90º

Previsão a partir de CSV

import pandas as pd, numpy as np

df = pd.read_csv("vendas_mensais.csv", parse_dates=["data"], index_col="data")

# Converter cada coluna em uma lista de arrays
inputs = [df[col].dropna().values.astype(np.float32) for col in df.columns]

point, quantiles = model.forecast(horizon=12, inputs=inputs)

# Construir um DataFrame de resultados
for i, col in enumerate(df.columns):
    last_date = df[col].dropna().index[-1]
    future_dates = pd.date_range(last_date, periods=13, freq="MS")[1:]
    forecast_df = pd.DataFrame({
        "data": future_dates,
        "previsao": point[i],
        "limite_inferior_80": quantiles[i, :, 2],  # percentil 20
        "limite_superior_80": quantiles[i, :, 8],  # percentil 80
    })
    print(f"\n--- {col} ---")
    print(forecast_df.to_string(index=False))

Previsão com Covariáveis (XReg)

TimesFM 2.5+ suporta variáveis exógenas através de forecast_with_covariates(). Requer timesfm[xreg].

# Requer: uv pip install timesfm[xreg]
point, quantiles = model.forecast_with_covariates(
    inputs=inputs,
    dynamic_numerical_covariates={"preco": preco_arrays},
    dynamic_categorical_covariates={"feriado": feriado_arrays},
    static_categorical_covariates={"regiao": rotulos_regiao},
    xreg_mode="xreg + timesfm",  # ou "timesfm + xreg"
)

Tipo de Covariável	Descrição	Exemplo
dynamic_numerical	Numérico variável no tempo	preço, temperatura, gasto promocional
dynamic_categorical	Categórico variável no tempo	indicador de feriado, dia da semana
static_numerical	Numérico por série	tamanho da loja, idade da conta
static_categorical	Categórico por série	tipo de loja, região, categoria de produto

Modos XReg:

• "xreg + timesfm" (padrão): TimesFM prevê primeiro, depois XReg ajusta os resíduos
• "timesfm + xreg": XReg ajusta primeiro, depois TimesFM prevê os resíduos

Consulte examples/covariates-forecasting/ para um exemplo completo com dados sintéticos de varejo.

Detecção de Anomalias (via Intervalos Quantílicos)

TimesFM não possui detecção de anomalias integrada, mas as previsões quantílicas fornecem naturalmente intervalos de predição que podem detectar anomalias:

point, q = model.forecast(horizon=H, inputs=[valores])

# Intervalo de predição de 90%
lower_90 = q[0, :, 1]  # percentil 10
upper_90 = q[0, :, 9]  # percentil 90

# Detectar anomalias: valores fora do IC 90%
actual = test_values  # seus dados de holdout
anomalias = (actual < lower_90) | (actual > upper_90)

# Níveis de gravidade
is_warning = (actual < q[0, :, 2]) | (actual > q[0, :, 8])  # fora do IC 80%
is_critical = anomalias  # fora do IC 90%

Gravidade	Condição	Interpretação
Normal	Dentro do IC 80%	Comportamento esperado
Aviso	Fora do IC 80%	Incomum, mas possível
Crítico	Fora do IC 90%	Estatisticamente raro (< 10% de probabilidade)

Consulte examples/anomaly-detection/ para um exemplo completo com visualização.

# Requer: uv pip install timesfm[xreg]
point, quantiles = model.forecast_with_covariates(
    inputs=inputs,
    dynamic_numerical_covariates={"temperatura": temp_arrays},
    dynamic_categorical_covariates={"dia_da_semana": dow_arrays},
    static_categorical_covariates={"regiao": rotulos_regiao},
    xreg_mode="xreg + timesfm",  # ou "timesfm + xreg"
)

Saída, Configuração, Fluxos de Trabalho e Ajuste

• references/output_and_config.md: leitura da previsão pontual e das 10 bandas de quantis, derivação de intervalos de predição e todos os campos de ForecastConfig.
• references/workflows.md: a sequência padrão de previsão, previsão de múltiplas séries a partir de um CSV amplo e backtesting com cobertura de intervalo.
• references/performance_tuning.md: configuração de GPU e TF32, per_core_batch_size por memória disponível e gerenciamento de memória.
• references/examples_and_validation.md: exemplos executáveis, a lista de verificação de qualidade, erros comuns e verificações de regressão.

🔗 Integração com Outras Skills

Com statsmodels

Use statsmodels para modelos clássicos (ARIMA, SARIMAX) como linha de base de comparação:

# Previsão TimesFM
tfm_point, tfm_q = model.forecast(horizon=H, inputs=[valores])

# Previsão ARIMA do statsmodels
from statsmodels.tsa.arima.model import ARIMA
arima = ARIMA(valores, order=(1,1,1)).fit()
arima_forecast = arima.forecast(steps=H)

# Comparar
print(f"TimesFM MAE: {np.mean(np.abs(actual - tfm_point[0])):.2f}")
print(f"ARIMA MAE:   {np.mean(np.abs(actual - arima_forecast)):.2f}")

Com matplotlib / scientific-visualization

Plote previsões com intervalos de predição como figuras de qualidade para publicação.

Com exploratory-data-analysis

Execute EDA na série temporal antes de prever para entender tendências, sazonalidade e estacionariedade.

📚 Scripts Disponíveis

scripts/check_system.py

Verificador de pré-voo obrigatório. Execute antes do primeiro carregamento do modelo.

python scripts/check_system.py

Exemplo de saída:

=== Verificação de Requisitos de Sistema TimesFM ===

[RAM]       Total: 32.0 GB | Disponível: 24.3 GB  ✅ APROVADO
[GPU]       NVIDIA RTX 4090 | VRAM: 24.0 GB      ✅ APROVADO
[Disco]     Livre: 142.5 GB                        ✅ APROVADO
[Python]    3.12.1                                 ✅ APROVADO
[timesfm]   Instalado (2.5.0)                      ✅ APROVADO
[torch]     Instalado (2.4.1+cu121)                ✅ APROVADO

VEREDITO: ✅ Sistema está pronto para TimesFM 2.5 (modo GPU)
Recomendado: per_core_batch_size=128

scripts/forecast_csv.py

Previsão CSV completa com verificação automática do sistema.

python scripts/forecast_csv.py entrada.csv \
    --horizon 24 \
    --date-col data \
    --value-cols vendas,receita \
    --output previsoes.csv

📖 Documentação de Referência

Guias detalhados em references/:

Arquivo	Conteúdo
references/system_requirements.md	Níveis de hardware, seleção GPU/CPU, fórmulas de estimativa de memória
references/api_reference.md	Documentação completa de ForecastConfig, opções de from_pretrained, formas de saída
references/data_preparation.md	Formatos de entrada, tratamento de NaN, carregamento de CSV, configuração de covariáveis

Armadilhas Comuns

1. Não executar a verificação do sistema → o carregamento do modelo pode travar em máquinas com pouca RAM. Sempre execute check_system.py primeiro.
2. Esquecer de chamar model.compile() → RuntimeError: Model is not compiled. Deve chamar compile() antes de forecast().
3. Não definir normalize_inputs=True → previsões instáveis para séries com valores grandes.
4. Usar v1/v2 em máquinas com < 32 GB RAM → use TimesFM 2.5 (200M params) em vez disso.
5. Não definir fix_quantile_crossing=True → os quantis podem não ser monotônicos (q10 > q50).
6. per_core_batch_size muito grande em GPU pequena → CUDA OOM. Comece pequeno, aumente gradualmente.
7. Passar arrays 2-D → TimesFM espera uma lista de arrays 1-D, não uma matriz 2-D.
8. Esquecer torch.set_float32_matmul_precision("high") → inferência mais lenta em GPUs Ampere+.
9. Não tratar NaN na saída → casos extremos com séries muito curtas. Sempre verifique np.isnan(point).any().
10. Usar infer_is_positive=True para séries que podem ser negativas → fixa as previsões em zero. Defina como False para temperatura, devoluções, etc.

Versões do Modelo

timeline
    accTitle: Histórico de Versões do TimesFM
    accDescr: Linha do tempo dos lançamentos dos modelos TimesFM mostrando contagens de parâmetros e melhorias principais.

    section 2024
        TimesFM 1.0 : 200M params, contexto 2K, apenas JAX
        TimesFM 2.0 : 500M params, contexto 2K, PyTorch + JAX
    section 2025
        TimesFM 2.5 : 200M params, contexto 16K, cabeça quantílica, sem indicador de frequência

Versão	Params	Contexto	Cabeça Quantílica	Flag de Frequência	Status
2.5	200M	16.384	Sim (contínua)	Não	Ativo, recomendado
2.0	500M	2.048	Sim (discreta)	Sim	Arquivado, não recomendado
1.0	200M	2.048	Não	Sim	Arquivado, não recomendado

Consulte references/performance_tuning.md para orientação sobre seleção de versão e migração.