Compétence en analyse des écarts pour TAO VCN Classify

Vous êtes analyste des résultats d’inférence de NVIDIA TAO VCN Classify (Visual Component Net). Votre mission consiste à identifier les échantillons les plus faibles pour chaque étiquette de référence en mesurant la distance signée par rapport au seuil de décision dans la mauvaise direction, puis à les mettre en évidence en vue d’une augmentation ou d’un réétiquetage en aval.

Cette compétence est volontairement légère. La tête de classification de VCN est une frontière binaire à score unique (PASS vs NO_PASS selon le siamese_score) ; l’analyse est donc de nature computationnelle, et non investigative. L’ensemble du calcul s’effectue via une seule invocation directe de Docker sur l’image tao_toolkit.data_services déclarée dans versions.yaml (résolue lors de l’exécution — voir Configuration). Le point d’entrée du conteneur prend la forme [hydra overrides...]; nous lui transmettons gap_analysis vcn_aoi key=value …. Chaque remplacement est une simple paire clé=valeur Hydra qui remplace de manière sélective le schéma GapAnalysisConfig du script (les valeurs par défaut sont intégrées au conteneur ; inspectez-le avec `docker run ... gap_analysis vcn_aoi --cfg=job`). (Il n’y a pas de mot-clé « dataset » à l’intérieur du conteneur — il s’agit du préfixe « pillar » du lanceur TAO, qui est supprimé ici.) Vous n’ avez pas besoin d’analyse déléguée, d’audits d’images en plusieurs phases ou de regroupement par type de composant — VCN n’expose pas ces dimensions. Examinez uniquement un petit ensemble d’échantillons faibles représentatifs pour qualifier les lacunes une fois que le conteneur a renvoyé ses résultats.

L’interface CLI peut varier selon les versions du conteneur data-services. Si l’appel de gap_analysis vcn_aoi échoue lors de l’analyse des arguments, examinez le schéma réel une fois par image à l’aide de la commande docker run --rm "$DS_IMAGE" gap_analysis vcn_aoi --cfg=job et harmonisez les clés renommées (par exemple, inference_csv vs inference_results_dir, output_dir vs results_dir) avant de réessayer. Le nom du fichier Parquet de sortie est kpi_gaps.parquet.

Données d’entrée

1. Répertoire des résultats de l’expérience — contient le fichier ` inference/inference.csv ` issu de l’inférence TAO VCN Classify. Colonnes requises : `input_path`, `object_name`, `label`, `siamese_score`. Transmettez le répertoire (par exemple inference/latest/), et non le fichier CSV — le conteneur lit le fichier inference_results_dir/inference.csv.
2. Répertoire du code/de la configuration d’entraînement — contient le fichier YAML d’entraînement VCN. Le conteneur lit les fichiers dataset.classify.input_map (liste des conditions d’éclairage) et dataset.classify.image_ext à partir de celui-ci pour développer chaque échantillon faible en une ligne par condition d’éclairage.
3. Répertoire « dataset » — la racine des images est ajoutée au début du chemin d’accès relatif « input_path » de chaque ligne (kpi_media_path).
4. Remplacements de schéma — min_recall, top_k_per_label et, en option, un seuil fixe sont transmis en tant que remplacements Hydra (valeurs par défaut : min_recall=1,0, top_k_per_label=50, threshold=-1,0, ce qui signifie un balayage). top_k_per_label doit être un entier positif — son omission fait basculer le conteneur en mode « filtre en dessous du seuil », ce qui, avec min_recall=1,0, ne renvoie que les erreurs de classification PASS et aucune ligne NO_PASS. Voir « Pièges courants ».

Configuration

Le balayage de seuil, le classement des faiblesses et l’expansion par éclairage s’exécutent tous au sein de l’image tao_toolkit.data_services déclarée dans versions.yaml. Résolvez l’URI concrète une seule fois au début de l’exécution, puis vérifiez que Docker, la boîte à outils de conteneurs NVIDIA et un GPU sont présents, et assurez-vous que l’image est mise en cache :

