Compétence DEFT en extraction et intégration

Vous êtes l'opérateur du workflow DEFT « intégration puis extraction » pour la zone d'intérêt (AOI) VCN. Votre tâche consiste à prendre un fichier Parquet d’images cibles faibles (résultat de l’analyse des écarts ou du routage) et un ensemble de sources, puis à produire un fichier Parquet dédupliqué d’images sources extraites qui ressemblent aux cibles — prêtes à être utilisées pour le prochain cycle d’entraînement.

Le workflow est fixe et déterministe : intégration des cibles, intégration du pool de sources, puis extraction des plus proches voisins. Le fichier Parquet généré à chaque étape sert d’entrée à l’étape suivante. Il n’y a ni recherche itérative, ni passe de regroupement en grappes, ni sélection impliquant une intervention humaine : la profondeur provient du choix du bon encodeur et du bon « topn », et non d’une analyse en plusieurs phases.

L’ensemble du processus n’est qu’une fine couche d’encapsulation autour de trois appels directs à `docker run` 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 -e [remplacements Hydra...] — en transmettant les embeddings image_embeddings -e … pour l’embedding et les voisins les plus proches TMM nearest_neighbors -e … pour l’exploration. L'option -e pointe vers un fichier YAML qui fournit des valeurs par défaut pour le schéma de la sous-tâche ; tout ce qui suit est une simple substitution Hydra (clé=valeur) qui remplace de manière sélective les champs de la spécification à chaque exécution. (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 omis ici.) Récupérez l’image une fois si elle n’est pas mise en cache : docker pull "$DS_IMAGE" (après avoir résolu $DS_IMAGE conformément à la configuration).

Les clés du schéma peuvent être renommées entre les versions de data-services (la compétence RCA a vu inference_csv → inference_results_dir, output_dir → results_dir). En cas de doute, examinez le schéma réel une fois par image : ` docker run --rm "$DS_IMAGE" embedding image_embeddings --cfg=job ` et ... `tmm nearest_neighbors --cfg=job`.

Entrées

1. Fichier Parquet cible — le résultat de l’analyse des écarts, généralement mining_gaps.parquet issu de tao-route-visual-changenet-samples (ou gaps.parquet issu de tao-analyze-gaps-visual-changenet si le routage a été ignoré). Colonne obligatoire : filepath. Si la colonne label est également présente, un filtrage tenant compte des étiquettes est disponible pendant l’exploration ; sinon, la tâche d’exploration ignore silencieusement le filtre.
2. Pool source — un fichier Parquet contenant les images candidates à analyser, comportant une colonne filepath. Si l’utilisateur ne dispose que d’un fichier CSV, il doit le convertir en fichier Parquet avec les mêmes colonnes avant l’étape 2. Pour le filtrage tenant compte des étiquettes, le pool doit également comporter une colonne label.
3. Fichier de spécifications d’encodage — un fichier YAML contenant model, model_path, batch_size et (uniquement lorsque model_path est un fichier TAO .pth/.ckpt) model_config_path. Réutilisé aux étapes 1 et 2 ;input_parquet/output_parquet sont fournis à chaque exécution sous forme de remplacements par Hydra. La même spécification DOIT régir les deux étapes d’encodage — les encodages provenant d’encodeurs différents ne sont pas comparables, et l’incompatibilité des encodeurs est la cause la plus fréquente des rapports indiquant que « les images extraites semblent sans rapport ».
4. Fichier de spécifications d’extraction — un fichier YAML contenant topn, knn_metric, filter_by_label et (rarement modifiés)source_embed_column_name/target_embed_column_name.source_parquet/target_parquet/output_parquet sont des remplacements effectués par Hydra au moment de l’exécution. Les représentations SigLIP et CLIP doivent utiliser knn_metric : cosine. Lorsque filter_by_label est défini sur true mais que l’un des fichiers Parquet de représentation ne comporte pas de colonne d’étiquette, le conteneur enregistre un avertissement et poursuit l’exécution sans filtrage.

Configuration

Résolvez l’URI concret tao_toolkit.data_services à partir du fichier versions.yaml 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 bien présents avant toute autre opération. Un GPU est requis à la fois pour le passage direct de l’encodeur et pour la recherche k-NN via cuML/cuDF ; ces deux étapes échouent sans CUDA.

# Résoudre l'URI tao_toolkit.data_services → l'URI concret nvcr.io/... à partir du fichier 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"

Chaque chemin d’accès de l’hôte que le conteneur lit ou écrit doit être monté via un bind mount. L’approche la plus prévisible consiste à monter la racine de l’espace de travail avec des chemins identiques à l’intérieur et à l’extérieur du conteneur, puis à réutiliser un seul alias $DOCKER pour les trois invocations :

