Kumo-Anomaly

Détection d'anomalies basée sur la diffusion et fine-tuning pour séries temporelles multivariées. Le modèle reconstruit les segments masqués aléatoirement et score chaque pas de temps par 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/Kumo-TS Poids pré-entraînés : https://huggingface.co/nvidia/Kumo-Anomaly

Pour les informations d'utilisation les plus à jour, consultez les fichiers README dans le dépôt Kumo-TS :

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

Dépendances externes

Identifiants

nvidia/Kumo-Anomaly est un dépôt public — aucun token requis pour télécharger les poids. Si vous rencontrez un 401/403 (accès restreint ou fork privé) ou un 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-Anomaly
uv sync                              # installer les dépendances (une seule fois)

# Inférence — données synthétiques, télécharge automatiquement les poids depuis HF au premier lancement
uv run python examples/quick_example.py

# Inférence — votre propre 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 uniquement les poids (réchauffer le cache avant d'être 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, auto-distribue sur tous les GPU 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/Kumo-TS/Kumo-Anomaly")  # cloner Kumo-TS 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 sur les colonnes non-numériques — supprimez 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 auto final_model.pth depuis HF
    model_config_path=None,          # None → télécharge auto 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())

Rapport (sdk_config)

perform_anomaly_analysis_with_diffusion accepte un mot-clé optionnel sdk_config — un ADDiffusionConfig, un chemin vers un fichier YAML, ou None pour les défauts. Il limite les paramètres de génération de rapport uniquement ; les args de comportement d'inférence (threshold_strategy, nsample, model_path, model_config_path) restent des arguments directs de la fonction.

from sdk.anomaly_analysis import ADDiffusionConfig, perform_anomaly_analysis_with_diffusion

results = perform_anomaly_analysis_with_diffusion(
    df=df,
    threshold_strategy="scs",
    sdk_config=ADDiffusionConfig(
        report_path="artifacts/anomaly_report.pdf",
        report_title="Anomaly Detection Report",
    ),
)

Ou passez un chemin YAML au lieu de la dataclass — load_sdk_config accepte un mappage plat ou imbriqué sous une clé de haut niveau sdk: (pour que le fichier puisse porter d'autres sections à côté), et rejette les clés inconnues :

sdk:
  report_path: artifacts/anomaly_report.pdf
  report_title: Anomaly Detection Report

results = perform_anomaly_analysis_with_diffusion(
    df=df,
    threshold_strategy="scs",
    sdk_config="sdk_config.yaml",
)

Champs ADDiffusionConfig : report_path (str/Path, défaut None — mettre pour activer le rapport PDF), timestamp_column (str, None), ground_truth_column (str, None), report_title (str, "Kumo-Anomaly Report"), report_max_pages (int, 10).

Référence CLI d'inférence

Fine-tuning

Fine-tuner sur vos propres données. Le CSV d'entraînement devrait contenir principalement du 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 de 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",
    model_config_path="artifacts/finetune_my_data/finetune_config.yaml",
    nsample=15,
)

AutoML (HPO : optimisation d'hyperparamètres)

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

Exigences des données

target_dim 18 est le défaut du fichier config, non une constante dure — lors du fine-tuning avec démarrage à chaud depuis un checkpoint publié (--pretrained-model), la config intégrée du checkpoint la remplace (le final_model.pth publié a été entraîné à target_dim=40). Vérifiez la config du checkpoint plutôt que de supposer 18 quand on raisonne sur le comportement PCA/padding pour fine-tuning avec démarrage à chaud.

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

Passez uniquement les colonnes de features numériques à l'API d'inférence — elle lève ValueError sur les colonnes non-numériques au lieu de les supprimer. Utilisez df.select_dtypes(include="number") ou supprimez 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/
└── kumo-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 plus faible perte de validation
├── final_finetuned_model.pth    # checkpoint de la dernière époque
├── metrics.json                 # scalaire pour AutoML : {"val_loss": <best>}
├── epoch_metrics.json           # log par époque : [{"epoch": N, "train_loss": …, "val_loss": …}]
└── finetune_config.yaml         # config utilisée pendant l'entraînement (pour reproducibilité)

Configuration du modèle (curriculum_medium.yaml)

Matériel

Pièges connus