# Résoudre tao_toolkit.data_services → URI concrète nvcr.io/... à partir de versions.yaml
DS_IMAGE=$(python3 -c "import yaml,os; print(yaml.safe_load(open(os.environ['TAO_SKILL_BANK_PATH']+'/versions.yaml'))['images']['tao_toolkit']['data_services'])")
echo "DS_IMAGE=$DS_IMAGE"

docker info > /dev/null && echo "OK : Docker"
nvidia-smi > /dev/null && echo "OK : GPU"
docker image inspect "$DS_IMAGE" > /dev/null \
  || docker pull "$DS_IMAGE"

TAO_SKILL_BANK_PATH est généralement exportée par la banque de compétences installée. Si elle n’est pas définie, pointez-la vers la racine du dépôt de la banque de compétences avant la résolution. Un GPU est requis ; interrompre la procédure dès le début sur un hôte sans GPU évite une erreur tardive source de confusion.

Trois règles de configuration sont essentielles et peuvent facilement prêter à confusion :

• Montage des chemins d’accès — chaque chemin d’accès de l’hôte que le conteneur lit ou écrit (inference.csv, fichier YAML d’entraînement, racine de l’image du jeu de données, répertoire de sortie) doit être monté en bind mount, le plus simplement avec -v $WORKSPACE:$WORKSPACE -w $WORKSPACE afin que les chemins absolus soient résolus de manière identique des deux côtés.
• Ne passez pas --user $(id -u):$(id -g) — cela déclenche une erreur KeyError : « getpwuid(): uid not found: » lors de l’importation des transformateurs par le conteneur ; la commande chown renvoie ensuite l’UID de l’hôte.
• -e est obligatoire, et non facultatif — les images actuelles l’exigent impérativement et se terminent par une erreur ValueError : « La sous-tâche vcn_aoi nécessite l’argument suivant : -e/--experiment_spec_file » avant d’analyser les remplacements de la ligne de commande.

Consultez le fichier references/container-setup.md pour connaître le modèle complet de montage de chemins d’accès, la justification de l’utilisation de--user/chown et de la commande chown d’Alpine, les recommandations relatives à l’utilisation de plusieurs options --v, ainsi que les détails concernant l’exigence -e .

Méthode

L’ensemble de la compétence consiste en un seul appel `docker run` suivi d’un petit contrôle visuel ponctuel. Le conteneur effectue en interne les étapes 1 à 4 (balayage de seuil, notation des faiblesses, sélection des K meilleurs, expansion par éclairage). Vous gérez l’étape 5 (contrôle visuel ponctuel) directement avec l’outil Read.

Étapes 1 à 4 — Exécuter le conteneur

$DOCKER gap_analysis vcn_aoi \
    inference_results_dir=/inference// \
    train_config=/train.yaml \
    kpi_media_path= \
    results_dir= \
    top_k_per_label=50

Toujours passer top_k_per_label. C’est l’argument qui fait passer le conteneur du filtre par défaut « échantillons inférieurs au seuil » à un classement top-K-par-étiquette correct. Avec min_recall=1,0, le seuil est, par construction, égal ou inférieur à chaque score NO_PASS ; le filtre « en dessous du seuil » ne renvoie donc QUE les lignes PASS mal classées et aucune ligne NO_PASS — ce qui est inutile en tant que file d’attente d’augmentation. Lorsque top_k_per_label est défini sur un entier positif (soit dans la spécification, soit via une redéfinition Hydra), le conteneur calcule la faiblesse signée par rapport au seuil pour chaque ligne et fait remonter les K plus faibles par étiquette de vérité de base, ce qui constitue la sortie classée par étiquette utilisée par les étapes en aval.

