Skill Pipeline d'Augmentation PAIDF

Pipeline unifié pour augmenter les données de caméra via les modèles d'IA génératives NVIDIA avec captionnage automatisé, génération et évaluation de qualité. BYOM (apportez votre propre modèle) : chaque modèle est atteint via un endpoint HTTP distant décrit par une entrée de la liste endpoints: de la config ; ajouter un modèle est généralement une modification de config, pas de code.

Purpose

Utilisez cette skill pour piloter le pipeline d'augmentation PAIDF de bout en bout :

• Sélectionner le bon modèle — Cosmos Transfer 2.5 (transformer une vidéo), Cosmos Predict 2.5 (générer/étendre une vidéo), image-edit (éditer une image), ou image-to-video (animer une première frame : Cosmos3 ou Veo 3.1).
• Créer et valider des configs YAML contre le schéma Pydantic PipelineConfig.
• Configurer le captionnage (VLM, LLM, VLM-template déterministe, texte, ou fichier) et les évaluateurs (vérification d'hallucinations, vérification d'attributs, vérification VLM).
• Lancer et exécuter l'inférence dans le conteneur Docker paidf-augmentation:1.1.0 (API distante uniquement — aucun poids de modèle local).

Utilisez cette skill lors de l'exécution d'inférence, de la création ou de l'édition de configs, du débogage d'erreurs de validation ou d'exécution, de l'ajout d'échantillons de données, de la configuration du captionnage, de l'ajustement des paramètres de génération, de l'enregistrement d'endpoints/adaptateurs BYOM, ou de la mise en place d'évaluateurs. Mots-clés déclencheurs : augmentation, cosmos transfer, cosmos predict, image edit, image-to-video, veo, augmentation d'attributs d'image, génération d'images défectueuses, captionnage, vérification d'attributs, validation de config.

Ne pas utiliser cette skill pour l'entraînement ou le fine-tuning de modèles, le déploiement de clusters ou d'endpoints NIM, ou le développement d'applications/bases de données sans rapport.

Prérequis

Entrées

Résolvez chaque valeur dans cet ordre de précédence : fichier d'état → arguments explicites du prompt → contexte de l'agent → prompt utilisateur. Ne demandez à l'utilisateur que ce qui reste non résolu.

Modèle BYOM : endpoints, adaptateurs, rôles

Le pipeline n'embarque jamais d'SDK par modèle. À la place :

