Pipeline d'ancrage d'images

Transformez les paires (image, légende) en annotations ancrées par image : légendes nettoyées, expressions référentielles avec plages de caractères, et boîtes englobantes en espace pixel pour chaque expression. Un seul VLM (Gemini ou tout point de terminaison compatible OpenAI) gère les deux étapes.

Objectif

Générer des données d'entraînement avec expressions de référence ancrées pour les modèles d'expressions référentielles et d'ancrage. Le VLM agit comme un annotateur « enseignant » : l'étape 0 extrait les expressions référentielles de la légende en regardant l'image ; l'étape 1 retourne un ensemble de boîtes englobantes par expression pour chaque image.

Architecture du pipeline

Étape 0 : Extraction d'expressions  → VLM nettoie la légende, extrait les expressions référentielles + plages de caractères
Étape 1 : Ancrage de phrases        → VLM retourne les boîtes englobantes pixel + scores par expression

Les étapes sont individuellement sélectionnables via workflow.steps. Chaque étape écrit un point de contrôle par échantillon dans step_<N>_*/.ckpt/<sample_id>.json et ignore les enregistrements déjà traités lors de la réexécution. Réglez workflow.force_reprocess: true pour ignorer les points de contrôle et retraiter à partir de zéro.

Instructions

Configuration initiale

Quand un utilisateur souhaite exécuter ce pipeline, parcourez ces étapes :

1. JSONL d'entrée : Demandez le chemin du JSONL. Chaque ligne doit être un objet comme {"image_path": "...", "caption": "..."}. image_path peut être absolu ou relatif.

2. Racine des images : Si des valeurs image_path sont relatives, réglez data.image_root au répertoire à partir duquel elles doivent être résolues.

3. Accès API : Demandez à l'utilisateur quel point de terminaison VLM il souhaite utiliser. Présentez ces cinq options et agissez selon le choix :

   1. Gemini — réglez vlm.backend: "gemini"; exigez GOOGLE_API_KEY (variable d'environnement ou vlm.gemini.api_key).
   2. NIM (par exemple https://inference-api.nvidia.com/v1) — réglez vlm.backend: "openai"; collectez base_url, model_name, et api_key.
   3. Service de microinférence TAO (auto-hébergé, compatible OpenAI). Confirmez si le serveur est déjà en cours d'exécution :
      • En cours d'exécution — collectez base_url, model_name, et (optionnellement) api_key; réglez vlm.backend: "openai".
      • Non en cours d'exécution — guidez l'utilisateur à travers la compétence skills/applications/tao-run-inference-service, qui met en place un service de microinférence TAO local avec une API compatible OpenAI. Avant de promettre un modèle spécifique, vérifiez skills/applications/tao-run-inference-service/references/service.yaml pour valid_network_arch_config_basenames. Une fois le serveur en place, collectez base_url, model_name, et (optionnellement) api_key; réglez vlm.backend: "openai".
   4. vLLM (auto-hébergé, compatible OpenAI). Confirmez si le serveur est déjà en cours d'exécution :
      • En cours d'exécution — collectez base_url, model_name, et (optionnellement) api_key; réglez vlm.backend: "openai".
      • Non en cours d'exécution — suivez references/vllm_server.md pour installer et lancer un serveur vLLM, puis collectez base_url, model_name, et (optionnellement) api_key; réglez vlm.backend: "openai".
   5. Personnalisé (tout autre point de terminaison compatible OpenAI) — réglez vlm.backend: "openai"; collectez base_url, model_name, et (optionnellement) api_key.

   Si l'utilisateur n'a pas de point de terminaison et ne souhaite pas en configurer un, arrêtez-vous et aidez à résoudre d'abord l'accès API.

4. Étapes du workflow : Choisissez l'une de :

   • Pipeline complet : ["0", "1"]
   • Extraction d'expressions uniquement : ["0"]
   • Ancrage uniquement : ["1"], qui nécessite la sortie de l'étape 0 existante à results_dir/step_0_expression_extraction/annotations.jsonl

5. Reprendre vs exécution fraîche : Par défaut, le workflow réutilise les points de contrôle et ignore les enregistrements complétés. Pour retraiter tout, réglez image_grounding.workflow.force_reprocess=true.

Exécution du pipeline

Le pipeline s'exécute à l'intérieur du conteneur TAO Toolkit via la CLI auto_label :

auto_label generate -e /path/to/spec.yaml \
    results_dir=/results \
    image_grounding.data.input_jsonl=/data/captions.jsonl \
    image_grounding.data.image_root=/data/images \
    image_grounding.vlm.gemini.api_key=$GOOGLE_API_KEY

Générez une spec par défaut : auto_label default_specs results_dir=/results module_name=auto_label, puis réglez autolabel_type: "image_grounding". Tous les champs supportent les surcharges en notation point Hydra sur la ligne de commande.

Voir references/configuration.md pour la structure YAML complète, tous les paramètres, la configuration des modèles/points de terminaison, et les motifs d'erreur.

Workflow pilote recommandé

1. Exécutez sur 5-10 images avec les deux étapes
2. Inspectez step_0_expression_extraction/annotations.jsonl — cleaned_caption et expressions[] sont-ils corrects ? Les bonnes phrases nominales sont-elles capturées ?
3. Inspectez step_1_grounding/annotations.jsonl — les boîtes englobantes dans expressions[].instances[] semblent-elles correctes ? Les scores de confiance sont-ils raisonnables ?
4. Si la qualité est insuffisante, passez le VLM à un modèle plus puissant (par exemple gemini-2.5-pro) ou augmentez media_resolution/max_output_tokens, puis réexécutez avec force_reprocess=true.
5. Montez en charge sur le dataset complet une fois satisfait.

Configuration

Champs de configuration clés (référence complète dans references/configuration.md) :

Entrées

Un seul fichier JSONL à data.input_jsonl. Un objet JSON par ligne :

Sorties

Toutes les sorties vont à results_dir/ :

• step_0_expression_extraction/annotations.jsonl — sortie par enregistrement enrichie de cleaned_caption et expressions[] (chacun avec text, expression_id, char_span, noun_chunk, instances[] vide).
• step_1_grounding/annotations.jsonl — mêmes enregistrements avec expressions[].instances[] rempli (chaque instance a bbox: [x1,y1,x2,y2] en espace pixel, score dans [0.0, 1.0], et bbox_id).
• results_dir/annotations.jsonl — copie de la sortie de la dernière étape pour plus de commodité.
• step_<N>_*/.ckpt/<sample_id>.json — points de contrôle par échantillon utilisés pour la reprise.

Prérequis

• Conteneur : nvcr.io/nvidia/tao/tao-toolkit:6.26.3-pyt
• Accès API : Au moins un point de terminaison VLM (clé API Gemini ou point de terminaison compatible OpenAI capable d'entrée d'image)