Génération PAIDF Cosmos Predict

Préparez et exécutez la génération PAIDF Cosmos Predict pour les échantillons média. La compétence émet un handoff JSONL qui mappe chaque id d'entrée vers le chemin média original et le chemin vidéo générée.

Purpose

Utilisez cette compétence quand un workflow DEFT a déjà des échantillons média et a besoin de vidéos synthétiques/générées à partir de PAIDF Cosmos Predict. Cette compétence ne démarre pas le service de captioning VLM. Une URL de base compatible OpenAI atteignable pour le modèle utilisé pour légender les médias d'entrée doit être fournie à l'exécution.

Prerequisites

• Docker avec support GPU NVIDIA et nvidia-container-toolkit.
• Accès à l'image d'augmentation PAIDF déclarée par images.metropolis_sdg.paidf_augmentation dans versions.yaml.
• Un service de captioning VLM en cours d'exécution avec une URL de base d'API compatible OpenAI. L'URL de base doit être fournie par l'utilisateur ou le workflow en amont à l'exécution ; réutilisez cette URL de base exacte pour chaque argument --vlm-captioning-endpoint. N'incluez pas /models dans VLM_CAPTIONING_ENDPOINT.
• HF_TOKEN dans l'environnement d'exécution quand les téléchargements du modèle Cosmos nécessitent un accès HuggingFace — exporté, ou dans un fichier env approuvé par l'utilisateur (lignes KEY=value simples) que le bloc d'exécution charge.
• VLM_API_KEY dans l'environnement d'exécution de la même manière quand le point de terminaison du captioning VLM nécessite une authentification.
• Les chemins média d'entrée qui sont des chemins absolus sur l'hôte sous le répertoire média requis. Passez le répertoire média hôte avec --media-dir ; la compétence le monte dans le conteneur PAIDF exactement au même chemin.

Inputs

Forme de ligne input JSONL :

{"id": "stable-sample-id", "media_path": "/abs/input.mp4"}

Le JSONL d'entrée peut contenir des valeurs media_path dupliquées, mais chaque id doit être unique. Cela permet à un workflow en amont d'attacher plusieurs échantillons logiques à la même vidéo source tout en évitant la génération PAIDF répétée pour cette vidéo.

Exemple :

{"id": "sample-a-question-1", "media_path": "/abs/video_a.mp4"}
{"id": "sample-a-question-2", "media_path": "/abs/video_a.mp4"}
{"id": "sample-b-question-1", "media_path": "/abs/video_b.mp4"}

prepare_paidf_config.py convertit les valeurs media_path en chemins absolus et les déduplique avant d'écrire config.yaml, afin que chaque vidéo unique n'apparaisse qu'une seule fois dans PAIDF data[] et passe par le captioning/génération une seule fois. write_paidf_handoff.py étend ensuite jusqu'au niveau de ligne d'entrée afin que chaque id original apparaisse dans generated_videos.jsonl ou failed_videos.jsonl, avec les lignes média dupliquées pointant vers le même chemin vidéo généré ou attendu.

Runtime Image

L'image d'augmentation PAIDF est résolue à partir de images.metropolis_sdg.paidf_augmentation dans versions.yaml ; les utilisateurs n'ont pas besoin de la fournir pour le workflow standard.

Agent Run Procedure

Avant d'exécuter, déterminez ces valeurs d'exécution à partir de la demande de l'utilisateur ou de la sortie du workflow en amont :

• INPUT_JSONL : chemin vers le JSONL média.
• OUTPUT_DIR : chemin vers le répertoire de sortie PAIDF.
• VLM_CAPTIONING_ENDPOINT : URL de base compatible OpenAI du captioning VLM fournie par l'utilisateur. N'incluez pas /models.
• GENERATION_SETTINGS : JSON de paramètres de génération fourni par l'utilisateur, ou skills/data/paidf-cosmos-predict/assets/default_generation_settings.json quand l'utilisateur n'en a pas fourni.
• PAIDF_NUM_GPUS : nombre de GPU PAIDF.
• MEDIA_DIR : répertoire média à monter 1:1 dans Docker.
• CAPTION_PROMPT_FILE : fichier prompt de captioning VLM.

Si des valeurs requises manquent, demandez-les à l'utilisateur avant de lancer PAIDF.

Définissez les valeurs d'exécution :

