Exécuter l'augmentation de données vidéo CDF

Exécutez le workflow d'augmentation de données vidéo existant de bout en bout. Lisez le guide de démarrage et le guide de payload avant de créer un payload. Considérez le DAG enregistré, le modèle de payload et le manifeste de plateforme comme la source de vérité si la documentation et l'implémentation diffèrent.

Utilisez les références groupées progressivement :

• Lisez setup-and-preflight.md lors de la préparation des entrées ou de la vérification d'un environnement contrôleur/calcul.
• Lisez payload-contract.md avant de générer ou de modifier un payload.
• Lisez airflow-direct-api.md avant de déclencher ou de surveiller une exécution via l'API.
• Lisez outputs.md avant de télécharger ou d'interpréter des artefacts.
• Lisez troubleshooting.md lorsqu'une vérification ou une exécution échoue, ou quand l'utilisateur demande d'arrêter une exécution.

Le workflow prépare les vidéos source, exécute l'ensemble de la chaîne d'étiquetage automatique et d'export d'entraînement sur la branche source, génère des variantes Cosmos Transfer, exécute la même chaîne sur les vidéos générées valides, valide les sorties de stockage et arrête les services appartenant à l'exécution. Il ne produit pas un seul manifeste de dataset final combiné.

Détails des composants

Distinguez les couches de configuration avant de créer un payload :

Consultez la skill du composant avant de créer ou de modifier sa configuration de conteneur, même quand cette configuration est utilisée dans une exécution VDA complète. Le YAML du composant et le payload de déclenchement Airflow sont des contrats différents ; ne mettez pas une configuration de conteneur entière directement dans conf.payload. Modifier uniquement les valeurs de payload supportées ne nécessite pas un nouveau DAG. Adressez les modifications structurelles au DAG uniquement à la skill d'authoring de DAG quand demandé ; la configuration/déploiement reste séparément autorisé.

Quand la demande nécessite une configuration ou un diagnostic de composant, consultez la documentation de ce composant et n'inventez pas de clés ou de valeurs. Les liens ci-dessous sont épinglés au dernier commit main de chaque référentiel de composant en date du 2026-10-20 ; une skill de composant installée séparément peut décrire une version différente.

Utilisez uniquement la documentation à ces commits ; ne substituez pas une branche mouvante ou une autre version. Si la documentation est inaccessible, rapportez la référence exacte et continuez uniquement le travail supporté par les orientations du workflow local ; n'inventez pas de paramètres de composant.

Les routes d'orchestration sont des skills sœurs dans ce référentiel : cdf-orchestration-setup pour la préparation d'environnement et la configuration du contrôleur Airflow, et cdf-orchestration-write-dag pour la composition de DAG personnalisé et la révision de parité de spécification.

Les skills de composant épinglées possèdent les schémas de conteneur, les options de modèle, la création d'invites et les internals d'évaluateur ; utilisez leur documentation référencée plutôt que de maintenir des copies locales. Cette skill possède le contrat de déclenchement VDA et les contraintes imposées par son DAG enregistré. Préservez ces surcharges dans payload-contract.md ; les capacités de composant ne deviennent pas automatiquement des options de DAG supportées. Conservez l'exécution via Airflow pour une demande de workflow. Si un contrat de composant épinglé diffère de l'image déployée ou de l'intégration DAG, rapportez l'incompatibilité de version avant de proposer des paramètres ; ne mettez pas silencieusement à jour une image ou ne contournez pas une surcharge. Le rendu de payload routinier, les vérifications d'état et le dimensionnement GPU ne nécessitent pas de charger les deux composants.

Sélectionner la cible d'exécution

Listez les DAG qu'Airflow a réellement chargés et vérifiez les erreurs d'importation avant de sélectionner un DAG. Un DAG de plateforme n'est enregistré que quand son manifeste existe. N'inventez jamais un ID de DAG et ne réinstallez pas Airflow uniquement parce que le DAG demandé est absent ; rapportez que l'installation existante ne le contient pas.

Utilisez Kubernetes sauf si l'utilisateur demande explicitement OSMO ou fournit un contexte d'exécution OSMO. Pour OSMO, exigez external_services: true, gardez chaque valeur service_lifecycle.*.enabled à false, et fournissez tous les points de terminaison VLM, LLM, Cosmos Transfer et Cosmos Evaluator requis. Le manifeste OSMO ne peut déployer aucun de ces services.

