timesfm-forecasting

Prévision avec TimesFM

Aperçu

TimesFM (Time Series Foundation Model) est un modèle fondation décodeur pré-entraîné développé par Google Research pour la prévision de séries temporelles. Il fonctionne zero-shot — fournissez-lui n'importe quelle série temporelle univariée et il retourne des prévisions ponctuelles avec des intervalles de prédiction quantiles calibrés, sans aucun entraînement.

Cette compétence encapsule TimesFM pour une inférence locale sécurisée et adaptée aux agents. Elle inclut un vérificateur système obligatoire qui contrôle la RAM, la mémoire GPU et l'espace disque avant le chargement du modèle, garantissant que l'agent ne fasse jamais planter la machine de l'utilisateur.

Chiffres clés : TimesFM 2.5 utilise 200 millions de paramètres (~800 Mo sur disque, ~1,5 Go en RAM sur CPU, ~1 Go de VRAM sur GPU). Le modèle archivé v1/v2 de 500 millions de paramètres nécessite ~32 Go de RAM. Exécutez toujours le vérificateur système en premier.

Quand utiliser cette compétence

Utilisez cette compétence lorsque :

• Vous devez prévoir n'importe quelle série temporelle univariée (ventes, demande, capteurs, signes vitaux, prix, météo)
• Vous avez besoin de prévisions zero-shot sans entraîner un modèle personnalisé
• Vous souhaitez des prévisions probabilistes avec des intervalles de prédiction calibrés (quantiles)
• Vous avez des séries temporelles de n'importe quelle longueur (le modèle gère 1 à 16 384 points de contexte)
• Vous devez prévoir par lots des centaines ou des milliers de séries efficacement
• Vous préférez une approche par modèle fondation plutôt que de régler manuellement les paramètres ARIMA/ETS

N'utilisez pas cette compétence lorsque :

• Vous avez besoin de modèles statistiques classiques avec interprétation des coefficients → utilisez statsmodels
• Vous avez besoin de classification ou de clustering de séries temporelles → utilisez aeon
• Vous avez besoin d'autorégression vectorielle multivariée ou de causalité de Granger → utilisez statsmodels
• Vos données sont tabulaires (non temporelles) → utilisez scikit-learn

Note sur la détection d'anomalies : TimesFM n'a pas de détection d'anomalies intégrée, mais vous pouvez utiliser les prévisions quantiles comme intervalles de prédiction — les valeurs en dehors de l'intervalle de confiance à 90 % (q10–q90) sont statistiquement inhabituelles. Voir le répertoire examples/anomaly-detection/ pour un exemple complet.

⚠️ Vérification préalable obligatoire : Contrôle des prérequis système

CRITIQUE — Exécutez TOUJOURS le vérificateur système avant de charger le modèle pour la première fois.

python scripts/check_system.py

Ce script vérifie :

1. RAM disponible — avertit si inférieure à 4 Go, bloque si inférieure à 2 Go
2. Disponibilité GPU — détecte les périphériques CUDA/MPS et la VRAM
3. Espace disque — vérifie l'espace pour le téléchargement du modèle (~800 Mo)
4. Version Python — nécessite Python 3.10+
5. Installation existante — vérifie si timesfm et torch sont installés

Note : Les poids du modèle NE sont PAS stockés dans ce dépôt. Les poids de TimesFM (~800 Mo) sont téléchargés à la demande depuis HuggingFace lors de la première utilisation et mis en cache dans ~/.cache/huggingface/. Le vérificateur préalable garantit des ressources suffisantes avant le début du téléchargement.

flowchart TD
    accTitle: Vérification système préalable
    accDescr: Diagramme de décision montrant les contrôles des prérequis système à effectuer avant de charger TimesFM.

    start["🚀 Exécuter check_system.py"] --> ram{"RAM ≥ 4 Go ?"}
    ram -->|"Oui"| gpu{"GPU disponible ?"}
    ram -->|"Non (2-4 Go)"| warn_ram["⚠️ Avertissement : RAM limitée<br/>CPU uniquement, petits lots"]
    ram -->|"Non (< 2 Go)"| block["🛑 BLOQUÉ<br/>Mémoire insuffisante"]
    warn_ram --> disk
    gpu -->|"CUDA / MPS"| vram{"VRAM ≥ 2 Go ?"}
    gpu -->|"CPU uniquement"| cpu_ok["✅ Mode CPU<br/>Plus lent mais fonctionne"]
    vram -->|"Oui"| gpu_ok["✅ Mode GPU<br/>Inférence rapide"]
    vram -->|"Non"| cpu_ok
    gpu_ok --> disk{"Disque ≥ 2 Go libres ?"}
    cpu_ok --> disk
    disk -->|"Oui"| ready["✅ PRÊT<br/>Chargement du modèle sécurisé"]
    disk -->|"Non"| block_disk["🛑 BLOQUÉ<br/>Espace nécessaire pour les poids"]

    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

Prérequis matériels par version du modèle