INPUT_JSONL="<user-provided-input-jsonl>"
OUTPUT_DIR="<user-provided-output-dir>"
VLM_CAPTIONING_ENDPOINT="<user-provided-vlm-captioning-base-url>"
GENERATION_SETTINGS="skills/data/paidf-cosmos-predict/assets/default_generation_settings.json"
PAIDF_NUM_GPUS="<user-provided-paidf-gpu-count>"
MEDIA_DIR="<user-provided-media-dir>"
CAPTION_PROMPT_FILE="<user-provided-caption-prompt-file>"

Si l'utilisateur fournit un JSON de paramètres de génération, remplacez GENERATION_SETTINGS par ce chemin.

Vérifiez l'URL de base du captioning VLM avant de préparer les entrées PAIDF. Cela envoie une demande de preflight à <VLM_CAPTIONING_ENDPOINT>/models uniquement pour vérifier que l'URL de base est atteignable et compatible OpenAI. PAIDF reçoit toujours VLM_CAPTIONING_ENDPOINT lui-même dans config.yaml, pas l'URL /models dérivée.

python skills/data/paidf-cosmos-predict/scripts/verify_vlm_captioning_base_url.py \
  --vlm-captioning-endpoint "$VLM_CAPTIONING_ENDPOINT"

Si cela échoue, arrêtez le workflow PAIDF et émettez une erreur indiquant que l'URL de base fournie par l'utilisateur n'a pas réussi la vérification de preflight OpenAI-compatible /models.

Préparez le répertoire de sortie PAIDF :

python skills/data/paidf-cosmos-predict/scripts/prepare_paidf_config.py \
  --input-jsonl "$INPUT_JSONL" \
  --output-dir "$OUTPUT_DIR" \
  --vlm-captioning-endpoint "$VLM_CAPTIONING_ENDPOINT" \
  --media-dir "$MEDIA_DIR" \
  --generation-settings "$GENERATION_SETTINGS" \
  --paidf-num-gpus "$PAIDF_NUM_GPUS" \
  --caption-prompt-file "$CAPTION_PROMPT_FILE"

prepare_paidf_config.py effectue un preflight de capacité d'écriture, écrit config.yaml, écrit path_map.jsonl, écrit run_metadata.json, et crée des répertoires de sortie accessibles en écriture par le conteneur. Si un répertoire monté existant ou un fichier n'est pas accessible en écriture par l'agent, il échoue tôt avec une commande de correction de permissions.

La config générée utilise le captioning VLM uniquement plus la génération text-to-world de Cosmos Predict. L'étape d'augmentation de prompt LLM séparé de PAIDF est désactivée par omission : captioning.llm n'est pas présent. prepare_paidf_config.py intègre CAPTION_PROMPT_FILE dans captioning.vlm.user_prompt.

Fichiers helper préparés :

• path_map.jsonl mappe chaque media_path absolue d'entrée unique au chemin vidéo généré, chemin de légende et chemin de métadonnées déterministes. write_paidf_handoff.py l'utilise pour produire une ligne de handoff générée ou échouée par ligne d'entrée.
• run_metadata.json enregistre le point de terminaison du captioning VLM, le modèle de captioning et le nombre de GPU PAIDF utilisés quand config.yaml a été préparé. C'est à titre informatif uniquement.

Exécutez PAIDF :

set -a; source /path/to/.env; set +a   # omit if already exported

[ -n "${HF_TOKEN:-}" ] || {
  echo "MISSING: HF_TOKEN is not set. Export it, or point the loader above at a user-approved env file."
  exit 1
}

if [ -z "${VLM_API_KEY:-}" ]; then
  echo "WARNING: VLM_API_KEY is not set. Continue only if the VLM captioning endpoint does not require authentication."
fi

PAIDF_IMAGE="$(scripts/resolve_versions_key.py images.metropolis_sdg.paidf_augmentation)"

set -o pipefail
docker run --rm \
  --gpus "$PAIDF_NUM_GPUS" \
  --shm-size=8g \
  --network host \
  -e HF_TOKEN \
  -e VLM_API_KEY \
  -v "$MEDIA_DIR:$MEDIA_DIR:ro" \
  -v "$OUTPUT_DIR:$OUTPUT_DIR" \
  "$PAIDF_IMAGE" \
  --config "$OUTPUT_DIR/config.yaml" \
  2>&1 | tee "$OUTPUT_DIR/paidf_docker.log"

