timesfm-forecasting

TimesFM Forecasting

Descripción general

TimesFM (Time Series Foundation Model) es un modelo fundacional decoder-only preentrenado desarrollado por Google Research para pronósticos de series temporales. Funciona zero-shot — introdúcele cualquier serie temporal univariada y devuelve pronósticos puntuales con intervalos de predicción de cuantiles calibrados, sin necesidad de entrenamiento.

Esta skill envuelve TimesFM para una inferencia local segura y fácil para agentes. Incluye un verificador de requisitos del sistema obligatorio que comprueba RAM, memoria GPU y espacio en disco antes de que el modelo se cargue, para que el agente nunca bloquee la máquina del usuario.

Números clave: TimesFM 2.5 usa 200M parámetros (~800 MB en disco, ~1.5 GB en RAM en CPU, ~1 GB VRAM en GPU). El modelo archivado v1/v2 de 500M parámetros necesita ~32 GB RAM. Ejecuta siempre el verificador de sistema primero.

Cuándo usar esta skill

Usa esta skill cuando:

• Pronostiques cualquier serie temporal univariada (ventas, demanda, sensores, signos vitales, precio, clima)
• Necesites pronóstico zero-shot sin entrenar un modelo personalizado
• Quieras pronósticos probabilísticos con intervalos de predicción calibrados (cuantiles)
• Tengas series temporales de cualquier longitud (el modelo maneja 1–16,384 puntos de contexto)
• Necesites pronosticar en lote cientos o miles de series de manera eficiente
• Quieras un enfoque de modelo fundacional en lugar de ajustar manualmente parámetros ARIMA/ETS

No uses esta skill cuando:

• Necesites modelos estadísticos clásicos con interpretación de coeficientes → usa statsmodels
• Necesites clasificación o agrupamiento de series temporales → usa aeon
• Necesites autorregresión vectorial multivariada o causalidad de Granger → usa statsmodels
• Tus datos sean tabulares (no temporales) → usa scikit-learn

Nota sobre detección de anomalías: TimesFM no tiene detección de anomalías incorporada, pero puedes usar los pronósticos de cuantiles como intervalos de predicción — los valores fuera del IC del 90% (q10–q90) son estadísticamente inusuales. Consulta el directorio examples/anomaly-detection/ para un ejemplo completo.

⚠️ Verificación previa obligatoria: comprobación de requisitos del sistema

CRÍTICO — SIEMPRE ejecuta el verificador de sistema antes de cargar el modelo por primera vez.

python scripts/check_system.py

Este script comprueba:

1. RAM disponible — advierte si está por debajo de 4 GB, bloquea si está por debajo de 2 GB
2. Disponibilidad de GPU — detecta dispositivos CUDA/MPS y VRAM
3. Espacio en disco — verifica espacio para la descarga del modelo de ~800 MB
4. Versión de Python — requiere 3.10+
5. Instalación existente — comprueba si timesfm y torch están instalados

Nota: Los pesos del modelo NO se almacenan en este repositorio. Los pesos de TimesFM (~800 MB) se descargan bajo demanda desde HuggingFace en el primer uso y se almacenan en caché en ~/.cache/huggingface/. El verificador previo asegura recursos suficientes antes de que comience cualquier descarga.

