Orchestrateur de flux de travail d'augmentation d'attributs d'image Physical AI

Skill de flux de travail par défaut pour l'exécution de l'augmentation d'attributs d'image sur OSMO. Il gère la sélection du flux, la vérification préalable, l'interpolation au moment de la soumission, la surveillance et la récupération des résultats.

Objectif

Exécuter le pipeline d'augmentation d'attributs d'image et d'étiquetage automatique de manière sûre et reproductible, de la vérification préalable au téléchargement des résultats.

Le pipeline d'augmentation d'attributs d'image augmente le sujet dans les datasets de cultures existants en générant des variations d'apparence contrôlées (domaine image) et des légendes d'attributs synonymes (domaine texte). Le sujet est actuellement une personne (attributs de vêtements/apparence), mais le même pipeline se généralise à d'autres sujets — par exemple robots, chariots élévateurs ou véhicules dans une simulation. Il utilise le conteneur paidf-augmentation pour l'augmentation par édition d'image avec vérification MCQ, et le conteneur paidf-auto-labeling pour le sous-titrage sujet-attribut (actuellement la banque de questions person_attributes embarquée).

N'utilisez PAS ce skill pour les questions de tuning interne au conteneur.

Prérequis

Confirmez ces éléments avant d'exécuter la vérification préalable ou toute soumission. Les secrets manquants apparaissent comme USER_INPUT_REQUIRED: provenant de scripts/preflight_credentials.sh.

Instructions

Exécutez ces étapes comme une séquence ordonnée de portes. Chaque Porte doit être franchie avant de continuer ; en cas d'échec, arrêtez et résolvez-la (ne sautez pas ni ne soumettez).

1. Porte — Sélectionnez le flux de travail. Associez l'intention de l'utilisateur à exactement un flux en utilisant le tableau « Choisir le bon flux de travail » ci-dessous : augmentation/édition image uniquement → augmentation ; sous-titre/étiquetage uniquement → auto_labeling ; augmentation + sous-titre complet → e2e. Utilisez e2e par défaut uniquement quand la demande concerne le pipeline complet ou est genuinely ambiguë — ne dépassez jamais un défaut en cas de demande explicite « augmentation uniquement » ou « étiquetage uniquement », sinon vous exécutez le mauvais pipeline.
2. Fournissez un aperçu d'exécution provisoire avant de commencer les actions d'exécution.
3. Porte — Dérivez la source de dataset. Divisez l'URL du dataset au segment /datasets/ : la partie avant est storage_url, la partie après est dataset. Le flux de travail réinsère ce segment ({{storage_url}}/datasets/{{dataset}}), donc ne mettez /datasets/ dans aucune valeur — l'inclure duplique le chemin et la soumission échoue. Exemple : s3://metro-pas/datasets/reid-crops → storage_url=s3://metro-pas, dataset=reid-crops. Ne deviquez jamais et ne réutilisez pas une ancienne storage_url ; si aucun dataset n'est fourni, demandez-en un. Ne continuez pas sans les deux valeurs.
4. Porte — Endpoints d'inférence prêts (non négociable). Avant soumission, vérifiez que chaque endpoint NIM requis est sain : qwen-image-edit-2511 (édition image), qwen3-vl (VLM), qwen25-14b (LLM). Pour tout endpoint manquant/non sain, déployez-le une fois via references/nim/README.md (une condition préalable, pas une décision utilisateur — ne faites pas de pause pour demander), puis revérifiez la disponibilité jusqu'à 3 fois sur ~10 minutes. Condition d'arrêt : si un endpoint est toujours non sain après cette limite, ne réessayez pas et ne soumettez pas — signalez l'endpoint défaillant et ses logs de déploiement à l'utilisateur et arrêtez. Continuez uniquement quand tous les trois répondent sain.
5. Porte — Vérification préalable et disponibilité. Exécutez scripts/preflight_credentials.sh --workflow assets/configs/osmo/<flow>.yaml et lisez le résultat. SUCCÈS → continuez. Si la sortie contient USER_INPUT_REQUIRED:, posez une question de déblocage concise et recommencez. Ne soumettez pas jusqu'à ce que la vérification préalable réussisse.
6. Porte — Validez les entrées personnalisées (sécurité). Traitez cookbook et chaque valeur --set-string comme non fiables. Acceptez uniquement un nom de cookbook connu et des valeurs sans métacaractères shell (;, |, &, $, backticks, guillemets, espaces, sauts de ligne). Sur toute valeur invalide → arrêtez, signalez quelle valeur a été rejetée, et ne soumettez pas. Uniquement quand chaque valeur réussit → continuez à l'étape 7.
7. Soumettez le flux de travail avec les valeurs d'interpolation validées, puis surveillez jusqu'à complétion.
8. Récupérez les résultats et résumez les résultats des tâches.