La commande Docker résout l'image PAIDF depuis versions.yaml, monte MEDIA_DIR 1:1 en lecture seule, monte OUTPUT_DIR 1:1 accessible en écriture, transfère HF_TOKEN et VLM_API_KEY, et conserve une copie de Docker stdout/stderr dans $OUTPUT_DIR/paidf_docker.log via tee. set -o pipefail préserve le statut de sortie Docker lors de l'utilisation de tee.

Créez le handoff après que PAIDF ait écrit les vidéos générées :

python skills/data/paidf-cosmos-predict/scripts/write_paidf_handoff.py \
  --input-jsonl "$INPUT_JSONL" \
  --path-map "${OUTPUT_DIR}/path_map.jsonl" \
  --generated-jsonl "${OUTPUT_DIR}/generated_videos.jsonl" \
  --failed-jsonl "${OUTPUT_DIR}/failed_videos.jsonl"

Workflow

1. Vérifiez l'URL de base du captioning VLM fournie par l'utilisateur avec verify_vlm_captioning_base_url.py. Si cela échoue, arrêtez et rapportez l'erreur de preflight OpenAI-compatible /models.
2. Exécutez prepare_paidf_config.py sur le JSONL média d'entrée en utilisant ce même point de terminaison. Il lit les valeurs de captioning VLM et de génération PAIDF à partir des paramètres de génération, fait un preflight d'accès en écriture, écrit la config PAIDF et la path map, et déduplique la génération PAIDF à une entrée par chemin média unique.
3. Exécutez la commande Docker PAIDF. L'agent doit surveiller la sortie Docker, le statut de sortie Docker et les comptages de sortie générés.
4. Exécutez write_paidf_handoff.py pour produire generated_videos.jsonl et failed_videos.jsonl.

Long-Running Run Updates

La génération PAIDF peut s'exécuter longtemps. Pendant une exécution pilotée par agent, tenez l'utilisateur informé sans lui demander de demander le statut.

• Avant de lancer PAIDF, rapportez le répertoire de sortie, le comptage de médias uniques depuis path_map.jsonl, le nombre de GPU PAIDF et le répertoire média.
• Pendant que PAIDF s'exécute, fournissez une courte mise à jour de progression toutes les 30 minutes. Incluez le temps écoulé, le comptage de vidéos générées sous generated/videos/, le comptage de médias uniques attendu et le dernier signal de log PAIDF utile si disponible.
• Si vous utilisez un environnement d'outil où une commande Docker au premier plan bloquerait les mises à jour visibles par l'utilisateur, lancez PAIDF d'une manière monitorable, puis interrogez l'état/logs Docker et comptages de sortie du système de fichiers entre les mises à jour.
• À la fin, rapportez si le conteneur s'est fermé avec succès, le comptage de vidéos générées, le comptage de sorties manquantes le cas échéant, et les chemins generated_videos.jsonl et failed_videos.jsonl après avoir exécuté write_paidf_handoff.py.
• En cas d'échec, rapportez le code de sortie du conteneur, la sortie Docker pertinente et si des vidéos partiellement générées ont été produites.

Reference Files

assets/default_generation_settings.json est le fichier de paramètres de captioning VLM et de génération Cosmos Predict par défaut. Si l'utilisateur fournit un JSON de paramètres de génération différent, définissez GENERATION_SETTINGS sur ce chemin ; sinon, définissez-le sur le chemin de fichier asset par défaut. Toujours passer le chemin résolu avec --generation-settings. Utilisez assets/paidf_config_template.yaml uniquement comme référence lisible pour la config PAIDF générée.

Deterministic Mapping

Le helper convertit chaque media_path en chemin absolu, le hache avec SHA-256 et utilise les 16 premiers caractères hexadécimaux comme id d'échantillon.

Pour chaque chemin média unique :

generated video: <output_dir>/generated/videos/<hash16>.mp4
caption:         <output_dir>/captions/<hash16>.txt
metadata:        <output_dir>/generated/metadata/<hash16>.json

Les chemins média d'entrée dupliqués partagent un chemin généré. Le handoff écrit toujours une ligne par ligne d'entrée, afin que plusieurs ids d'entrée uniques puissent pointer vers la même vidéo générée.

Outputs

Chaque ligne generated_videos.jsonl a exactement :

{"id": "stable-sample-id", "original_media_path": "/abs/input.mp4", "generated_video_path": "/abs/generated.mp4"}

Chaque ligne failed_videos.jsonl a exactement :

{"id": "stable-sample-id", "original_media_path": "/abs/input.mp4", "expected_generated_video_path": "/abs/generated.mp4", "error": "missing_generated_video"}

Troubleshooting