Calcul minimum

Pour Kubernetes, soit C le nombre de vérificateurs d'évaluateur gérés activés, de zéro à trois. Chaque vérificateur géré—hallucination, vérification d'attribut et plausibilité physique—nécessite un GPU. Utilisez C=0 quand l'évaluateur est externe ou tous les vérifications sont désactivées.

Le plancher absolu réserve un GPU pour une tâche batch exécutable ; le minimum pratique réserve deux car l'étiquetage automatique source et le traitement Cosmos/sortie peuvent se chevaucher. L'ajout interne Kubernetes ajoute un GPU pour le point de terminaison de langage partagé et deux pour Cosmos3-Nano Transfer. Ainsi, le payload interne par défaut avec les trois vérifications bundlées activées nécessite 7 GPU pour faire progresser et 8 GPU pour le graphe parallèle par défaut. Avec plausibilité physique désactivée mais hallucination gérée et vérification d'attribut activées, les planchers correspondants sont 6 et 7 GPU. OSMO attribue à chaque tâche active 1 GPU, 11 CPU, 100 GiB RAM et 100 GiB de stockage. Lisez setup-and-preflight.md pour les hypothèses, la mise à l'échelle et les exemples de service externe.

Entrée manuelle de payload dans l'interface Airflow

Si l'utilisateur veut explicitement entrer son propre payload dans l'interface Airflow, confirmez la préparation du contrôleur, rendez l'interface accessible et rapportez l'URL. Ne générez, ne confirmez et ne soumettez pas un deuxième payload en leur nom. Une fois qu'ils disent avoir déclenché une exécution, localisez-la via l'API et reprenez la surveillance à partir de la configuration DagRun enregistrée.

Collecter le contrat d'exécution

Avant de construire un payload, confirmez :

• input_path : une vidéo unique accessible ou un répertoire contenant des fichiers .mp4, .avi, .mov, .mkv ou .webm.
• output_directory : un préfixe de stockage accessible en écriture et approprié à l'exécution.
• Plateforme cible et mode external_services.
• max_videos : utilisez un entier positif pour une exécution bornée. Utilisez null, zéro ou un entier négatif pour toutes les vidéos ; la validation normalise chaque forme illimitée en null avant la découverte d'entrées.
• cosmos.num_augmentation et un cosmos.variable_distribution non vide et approprié à la vidéo.
• Vérifications d'évaluateur activées et si l'évaluateur est géré ou externe.
• Pour le mode externe, les URLs réelles de service utilisées par cosmos, captioning, visual_qa et reasoning. cosmos.cosmos_transfer_service_url est opérationnellement requis bien que le schéma actuel n'en rejette pas l'absence.

N'inventez jamais un chemin ou point de terminaison — utilisez uniquement les valeurs que l'utilisateur a fournies, y compris celles qu'il a fournies plus tôt pour une exécution précédente. Ne demandez pas à l'utilisateur de coller les identifiants ; héritez-les de connexions Airflow configurées, secrets Kubernetes, configuration OSMO ou environnement shell.

Pour un fichier local ou un répertoire vidéo plat, validez avant upload :

python3 scripts/upload_videos.py --path /path/to/videos --validate-only
python3 scripts/upload_videos.py \
  --path /path/to/videos \
  --destination-path video-data-augmentation/my-run

La commande upload nécessite un UPLOAD_DESTINATION configuré et la chaîne de credentials AWS standard.

Outils groupés

• scripts/upload_videos.py : validez et uploadez optionnellement une vidéo locale ou un répertoire plat.
• scripts/payload.py : générez ou validez des payloads Kubernetes et OSMO autonomes.
• scripts/summarize_results.py : résumez les fichiers candidat, évaluateur, étiquetage, export et rapport d'une exécution téléchargée sans charger de média.
• assets/variable-distribution.json : distribution météo/heure de la journée éditable pour l'invite VDA groupée.

Exécutez les commandes à partir du répertoire de cette skill. Les scripts n'ont jamais besoin de credentials dans les arguments de commande.

Créer et valider le payload

