PAIDF AnomalyGen

Pipeline multi-phases (0–7) ; le flag mode sélectionne les phases à exécuter.

Exécutez chaque phase jusqu'à son terme sans interruption en cours d'exécution. Rassemblez tous les paramètres requis à l'avance et exécutez chaque commande depuis la racine du dépôt.

Configuration shell. Toutes les références ${ANOMALYGEN_SCRIPTS} pointent vers le répertoire des scripts d'aide fournis. Dans le conteneur, c'est préconfiguré (ENV ANOMALYGEN_SCRIPTS=<dir>/scripts/utilities) ; sur l'hôte, exportez-le une fois par shell :

export ANOMALYGEN_SCRIPTS="$(git rev-parse --show-toplevel)/scripts/utilities"

Les invocations python3 -m scripts.utilities.<name> fonctionnent depuis n'importe quel répertoire courant à l'intérieur du conteneur (PYTHONPATH est préconfiguré) et depuis la racine du dépôt sur l'hôte. Lorsque vous êtes dans un conteneur produit (ANOMALYGEN_PRODUCT_MODE=1), invoquez anomalygen-guard avant tout travail GPU ; s'il rapporte BLOCKED, corrigez les problèmes listés avant de continuer.

Démarrage rapide

Le pipeline s'exécute dans le conteneur metropolis_sdg.paidf_anomalygen (déclaré dans versions.yaml) ou sur tout hôte avec l'environnement conda cosmos-predict2 actif. Toutes les commandes de phase supposent cet environnement, à la racine du dépôt, avec ANOMALYGEN_SCRIPTS exporté.

Exécution minimale end-to-end (mode=full) :

# 1. Définir les variables partagées (voir « Shared variables » pour l'ensemble complet).
export ANOMALYGEN_SCRIPTS="$(git rev-parse --show-toplevel)/scripts/utilities"
MODE=full
NAME=my_exp
DATASET_DIR=/data/uc1
DEFECT_DESC=assets/defect_spec_template.jsonl
NUM_SDG=20
MODEL_SIZE=2b

# 2. Phase 0 — vérifier / télécharger les checkpoints (~140 GB ; nécessite HF_TOKEN).
${ANOMALYGEN_SCRIPTS}/check.sh || ${ANOMALYGEN_SCRIPTS}/download_checkpoints.sh

# 3. Parcourir les phases 1→7 dans l'ordre (voir chaque section de phase).

Pour mode=inference_only (réutiliser un checkpoint), définissez aussi CKPT/STEP et ignorez la phase 1. Pour mode=finetune_only, exécutez uniquement les phases 0–1.

Exécution en Docker — lancement du conteneur, montages et permissions

L'image paidf-anomalygen s'exécute en tant qu'utilisateur non-root intégré (USER anomalygen, uid=10000), indépendamment de votre uid d'hôte. Docker ne remappe pas les uids sur les montages bind, donc un répertoire d'hôte possédé par votre uid n'est pas accessible en écriture par uid 10000 et le conteneur échoue dès qu'il tente de créer un fichier là. Exécutez en tant que votre uid d'hôte avec --user "$(id -u):$(id -g)" plus les compagnons obligatoires /etc/passwd+/etc/group et HOME/cache-redirect, et exécutez le test de préflight d'écriture fail-fast avant la phase 0. Voir references/docker.md pour la commande docker run complète, le tableau des flags critiques, l'extrait de préflight et le fallback chown/chmod pour uid-10000.

Fichiers de référence — lire avant d'exécuter les phases

Lisez references/finetune.md avant les phases 0/1 et references/inference.md avant les phases 2–7 ; pour mode=full, lisez les deux avant de commencer. Les autres références ci-dessous sont à la demande — lisez-les lors du dépannage ou si vous avez besoin de tous les détails pour une phase spécifique.

Paramètres requis

L'allocation de num_SDG dépend de prep_testcase.sh --mode : inference (défaut, phase 2) est uniforme sur les types de défauts, surcharge per-défaut via --per-defect-counts ; validation (JSONL de validation de la phase 1) est proportionnelle aux comptes des masques d'entraînement (arrondi à plus grande fraction) et impose ≥1 par défaut. Voir references/prep-testcase.md pour le tableau complet des modes.

Conditionnellement requis

Paramètres optionnels

Validation de mode (fail fast avant toute phase)

• mode non défini → arrêt : « mode est requis (full | inference_only | finetune_only). »
• mode=inference_only manquant checkpoint_dir ou step → arrêt : « inference_only nécessite checkpoint_dir et step. »
• mode=full avec checkpoint_dir ou step fourni → arrêt : « full mode exécute finetune ; utilisez mode=inference_only pour réutiliser un checkpoint existant. »

Variables partagées

À définir une fois avant la phase 0 :

