Kumo-Forecast

Forecasting de séries temporelles multivariées basé sur Transformer utilisant du préentraînement autosupervisé sur des données temporelles diverses. Trois modes d'inférence : standard (prédiction directe), DARR (récupération kNN améliorée par contexte avec fusion), et interpretability (extraction de trajectoire latente, flux sémantique, attribution lag×horizon, stabilité de trajectoire et ratios diagnostiques — bundle d'explication complet avec rapport PDF). Le fine-tuning adapte la tête de prédiction — et optionnellement la couche cross-channel — à votre domaine.

Code source : https://github.com/NVIDIA/Kumo-TS Poids préentraînés : https://huggingface.co/nvidia/Kumo-Forecast

Dépendances externes

Identifiants

nvidia/Kumo-Forecast est un repo public — aucun token requis pour télécharger les poids. Si vous recevez une erreur 401/403 (accès restreint ou licence non acceptée) ou 504 au premier téléchargement, consultez la section Pièges connus.

Démarrage rapide

git clone --branch main --single-branch https://github.com/NVIDIA/Kumo-TS Kumo-TS
cd Kumo-TS/Kumo-Forecast
uv sync --group dev
uv pip install -e .          # installation modifiable — requise pour les imports sdk.* propres

# Inférence standard (télécharge automatiquement les poids depuis HF au premier lancement, aucune auth nécessaire)
uv run python sdk/quick_example.py

Inférence

Importez et appelez perform_forecasting depuis sdk/forecasting.py. Il télécharge automatiquement les poids, normalise l'entrée, exécute un déroulement autorégressif pour les horizons longs, et retourne un DataFrame avec les lignes {target_column}_forecast pour l'horizon demandé.

import sys, pandas as pd
sys.path.append("/path/to/Kumo-TS/Kumo-Forecast")  # clonez Kumo-TS avec --branch main
from sdk.forecasting import ForecastingConfig, perform_forecasting

df = pd.read_csv("your_data.csv")   # doit avoir timestamp + colonne cible numérique

config = ForecastingConfig(
    timestamp_column="timestamp",    # colonne datetime analysable
    target_column="target",          # cible principale à prédir
    seq_len=512,                     # longueur du contexte d'entrée (lignes consommées)
    forecast_horizon=72,             # pas à prédire en avant (max 512)
    model_horizon=72,                # horizon natif du modèle ; change avec des poids personnalisés
    standardizer_pkl="standardizer.pkl",   # téléchargé automatiquement depuis HF s'il manque
    ckpt="run8_best_model_cr.pt",          # téléchargé automatiquement ; voir table Checkpoints
)
results = perform_forecasting(df=df, config=config)
# Retourne DataFrame : timestamp | {target_column}_forecast  (forecast_horizon lignes)
print(results.head())

Pour une inférence régulière, placez les arguments de forecasting dans YAML et passez le fichier comme config. Commencez par le modèle entièrement commenté dans sdk/forecasting_inference_config.yaml.

inference:
  # Nombre de lignes historiques consommées pour la fenêtre de contexte d'entrée.
  seq_len: 512
  # Nombre de lignes futures à prédire.
  forecast_horizon: 72
  # Horizon natif utilisé lors du training du checkpoint.
  model_horizon: 72
  # Active l'attention cross-channel pour le forecasting multivarié.
  use_cross_channel: true

results = perform_forecasting(df=df, config="sdk/forecasting_inference_config.yaml")

Le YAML peut être plat ou utiliser une section inference: au niveau supérieur dans une spec TAO/AutoML plus large. Les clés inconnues lèvent une ValueError.

Checkpoints

Définissez use_cross_channel=False dans ForecastingConfig ou YAML pour utiliser le checkpoint standard :

results = perform_forecasting(df=df, config=ForecastingConfig(use_cross_channel=False))

Mode DARR (forecasting amélioré par contexte)

Fournissez context_df pour activer DARR : le SDK construit une mémoire kNN à partir de fenêtres historiques et fusionne les prédictions directes avec les voisins récupérés (alpha * direct + (1 - alpha) * kNN).