Commencez par le plus petit payload qui exprime l'exécution demandée, puis validez-le avec scripts/payload.py. Quand le référentiel est disponible, validez aussi avec VideoDataAugmentationDagConfig de airflow/dags/workflows/video_data_augmentation_dag/models/payload.py ; c'est l'autorité pour le code déployé.

Préservez ces invariants :

• Top-level external_services contrôle le cycle de vie VLM, LLM et Cosmos Transfer. Les modes de service imbriqués et les répertoires de sortie doivent être en accord avec le top level.
• Le mode Kubernetes interne active les entrées de cycle de vie VLM, LLM et Cosmos Transfer. Le manifeste Kubernetes enregistré utilise un point de terminaison de modèle de langage partagé et un point de terminaison Cosmos3-Nano Transfer à deux GPU.
• Le mode externe fournit tous les points de terminaison utilisés par chaque étape activée. Si les résumés de légende sont désactivés, le point de terminaison LLM de légende n'est pas requis.
• Quand un objet cosmos est présent, incluez une variable_distribution explicite non vide ; sinon le modèle partagé peut revenir à une distribution de vêtements non liée.
• La config transfer groupée fixe le modèle de génération à nvidia/Cosmos3-Nano ; cosmos.cosmos_transfer_model ne le remplace pas.
• Le DAG remplace visual_qa.question_bank_file par sa banque de questions groupée. Ne prétendez pas qu'une valeur de payload change les questions VDA.
• Les champs inconnus peuvent être ignorés par le schéma. Vérifiez les noms de champs plutôt que de traiter l'analyse réussie comme une preuve que chaque option demandée a pris effet.
• Sur Kubernetes, les vérifications d'évaluateur activées peuvent utiliser soit un cosmos.cosmos_evaluator_service_url explicite soit des composants d'évaluateur gérés. Sur OSMO, chaque vérification activée nécessite une URL d'évaluateur externe accessible à partir de tâches OSMO ; sinon désactivez tous les vérifications explicitement.

Montrez le payload résolu et validé à l'utilisateur sans secrets et obtenez la confirmation avant de soumettre une exécution. L'autorisation de soumission couvre une seule exécution.

Génération Kubernetes interne typique :

python3 scripts/payload.py render \
  --platform k8s --service-mode internal \
  --input-path s3://bucket/vda/input/ \
  --output-directory s3://bucket/vda/output \
  --max-videos 1 --num-augmentation 1 \
  --variable-distribution assets/variable-distribution.json \
  --output /tmp/vda-payload.json

Vérification préalable de l'installation existante

Ne déployez ni réinstallez sauf si l'utilisateur le demande explicitement. Avant de déclencher :

1. Inspectez la branche/worktree de référentiel active et l'état du contrôleur actif. Confirmez que les pods du contrôleur sont sains, le DAG cible est chargé et non en pause, et aucune erreur d'importation pertinente n'existe.

2. Vérifiez les pools Airflow requis et les slots ouverts. Kubernetes utilise k8s_rtx6000_1, default_pool (l'augmentation en mode interne s'exécute aussi ici) et cosmos_transfer_3_service_pool pour le mode externe ; OSMO utilise osmo_rtx6000_1, default_pool et cosmos_transfer_3_service_pool.

3. Vérifiez la plateforme de tâche sélectionnée, l'accès au stockage d'objets, la réachabilité des points de terminaison, la compatibilité image/modèle, l'espace de cache/stockage et les connexions Airflow requises ou secrets sans imprimer les valeurs de credentials.

4. Vérifiez les GPU libres réels ainsi que la capacité annoncée et les consommateurs en cours d'exécution. Les étapes batch Kubernetes utilisent des profils de tâche GPU dans les deux modes de service. Le mode interne déploie en outre le point de terminaison de langage partagé et le point de terminaison Cosmos Transfer à deux GPU. Chaque vérificateur géré activé consomme un GPU. Appliquez le plancher de calcul minimum ci-dessus, puis dimensionnez pour le graphe d'exécution actif, les entrées mappées, les répliques et la concurrence du pool.

5. Rapportez les pods échoués obsolètes ou les ressources antérieures appartenant à l'exécution. Nettoyez uniquement les ressources appartenant à une exécution que l'utilisateur possède et uniquement avec autorisation.