MODE=<full|inference_only|finetune_only>
NAME=<exp>
DATASET_DIR=<dataset_dir>
CLEAN_DIR=${clean_dir:-${DATASET_DIR}}
CKPT=<checkpoint_dir>      # requis ssi MODE=inference_only ; auto-dérivé après phase 1 quand MODE=full
STEP=<iter>                # requis ssi MODE=inference_only ; auto-dérivé après phase 1 quand MODE=full
NUM_SDG=<N>
DEFECT_DESC=<defect_spec.jsonl>
DEFECTS=(T+A T+B)          # Noms TEXTURE+TYPE. Pour mode=inference_only, dériver de ${CKPT}/ag_config.yaml → dataloader_train.dataset.anomaly_types (également imprimé par validate_checkpoint.py en phase 0). Pour mode=full, prendre des entrées DEFECT_DESC. Voir references/inference.md §Phase 0.
NUM_SEARCH_RUN=${num_search_run:-3}
NN_THRESHOLD=${nn_threshold:-0.4}
MODEL_SIZE=<2b|14b>
NUM_GPUS=${num_gpus:-1}
MAX_ITER=${max_iter:-75000}
SAVE_ITER=${save_iter:-5000}
VALIDATION_ITER=${validation_iter:-5000}
LR=${lr:-0.02}
BATCH_SIZE=${batch_size:-2}
IMAGE_SIZE=${image_size:-512}
VALIDATION_JSONL=${validation_jsonl:-}  # optionnel ; défini par phase 1 étape 2 si non fourni par l'utilisateur

BASE=results/${NAME}
JSONL=ag_inference/${NAME}/testcase.jsonl
ORIGINAL=${BASE}/original
SEARCHED=${BASE}/searched
ROUNDS=${BASE}/rounds
REGENS=${BASE}/regens

Préflight guard (mode produit uniquement)

Quand ANOMALYGEN_PRODUCT_MODE=1, exécutez .agents/skills/anomalygen-guard/scripts/preflight.py avant tout travail GPU et corrigez tout problème BLOCKED. --validation-jsonl est transféré uniquement quand l'utilisateur en a fourni un ; pour MODE=finetune_only, omettez --num-sdg s'il n'est pas fourni. Voir references/guard-and-custom-counts.md pour la commande complète du préflight avec tous les flags transférés et les vérifications d'entrées nulles validation-JSONL / allocate_samples.py.

Phase 0 — checkpoints

Lisez references/finetune.md §Phase 0 pour les exigences HF_TOKEN et ce qui est téléchargé (~140 GB). Vérifiez d'abord ; ne téléchargez que ce qui manque.

${ANOMALYGEN_SCRIPTS}/check.sh \
    || ${ANOMALYGEN_SCRIPTS}/download_checkpoints.sh

Phase 1 — fine-tune (ignorer quand MODE=inference_only)

Lisez references/finetune.md §Phase 1 pour la structure du dataset, les détails du template de config et la sélection du meilleur checkpoint. Quatre étapes : (1) valider le dataset / dériver les types d'anomalies, (2) générer la JSONL de validation (ignorer si l'utilisateur a fourni VALIDATION_JSONL), (3) générer la config d'entraînement — la montrer à l'utilisateur et demander la confirmation avant d'écrire — (4) lancer l'entraînement en arrière-plan. Puis dériver CKPT (le chemin encode MODEL_SIZE en majuscules) et STEP (étape avec le plus haut nn_score des logs de validation). Si MODE=finetune_only, arrêter après l'entraînement. Voir references/finetune-commands.md pour les commandes exactes des étapes 1–4 et l'extrait de dérivation CKPT/STEP.

Phase 2 — prep-testcase (ignorer quand MODE=finetune_only)

Lisez references/inference.md §Phase 2 pour les détails du routage AMP et le dimensionnement de n_seeds. Ne passez PAS --seeds — il est auto-calculé et n'est pas un flag reconnu. prep_testcase.sh utilise par défaut --mode inference (allocation uniforme sur les types de défauts, pas de plancher KPI), que la phase 2 utilise toujours.

${ANOMALYGEN_SCRIPTS}/prep_testcase.sh \
    --name ${NAME} --num-sdg ${NUM_SDG} \
    --dataset-dir ${DATASET_DIR} \
    --clean-dir ${CLEAN_DIR} \
    --defect-spec ${DEFECT_DESC} \
    --amp-output-dir ag_inference/${NAME}/amp \
    --output-jsonl ${JSONL}

Comptes per-défaut personnalisés : quand l'utilisateur spécifie les comptes par type de défaut, traduisez en --num-sdg plus un dict JSON --per-defect-counts (les types absents du dict obtiennent 0 ; la somme devrait égaler --num-sdg, sinon le script avertit sur stderr et utilise la somme override). Confirmez l'allocation quand l'intention est ambiguë. Voir references/guard-and-custom-counts.md pour l'exemple de commande --per-defect-counts complet et le détail de gestion d'ambiguïté.

Phase 3 — SDG → original/

