TimesFM 2.5: Previsão de Séries Temporais com Zero-Shot, Covariáveis e Detecção de Anomalias

Por que o TimesFM 2.5 importa agora?

Em agosto de 2026, fazer previsões de séries temporais com qualidade profissional está ao alcance de qualquer pessoa com um notebook e conexão à internet. O TimesFM 2.5, modelo de forecasting do Google Research, traz previsão probabilística com quantis, integração de covariáveis externas e detecção de anomalias — tudo em um pacote de ~200 milhões de parâmetros que roda no Google Colab gratuito. Há dois anos, você precisaria de um cluster Spark e um time de dados dedicado. Hoje, pip install timesfm resolve.

O que é o TimesFM 2.5

O TimesFM 2.5 (Time Series Foundation Model) é um modelo fundacional para séries temporais desenvolvido pelo Google Research. Diferente de modelos tradicionais como ARIMA ou Prophet, que precisam ser treinados do zero para cada série, o TimesFM funciona em modo zero-shot: você fornece o histórico e ele gera previsões imediatas, sem treinamento por série. A versão 2.5 adiciona cabeçalho de quantis contínuos, correção de cruzamento de quantis e suporte a covariáveis dinâmicas via XReg.

✅ O que você ganha

• Zero-shot imediato: Sem treinamento por série — alimente o histórico e receba previsões em segundos
• Previsão probabilística: 10 quantis (q10 a q90) mais a média, permitindo intervalos de confiança e análise de risco
• Covariáveis externas (XReg): Incorpore preço, temperatura, feriados, promoções e features categóricas no forecast
• Detecção de anomalias integrada: Compare valores observados contra intervalos de previsão para alertas automáticos
• Escalável: Processamento em batch de dezenas de séries simultaneamente com throughput ajustável
• Open source: Apache 2.0, roda em CPU e GPU, disponível no Hugging Face

⚠️ O que você NÃO ganha

• Não substitui modelos treinados em domínio específico: Em séries muito idiossincráticas (dados de sensores industriais com padrões atípicos), um modelo fine-tunado ainda pode superar o zero-shot
• Não lida com frequências irregulares: O TimesFM espera séries igualmente espaçadas (diárias, semanais, horárias)
• Contexto limitado a 1024 pontos: Séries com múltiplos anos de dados diários precisam de janelamento

Tabela de requisitos

Passo a passo: pipeline completo de forecasting

1. Instalação e configuração do ambiente

O primeiro passo é instalar o pacote timesfm com suporte a PyTorch e preparar o ambiente:

# Instalação única — o pacote inclui o modelo e dependências
pip install timesfm[torch]

import timesfm
import numpy as np
import pandas as pd
import torch
import matplotlib.pyplot as plt

# Configurar seeds para reprodutibilidade
np.random.seed(7)
torch.manual_seed(7)
torch.set_float32_matmul_precision("high")

# Detectar dispositivo
DEVICE = "cuda" if torch.cuda.is_available() else "cpu"
print(f"Dispositivo: {DEVICE}")

Por que isso importa: O TimesFM 2.5 usa torch.set_float32_matmul_precision("high") para ativar kernels otimizados da NVIDIA — em GPU, isso pode dobrar o throughput de inferência. Se estiver no Colab, ative o runtime GPU em “Ambiente de execução → Alterar tipo de ambiente”.

2. Gerando um dataset de varejo realista

O tutorial gera dados sintéticos de 6 lojas com 1.200 dias de vendas, incluindo tendência, sazonalidade semanal e anual, elasticidade de preço, lift de promoções e efeito de temperatura:

N_DAYS = 1200
N_STORES = 6

# Para cada loja, geramos:
# - Nível base com tendência linear
# - Sazonalidade semanal (dias da semana)
# - Sazonalidade anual (senoide)
# - Elasticidade-preço (vendas caem quando preço sobe)
# - Lift promocional (vendas sobem em promoções)
# - Efeito de feriados (+55 unidades em feriados)
# - Efeito de temperatura
# - Ruído aleatório

Verificação intermediária: Execute df.head() e confirme que as colunas são date, store, region, sales, price, promo, holiday, dow, temp. Você deve ver ~7.200 linhas (6 lojas × 1.200 dias).

3. Carregando o modelo e fazendo a primeira previsão zero-shot