• endpoints: est une liste. Chaque entrée a role, url, model (la chaîne du modèle sur le fil), un optionnel id (uniquement pour lever l'ambiguïté entre 2+ endpoints partageant un rôle), un optionnel adapter (contrat API ; défauts selon le rôle), api_key_env, et timeout.
• Rôles: vlm, llm (captionnage + évaluateurs), image_edit, video_transfer (Cosmos Transfer), video_predict (Cosmos Predict), image2video (Cosmos3 / Veo).
• Adaptateurs (contrats API): openai.chat.completions, openai.images.edits, openai.video.sync, openai.video.async, nim, passthrough. Le même modèle peut être servi sur différents contrats en changeant uniquement le champ adapter de l'endpoint.
• Sélection du modèle: augmentation.model.name se résout en un endpoint par id, sinon par role, sinon par la map nom-de-modèle→rôle (image-edit→image_edit, cosmos-transfer2.5→video_transfer, cosmos-predict→video_predict, cosmos3-image2video→image2video).

Modèles Supportés

Quand l'utilisateur n'a pas spécifié de modèle, choisissez selon leur type d'entrée et objectif :

Règle clé : vidéo en entrée + changement d'attribut de scène → Cosmos Transfer. Générer une nouvelle vidéo à partir d'un conditionnement texte/image/vidéo → Cosmos Predict. Édition d'image unique → image edit. Image fixe → clip en mouvement → image-to-video.

Tous les modèles s'exécutent via HTTP distant par un seul BaseExecutor ; il n'y a pas de local torchrun et pas de champ executor_type.

Usage

Étape 1 : Lancer le Conteneur Docker

Définissez PAIDF_IMAGE_ID sur l'ID d'image immutable sha256: enregistré à partir de la construction locale de confiance (ou fourni dans les métadonnées de version de confiance). L'ID d'image est spécifique à la compilation et à l'architecture, donc ce repository ne peut pas fournir une valeur universelle unique. Vérifiez que le tag de commodité mutable se résout toujours à l'ID attendu, puis exécutez l'ID directement :

set -e

PAIDF_IMAGE_ID="sha256:<expected-image-id>"
test "$(docker image inspect --format '{{.Id}}' paidf-augmentation:1.1.0)" = "$PAIDF_IMAGE_ID"
docker network inspect paidf >/dev/null 2>&1 || \
  docker network create paidf

docker run -it --rm \
  --network paidf \
  -v "$(pwd)/modules:/workspace/modules" \
  -v "$(pwd)/configs:/workspace/configs" \
  -v "$(pwd)/data:/workspace/data" \
  --entrypoint /bin/bash \
  "$PAIDF_IMAGE_ID"

Ne pas déduire PAIDF_IMAGE_ID du tag et immédiatement lui faire confiance ; comparez le tag contre le digest enregistré lors de la construction ou de la publication de l'image. Si une version de registry fournit un manifest signé, vérifiez cette signature avant de faire un pull et utilisez sa référence name:tag@sha256:<manifest-digest> à la place.

• Networking : l'augmentation ne fait que des requêtes sortantes, elle n'a donc besoin d'aucun ports -p/--publish. Gardez le bridge partagé paidf montré ci-dessus pour les endpoints distants. Pour un autre conteneur de modèle, attachez-le au même bridge et utilisez son nom de conteneur dans l'URL de l'endpoint. Exécutez les modèles locaux hôte dans un conteneur sur ce bridge, ou utilisez un endpoint distant ; ne pas donner au conteneur d'augmentation l'accès au réseau hôte.
• Clés API : préférez un gestionnaire de secrets de plateforme qui injecte les variables d'env requises. Sinon, exportez uniquement les clés requises et transmettez leurs noms avec -e VAR_NAME ; ne jamais monter ou charger un fichier d'identifiants large.
• Aucun GPU nécessaire pour l'inférence distante — ajoutez --gpus pour data_processing.alignment et tout décodage H.264 ; choisissez un GPU non partagé avec un serveur de modèle occupé. Le conteneur s'exécute en tant qu'uid 10000 ; assurez-vous que data/ est inscriptible (ou --user "$(id -u):$(id -g)").

Sécurité : Le networking hôte est interdit pour ce workflow, en particulier quand des clés API sont présentes. Consultez pipeline-operations.md.

Étape 2 : Exécuter le Pipeline (À l'intérieur du Conteneur)

uv run --no-sync modules/cli.py --config configs/<config_file>.yaml

# Avec les surcharges CLI OmegaConf (syntaxe dot-list)
uv run --no-sync modules/cli.py --config configs/cookbook/video-data-augmentation/config_video_transfer_CT25_nim.yaml \
  data.0.inputs.rgb=/workspace/data/input.mp4 \
  augmentation.parameters.seed=42

Variables d'environnement : les clés se résolvent en variable api_key_env → la variable d'env par défaut du rôle. Si api_key_env nomme une variable non définie, la résolution revient à la valeur par défaut du rôle ; omettez-la pour les endpoints non authentifiés. LOG_LEVEL définit la journalisation.

Schéma de Configuration

Les configs sont validées contre PipelineConfig (modules/aug_utils/schema/) et ont sept sections de haut niveau : data, endpoints (une liste), pipeline, captioning, augmentation, data_processing, et evaluators. Le YAML complet par section est dans configuration-schema.md ; le flux d'exécution et les tâches d'édition courantes sont dans pipeline-operations.md.

Exemples

Les configs se trouvent sous configs/cookbook/<use-case>/. Consultez l'index du cookbook pour l'organisation des dossiers.

Les détails par-config captioning / evaluator / adapter se trouvent dans config-decision-tree.md.

Dépannage

Exécutez toute l'inférence et la validation de schéma à l'intérieur du conteneur Docker pour un environnement cohérent. Pour les erreurs de validation de config, erreurs d'exécution/endpoint, et les timings typiques par étape, consultez troubleshooting.md.

Limitations

• Inférence distante uniquement. Tous les modèles s'exécutent derrière des endpoints HTTP distants ; aucun poids local, pas de torchrun, pas d'executor_type, pas d'exécuteur Gradio.
• GPU pour l'alignment et le décodage H.264. L'inférence distante ne nécessite aucun GPU. Un GPU CUDA est requis par data_processing.alignment (cupy) et par quoi que ce soit décodant H.264 — les évaluateurs et data_processing.transcode — car l'image embarque uniquement le décodeur matériel h264_cuvid (le décodage logiciel AVC est désactivé pour des raisons de licence). VP9 décode en logiciel. La sortie vidéo est VP9 uniquement.
• Inférence uniquement. Ce pipeline augmente et génère des médias — il n'entraîne ou fine-tune aucun modèle.
• L'authentification varie par endpoint. Les endpoints hébergés (ex. Veo) nécessitent une clé via api_key_env ; les endpoints locaux (ex. vLLM) n'en nécessitent aucune.

Fichiers de référence

• configuration-schema.md — YAML complet par section pour chaque section de config.
• config-decision-tree.md — quelle config choisir, sélection du modèle/captionnage, règles d'override d'alignment.
• pipeline-operations.md — flux du pipeline, exemple travaillé, tâches courantes, stockage, notes de sécurité.
• captioning-strategy-guide.md — les 6 modes de captionnage avec YAML complet.
• evaluator-setup-guide.md — accordage d'hallucinations, vérification d'attributs, câblage MCQ.
• troubleshooting.md — erreurs de validation/exécution et timings par étape.
• image-attribute-augmentation.md — workflow image-edit Image Attribute Augmentation et empaquetage de dataset.
• event-video-gen.md — génération d'événements smart-space image-to-video.