Prévision NV-Tesseract

Prévision multivariée de séries temporelles basée sur Transformer utilisant un préentraînement autosupervisé sur des données temporelles diversifiées. Trois modes d'inférence : standard (prévision directe), DARR (fusion kNN améliorée par contexte), et interprétabilité (extraction de trajectoire latente, flux sémantique, attribution lag×horizon, stabilité de trajectoire et ratios de diagnostic — bundle d'explication complet avec rapport PDF). L'ajustement affine l'en-tête de prévision — et optionnellement la couche cross-channel — à votre domaine.

Code source : https://github.com/NVIDIA/NV-Tesseract Poids préentraînés : https://huggingface.co/nvidia/nv-tesseract-forecasting

Dépendances externes

Identifiants

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

Démarrage rapide

git clone --branch main --single-branch https://github.com/NVIDIA/NV-Tesseract
cd NV-Tesseract/forecasting
uv sync --group dev
uv pip install -e .          # installation éditable — requise pour les imports sdk.* propres

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

Inférence

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

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

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

results = perform_forecasting(
    df=df,
    timestamp_column="timestamp",    # colonne datetime analysable
    target_column="target",          # cible primaire à prévoir
    seq_len=512,                     # longueur du contexte d'entrée (lignes consommées)
    forecast_horizon=72,             # pas en avant à prédire (max 512)
    model_horizon=72,                # horizon natif du modèle ; changer 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 tableau Checkpoints
)
# Retourne DataFrame : timestamp | {target_column}_forecast  (forecast_horizon lignes)
print(results.head())

Checkpoints

Passez use_cross_channel=False pour utiliser le checkpoint standard :

results = perform_forecasting(df=df, use_cross_channel=False, ...)

Mode DARR (prévision améliorée 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")   # besoin de ≥ seq_len + model_horizon lignes

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

Les datasets de contexte et d'entrée n'ont pas besoin de colonnes identiques — le SDK s'aligne sur les caractéristiques 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 Framework d'Interprétabilité Agnostique au Modèle. Il produit des explications localisées, spécifiques à l'horizon et conscientes du temps — incluant l'attribution lag×horizon, le flux sémantique, la stabilité de trajectoire, les ratios de diagnostic, et (pour les entrées multivariées) l'attribution axe-canal et l'analyse de couplage.

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

Ajustement affine

Affinez l'en-tête de prévision (encodeur/embedder gelé par défaut) sur vos propres séries temporelles. --ckpt-init auto lance le démarrage à chaud depuis le checkpoint NV-Tesseract publié ; --ckpt-init none entraîne un nouvel en-tête depuis le backbone de base.

cd /path/to/NV-Tesseract/forecasting
# 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 d'ajustement affine

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

Inférence avec checkpoint ajusté affin

results = perform_forecasting(
    df=df,
    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éfinir True si entraîné avec --use-cross-channel
)

Exigences de données

Structure de sortie

Inférence (standard / DARR) :

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

Ajustement affine (--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 arguments
├── metrics.json             # résumé scalaire : {"val_mse": float, "val_mae": float} — consommé par le 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 pour AutoML pour l'ajustement affine et l'inférence DARR. Quand une demande HPO arrive, routez-la via tao-skill-bank:tao-run-automl avec le skill_dir de ce modèle.

Lisez references/automl.md quand l'utilisateur demande la configuration AutoML/HPO, les paramètres ajustables, les exemples de runner, les scripts d'inférence de trial, HPO DARR, ou les détails de remise des résultats AutoML.

Pièges connus