model = timesfm.TimesFM_2p5_200M_torch.from_pretrained(
    "google/timesfm-2.5-200m-pytorch"
)

# Configuração base: até 1024 pontos de contexto, até 256 de horizonte
model.compile(timesfm.ForecastConfig(
    max_context=1024,
    max_horizon=256,
    normalize_inputs=True,
    use_continuous_quantile_head=True,
    fix_quantile_crossing=True,
))

# Previsão zero-shot para 56 dias
HORIZON = 56
point, quant = model.forecast(horizon=HORIZON, inputs=[train])
# point.shape = (1, 56) — previsão pontual (mediana)
# quant.shape = (1, 56, 10) — 10 quantis: q10, q20, ..., q90

Por que fix_quantile_crossing=True: Em horizontes longos, os quantis podem se cruzar (q90 ficar menor que q50, por exemplo). Esse flag garante monotonicidade — os quantis são sempre ordenados.

4. Métricas de avaliação e comparação com baselines

O tutorial calcula MAE, RMSE, MAPE, sMAPE, MASE e cobertura de intervalo de previsão, comparando o TimesFM contra baselines simples como naive sazonal e último valor:

# MASE (Mean Absolute Scaled Error) — a métrica mais robusta
# MASE < 1: modelo melhor que naive
# MASE > 1: modelo pior que naive

# No teste com 6 lojas e 56 dias de horizonte:
# TimesFM: MASE ≈ 0.45
# SNaive:  MASE = 1.0 (baseline)
# Redução de 55% no erro em relação ao naive sazonal

5. Backtesting com janela deslizante (rolling-origin)

Em vez de avaliar em apenas uma janela de holdout (o que pode ser enganoso), o backtesting avalia o modelo em múltiplas origens históricas:

# 6 folds × 56 dias × 6 séries = 36 avaliações independentes
# Cada fold caminha 56 dias para trás no tempo
# Resultado: MASE consistente entre 0.35 e 0.55 em todos os folds

Por que isso importa: Um MASE estável entre folds diferentes indica que o modelo não está sobre-ajustado a um período específico. Se o MASE variasse de 0.3 a 1.5 entre folds, você saberia que o modelo só funciona bem em certas condições.

6. Integração de covariáveis com XReg

O grande diferencial do TimesFM 2.5 é a capacidade de incorporar covariáveis externas conhecidas no futuro — como preços planejados, calendário de promoções e previsão de temperatura:

# Dois modos de fusão:
# "xreg + timesfm": covariáveis processadas primeiro, depois o modelo
# "timesfm + xreg": modelo processa a série, depois covariáveis refinam

dynamic_numerical = {"price": [...], "temp": [...]}
dynamic_categorical = {"promo": [...], "holiday": [...], "dow": [...]}
static_categorical = {"region": [...], "store": [...]}

point, quant = model.forecast_with_covariates(
    inputs=series,
    dynamic_numerical_covariates=dynamic_numerical,
    dynamic_categorical_covariates=dynamic_categorical,
    static_categorical_covariates=static_categorical,
)

Na prática: Se você sabe que vai fazer uma promoção daqui a 3 semanas, pode informar isso como covariável futura e o modelo ajusta a previsão de vendas para cima naquele período específico.

7. Detecção de anomalias com intervalos de previsão

Este é um dos usos mais práticos do TimesFM 2.5: comparar valores observados contra os intervalos de previsão e disparar alertas:

# Para cada ponto no horizonte de detecção:
# - Se valor real < q10 ou > q90 → "WARNING"
# - Se valor real < (q10 - 1.5×IQR) ou > (q90 + 1.5×IQR) → "CRITICAL"

# O tutorial injeta anomalias artificiais (spikes, quedas)
# e o detector captura ~100% dos eventos com severidade apropriada

Caso de uso real: Monitoramento de vendas diárias de e-commerce. Se as vendas de um produto caírem abaixo do q10 previsto por 3 dias consecutivos, dispare um alerta para a equipe de merchandising verificar ruptura de estoque.

8. Throughput e robustez

O tutorial testa o modelo em condições adversas:

