Skill d'augmentation CDF — Pipeline

Pipeline Remote-API pour captionner, générer et évaluer des données de caméra augmentées. Les modèles sont configurés comme endpoints HTTP ; aucun poids de modèle local n'est inclus.

Objectif

À utiliser pour sélectionner un mode de génération supporté, créer et valider un fichier YAML PipelineConfig, configurer le captionnage/les évaluateurs, et exécuter le conteneur cdf-augmentation:1.2.0. Il couvre Cosmos Transfer/Predict, les contrôles Cosmos3 WSM, l'édition d'images, la conversion image-vers-vidéo, les endpoints BYOM et les portails de qualité.

N'utilisez pas ce 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 non liés.

Prérequis

Entrées

Résolvez chaque valeur dans cet ordre de priorité : fichier d'état → arguments d'invite explicites → contexte d'agent → invite utilisateur. Demandez à l'utilisateur uniquement ce qui reste non résolu.

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

Chaque entrée de liste endpoints: déclare role, url, le modèle en câblage, et optionnellement id, adapter, api_key_env et timeout. Les rôles sont vlm, llm, image_edit, video_transfer, video_predict, image2video et evaluator. augmentation.model.name se résout par ID d'endpoint, puis par rôle, puis par le mappage de noms de modèles connus. Les contrats d'adaptateur et les champs complets sont dans configuration-schema.md.

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é : utilisez Cosmos Transfer pour les changements de scène vidéo, Cosmos Predict pour les vidéos nouvelles/continuées, image edit pour les éditions d'images fixes, et image-to-video pour animer une image. Pour Cosmos3 WSM, définissez data[].inputs.controls.wsm. Les détails de sélection de config sont dans config-decision-tree.md.

Tous les modèles fonctionnent via HTTP à distance à travers un seul BaseExecutor ; il n'y a pas de torchrun local et aucun champ executor_type.

Flux de travail canonique

Suivez cet arbre de décision ordonné ; ouvrez les références liées uniquement pour les détails du mode sélectionné.

Budget de correction de config

config_attempts compte les versions YAML, pas les appels de validation ou de preflight. Conservez-le tout au long du flux de travail et ne le réinitialisez jamais.

1. Définissez-le à 1 après la création initiale.
2. En cas d'erreur corrigible, s'il est déjà à 3, ARRÊTEZ et signalez l'erreur. Sinon incrémentez-le une fois et effectuez un passage de correction unique contenant tous les correctifs YAML actuellement signalés.
3. Validez et faites le preflight de cette version éditée sans un autre incrément. Répétez la règle 2 seulement si une vérification ultérieure trouve une autre erreur YAML corrigible.

ÉTAPE 0 — Portail d'entrée obligatoire

Exécutez ce portail avant toute autre étape :

• Portail d'étendue : si la demande demande l'entraînement, le fine-tuning, le déploiement de cluster/NIM, ou un développement non lié, refusez et ARRÊTEZ.
• Portail d'entrée : résolvez les valeurs à l'aide des Entrées. Si des valeurs obligatoires restent non résolues, demandez uniquement ces valeurs et ARRÊTEZ jusqu'à ce qu'elles soient fournies.
• Procédez seulement quand les deux portails passent et que le type d'entrée et l'objectif d'augmentation sont connus.