Lisez references/inference.md §Phase 3 pour la validation JSONL par rapport au checkpoint, les mises en garde multi-GPU et la vérification de sortie.

python3 -m scripts.utilities.validate_checkpoint ${CKPT} --step ${STEP}
python3 -m scripts.utilities.validate_jsonl ${CKPT} ${JSONL}

${ANOMALYGEN_SCRIPTS}/run_sdg.sh \
    --checkpoint_dir ${CKPT} --step ${STEP} \
    --input_jsonl ${JSONL} --output_dir ${ORIGINAL} \
    --model_size ${MODEL_SIZE} --num_gpus ${NUM_GPUS}

${ANOMALYGEN_SCRIPTS}/verify_output.sh ${JSONL} ${ORIGINAL}

Phase 4 — eval original/

Lisez references/inference.md §Eval pour l'interprétation des scores et l'explication du compte des features. run_eval.sh écrit per_sample.csv et eval.log à l'intérieur de original/ et fusionne nn_score dans SDG_result.csv.

${ANOMALYGEN_SCRIPTS}/run_eval.sh \
    --real-path ${DATASET_DIR} --generated-path ${ORIGINAL} \
    --anomaly-types ${DEFECTS[@]}

Phase 5 — rounds de recherche per-sample

Lisez references/inference.md §Phase 5 pour la stratégie de tirage, les plages et la guidance re-AMP. Pour r dans 1..NUM_SEARCH_RUN :

1. Lisez le per_sample.csv du round précédent (ou ${ORIGINAL}/per_sample.csv pour r=1).
2. Écrivez ${ROUNDS}/round_${r}/draws.json avec (guidance, crop_ratio) sélectionné par échantillon.
3. Exécutez le round via ${ANOMALYGEN_SCRIPTS}/run_round.sh (SDG + eval ; le répertoire du round obtient sa propre sdg/{SDG_result.csv, per_sample.csv, eval.log}). Voir references/inference-commands.md §Phase 5 pour la commande complète et les flags.

NUM_SEARCH_RUN=0 est valide — ignorez entièrement cette phase et laissez la phase 6 cloner original/ dans searched/.

Phase 6 — assembler searched/ (couture uniquement)

Exécutez toujours l'assemblage (fonctionne avec 0 rounds — searched/ clone original/, donc la suite lit toujours searched/ indépendamment de num_search_run). Couture uniquement : copie les images gagnantes par index d'échantillon dans searched/ et reporte le nn_score / mnn_score per-sample depuis le per_sample.csv de chaque source-round sélectionné. Pas d'eval — la phase 7 émet le eval.log canonique.

mkdir -p ${ROUNDS}
python3 -m scripts.utilities.assemble_searched \
    --original-dir ${ORIGINAL} --original-csv ${ORIGINAL}/per_sample.csv \
    --rounds-dir ${ROUNDS} --searched-dir ${SEARCHED}

Phase 7 — filtrer + regénérer + eval (défaut nn_threshold=0.4)

La phase 7 s'exécute par défaut (nn_threshold=0.4) à chaque invocation mode=full et mode=inference_only ; passez nn_threshold=0 pour l'ignorer. Elle filtre searched/ par nn_threshold, regénère les échantillons supprimés via re-AMP (nouvel appairage (clean, submask) dans le même type de défaut) pour jusqu'à 5 tentatives, puis se replie sur les meilleurs regens non-passants et enfin sur les originals supprimés, donc le bucket final égale toujours num_SDG.

Exécutez python3 -m scripts.utilities.filter_with_regen. Elle exécute le run_eval.sh final en interne — l'unique eval par rapport à searched/. Lisez references/inference.md §Phase 7 pour les mécaniques de regen, le traçage de colonne source et le schéma regens/regen_summary.csv ; voir references/inference-commands.md §Phase 7 pour la commande complète et les flags.

Layout de sortie

Chaque bucket qui est évalué porte la même triade de fichiers : SDG_result.csv (params de génération + nn_score), per_sample.csv (nn et mnn per-sample), et eval.log (FID agrégé / moyenne per-défaut). Les buckets vivent sous results/<name>/ comme original/ (phases 3+4), searched/ (couture phase 6 + filtrage+regen+eval phase 7), rounds/round_NN/ (phase 5, plus search_summary.csv), et regens/regen_NN/ (phase 7, plus regen_summary.csv).

Voir references/output-layout.md pour l'arborescence complète avec annotations par fichier et la checklist Vérification post-exécution (comptes d'images par bucket, vérifications de lignes search_summary.csv / regen_summary.csv, et les champs nn_score / mnn_score / fid per-type dans chaque eval.log).

Gestion des erreurs

Les modes de défaillance courants du pipeline (répertoires de masques manquants, sortie AMP courte/vide et l'arrêt « 0 entries written », reprise SDG mid-round, step hors-limites) sont couverts dans references/error-handling.md ; voir aussi references/finetune.md et references/inference.md pour la gestion des erreurs phase-spécifiques.