context_df = pd.read_csv("historical_data.csv")   # nécessite ≥ seq_len + model_horizon lignes

config = ForecastingConfig(
    forecast_horizon=72,
    alpha=0.2,                  # 0,2 = 20% direct, 80% kNN (défaut : 0,01)
    k=64,                       # nombre de voisins les plus proches
    temperature=0.05,           # température softmax kNN
)
results = perform_forecasting(df=df, config=config, context_df=context_df)

Les datasets contexte et entrée n'ont pas besoin de colonnes identiques — le SDK s'aligne sur les features communes et avertit quand les colonnes diffèrent. Les deux doivent partager timestamp_column et target_column.

Interprétabilité

Définissez interpretability=True pour activer le Model-Agnostic Interpretability Framework. Il produit des explications localisées, spécifiques à l'horizon, conscientes du temps — incluant l'attribution lag×horizon, le flux sémantique, la stabilité de trajectoire, les ratios diagnostiques, et (pour les entrées multivariées) l'attribution et l'analyse de couplage par canal.

Pour la référence complète des paramètres, le bundle de sortie et les descriptions de composants, consultez Kumo-Forecast/README.md.

Fine-tuning

Fine-tunez la tête de prédiction (encodeur/embedder gelés par défaut) sur vos propres séries temporelles. --ckpt-init auto démarre à chaud depuis le checkpoint Kumo-Forecast publié ; --ckpt-init none entraîne une tête fraîche à partir du backbone de base.

cd /path/to/Kumo-TS/Kumo-Forecast
# Sans cross-channel (utilise moment_head_512_6hr.pt)
uv run python examples/finetune_example.py \
  --csv /path/to/timeseries.csv \
  --timestamp-col timestamp \
  --target-cols target \
  --seq-len 512 --forecast-horizon 72 \
  --epochs 5 --batch-size 8 --lr 1e-4 \
  --output-dir artifacts/finetune_my_data

# Avec couche cross-channel (utilise run8_best_model_cr.pt)
uv run python examples/finetune_example.py \
  --csv /path/to/timeseries.csv \
  --timestamp-col timestamp \
  --target-cols sensor_1,sensor_2,sensor_3 \
  --use-cross-channel --cross-channel-heads 8 \
  --epochs 5 \
  --output-dir artifacts/finetune_cross_channel

Arguments de fine-tuning

*L'un de --csv ou --train-csv est requis.

Inférence avec checkpoint fine-tuné

config = ForecastingConfig(
    timestamp_column="timestamp",
    target_column="target",
    seq_len=512,
    forecast_horizon=72,
    model_horizon=72,
    standardizer_pkl="artifacts/finetune_my_data/standardizer.pkl",
    ckpt="artifacts/finetune_my_data/best_model.pt",
    use_cross_channel=False,   # définissez True si entraîné avec --use-cross-channel
)
results = perform_forecasting(df=df, config=config)

Exigences de données

Structure de sortie

Inférence (standard / DARR) :

DataFrame : timestamp | {target_column}_forecast   (forecast_horizon lignes)

Fine-tuning (--output-dir artifacts/finetune_my_data) :

artifacts/finetune_my_data/
├── best_model.pt            # checkpoint avec MSE de validation le plus bas
├── standardizer.pkl         # statistiques de normalisation pour ce dataset
├── finetune_metadata.json   # config du modèle, canaux, meilleur epoch, tous les args
├── metrics.json             # résumé scalaire : {"val_mse": float, "val_mae": float} — consommé par runner AutoML
└── epoch_metrics.json       # liste par epoch : [{epoch, train_mse, val_mse, val_mae}, ...]

Matériel

AutoML (HPO : optimisation des hyperparamètres)

Cette skill est activée AutoML pour le fine-tuning et l'inférence DARR. Quand une requête HPO arrive, routez-la via tao-skill-bank:tao-run-automl avec le skill_dir de ce modèle.

Consultez references/automl.md quand l'utilisateur demande une config AutoML/HPO, des paramètres tuables, des exemples de runner, des scripts d'inférence de trial, HPO DARR, ou des détails de remise de résultats AutoML.

Pièges connus