1. Sélectionnez le modèle dans Modèles supportés à l'aide de ce type d'entrée et objectif.
2. Créez le YAML dans cet ordre : data, endpoints, captioning, augmentation, evaluators, pipeline, puis data_processing. Omettez les sections optionnelles plutôt que de créer des placeholders. Définissez config_attempts = 1 (tentative config 1 sur 3).
3. Branchez sur le résultat demandé :
   • Configuration uniquement ou "ne pas exécuter" : ne construisez pas, ne lancez pas, ne faites pas le preflight, ni l'inférence. Un runtime de confiance est un conteneur déjà en cours d'exécution dont l'ID d'image/digest immutable enregistré, le commit checkout et les mounts config satisfont l'étape 4. Si la validation a été explicitement demandée et qu'un tel runtime existe, exécutez seulement la commande de validation et appliquez les règles d'échec de l'étape 5. Retournez la config (marquez-la non validée si la validation n'a pas été exécutée) et ARRÊTEZ.
   • Inférence/exécution demandée : procédez à l'étape 4.
4. Préparez le runtime dans ces sous-étapes vérifiables : a. Obtenez EXPECTED_RELEASE_REF de l'utilisateur comme un commit complet approuvé par le propriétaire de version ou récupérez-le du manifeste de version vérifiée. b. Vérifiez que l'arborescence Git est propre. c. Vérifiez que HEAD correspond à EXPECTED_RELEASE_REF. Si une balise de version a sélectionné la révision, vérifiez d'abord la balise, puis comparez son commit complet résolu. d. Construisez l'image et capturez son ID d'image immutable sha256:, ou obtenez un digest de registre vérifiée. e. Créez le bridge Docker cdf si nécessaire et attachez les services locaux. f. Lancez le conteneur en utilisant l'ID d'image enregistré, le réseau cdf, les mounts de volume requis, --entrypoint /bin/bash, et seulement les variables de clé d'endpoint nommées par api_key_env plus les variables de credential de stockage scoped requises pour le média distant configuré. Si une sous-étape échoue, ARRÊTEZ et signalez l'exact de l'échec et la correction appropriée : nettoyez un arbre sale, fournissez la révision approuvée, résolvez une inadéquation de révision, vérifiez le démon/build Docker, corrigez la configuration réseau, ou corrigez le lancement du conteneur. Ne continuez pas avec un runtime partiel.
5. À l'intérieur du conteneur, exécutez la commande de validation uniquement dans l'étape 2 d'Utilisation et classifiez son résultat en préservant config_attempts (tentative config actuelle N sur 3) :
   • Succès : si aucun évaluateur Cosmos externe n'est activé, procédez directement à l'étape 7. Si l'un est activé, procédez à l'étape 6.
   • Erreur YAML/schéma modifiable : quand les détails d'URL d'endpoint/modèle requis sont connus, appliquez la règle du Budget de correction de config, puis relancez la validation sur cette version YAML.
   • Infrastructure/entrée inconnue : pour les détails d'endpoint manquants, les credentials, DNS, connectivité, ou services unhealthy, ne modifiez pas de manière spéculative. ARRÊTEZ et signalez l'erreur ou demandez les détails d'endpoint manquants.
6. Avec l'évaluation Cosmos externe activée, préservez config_attempts (tentative config actuelle N sur 3) et exécutez son portail hard de preflight avant le captionnage/génération en interrogeant /health, /checkers et /dependency-graph :
   • Passage : nécessitez /health.status == "healthy" ; nécessitez que chaque checks[].name configuré corresponde exactement à une chaîne dans le tableau checkers de haut niveau retourné par /checkers et une clé dans l'objet checkers de haut niveau retourné par /dependency-graph. N'utilisez pas de correspondance de sous-chaîne, alias ou champ imbriqué. Procédez ensuite à l'étape 7.
   • Erreur config : seule une réponse 4xx de /checkers ou /dependency-graph dont le corps identifie explicitement un nom de checker configuré ou un champ config invalide se qualifie. Appliquez la règle du Budget de correction de config, puis retournez à l'étape 5 ; la revalidation n'incrémente pas le compteur.
   • Échec infrastructure : tout timeout, erreur réseau/DNS, réponse 5xx, échec /health, service unhealthy, ou checker déployé manquant arrête le flux de travail avant la génération. Ne créez pas de candidat et signalez la cause racine.
7. Entrez l'inférence seulement après que l'étape 5 réussisse et, quand l'évaluation externe est activée, l'étape 6 passe. Exécutez une boucle de candidats limitée à pipeline.retry + 1 candidats (retry par défaut à 1, donc le maximum par défaut est 2). Résolvez la seed de base une seule fois avant le premier candidat tel que défini dans Entrées ; la relance n utilise base_seed + n :
   • Générez un candidat et exécutez ses évaluateurs configurés.
   • En cas de passage, acceptez-le et quittez la boucle.
   • En cas d'échec de qualité avec des tentatives restantes, définissez la seed suivante à base_seed + next_retry_number. Si regenerate_caption_on_retry: true, régénérez la caption ensuite ; puis générez le remplacement. Si false, générez le remplacement immédiatement.
   • En cas d'épuisement des relances de qualité, échouez l'évaluation et quittez la boucle.
   • En cas d'échec de service/contrat, arrêtez sur le candidat actuel sans en générer un autre. Pour l'évaluation Cosmos externe, cela signifie un échec de soumission, sondage ou découverte ; une exécution échouée ; un résultat manquant ou ignoré ; ou un contrat d'ouverture invalide sans un booléen littéral de haut niveau passed. Avec pipeline.evaluation.strict: true (par défaut), appliquez retain_failures : sa valeur par défaut true retient vidéo, caption, metadata et résultats d'évaluation pour inspection ; false explicite les supprime. Avec strict: false, retenez les fichiers et signalez l'échec de l'évaluateur sans échouer l'échantillon.
     • Si les métadonnées du fournisseur contiennent error_code: ambiguous_post, préservez le candidat retenu, ne le resoumettez pas automatiquement, ARRÊTEZ et déférez à la récupération d'opérateur. Suivez le flux de récupération ambiguous-POST.

Utilisation

Étape 1 : Vérifier, construire et lancer le conteneur Docker

Définissez EXPECTED_RELEASE_REF à un commit complet de 40 caractères examiné par le propriétaire de la version, jamais une balise ou branche. Si une balise de version signée sélectionne la révision, vérifiez d'abord la balise et enregistrez son commit complet résolu en tant que EXPECTED_RELEASE_REF. Construisez seulement à partir d'un checkout correspondant propre, puis enregistrez l'ID d'image immutable résultant. Pour une version prébâtie, utilisez son digest vérifiée.

set -e

EXPECTED_RELEASE_REF="${EXPECTED_RELEASE_REF:?set a reviewed full commit ID}"
test "${#EXPECTED_RELEASE_REF}" -eq 40
case "$EXPECTED_RELEASE_REF" in *[!0-9a-fA-F]*) exit 1 ;; esac
test -z "$(git status --porcelain)"
test "$(git rev-parse HEAD)" = "$(git rev-parse "${EXPECTED_RELEASE_REF}^{commit}")"

