TimesFM Forecasting

Escolha o modelo/API primeiro

A versão do pacote Python é 3.0.2; as versões de checkpoint são separadas.

O upstream identifica 3.0 como o modelo mais recente. Esta habilidade mantém 2.5 como seu fluxo de trabalho local padrão porque seus pesos licenciados pela Apache têm termos de uso diferentes. Para alvos multivariados 3.0, covariáveis apenas do passado ou Apple MLX, leia references/timesfm3.md antes de adaptar o código. Serviços autorizados do Google Cloud têm termos separados; um direito no Cloud não altera a licença dos pesos baixados. Veja o aviso de licença do upstream.

Use o TimesFM para prever um alvo temporal ordenado sem treinamento de modelo específico para a tarefa. Não é um estimador de efeito causal, detector clínico ou modelo climático baseado em física. Zero-shot descreve o ajuste; não estabelece ausência de sobreposição de benchmark no pré-treinamento ou boa precisão em um novo domínio.

Fluxo de Trabalho

1. Estabeleça a cadência, unidades, origem da previsão, horizonte, covariáveis conhecidas na origem, cortes de avaliação e uma linha de base ingênua/sazonal-ingênua.
2. Valide uma grade de tempo ordenada, única e regular. Não dropna() lacunas internas: isso altera o espaçamento temporal. Rejeite entradas não finitas ou impute explicitamente dentro de cada histórico de treinamento. Nunca preencha usando alvos futuros mantidos fora.
3. Execute python scripts/check_system.py antes de baixar/carregar pesos. Seus limites de RAM disponível e volume de cache são heurísticas, não uma garantia contra OOM. Comece com tamanho de lote 1; meça o uso de pico real.
4. Carregue o checkpoint escolhido com uma revisão imutável registrada. Para 2.5, compile configurações explícitas de contexto positivo/horizonte; zero não significa "usar o máximo". Mantenha contexto + horizonte arredondado para patches <=16.384 e horizonte <=1.024 ao usar a cabeça de quantil contínua.
5. Preveja, valide formas/valores finitos/ordem de quantil e exporte a origem da previsão, frequência, configuração e revisão do checkpoint.
6. Avalie em origens rolantes com pré-processamento ajustado independentemente por origem. Relate precisão, cobertura de intervalo e largura de intervalo por horizonte; rotule os intervalos de quantil como nominais até que sejam calibrados em dados relevantes.

Instalação

Execute em um ambiente separado. Os comandos abaixo visam a versão revisada. Extras de shell e restrições de versão devem ser citados, particularmente em zsh.

uv venv .venv-timesfm
uv pip install --python .venv-timesfm/bin/python "timesfm[torch]==3.0.2" numpy pandas
.venv-timesfm/bin/python scripts/check_system.py

Use o seletor de instalação PyTorch atual para uma roda CUDA que corresponda ao host. O carregador 2.5 nesta versão escolhe cuda:0 se CUDA existir, caso contrário, CPU; detectar MPS não habilita a inferência MPS. Não use model.to(...) no wrapper como se fosse um nn.Module. Para XReg apenas CPU, instale jax e scikit-learn junto com o perfil PyTorch; o extra [xreg] do upstream solicita jax[cuda], o que não é apropriado para macOS. Flax é um backend opcional separado; não é exigido pelos scripts empacotados.

from importlib.metadata import version
import timesfm
print(version("timesfm"))  # package has no guaranteed timesfm.__version__
assert hasattr(timesfm, "TimesFM_2p5_200M_torch")

TimesFM 2.5 início rápido

Os exemplos de carregamento de checkpoint são ilustrativos: a validação desta atualização usou código de pacote nativo com modelos aleatórios minúsculos e fixtures de decodificação controladas, sem baixar pesos pré-treinados. Isso verifica a mecânica, não a precisão.

import numpy as np
import timesfm

model = timesfm.TimesFM_2p5_200M_torch.from_pretrained(
    "google/timesfm-2.5-200m-pytorch",
    revision="1d952420fba87f3c6dee4f240de0f1a0fbc790e3",
    torch_compile=False,  # evitar o início da compilação durante uma execução inicial de fumaça
)
model.compile(timesfm.ForecastConfig(
    max_context=512, max_horizon=128, per_core_batch_size=1,
    normalize_inputs=True, use_continuous_quantile_head=True,

…