• Throughput: 48 séries processadas em lote — de 1.2 a 8.5 séries/segundo dependendo do batch size
• NaN no input: O modelo lida com valores ausentes no início e no meio da série, produzindo forecasts finitos
• Contexto curto: Com apenas 32 pontos históricos (1 mês diário), o MASE ainda fica abaixo de 0.9
• Clipping de valores negativos: Com infer_is_positive=True, forecasts nunca ficam abaixo de zero

Casos de uso reais

1. Previsão de demanda no varejo: 500+ SKUs, previsão diária com horizonte de 8 semanas, incorporando calendário promocional como covariável
2. Detecção de anomalias em operações: Monitoramento de 200+ métricas de infraestrutura (CPU, latência, erros) com alertas baseados em quantis
3. Planejamento de capacidade: Previsão de tráfego para alocação dinâmica de recursos em nuvem com 12 semanas de antecedência
4. Forecasting financeiro: Projeção de receita trimestral com intervalos de confiança para apresentação ao conselho
5. Supply chain: Previsão de lead time de fornecedores integrada a dados de frete e clima como covariáveis externas

Tabela comparativa: TimesFM 2.5 vs alternativas

Troubleshooting

• ❌ Sintoma:ImportError: No module named 'timesfm'
  → Causa: Instalação não concluída ou ambiente virtual não ativado
  → Solução: Execute pip install timesfm[torch] --upgrade e verifique com pip show timesfm
• ❌ Sintoma:CUDA out of memory ao carregar o modelo
  → Causa: GPU com menos de 4 GB de VRAM
  → Solução: Force CPU com import os; os.environ["CUDA_VISIBLE_DEVICES"]="" ou use per_core_batch_size=1
• ❌ Sintoma: Previsões idênticas para todas as séries
  → Causa:normalize_inputs não está funcionando — possível bug com série de comprimento diferente
  → Solução: Verifique que todos os inputs têm o mesmo comprimento ou normalize manualmente com (series - mean) / std
• ❌ Sintoma: Quantis cruzados (q90 menor que q50)
  → Causa:fix_quantile_crossing=False ou horizonte muito longo (>256)
  → Solução: Ative fix_quantile_crossing=True e reduza max_horizon
• ❌ Sintoma:ValueError ao usar XReg com séries de comprimentos diferentes
  → Causa: As covariáveis precisam cobrir contexto + horizonte para cada série
  → Solução: Verifique que o comprimento das covariáveis é len(contexto) + horizonte para cada série no batch

FAQ

P: Preciso de GPU para usar o TimesFM 2.5?
Não. O modelo roda em CPU e é perfeitamente utilizável para previsões de algumas dezenas de séries. A GPU acelera o processamento em batch (48+ séries simultâneas) e reduz o tempo de 45 para ~8 segundos.

P: Posso fazer fine-tuning com meus dados?
Sim. O modelo é um checkpoint PyTorch padrão e pode ser fine-tunado com seus dados. Mas o ponto forte do TimesFM é o zero-shot — na maioria dos casos, o ganho do fine-tuning não justifica o custo computacional.

P: Qual a frequência mínima suportada?
O modelo não impõe frequência — você pode usar dados horários, diários, semanais ou mensais. O que importa é que a série seja igualmente espaçada e que a sazonalidade capturável caiba na janela de contexto (1024 pontos).

P: TimesFM substitui o Prophet?
Para forecasting em escala (múltiplas séries), sim. Para uma única série com forte componente de sazonalidade anual e feriados personalizados, o Prophet ainda pode ser mais interpretável e fácil de ajustar manualmente.

P: Como exporto as previsões para produção?
O tutorial inclui exportação para CSV e JSON. Para produção, você pode serializar o modelo com torch.save() e servir via FastAPI ou Flask com inferência em batch.

O futuro do forecasting zero-shot

O TimesFM 2.5 representa um ponto de inflexão: forecasting de qualidade profissional está se tornando uma commodity acessível. Em 2027, a tendência é que modelos fundacionais de séries temporais se tornem o padrão para 80% dos casos de uso, com modelos especializados reservados para domínios de nicho (finanças de alta frequência, sensores IoT com padrões físicos específicos). O Google já sinalizou que versões futuras trarão suporte a frequências múltiplas (horário + diário + semanal no mesmo modelo) e fine-tuning com LoRA. Para o profissional de dados brasileiro, este é o momento de migrar de ARIMA/Prophet para TimesFM — a redução de código e o ganho de acurácia são significativos demais para ignorar.