DOCKER_BUILDKIT=0 docker build \
  -t cdf-augmentation:1.2.0 \
  -f docker/Dockerfile .
CDF_IMAGE_ID="$(docker image inspect --format '{{.Id}}' cdf-augmentation:1.2.0)"
case "$CDF_IMAGE_ID" in sha256:*) ;; *) exit 1 ;; esac
test "$(docker image inspect --format '{{.Id}}' cdf-augmentation:1.2.0)" = "$CDF_IMAGE_ID"

docker network inspect cdf >/dev/null 2>&1 || \
  docker network create cdf
# Attachez chaque conteneur de modèle local une fois, par exemple :
# docker network connect cdf vlm

# Exemple uniquement : remplacez par exactement les noms api_key_env déclarés par
# la config sélectionnée ; utilisez un tableau vide quand chaque endpoint n'a pas d'authentification.
CDF_ENDPOINT_KEY_ARGS=()
# Exemple authentifié :
# CDF_ENDPOINT_KEY_ARGS=(-e VLM_API_KEY -e LLM_API_KEY -e VEO_API_KEY)

# Transférez seulement les noms de credential requis par la config de média distant.
# Donnez aux conteneurs checker leurs propres credentials scoped en déploiement.
CDF_STORAGE_CREDENTIAL_ARGS=()
# Exemple compatible S3 (incluez seulement les noms que votre config de stockage nécessite) :
# CDF_STORAGE_CREDENTIAL_ARGS=(-e AWS_ACCESS_KEY_ID -e AWS_SECRET_ACCESS_KEY \
#   -e AWS_DEFAULT_REGION -e AWS_ENDPOINT_URL)

docker run -it --rm \
  --network cdf \
  "${CDF_ENDPOINT_KEY_ARGS[@]}" \
  "${CDF_STORAGE_CREDENTIAL_ARGS[@]}" \
  -v "$(pwd)/modules:/workspace/modules" \
  -v "$(pwd)/configs:/workspace/configs" \
  -v "$(pwd)/data:/workspace/data" \
  --entrypoint /bin/bash \
  "$CDF_IMAGE_ID"

Conservez l'ID sha256: capturé et utilisez-le directement pour chaque lancement ultérieur ; ne réinterprétez jamais la balise mutable comme cible de lancement. Pour les versions de registre, vérifiez le manifeste signé et utilisez name:tag@sha256:<manifest-digest>.