Lit le fichier inference.csv, parcourt chaque valeur unique de siamese_score plus une juste en dessous du minimum, conserve les candidats dont le rappel de la classe NO_PASS est ≥ min_recall (avec une tolérance de 1e-12 ), puis choisit le seuil présentant le meilleur F1 (en cas d’égalité : précision, puis valeur du seuil). Pour chaque ligne, calcule la faiblesse signée par rapport à ce seuil (positive = classification erronée, négative = correcte, amplitude = marge). Trie par faiblesse en ordre décroissant et sélectionne les top_k_per_label les plus élevés par étiquette de référence, puis développe chaque ligne faible en une ligne par condition d’éclairage à l’aide de dataset.classify.input_map et dataset.classify.image_ext issus du fichier YAML d’entraînement.

Si aucun seuil candidat n’atteint l’objectif de rappel, le conteneur se termine avec un code de sortie non nul et écrit le fichier unreachable_kpi.txt dans le répertoire results_dir, expliquant quel rappel le modèle peut réellement atteindre. Dans ce cas, arrêtez l’analyse après l’appel Docker, rédigez un rapport d’une seule section expliquant que le modèle est fondamentalement incapable d’atteindre le KPI quel que soit le point de fonctionnement, et recommandez un réentraînement ou un réétiquetage — ignorez le contrôle visuel ponctuel.

Le conteneur écrit dans le répertoire « results_dir »:

Affichez le résumé de la sortie standard du conteneur (seuil choisi, nombre de lignes conservées, répartition par étiquette) sur votre propre sortie standard afin que le hook script-check puisse vérifier la sortie générée par l'exécution.

Étape 5 — Contrôle visuel ponctuel (petit, fixe)

Ignorez cette étape si le fichier unreachable_kpi.txt existe. Sinon, utilisez l’outil « Read » pour afficher les 5 échantillons PASS les plus faibles et les 5 échantillons NO_PASS les plus faibles issus du fichier kpi_gaps.parquet (dédupliqués à une ligne par échantillon, en utilisant le chemin d’accès FIRST-lighting), classez chacun d’entre eux dans l’une des catégories suivantes : « étiquetage erroné », « cas limite », « qualité des données » ou « systématique », puis copiez chaque image visualisée (redimensionnée à 128×128 si le PIL est disponible, sinon copiez-la simplement) dans /rca_images/. Il s’agit de la seule inspection d’images requise — ne consultez pas des dizaines d’images, n’effectuez pas de regroupement par mode de défaillance et ne vérifiez pas les images de référence (VCN ne dispose pas d’images de référence).

Consultez le fichier references/visual-spot-check.md pour connaître l’ordre exact de sélection des échantillons, la règle de déduplication par éclairage, la définition complète de chaque catégorie de verdict et les détails relatifs à la copie des images.

Appel de référence

Copiez-collez et modifiez l’espace de travail, les quatre chemins d’accès et les deux paramètres numériques ; cela exécute le processus de bout en bout. Capturez la sortie standard (stdout) afin que le hook script-check puisse voir le nombre de lignes.

WORKSPACE=           # monté de manière identique à l’intérieur du conteneur
EXP_DIR=     # contient inference/inference.csv et train.yaml ; doit se trouver à l’intérieur de $WORKSPACE
DATASET_ROOT=         # racine des images pour les entrées input_path du fichier inference.csv ; doit se trouver dans $WORKSPACE
MIN_RECALL=1.0                       # valeur par défaut « zéro omission » ; à réduire si les exigences des indicateurs de performance sont assouplies
TOP_K=50                             # budget d’augmentation par étiquette
OUT="$EXP_DIR/rca_results/$(date +%Y-%m-%d_%H%M%S)"
SPEC="$OUT/vcn_aoi_spec.yaml"
IMG=$(python3 -c "import yaml,os; print(yaml.safe_load(open(os.environ['TAO_SKILL_BANK_PATH']+'/versions.yaml'))['images']['tao_toolkit']['data_services'])")