WORKSPACE=
DOCKER="docker run --gpus all --rm --ipc=host -v $WORKSPACE:$WORKSPACE -w $WORKSPACE $DS_IMAGE"

Ne passez pas l’option --user $(id -u):$(id -g) — cela déclenche une erreur KeyError getpwuid() lors de l’importation des transformateurs avant même que le travail ne commence. Le conteneur s’exécute en tant que root ; la commande chown rétablit ensuite l’UID de l’hôte.

Créez les deux fichiers de spécification une fois par itération, en les plaçant dans $WORKSPACE afin que l’argument -e soit résolu des deux côtés du montage ; les valeurs propres à chaque exécution ne figurent pas dans la spécification et sont transmises sous forme de substitutions Hydra. Si le pool de données source est au format CSV, convertissez-le au préalable en Parquet (en conservant le chemin d’accès au fichier et l’étiquette, le cas échéant). Le fichier embedding_spec.yaml par défaut utilise model: SigLIP, model_path: google/siglip-base-patch16-224, batch_size: 64; le fichier mining_spec.yaml par défaut utilise topn : 5, knn_metric : cosine, filter_by_label : « false » (entre guillemets — le schéma l'interprète comme une chaîne de caractères).

Consultez le fichier references/setup.md pour obtenir les notes complètes sur l’environnement, la gestion de TAO_SKILL_BANK_PATH, la justification du montage de chemin d’accès, la solution de contournement pour le changement de propriétaire (chown) de getpwuid, l’extrait de code CSV-vers-Parquet et les blocs de création de fichiers de spécification tels quels.

Méthode

Trois commandes, dans l’ordre. Le fichier Parquet généré par chaque commande sert d’entrée à la commande suivante. Exécutez-les en Bash standard ; l’alias $DOCKER défini dans la configuration gère le conteneur, le GPU et les montages. Chaque invocation suit le même schéma : -e pour les valeurs par défaut intégrées, puis quelques modifications Hydra pour les chemins spécifiques à l’exécution.

Étape 1 — Intégrer les images cibles

$DOCKER embedding image_embeddings \
    -e  \
    input_parquet= \
    output_parquet=

Lit la sortie de l’analyse des lacunes / du routage et écrit un fichier Parquet contenant le chemin d’accès, l’intégration et toutes les colonnes de métadonnées supplémentaires (par exemple, label, siamese_score, weakness) reprises telles quelles depuis l’entrée. Affichez le schéma de sortie (pd.read_parquet(...).columns) sur la sortie standard (stdout) afin que le hook « script-check » puisse vérifier que la colonne d’encodage existe bel et bien.

Si vous devez remplacer model / model_path / batch_size pour une exécution sans modifier la spécification, ajoutez-les en tant que remplacements Hydra (par exemple model_path=...).

Étape 2 — Intégrer le pool source

$DOCKER embedding image_embeddings \
    -e  \
    input_parquet= \
    output_parquet=

Même structure de commande qu’à l’étape 1, appliquée au pool source. Utilisez le fichier embedding_spec.yaml identique à celui de l’étape 1, et ne modifiez pas ici les paramètres model / model_path / batch_size — des configurations d’encodeur différentes entre les deux étapes produisent des représentations non comparables.

Étape 3 — Recherche des plus proches voisins

$DOCKER tmm nearest_neighbors \
    -e  \
    source_parquet= \
    target_parquet= \
    output_parquet=

Pour chaque embedding cible, cette commande identifie les topn embeddings source les plus proches selon la métrique choisie, élimine les doublons entre les cibles et génère un fichier Parquet à colonne unique (chemin d’accès) contenant les chemins source uniques extraits. Le conteneur génère également un fichier mining_summary.txt à côté du fichier Parquet de sortie, contenant : le nombre de requêtes, le nombre de voisins, les doublons supprimés et (lorsque le filtrage par étiquette est activé) le nombre de paires conservées par rapport à celles supprimées. Ajustez les paramètres `topn`, `knn_metric` ou `filter_by_label` via une redéfinition Hydra en ligne lors du balayage (par exemple, `topn=10`) — il n’est pas nécessaire de réécrire la spécification.

Lorsque filter_by_label=true mais que l’un des fichiers Parquet d’encodage manque la colonne d’étiquette, le conteneur enregistre un avertissement et poursuit l’opération sans filtrage. Si le résultat de l’exploration semble plus volumineux que prévu ou contient des paires inter-étiquettes, consultez le journal Docker à la recherche de cet avertissement avant de supposer que la tâche s’est déroulée correctement.

Consultez le fichier references/reference-invocation.md pour obtenir la recette de bout en bout minimale à copier-coller et modifier (qui résout $DS_IMAGE, écrit les deux spécifications, exécute les trois étapes, attribue les droits de propriété aux sorties et affiche le nombre de lignes) à exécuter sous la forme d’un seul bloc Bash en continu.

Sorties et rapport

Enregistrez tout dans un dossier horodaté situé dans le répertoire de l’expérience / itération. Obtenez l’horodatage réel en exécutant la commande `date +%Y-%m-%d_%H%M%S ` dans Bash — ne le codez PAS en dur et ne le devinez PAS. Si l’utilisateur spécifie un chemin de sortie personnalisé, utilisez-le directement tout en conservant la même structure interne. Le hook de packaging ajoute automatiquement les dossiers `mining_config/` et le fichier ` claude_session.jsonl ` lorsque `Mining_Report.md ` est écrit.

Le fichier Parquet issu de l’exploration est l’artefact utilisé en aval par l’entraînement. Les deux fichiers Parquet d’embedding sont intermédiaires mais méritent d’être conservés — ils sont réutilisables sur plusieurs exécutions d’exploration portant sur le même ensemble de sources, et constituent la seule source à consulter lorsqu’un rapport « apparemment sans rapport » nécessite un débogage au niveau de l’encodeur.

Consultez references/outputs-and-reporting.md pour connaître la structure complète du répertoire de sortie et le modèle exact de Mining_Report.md (Verdict, Entrées, Cohérence de l’encodeur, Exécution de l’exploration, Répartition par étiquette, Validité des résultats, Actions recommandées ; respectez un nombre de mots compris entre 600 et 1 200).

Pièges courants

L’erreur la plus fréquente réside dans l’incompatibilité des encodeurs entre les deux étapes d’encodage — la cause la plus courante de résultats de mining erronés ; les deux étapes doivent utiliser le même fichier embedding_spec.yaml. Autres pièges récurrents : passer l’option --user ( erreur KeyError « getpwuid » ), sauter une étape d’embedding, une colonne d’étiquettes manquante rendant silencieusement inutile l ’option filter_by_label=true, des fichiers de spécification situés en dehors de $WORKSPACE, des ??? sentinelles non résolues, des points de contrôle TAO sans model_config_path, des pools de sources CSV alimentés directement, des incohérences entre les chemins d’accès de l’hôte et du conteneur, l’absence de GPU, une image non récupérée ou une balise :latest, et une taille de source supérieure à topn × N_targets (ce qui est normal — indiquez le nombre réel de données extraites).

Consultez references/troubleshooting.md pour obtenir la liste complète des pièges avec les erreurs exactes, leurs causes et les solutions.

Ordre d’exécution

1. Déterminez la valeur de DS_IMAGE à partir du fichier versions.yaml (images.tao_toolkit.data_services), puis exécutez une seule fois les commandes docker info, nvidia-smi et docker image inspect "$DS_IMAGE" (en récupérant l’image si elle est manquante) pour valider l’environnement. Interrompez le processus avec un message clair en cas d’échec.
2. Exécutez ` date +%Y-%m-%d_%H%M%S ` pour obtenir l’horodatage ; créez les répertoires ` `, `/mining_results/` et `/`.
3. Écrivez les fichiers `embedding_spec.yaml ` et `mining_spec.yaml` dans le répertoire horodaté, en indiquant le choix de l’encodeur et les paramètres de minage. Conservez-les sous $WORKSPACE afin que le chemin `-e` soit résolu à l’intérieur du conteneur.
4. Si le pool source est au format CSV, convertissez-le d’abord au format Parquet (en conservant le chemin d’accès au fichier et l’étiquette).
5. Exécutez l’étape 1 (intégration des cibles) via `docker run … embedding image_embeddings -e embedding_spec.yaml input_parquet=… output_parquet=…`. Affichez le nombre de lignes et de colonnes du fichier Parquet de sortie sur la sortie standard (stdout).
6. Exécutez l’étape 2 (intégration du pool source) avec le fichier ` embedding_spec.yaml ` identique à celui de l’étape 1. Affichez le nombre de lignes et de colonnes du fichier Parquet de sortie.
7. Exécutez l’étape 3 (extraction des voisins les plus proches) via ` docker run … tmm nearest_neighbors -e mining_spec.yaml source_parquet=… target_parquet=… output_parquet=…`. Vérifiez que le fichier ` mining_summary.txt` a bien été créé à côté de `mined.parquet`.
8. Calculez la répartition par étiquette (section 5) en joignant le fichier Parquet des représentations cibles à la sortie de l’extraction sur le chemin d’accès, si les deux contiennent des étiquettes.
9. Écrivez enfin le fichier Mining_Report.md — son écriture déclenche le hook de packaging, qui copie les journaux de session et la configuration de la compétence.