flowchart TD
    accTitle: Verificación previa del sistema
    accDescr: Diagrama de flujo de decisión que muestra las comprobaciones de requisitos del sistema que deben pasar antes de cargar TimesFM.

    start["🚀 Ejecutar check_system.py"] --> ram{"¿RAM ≥ 4 GB?"}
    ram -->|"Sí"| gpu{"¿GPU disponible?"}
    ram -->|"No (2-4 GB)"| warn_ram["⚠️ Advertencia: RAM ajustada<br/>Solo CPU, lotes pequeños"]
    ram -->|"No (< 2 GB)"| block["🛑 BLOQUEADO<br/>Memoria insuficiente"]
    warn_ram --> disk
    gpu -->|"CUDA / MPS"| vram{"¿VRAM ≥ 2 GB?"}
    gpu -->|"Solo CPU"| cpu_ok["✅ Modo CPU<br/>Más lento pero funciona"]
    vram -->|"Sí"| gpu_ok["✅ Modo GPU<br/>Inferencia rápida"]
    vram -->|"No"| cpu_ok
    gpu_ok --> disk{"¿Disco ≥ 2 GB libres?"}
    cpu_ok --> disk
    disk -->|"Sí"| ready["✅ LISTO<br/>Seguro cargar modelo"]
    disk -->|"No"| block_disk["🛑 BLOQUEADO<br/>Se necesita espacio 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 versión del modelo

Modelo	Parámetros	RAM (CPU)	VRAM (GPU)	Disco	Contexto
TimesFM 2.5 (recomendado)	200M	≥ 4 GB	≥ 2 GB	~800 MB	hasta 16,384
TimesFM 2.0 (archivado)	500M	≥ 16 GB	≥ 8 GB	~2 GB	hasta 2,048
TimesFM 1.0 (archivado)	200M	≥ 8 GB	≥ 4 GB	~800 MB	hasta 2,048

Recomendación: Usa siempre TimesFM 2.5 a menos que tengas una razón específica para usar un checkpoint anterior. Es más pequeño, más rápido y admite un contexto 8 veces más largo.

🔧 Instalación

Paso 1: Verificar el sistema (siempre primero)

python scripts/check_system.py

Paso 2: Instalar TimesFM

# Usando uv (recomendado por este repositorio)
uv pip install timesfm[torch]

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

Paso 3: Instalar PyTorch para tu hardware

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

# Solo 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  # El soporte MPS está integrado

Paso 4: Verificar la instalación

import timesfm
import numpy as np
print(f"Versión de TimesFM: {timesfm.__version__}")
print("Instalación correcta")

🎯 Inicio rápido

Ejemplo mínimo (5 líneas)

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

punto, cuantiles = model.forecast(horizon=24, inputs=[
    np.sin(np.linspace(0, 20, 200)),  # cualquier array 1-D
])
# punto.shape == (1, 24)        — pronóstico mediano
# cuantiles.shape == (1, 24, 10) — bandas del percentil 10 al 90

Pronóstico desde CSV

import pandas as pd, numpy as np

df = pd.read_csv("monthly_sales.csv", parse_dates=["date"], index_col="date")

# Convertir cada columna a una lista de arrays
inputs = [df[col].dropna().values.astype(np.float32) for col in df.columns]

punto, cuantiles = model.forecast(horizon=12, inputs=inputs)

# Construir un 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({
        "date": future_dates,
        "forecast": punto[i],
        "lower_80": cuantiles[i, :, 2],  # percentil 20
        "upper_80": cuantiles[i, :, 8],  # percentil 80
    })
    print(f"\n--- {col} ---")
    print(forecast_df.to_string(index=False))

Pronóstico con covariables (XReg)

TimesFM 2.5+ admite variables exógenas a través de forecast_with_covariates(). Requiere timesfm[xreg].

# Requiere: uv pip install timesfm[xreg]
punto, cuantiles = model.forecast_with_covariates(
    inputs=inputs,
    dynamic_numerical_covariates={"price": price_arrays},
    dynamic_categorical_covariates={"holiday": holiday_arrays},
    static_categorical_covariates={"region": region_labels},
    xreg_mode="xreg + timesfm",  # o "timesfm + xreg"
)

Tipo de covariable	Descripción	Ejemplo
dynamic_numerical	Numérica variable en el tiempo	precio, temperatura, gasto en promoción
dynamic_categorical	Categórica variable en el tiempo	indicador de festivo, día de la semana
static_numerical	Numérica por serie	tamaño de tienda, antigüedad de la cuenta
static_categorical	Categórica por serie	tipo de tienda, región, categoría de producto

Modos XReg:

• "xreg + timesfm" (predeterminado): TimesFM pronostica primero, luego XReg ajusta los residuos
• "timesfm + xreg": XReg ajusta primero, luego TimesFM pronostica los residuos

Consulta examples/covariates-forecasting/ para un ejemplo completo con datos sintéticos de venta minorista.

Detección de anomalías (mediante intervalos de cuantiles)

TimesFM no tiene detección de anomalías incorporada, pero los pronósticos de cuantiles proporcionan naturalmente intervalos de predicción que pueden detectar anomalías:

punto, q = model.forecast(horizon=H, inputs=[values])

# Intervalo de predicción del 90%
lower_90 = q[0, :, 1]  # percentil 10
upper_90 = q[0, :, 9]  # percentil 90

# Detectar anomalías: valores fuera del IC del 90%
actual = test_values  # tus datos de reserva
anomalias = (actual < lower_90) | (actual > upper_90)

# Niveles de gravedad
is_warning = (actual < q[0, :, 2]) | (actual > q[0, :, 8])  # fuera del IC del 80%
is_critical = anomalias  # fuera del IC del 90%

Gravedad	Condición	Interpretación
Normal	Dentro del IC del 80%	Comportamiento esperado
Advertencia	Fuera del IC del 80%	Inusual pero posible
Crítico	Fuera del IC del 90%	Estadísticamente raro (< 10% de probabilidad)

Consulta examples/anomaly-detection/ para un ejemplo completo con visualización.

Salida, configuración, flujos de trabajo y ajuste