mkdir -p "$OUT"

# Écrire la spécification d’analyse des écarts pour cette exécution
cat > "$SPEC" <<EOF
min_recall: $MIN_RECALL
top_k_per_label: $TOP_K
EOF

docker run --gpus all --rm --ipc=host \
    -v "$WORKSPACE:$WORKSPACE" -w "$WORKSPACE" \
    "$IMG" gap_analysis vcn_aoi \
    -e "$SPEC" \
    inference_results_dir="$EXP_DIR/inference/latest/" \
    train_config="$EXP_DIR/train.yaml" \
    kpi_media_path="$DATASET_ROOT" \
    results_dir="$OUT"

# Le conteneur écrit en tant qu’utilisateur root avec l’option --user désactivée ; réattribuer les droits de propriété à l’UID de l’hôte si nécessaire.
docker run --rm -v "$WORKSPACE:/w" alpine chown -R "$(id -u):$(id -g)" "/w/$(realpath --relative-to="$WORKSPACE" "$OUT")"

# Affichage de contrôle pour que le hook script-check voie des nombres réels
python3 - "$OUT" << 'PYEOF'
import json, os, sys
out = sys.argv[1]
unreachable = os.path.join(out, "unreachable_kpi.txt")
if os.path.isfile(unreachable):
    print("KPI INACCESSIBLE — voir", unreachable)
    sys.exit(0)
with open(os.path.join(out, "threshold.txt")) as f:
    print("seuil :", f.read().strip())
with open(os.path.join(out, "metrics.json")) as f:
    m = json.load(f)
print(f"précision={m['precision']:.4f} rappel={m['recall']:.4f} F1={m['f1']:.4f}")
import pandas as pd
df = pd.read_parquet(os.path.join(out, "kpi_gaps.parquet"))
print(f"kpi_gaps.parquet : rows={len(df)}, cols={list(df.columns)}")
print(df['label'].value_counts())
PYEOF

Résultats

Enregistrer tout dans un dossier horodaté situé dans le répertoire des résultats de l'expérience. Les résultats du conteneur y sont directement enregistrés ; le contrôle visuel ponctuel écrit dans le répertoire rca_images/; tout hook de packaging d'exécution peut ajouter des artefacts de capture session/config après l'écriture du fichier RCA_Report.md.

/rca_results/AAAA-MM-JJ_HHMMSS/
├── RCA_Report.md              # Rapport complet d’analyse des écarts (à rédiger par vos soins)
├── kpi_gaps.parquet           # Conteneur : les K plus faibles par étiquette, détaillés par éclairage
├── threshold.txt              # Conteneur : seuil de décision choisi (nombre à virgule flottante unique)
├── metrics.json               # Conteneur : matrice de confusion + statistiques de distribution par étiquette
├── weak_samples_breakdown.txt # Conteneur : nombres par étiquette / échantillons mal classés / nombres marginaux
├── unreachable_kpi.txt        # Conteneur : UNIQUEMENT lorsqu’aucun seuil ne satisfait à min_recall
├── rca_images/                # Vous : vignettes des 10 échantillons faibles visualisés
├── rca_config/                # Copié automatiquement par le hook
└── session log/artifacts      # Facultatif, capture du packaging dépendant de l’exécution

Au début de l’exécution, récupérez l’horodatage réel en exécutant la commande `date +%Y-%m-%d_%H%M%S ` dans Bash. Ne l’indiquez PAS de manière statique et ne le devinez PAS. Si l’utilisateur spécifie un chemin de sortie personnalisé, utilisez-le à la place tout en conservant la même structure interne.

Pièges courants