Modèle	Paramètres	RAM (CPU)	VRAM (GPU)	Disque	Contexte
TimesFM 2.5 (recommandé)	200M	≥ 4 Go	≥ 2 Go	~800 Mo	jusqu'à 16 384
TimesFM 2.0 (archivé)	500M	≥ 16 Go	≥ 8 Go	~2 Go	jusqu'à 2 048
TimesFM 1.0 (archivé)	200M	≥ 8 Go	≥ 4 Go	~800 Mo	jusqu'à 2 048

Recommandation : Utilisez toujours TimesFM 2.5 sauf si vous avez une raison spécifique d'utiliser un point de contrôle plus ancien. Il est plus petit, plus rapide et supporte un contexte 8 fois plus long.

🔧 Installation

Étape 1 : Vérifier le système (toujours en premier)

python scripts/check_system.py

Étape 2 : Installer TimesFM

# Avec uv (recommandé par ce dépôt)
uv pip install timesfm[torch]

# Pour le backend JAX/Flax (plus rapide sur TPU/GPU)
uv pip install timesfm[flax]

Étape 3 : Installer PyTorch pour votre matériel

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

# CPU uniquement
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  # Le support MPS est intégré

Étape 4 : Vérifier l'installation

import timesfm
import numpy as np
print(f"Version TimesFM : {timesfm.__version__}")
print("Installation OK")

🎯 Démarrage rapide

Exemple minimal (5 lignes)

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)),  # n'importe quel tableau 1-D
])
# point.shape == (1, 24)        — prévision médiane
# quantiles.shape == (1, 24, 10) — bandes du 10e au 90e percentile

Prévision à partir d'un CSV

import pandas as pd, numpy as np

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

# Convertir chaque colonne en une liste de tableaux
inputs = [df[col].dropna().values.astype(np.float32) for col in df.columns]

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

# Construire un DataFrame de résultats
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": point[i],
        "lower_80": quantiles[i, :, 2],  # 20e percentile
        "upper_80": quantiles[i, :, 8],  # 80e percentile
    })
    print(f"\n--- {col} ---")
    print(forecast_df.to_string(index=False))

Prévision avec covariables (XReg)

TimesFM 2.5+ prend en charge les variables exogènes via forecast_with_covariates(). Nécessite timesfm[xreg].

# Nécessite : uv pip install timesfm[xreg]
point, quantiles = 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",  # ou "timesfm + xreg"
)

Type de covariable	Description	Exemple
dynamic_numerical	Numérique variant dans le temps	prix, température, dépenses promotionnelles
dynamic_categorical	Catégoriel variant dans le temps	indicateur de jour férié, jour de la semaine
static_numerical	Numérique par série	taille du magasin, ancienneté du compte
static_categorical	Catégoriel par série	type de magasin, région, catégorie de produit

Modes XReg :

• "xreg + timesfm" (par défaut) : TimesFM prévoit d'abord, puis XReg ajuste les résidus
• "timesfm + xreg" : XReg s'ajuste d'abord, puis TimesFM prévoit les résidus

Voir examples/covariates-forecasting/ pour un exemple complet avec des données de vente au détail synthétiques.

Détection d'anomalies (via intervalles quantiles)

TimesFM n'a pas de détection d'anomalies intégrée, mais les prévisions quantiles fournissent naturellement des intervalles de prédiction qui peuvent détecter les anomalies :

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

# Intervalle de prédiction à 90 %
lower_90 = q[0, :, 1]  # 10e percentile
upper_90 = q[0, :, 9]  # 90e percentile

# Détecter les anomalies : valeurs en dehors de l'IC à 90 %
actual = test_values  # vos données de validation
anomalies = (actual < lower_90) | (actual > upper_90)

# Niveaux de gravité
is_warning = (actual < q[0, :, 2]) | (actual > q[0, :, 8])  # en dehors de l'IC à 80 %
is_critical = anomalies  # en dehors de l'IC à 90 %

Gravité	Condition	Interprétation
Normal	Dans l'IC à 80 %	Comportement attendu
Avertissement	En dehors de l'IC à 80 %	Inhabituel mais possible
Critique	En dehors de l'IC à 90 %	Statistiquement rare (< 10 % de probabilité)

Voir examples/anomaly-detection/ pour un exemple complet avec visualisation.

# Nécessite : uv pip install timesfm[xreg]
point, quantiles = model.forecast_with_covariates(
    inputs=inputs,
    dynamic_numerical_covariates={"temperature": temp_arrays},
    dynamic_categorical_covariates={"day_of_week": dow_arrays},
    static_categorical_covariates={"region": region_labels},
    xreg_mode="xreg + timesfm",  # ou "timesfm + xreg"
)

Sortie, configuration, workflows et réglage

• references/output_and_config.md : lecture de la prévision ponctuelle et des 10 bandes quantiles, dérivation des intervalles de prédiction, et chaque champ de ForecastConfig.
• references/workflows.md : la séquence de prévision standard, la prévision de nombreuses séries à partir d'un CSV large, et le backtesting avec couverture des intervalles.
• references/performance_tuning.md : configuration GPU et TF32, per_core_batch_size en fonction de la mémoire disponible, et gestion de la mémoire.
• references/examples_and_validation.md : exemples exécutables, liste de contrôle qualité, erreurs courantes, et contrôles de régression.