• references/output_and_config.md: lectura del pronóstico puntual y las 10 bandas de cuantiles, derivación de intervalos de predicción y cada campo de ForecastConfig.
• references/workflows.md: la secuencia de pronóstico estándar, pronóstico de muchas series desde un CSV ancho y backtesting con cobertura de intervalos.
• references/performance_tuning.md: configuración de GPU y TF32, per_core_batch_size según la memoria disponible y gestión de la memoria.
• references/examples_and_validation.md: ejemplos ejecutables, la lista de verificación de calidad, errores comunes y comprobaciones de regresión.

🔗 Integración con otras skills

Con statsmodels

Usa statsmodels para modelos clásicos (ARIMA, SARIMAX) como línea base de comparación:

# Pronóstico de TimesFM
tfm_punto, tfm_q = model.forecast(horizon=H, inputs=[values])

# Pronóstico ARIMA de statsmodels
from statsmodels.tsa.arima.model import ARIMA
arima = ARIMA(values, order=(1,1,1)).fit()
arima_pronostico = arima.forecast(steps=H)

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

Con matplotlib / scientific-visualization

Grafica pronósticos con intervalos de predicción como figuras de calidad de publicación.

Con exploratory-data-analysis

Realiza EDA en la serie temporal antes de pronosticar para comprender tendencias, estacionalidad y estacionariedad.

📚 Scripts disponibles

scripts/check_system.py

Verificador previo obligatorio. Ejecutar antes de la primera carga del modelo.

python scripts/check_system.py

Ejemplo de salida:

=== Verificación de requisitos del sistema de TimesFM ===

[RAM]       Total: 32.0 GB | Disponible: 24.3 GB  ✅ APROBADO
[GPU]       NVIDIA RTX 4090 | VRAM: 24.0 GB      ✅ APROBADO
[Disco]     Libre: 142.5 GB                        ✅ APROBADO
[Python]    3.12.1                                 ✅ APROBADO
[timesfm]   Instalado (2.5.0)                      ✅ APROBADO
[torch]     Instalado (2.4.1+cu121)                ✅ APROBADO

VEREDICTO: ✅ El sistema está listo para TimesFM 2.5 (modo GPU)
Recomendado: per_core_batch_size=128

scripts/forecast_csv.py

Pronóstico de CSV de extremo a extremo con verificación automática del sistema.

python scripts/forecast_csv.py input.csv \
    --horizon 24 \
    --date-col date \
    --value-cols sales,revenue \
    --output forecasts.csv

📖 Documentación de referencia

Guías detalladas en references/:

Archivo	Contenido
references/system_requirements.md	Niveles de hardware, selección de GPU/CPU, fórmulas de estimación de memoria
references/api_reference.md	Documentación completa de ForecastConfig, opciones de from_pretrained, formas de salida
references/data_preparation.md	Formatos de entrada, manejo de NaN, carga de CSV, configuración de covariables

Errores comunes

1. No ejecutar la verificación del sistema → la carga del modelo falla en máquinas con poca RAM. Ejecuta siempre check_system.py primero.
2. Olvidar model.compile() → RuntimeError: El modelo no está compilado. Se debe llamar a compile() antes de forecast().
3. No establecer normalize_inputs=True → pronósticos inestables para series con valores grandes.
4. Usar v1/v2 en máquinas con < 32 GB de RAM → usa TimesFM 2.5 (200M parámetros) en su lugar.
5. No establecer fix_quantile_crossing=True → los cuantiles pueden no ser monótonos (q10 > q50).
6. per_core_batch_size enorme en GPU pequeña → CUDA OOM. Empieza pequeño, aumenta.
7. Pasar arrays 2-D → TimesFM espera una lista de arrays 1-D, no una matriz 2-D.
8. Olvidar torch.set_float32_matmul_precision("high") → inferencia más lenta en GPUs Ampere+.
9. No manejar NaN en la salida → casos extremos con series muy cortas. Siempre comprueba np.isnan(punto).any().
10. Usar infer_is_positive=True para series que pueden ser negativas → fija los pronósticos en cero. Establece como False para temperatura, rendimientos, etc.

Versiones del modelo

timeline
    accTitle: Historial de versiones de TimesFM
    accDescr: Línea de tiempo de los lanzamientos del modelo TimesFM que muestra el recuento de parámetros y las mejoras clave.

    section 2024
        TimesFM 1.0 : 200M parámetros, contexto de 2K, solo JAX
        TimesFM 2.0 : 500M parámetros, contexto de 2K, PyTorch + JAX
    section 2025
        TimesFM 2.5 : 200M parámetros, contexto de 16K, cabeza de cuantiles, sin indicador de frecuencia

Versión	Parámetros	Contexto	Cabeza de cuantiles	Indicador de frecuencia	Estado
2.5	200M	16,384	Sí	No	Activo
2.0	500M	2,048	Sí	Sí	Archivado
1.0	200M	2,048	No	Sí	Archivado

Consulta references/model_versions.md para una guía detallada de migración si actualizas desde versiones anteriores.