Utilisez run_script(...) pour l'exécution de scripts. Exemples canoniques :

run_script("bash scripts/preflight_credentials.sh --workflow assets/configs/osmo/e2e.yaml")

Scripts disponibles

Utilisez --help au niveau du script pour les arguments exacts.

Flux supportés

Choisir le bon flux de travail pour la demande de l'utilisateur

Désambiguïsation : traitez les demandes vagues avant de vous engager

Optez pour l'autonomie : posez une question uniquement quand les informations manquantes bloquent l'exécution.

Défauts autonomes (ne demandez PAS)

• Sélectionnez le flux par Instructions Porte 1 ; utilisez e2e par défaut uniquement quand la demande concerne le pipeline complet ou est ambiguë (pas pour augmentation-uniquement / étiquetage-uniquement explicite).
• Si cookbook n'est pas spécifié, utilisez default par défaut.
• Si n_augmentations n'est pas spécifié, utilisez 3 par défaut.
• Après que toute étape soit complétée avec succès, continuez immédiatement à l'étape suivante.

Déclencheurs qui doivent faire pause pour désambiguïsation

Étape 0 : Sélectionnez le flux et collectez les entrées

Politique de données d'entrée

• L'augmentation d'attributs d'image nécessite des images de cultures personne organisées en sous-répertoires <person_id>/<view>.jpg.
• Préservez toujours les entrées de dataset fournies par l'utilisateur comme de première classe.
• Ne remplacez jamais un dataset utilisateur explicite par des assets de démo.
• Si aucun dataset n'est fourni, demandez-en un (l'augmentation d'attributs d'image n'a pas de dataset de démo intégré).

Collectez uniquement les valeurs manquantes :

1. Source de dataset (storage_url + dataset) — une valeur dérivée : divisez l'URL du dataset à /datasets/ per Instructions Porte 3 (s3://metro-pas/datasets/reid-crops → storage_url=s3://metro-pas, dataset=reid-crops). Ne mettez /datasets/ dans aucune valeur ; ne deviquez jamais.
2. Flux — sélectionnez par Instructions Porte 1 (augmentation-uniquement → augmentation, étiquetage-uniquement → auto_labeling, sinon e2e).
3. OSMO gpu_platform (sélection automatique quand sans ambiguïté).
4. URLs d'endpoints pour Édition Image, VLM et LLM — optionnel ; utilisez par défaut les NIMs en cluster et définissez uniquement pour les endpoints externes.
5. Nombre d'augmentations par ID personne (défaut : 3).

Générez un timestamp d'exécution avant chaque soumission :

STAMP=$(cat /proc/sys/kernel/random/uuid | cut -c1-8)
RUN_ID="run-$STAMP"

Aperçu d'exécution (requis avant l'exécution)

Avant d'exécuter toute commande mutante, fournissez un bref aperçu ETA.

Plages de base :