🔗 Intégration avec d'autres compétences

Avec statsmodels

Utilisez statsmodels pour les modèles classiques (ARIMA, SARIMAX) comme base de comparaison :

# Prévision TimesFM
tfm_point, tfm_q = model.forecast(horizon=H, inputs=[values])

# Prévision ARIMA avec statsmodels
from statsmodels.tsa.arima.model import ARIMA
arima = ARIMA(values, order=(1,1,1)).fit()
arima_forecast = arima.forecast(steps=H)

# Comparer
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}")

Avec matplotlib / scientific-visualization

Tracez les prévisions avec des intervalles de prédiction sous forme de figures de qualité publication.

Avec exploratory-data-analysis

Effectuez une analyse exploratoire des données sur la série temporelle avant la prévision pour comprendre les tendances, la saisonnalité et la stationnarité.

📚 Scripts disponibles

scripts/check_system.py

Vérificateur préalable obligatoire. À exécuter avant le premier chargement du modèle.

python scripts/check_system.py

Exemple de sortie :

=== Vérification des prérequis système TimesFM ===

[RAM]       Total : 32,0 Go | Disponible : 24,3 Go  ✅ RÉUSSI
[GPU]       NVIDIA RTX 4090 | VRAM : 24,0 Go        ✅ RÉUSSI
[Disque]    Libre : 142,5 Go                         ✅ RÉUSSI
[Python]    3.12.1                                    ✅ RÉUSSI
[timesfm]   Installé (2.5.0)                          ✅ RÉUSSI
[torch]     Installé (2.4.1+cu121)                    ✅ RÉUSSI

VERDICT : ✅ Le système est prêt pour TimesFM 2.5 (mode GPU)
Recommandé : per_core_batch_size=128

scripts/forecast_csv.py

Prévision CSV de bout en bout avec vérification système automatique.

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

📖 Documentation de référence

Guides détaillés dans references/ :

Fichier	Contenu
references/system_requirements.md	Niveaux matériels, sélection GPU/CPU, formules d'estimation de mémoire
references/api_reference.md	Documentation complète de ForecastConfig, options from_pretrained, formes de sortie
references/data_preparation.md	Formats d'entrée, gestion des NaN, chargement CSV, configuration des covariables

Pièges courants

1. Ne pas exécuter la vérification système → le chargement du modèle plante sur les machines à faible RAM. Exécutez toujours check_system.py en premier.
2. Oublier model.compile() → RuntimeError: Model is not compiled. Vous devez appeler compile() avant forecast().
3. Ne pas définir normalize_inputs=True → prévisions instables pour les séries avec de grandes valeurs.
4. Utiliser v1/v2 sur des machines avec moins de 32 Go de RAM → utilisez TimesFM 2.5 (200M paramètres) à la place.
5. Ne pas définir fix_quantile_crossing=True → les quantiles peuvent ne pas être monotones (q10 > q50).
6. per_core_batch_size trop grand sur un petit GPU → CUDA OOM. Commencez petit, augmentez progressivement.
7. Passer des tableaux 2-D → TimesFM attend une liste de tableaux 1-D, pas une matrice 2-D.
8. Oublier torch.set_float32_matmul_precision("high") → inférence plus lente sur les GPU Ampere+.
9. Ne pas gérer les NaN dans la sortie → cas particuliers avec des séries très courtes. Vérifiez toujours np.isnan(point).any().
10. Utiliser infer_is_positive=True pour des séries pouvant être négatives → bloque les prévisions à zéro. Définissez sur False pour la température, les rendements, etc.

Versions du modèle

timeline
    accTitle: Historique des versions TimesFM
    accDescr: Chronologie des versions du modèle TimesFM montrant le nombre de paramètres et les améliorations clés.

    section 2024
        TimesFM 1.0 : 200M paramètres, contexte 2K, JAX uniquement
        TimesFM 2.0 : 500M paramètres, contexte 2K, PyTorch + JAX
    section 2025
        TimesFM 2.5 : 200M paramètres, contexte 16K, tête quantile, indicateur de fréquence supprimé

Version	Paramètres	Contexte	Tête quantile	Indicateur de fréquence	Statut
2.5	200M	16 384	Oui	Non	Actif
2.0	500M	2 048	Non (post-hoc)	Oui	Archivé
1.0	200M	2 048	Non (post-hoc)	Oui	Archivé

Recommandation : Utilisez TimesFM 2.5. C'est la version la plus performante pour la grande majorité des cas d'usage.

Licence

Ce projet est sous licence Apache 2.0. TimesFM est sous licence Apache 2.0 par Google.

Références

• TimesFM : https://github.com/google-research/timesfm
• HuggingFace : https://huggingface.co/google/timesfm-2.5-200m-pytorch
• TimesFM 2.5 Article : https://arxiv.org/abs/2504.14296