NV-Tesseract AD Diffusion

Détection d'anomalies basée sur la diffusion et fine-tuning pour séries temporelles multivariées. Le modèle reconstruit des segments masqués aléatoirement et évalue chaque pas de temps par l'erreur absolue moyenne (MAE) entre la reconstruction et le signal original ; le seuillage adaptatif (SCS ou MACS) convertit les scores en étiquettes binaires.

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

Pour les informations d'utilisation les plus à jour, consultez les fichiers README du dépôt NV-Tesseract :

• ad_diffusion/README.md — référence SDK complète, architecture du modèle et documentation API
• ad_diffusion/examples/datasets/README.md — format des données, génération de données synthétiques et conventions CSV

Dépendances externes

Identifiants

nvidia/nv-tesseract-ad-diffusion est un dépôt public — aucun token requis pour télécharger les poids. Si vous rencontrez une erreur 401/403 (accès restreint ou fork privé) ou une 504 lors du premier téléchargement, consultez la section Pièges connus.

Démarrage rapide

git clone --branch main --single-branch https://github.com/NVIDIA/NV-Tesseract
cd NV-Tesseract/ad_diffusion
uv sync                              # installer les dépendances (une seule fois)

# Inférence — données synthétiques, télécharge automatiquement les poids de HF à la première exécution
uv run python examples/quick_example.py

# Inférence — vos propres données CSV
uv run python examples/quick_example.py \
  --model-path final_model.pth \
  --config-path curriculum_medium.yaml \
  --dataset-path /path/to/data.csv

# Pré-télécharger les poids uniquement (réchauffer le cache avant d'aller hors ligne)
uv run python examples/quick_example.py --download-weights

# Fine-tuner sur vos propres données de comportement normal
uv run python examples/finetune_example.py \
  --csv /path/to/normal_training_data.csv \
  --timestamp-col timestamp \
  --label-col is_anomaly \
  --epochs 20 \
  --output-dir artifacts/finetune_my_data

Inférence

Utilisez perform_anomaly_analysis_with_diffusion dans sdk/anomaly_analysis.py. Elle valide l'entrée, distribue automatiquement sur tous les GPUs visibles, applique le seuillage adaptatif (SCS ou MACS) et retourne le DataFrame original avec les colonnes Anomaly (0/1) et MAE ajoutées.

import sys, pandas as pd
sys.path.append("/path/to/NV-Tesseract/ad_diffusion")  # cloner NV-Tesseract avec --branch main
from sdk.anomaly_analysis import perform_anomaly_analysis_with_diffusion

df = pd.read_csv("your_data.csv")

# L'API lève ValueError pour les colonnes non numériques — supprimer d'abord le timestamp, les IDs et les étiquettes.
df = df.select_dtypes(include="number")

results = perform_anomaly_analysis_with_diffusion(
    df=df,
    threshold_strategy="scs",       # "scs" (rapide) ou "macs" (adaptatif)
    model_path=None,                 # None → télécharge automatiquement final_model.pth depuis HF
    config_path=None,                # None → télécharge automatiquement curriculum_medium.yaml depuis HF
    nsample=15,                      # échantillons de diffusion par fenêtre ; ↑ précision, ↑ latence
    preprocess_model_dir=None,       # répertoire optionnel du modèle de prétraitement
)
# colonnes de results : Anomaly (0/1), MAE (float), plus toutes les colonnes originales
print(results[["Anomaly", "MAE"]].describe())

Référence CLI pour l'inférence

Fine-tuning

Fine-tuner sur vos propres données. Le CSV d'entraînement devrait contenir principalement un comportement normal. Validez le modèle pré-entraîné sur votre domaine avant le fine-tuning.

uv run python examples/finetune_example.py \
  --csv /path/to/normal_data.csv \
  --val-csv /path/to/val_data.csv \   # optionnel ; sinon --val-ratio divise --csv
  --pretrained-model final_model.pth \
  --epochs 20 --batch-size 16 --lr 1e-5 \
  --output-dir artifacts/finetune_my_data

Arguments du fine-tuning

Exécuter l'inférence avec un checkpoint fine-tuné

results = perform_anomaly_analysis_with_diffusion(
    df=df,
    threshold_strategy="scs",
    model_path="artifacts/finetune_my_data/best_finetuned_model.pth",
    config_path="artifacts/finetune_my_data/finetune_config.yaml",
    nsample=15,
)

AutoML (HPO : optimisation des hyperparamètres)

Cette skill supporte AutoML pour HPO de fine-tuning et HPO d'inférence avec étiquettes 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 réglables, la configuration VirtualEnvSDK, le flux config, les contraintes de window-length, les scripts de test d'inférence ou les détails de remise des résultats AutoML.

Exigences des données

timestamp,sensor_1,sensor_2,sensor_3
2024-01-01 00:00:00,0.42,1.10,-0.33
...

Passer uniquement les colonnes de caractéristiques numériques à l'API d'inférence — elle lève ValueError pour les colonnes non numériques au lieu de les supprimer. Utiliser df.select_dtypes(include="number") ou supprimer par nom avant d'appeler. Le fine-tuning gère cela via les args CLI --timestamp-col, --label-col et --drop-cols.

Structure de sortie

Inférence (examples/quick_example.py) :

examples/datasets/
└── anomaly_results.csv      # colonnes originales + Anomaly (0/1) + MAE

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

artifacts/finetune_my_data/
├── best_finetuned_model.pth     # checkpoint avec la perte de validation la plus faible
├── final_finetuned_model.pth    # checkpoint du dernier epoch
├── metrics.json                 # scalaire pour AutoML : {"val_loss": <best>}
├── epoch_metrics.json           # log par epoch : [{"epoch": N, "train_loss": …, "val_loss": …}]
└── finetune_config.yaml         # config utilisée durant l'entraînement (pour la reproductibilité)

Configuration du modèle (curriculum_medium.yaml)

Matériel

Pièges connus