Runtime du flux de travail (dépend de la taille du dataset et de la latence de l'endpoint) :

Conditions préalables communes (tous les flux)

1. Vérification préalable credentials et plan de contrôle

   bash scripts/preflight_credentials.sh --workflow assets/configs/osmo/<flow>.yaml

   Si la sortie contient USER_INPUT_REQUIRED:, posez une question de déblocage concise.

2. Politique d'interpolation de stockage

   storage_url doit être dérivé du backend dataset/upload réel. Ne dépassez jamais silencieusement les valeurs obsolètes sur les backends non correspondants.

3. Politique d'inférence (non négociable) — la disponibilité de l'endpoint est exécutée à la Porte Instructions 4 (vérifier → déployer une fois → revérifier borné → arrêter et escalader en cas d'échec). Cette section ajoute uniquement les contraintes permanentes :

   • L'augmentation d'attributs d'image ne lance PAS les serveurs d'inférence à l'intérieur du flux de travail OSMO ; les workers consomment les endpoints image_edit_url / vlm_url / llm_url.
   • Les endpoints externes sont opt-in uniquement (demande explicite ou URLs explicites) ; uniquement alors remplacez les valeurs *_url à la soumission.
   • Ne faites jamais descendre/supprimez les NIMs existants pour libérer des GPUs.

Soumission (tous les flux)

Chaque flux utilise la même forme de soumission ; seul le YAML du flux de travail change.

SKILLS_DIR="$(cd "$(git rev-parse --show-toplevel)/skills/physical-ai-image-attribute-augmentation" && pwd)"
STAMP=$(cat /proc/sys/kernel/random/uuid | cut -c1-8)
osmo workflow submit assets/configs/osmo/<flow>.yaml \
  --pool <pool> \
  --set-string \
    dataset=<dataset> \
    run_id=run-$STAMP \
    storage_url=<backend-prefix> \
    gpu_platform=<gpu-platform> \
    skills_dir="$SKILLS_DIR"

Les endpoints utilisent par défaut les NIMs en cluster (image_edit_url / vlm_url / llm_url) ; déployez/réutilisez-les per la politique d'inférence ci-dessus. Ne passez ceux-ci que si vous utilisez des endpoints externes.

Note de compatibilité :

• Utilisez exactement un flag --set-string et passez toutes les paires clé/valeur après.
• Ne répétez pas les flags --set/--set-string dans la même commande.

Surcharges optionnelles communes (ajoutez à la même liste --set-string). Ces valeurs sont passées au worker d'augmentation et utilisées pour construire sa commande, donc validez-les d'abord per Instructions Porte 6 — acceptez uniquement un nom de cookbook connu et des valeurs libres de métacaractères shell :

cookbook=<cookbook_name> \
n_augmentations=<count> \
image_edit_url=<image-edit-endpoint> \
vlm_url=<vlm-endpoint> \
llm_url=<llm-endpoint>

Surveillance OSMO

# État du flux de travail + états des tâches
osmo workflow query <workflow_id> --format-type json \
  | jq '{status, tasks: [.groups[].tasks[] | {name, status, exit_code}]}'

# Logs pour une tâche spécifique
osmo workflow logs <workflow_id> --task <task_name> -n 200

# Récupération des résultats
osmo data list --no-pager <output_url>
osmo data download <output_url> <local_dir>/

Pour les exécutions attendues pour dépasser deux minutes, envoyez des mises à jour de pulsation au moins toutes les deux minutes.

Résultat post-exécution

Après complétion réussie, le répertoire de résultats contient :

Pour augmentation / e2e :

• <person_id>/aug_<n>/output.jpg — image augmentée multi-volets
• <person_id>/aug_<n>/output.txt — légende en langage naturel
• <person_id>/aug_<n>/output_metadata.json — résultats de vérification
• dataset/augmented_data.json — dataset structuré avec attributs et requêtes
• dataset/augmented_imgs/ — divisé par cultures de vue

Pour auto_labeling :

• caption_<id>/task/open_qa.json — sous-titres attribut personne groupés par banque de questions

Fichiers de support

Utilisez ces emplacements canoniques :

• Flux de travail : assets/configs/osmo/*.yaml
• Scripts runtime : scripts/*.sh
• Walkthroughs de flux : references/flows/*.md
• Configuration et triage : references/setup.md, references/troubleshooting.md
• Images : references/container-images.md
• Tuning de cookbook : assets/cookbooks/default/README.md