TAO Mine OD Images (Appariement de voisins uniques)

Utilisez cette skill pour exécuter l'extraction de données TAO Data Services TMM unique-neighbor matching pour la détection d'objets. La skill consomme les fichiers parquet source et cible pré-embarqués et écrit un répertoire de sorties incluant final_unique_files.parquet et summary.json. Elle ne calcule pas les embeddings ; les étapes en amont doivent d'abord produire les fichiers parquet source et cible embarqués.

Le point d'entrée du conteneur est :

tmm unique_neighbor_matching -e /absolute/path/to/unique_neighbor_matching.yaml

Inputs

L'utilisateur peut fournir soit une spécification existante, soit les champs nécessaires pour en générer une.

Champs de spécification requis :

Champs optionnels courants :

Les deux parquets d'entrée doivent contenir les colonnes chemin de fichier et embedding. Les embeddings source et cible doivent avoir été produits par le même encodeur ; des encodeurs mal appariés produisent des résultats aberrants.

Le modèle par défaut est assets/default_unique_neighbor_matching.yaml.

Quick Start

Exécutez à partir de la racine du repo tao-skill-bank. Résolvez l'image TAO Data Services épinglée à partir de versions.yaml, vérifiez la spécification, montez la racine d'exécution avec des chemins identiques hôte/conteneur et transmettez les logs Docker.

Écrivez la spécification dans le répertoire de sortie. L'exécution ne la conserve pas, donc un ensemble extrait ne porte autrement aucune trace du budget, de la politique d'allocation ou de la liste de classes rares qui l'a produit — et ces éléments décident quelles images ont été sélectionnées. Les conserver ensemble rend la sélection récupérable à partir de la seule exécution.

OUTPUT_DIR=/absolute/path/for/this/run           # output_dir in the spec
SPEC="$OUTPUT_DIR/unique_neighbor_matching.yaml" # spec lives beside its outputs
RUN_ROOT=/absolute/path/that/contains/specs/data/and/results
GPU_COUNT=1

python3 skills/data/tao-mine-od-images/scripts/verify_unique_neighbor_matching_spec.py \
  --spec "$SPEC"

DS_IMAGE=nvcr.io/nvidia/tao/tao-toolkit:7.2.0-data-services  # versions-key: images.tao_toolkit.data_services

docker run --rm --gpus "$GPU_COUNT" --shm-size=8g --network=host \
  -v "$RUN_ROOT:$RUN_ROOT" \
  -w "$RUN_ROOT" \
  "$DS_IMAGE" \
  tmm unique_neighbor_matching -e "$SPEC"

Ne passez pas --user $(id -u):$(id -g) au conteneur TAO data-services ; certaines images TAO DS appellent getpass.getuser() au démarrage et échouent quand l'UID n'est pas dans /etc/passwd.

Generate A Spec

Si l'utilisateur fournit les chemins source/cible et un répertoire de sortie au lieu d'une spécification prête, copiez le modèle et remplissez les null. Chaque valeur d'ajustement qu'il porte déjà est celle que cette étape souhaite — ne changez une valeur que délibérément.

cp skills/data/tao-mine-od-images/assets/default_unique_neighbor_matching.yaml "$SPEC"

Remplissez source_path, target_path, output_dir et desired_unique_count, tous comme chemins absolus, puis validez :

python3 skills/data/tao-mine-od-images/scripts/verify_unique_neighbor_matching_spec.py --spec "$SPEC"

source_path: /absolute/path/source_embeddings.parquet
target_path: /absolute/path/target_embeddings.parquet
output_dir: /absolute/path/results/mining_output
desired_unique_count: 500
allocation_policy: global          # ou class_stratified — voir ci-dessous
distance_metric: euclidean

Pour le mode stratifié par classe, définissez allocation_policy: class_stratified et fournissez rare_class_list, source_detection_file, target_detection_file et detection_format. verify rejette la politique sans eux : en l'absence de ces champs, l'extracteur revient à un appariement global, qui extrait les mauvaises images plutôt que d'échouer.

Le modèle est le seul endroit où une valeur par défaut existe, donc rien ne peut la contredire. verify rapporte le budget, la politique et la métrique, puisque le parquet extrait est une liste de chemins de fichiers et ne contient rien sur les raisons pour lesquelles ces fichiers ont été choisis.

Conservez la spécification, les parquets d'entrée et le répertoire de sortie sous RUN_ROOT afin que les mêmes chemins se résolvent à l'intérieur du conteneur.

Preflight

Avant de lancer Docker :

1. Vérifiez l'accès à Docker et au GPU :

docker info > /dev/null
nvidia-smi -L

2. Résolvez et tirez l'image data-services si nécessaire :

DS_IMAGE=nvcr.io/nvidia/tao/tao-toolkit:7.2.0-data-services  # versions-key: images.tao_toolkit.data_services
docker image inspect "$DS_IMAGE" > /dev/null || docker pull "$DS_IMAGE"

3. Validez la spécification :

python3 skills/data/tao-mine-od-images/scripts/verify_unique_neighbor_matching_spec.py \
  --spec "$SPEC"

4. Confirmez que RUN_ROOT contient la spécification, les deux parquets d'entrée (ou répertoires) et le répertoire de sortie. Montez RUN_ROOT au même chemin absolu à l'intérieur de Docker.

Outputs

final_unique_files.parquet contient une colonne de chemin de fichier. summary.json inclut retrieved_unique_count, coverage_pct et (quand les fichiers de détection sont fournis) les ventilations par classe pour les ensembles cible et source sélectionnés.

Troubleshooting

The subtask unique_neighbor_matching requires -e/--experiment_spec_file : réexécutez avec tmm unique_neighbor_matching -e "$SPEC".

Chemin d'entrée non trouvé à l'intérieur de Docker : utilisez un montage RUN_ROOT où les chemins hôte et conteneur sont identiques.

ValueError: detection_format is required : définissez detection_format: coco ou detection_format: kitti chaque fois que source_detection_file ou target_detection_file est défini.

ValueError: rare_class_list is required when allocation_policy is class_stratified : définissez rare_class_list et les deux fichiers de détection lors de l'utilisation de class_stratified.

coverage_pct faible dans summary.json : le pool source est plus petit que desired_unique_count. Élargissez le pool ou augmentez candidate_expansion_factor.

Pas de GPU ou erreurs cuDF/cuML : l'extraction nécessite au moins un GPU CUDA. Vérifiez nvidia-smi -L, le flag Docker --gpus et l'installation du toolkit de conteneur NVIDIA.