6. À partir de la racine du référentiel, confirmez que le déploiement mappe chaque bucket que le payload lit ou écrit :

   python3 skills/cdf-orchestration-preflight/scripts/storage_check.py --payload <payload.json>

   Il doit imprimer Storage mapping: ready. Une ligne UNMAPPED signifie que l'exécution échouerait au runtime ; rapportez le champ non mappé et les préfixes configurés à l'utilisateur. Utiliser ce bucket nécessite de modifier la configuration de stockage du contrôleur et de le redéployer ; avec l'autorisation de l'utilisateur, adressez cette modification à orchestration setup, puis relancez la vérification.

Si l'installation existante n'est pas prête, rapportez le prérequis échoué. Le déploiement, la réinstallation du contrôleur, le redimensionnement du pool et le nettoyage destructif nécessitent une autorisation explicite séparée. Utilisez airflow-direct-api.md pour les vérifications concrètes ; n'inférez pas la préparation uniquement à partir d'une interface Airflow saine.

Soumettre et surveiller

Soumettez exactement une exécution avec le payload confirmé sous conf.payload, un ID d'exécution unique explicite quand l'interface le supporte, et la date logique requise pour l'API REST Airflow. Enregistrez l'ID DAG, l'ID DagRun, la plateforme, le mode de service, l'entrée, le préfixe de sortie, la limite d'entrée demandée, le nombre d'augmentations et les vérifications d'évaluateur activées. Si la réponse de soumission est incertaine, recherchez le même ID d'exécution avant de réessayer ; ne créez pas une exécution dupliquée.

Surveillez jusqu'à ce que le DagRun atteigne success ou failed. Inspectez les instances de tâche et les logs quand l'état stagne ou échoue, notamment :

• auto_labeling_input pour la branche vidéo source.
• cosmos_augmentation et tâches d'évaluateur pour les candidats générés.
• auto_labeling_output pour les vidéos générées valides.
• validated_output pour les vérifications finales d'artefacts.
• Tâches d'arrêt de service pour le nettoyage, sans confondre le nettoyage réussi avec la réussite du workflow.

Pour un arrêt demandé, suivez Arrêt d'une exécution. Utilisez le reste de cette référence pour le routage de panne basé sur les preuves.

Vérifier et rapporter le résultat

Pour <output_directory>/<dag_run_id>/, vérifiez :

• cosmos/<video_key>/<augmentation_index>/ contient output.mp4, caption.txt et metadata.json pour chaque candidat réussi. Comptabilisez séparément les candidats rejetés par l'évaluateur ou incomplets.
• auto_labeling_input/ et training_export/auto_labeling_input/ contiennent la sortie de branche source.
• auto_labeling_output/ et training_export/auto_labeling_output/ contiennent la sortie de branche générée pour les candidats valides.
• Les médias générés se décodent complètement et les nombres de vidéo/candidat observés sont en accord avec le payload confirmé et les résultats d'évaluateur.
• Les services gérés appartenant à l'exécution ont été supprimés tandis que les services externes sont restés intouchés.

Retournez l'état terminal, la tâche échouée et la cause racine concise si applicable, les nombres de candidat et d'évaluateur, les préfixes d'artefacts, l'état de nettoyage de service et tout écart de validation. Déclarez clairement que les deux branches d'export d'entraînement sont séparées. Téléchargez ou analysez les artefacts uniquement quand l'utilisateur le demande. Quand il le fait, lisez outputs.md, téléchargez uniquement le préfixe d'exécution nommé et utilisez scripts/summarize_results.py avant une inspection médias plus approfondie.

Limites

• Adressez la génération autonome à cdf-augmentation et l'étiquetage autonome à cdf-auto-labeling en utilisant les références épinglées ci-dessus. Le DAG VDA existant n'a aucun switch génération-uniquement ; ne déclenchez pas le graphe complet pour une demande de sous-ensemble sans acceptation.
• Utilisez le workflow autonomous_vehicle_dataset_generation_dag_k8s pour le traitement CDF-AV piloté par récupération et les manifestes de dataset sauvegardé ou récupération.
• Utilisez le workflow de génération vidéo d'événement pour la génération d'anomalie image-vers-vidéo à partir d'images d'amorce.
• Ne transformez pas silencieusement une demande d'exécution en déploiement, édition de DAG, workflow personnalisé, remplacement de point de terminaison ou modification de politique de qualité.