Le mode de défaillance le plus grave consiste à oublier top_k_per_label lorsque min_recall=1.0: à ce niveau de rappel, le seuil choisi est égal ou inférieur à chaque score NO_PASS ; ainsi, sans top_k_per_label, le conteneur revient à un filtre « échantillons inférieurs au seuil » qui renvoie UNIQUEMENT les lignes PASS mal classées et zéro ligne NO_PASS, ce qui perturbe la file d’attente d’augmentation. Incluez toujours une valeur positive explicite pour top_k_per_label (valeur par défaut : 50) dans la spécification ou en tant que paramètre de remplacement Hydra.

Consultez references/pitfalls.md pour la liste de contrôle complète, couvrant : l’oubli de top_k_per_label; le passage de l’option --user; l’appel avec uniquement des modifications Hydra (sans -e ) ; un fichier de spécification en dehors de $WORKSPACE; un fichier de spécification contenant des sentinelles ??? non résolues ; une image non récupérée / une balise erronée ; incompatibilité de chemin de montage ; fichier unreachable_kpi.txt écrit ; fichier inference.csv manquant des colonnes obligatoires ; YAML d’entraînement manquant dataset.classify.input_map ou image_ext; kpi_media_path ne correspondant pas aux préfixes d’input_path; et aucun GPU détecté depuis l’intérieur du conteneur.

Structure du rapport

Rédigez le fichier RCA_Report.md sous la forme d’une analyse concise (1 000 à 1 800 mots) des lacunes de calcul — la profondeur provient de chiffres précis et d’une liste d’actions claire, et non d’un récit. Le modèle complet du rapport (7 sections : Verdict, Sélection des seuils, Répartition des faiblesses, Échantillons les plus faibles Top-K, Vérification visuelle ponctuelle, Ventilation par étiquette, Actions recommandées — avec la matrice de confusion et la mise en page des tableaux) se trouve dans references/output-template.md. Lorsque le fichier unreachable_kpi.txt existe, remplacez les sections 3 à 6 par une seule section concise reprenant le contenu de ce fichier et réduisez la section 7 à une seule recommandation : réentraînement ou réétiquetage.

Ordre d’exécution

1. Résolvez DS_IMAGE à partir de versions.yaml (images.tao_toolkit.data_services), puis exécutez une fois les commandes docker info, nvidia-smi et docker image inspect "$DS_IMAGE" (en effectuant un pull si l’image est manquante) pour valider l’environnement. Interrompez le processus avec un message clair en cas d’échec de l’une de ces commandes.
2. Exécutez « date +%Y-%m-%d_%H%M%S » pour obtenir l’horodatage ; créez les répertoires « /rca_results/ » et «/ ».
3. Écrivez le fichier ` vcn_aoi_spec.yaml ` dans le répertoire horodaté en renseignant les champs `min_recall ` et `top_k_per_label`. Conservez-le sous `$WORKSPACE ` afin que le chemin `-e ` soit résolu à l’intérieur du conteneur.
4. Exécutez ` docker run … "$DS_IMAGE" gap_analysis vcn_aoi -e vcn_aoi_spec.yaml inference_results_dir=… train_config=… kpi_media_path=… output_dir=…`. Le conteneur écrit les fichiers kpi_gaps.parquet, threshold.txt, metrics.json et weak_samples_breakdown.txt dans le répertoire results_dir. Affichez le seuil choisi et le nombre de lignes conservées sur la sortie standard (stdout) afin que le hook script-check puisse vérifier la sortie générée par l’exécution.
5. Si le fichier unreachable_kpi.txt existe, ignorez l’étape 6 et générez le rapport abrégé. Sinon, continuez.
6. Sélectionnez 10 échantillons faibles (les 5 PASS les plus faibles + les 5 NO_PASS les plus faibles) dans kpi_gaps.parquet, affichez chaque image de test avec Read, classez-les, puis copiez-les dans le répertoire rca_images/.
7. Écrivez RCA_Report.md en dernier — son écriture déclenche le hook de packaging, qui copie les journaux de session et la configuration de la compétence en parallèle.