• Réseau : l'augmentation est un client de sortie uniquement et ne publie pas de ports. Utilisez le bridge cdf défini par l'utilisateur pour le conteneur d'augmentation et chaque conteneur local de modèle, Arbitrator et checker. cosmos-evaluator peut être un hostname de conteneur/DNS sur ce bridge ; ce n'est pas un second nom de bridge. Modifiez les URLs d'endpoint de l'host local vers les noms DNS du conteneur, par exemple http://vlm:8000/v1. Le bridge par défaut suffit quand chaque endpoint est distant.
• Clés API : préférez un gestionnaire de secrets de plateforme qui injecte les variables d'environnement requises. Sinon, exportez seulement les clés requises et transmettez leurs noms avec -e VAR_NAME ; ne montez jamais ou ne chargez un fichier de credential large.
• Aucun GPU requis pour l'inférence à distance — ajoutez --gpus pour data_processing.alignment et tout décode H.264 ; choisissez un GPU non partagé avec un serveur de modèle occupé. Le conteneur s'exécute en uid 10000 ; assurez-vous que data/ est inscriptible (ou --user "$(id -u):$(id -g)").

Avertissement : Ne jamais activer le mode host-network Docker sur les hosts partagés, multi-locataires ou de production. C'est permis seulement quand les trois conditions tiennent : (1) un service host-local requis ne peut pas être déplacé sur le bridge cdf, (2) l'host est mono-locataire et isolé sans autres charges de travail, et (3) l'utilisateur envoie un message explicite dans la conversation actuelle choisissant la mise en réseau host après avoir reçu un avertissement qu'elle supprime l'isolation de namespace réseau. Le silence, la documentation antérieure, ou une approbation antérieure non liée n'est pas l'acceptation. Ne le sélectionnez pas automatiquement. Consultez pipeline-operations.md.

Étape 2 : Valider, puis exécuter (à l'intérieur du conteneur)

# Preflight schéma et section croisée uniquement : pas d'appels endpoint ou inférence.
uv run --no-sync modules/cli.py --config configs/<config_file>.yaml --validate-only

# Exécutez seulement après que la validation réussisse.
uv run --no-sync modules/cli.py --config configs/<config_file>.yaml

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

Variables d'environnement : les clés de génération/captionnage se résolvent en tant que variable api_key_env → la variable d'environnement par défaut du rôle. L'évaluation Cosmos externe lit seulement la variable explicitement nommée par son endpoint et échoue l'initialisation quand cette variable n'est pas définie. Omettez api_key_env pour les endpoints sans authentification. LOG_LEVEL définit la journalisation.

Schéma de configuration

Les configs sont validées par rapport à PipelineConfig (modules/aug_utils/schema/) et ont sept sections de haut niveau. Créez-les dans l'ordre canonique ci-dessus ; l'ordre des clés YAML ne change pas la sémantique runtime. Le YAML complet par section est dans configuration-schema.md ; le flux runtime et les tâches d'édition courantes sont dans pipeline-operations.md.

Dépannage

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

Limitations

• Inférence à distance uniquement. Tous les modèles fonctionnent derrière des endpoints HTTP distants ; pas de poids locaux, pas de torchrun, pas de executor_type, pas d'exécuteur Gradio.
• GPU pour les étapes locales configurées. L'inférence à distance ne nécessite aucun GPU du conteneur d'augmentation. Un GPU CUDA est requis par data_processing.alignment (cupy) et par toute étape locale décodant H.264 car l'image ne contient que le décodeur matériel h264_cuvid (le décode AVC logiciel est désactivé pour des raisons de licence). VP9 décode en logiciel. La sortie vidéo est VP9 uniquement.
• Le média de l'évaluateur externe doit être distant. Quand un évaluateur externe est activé, la validation du schéma rejette le data[].inputs.rgb local, le média de contrôle, la vidéo data[].output.video générée, et le média compagnon configuré. Utilisez des URIs lisibles par checker s3://, msc://, gs://, az://, ou HTTP(S) ; le pipeline ne charge pas les fichiers locaux uniquement pour l'évaluation.
• Inférence uniquement. Ce pipeline augmente et génère des médias — il n'entraîne ni ne fine-tune les modèles.
• Auth varie par endpoint. Les endpoints hébergés (p. ex. Veo) nécessitent une clé via api_key_env ; les endpoints locaux (p. ex. vLLM) n'en nécessitent aucune.

Fichiers de référence

• configuration-schema.md — YAML complet par section pour chaque section config.
• config-decision-tree.md — quelle config commencer, sélection du modèle/captionnage, règles de remplacement d'alignment.
• pipeline-operations.md — flux du pipeline, exemple travaillé, tâches courantes, stockage, notes de sécurité.
• captioning-strategy-guide.md — tous les 6 modes de captionnage avec YAML complet.
• evaluator-setup-guide.md — tuning d'évaluateur intégré plus découverte Cosmos externe, ouverture et sémantique d'échec.
• troubleshooting.md — erreurs de validation/runtime 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énement image-to-video de smart-space.