Skill: TAO Run DEFT CR ITS Mining

Prérequis

Avant le préflight, suivez references/host-prerequisites.md ; utilisez son DEFT_PYTHON sélectionné pour chaque helper fourni et arrêtez si la sonde de dépendance échoue.

Ressources fournies

Résolvez DEFT_SKILL_ROOT vers le répertoire absolu contenant ce SKILL.md installé. Le runtime de l'agent ou du plugin résout ce chemin ; ce n'est pas une entrée utilisateur. Invoquez les helpers fournis avec "$DEFT_PYTHON" "$DEFT_SKILL_ROOT/scripts/<name>.py" .... N'exigez jamais un checkout de skill-bank ou de changer le répertoire de travail de l'utilisateur vers une racine de repository.

Ce workflow invoque tao-finetune-cosmos-embed, tao-analyze-gaps-vlm-bcq, tao-mine-nearest-neighbors, et le skill de plateforme sélectionné par nom de skill enregistré. Ces skills possèdent leurs credentials, actions et actifs fournis. Cosmos Reason est détenu par le workflow : résolvez images.tao_toolkit.deft_cosmos_reason, générez les TOMLs avec les helpers de ce workflow et les templates de base configurés, et soumettez les commandes exactes train/evaluate dans references/mining-loop.md via la plateforme sélectionnée. N'invoquez pas tao-finetune-cosmos-reason pour la planification, les templates, les bundles d'action, les commandes ou la résolution des hooks.

Entrées utilisateur (DEFT Workspace et Workflow Configuration Yaml)

L'utilisateur doit fournir un chemin absolu du DEFT workspace qui sera utilisé pour l'intégralité de l'exécution. Ce chemin ne doit pas être /workspace car cela entrerait en conflit avec les skills Cosmos Reason.

La disposition du DEFT workspace doit être la suivante :

<deft_workspace>/
├── data/
├── hf_cache/
├── model/
├── specs/
└── results/

Chaque exécution du workflow écrit dans un répertoire spécifique à l'exécution à l'intérieur de <deft_workspace>/results/. Si run.name est défini dans workflow.yaml, cette valeur exacte est utilisée comme nom de répertoire ; sinon le workflow crée un répertoire horodaté. Par exemple, run.name: deft_cr_its_mining_test écrit l'évaluation de base sous <deft_workspace>/results/deft_cr_its_mining_test/baseline/evaluate.

La disposition du répertoire d'exécution est :

<deft_workspace>/results/<run_name_or_timestamp>/
├── workflow.yaml
├── deft_state.json
├── loop_log.jsonl
├── bcq_accuracy_report.md
├── bcq_accuracy_summary.json
├── baseline/
│   └── evaluate/
│       └── bcq_accuracy_metrics.json
├── cosmos_embed_output/
│   ├── kpi/
│   └── train/
├── embedding_parquets/
│   ├── kpi/
│   │   └── embeddings.parquet
│   └── train/
│       └── embeddings.parquet
├── iter_1/
│   └── evaluate/
│       └── bcq_accuracy_metrics.json
├── iter_2/
└── ...

workflow.yaml est une copie de la config haut niveau qui a produit l'exécution. loop_log.jsonl est la source d'événements append-only pour la reprise, et chaque append de stage-log actualise atomiquement deft_state.json comme snapshot courant. baseline/evaluate/ stocke l'évaluation initiale du modèle de base. Chaque évaluation complétée stocke aussi bcq_accuracy_metrics.json. bcq_accuracy_report.md et bcq_accuracy_summary.json au niveau de l'exécution comparent la base avec chaque itération complétée. cosmos_embed_output/kpi/ et cosmos_embed_output/train/ stockent les sorties brutes de préparation et inférence Cosmos Embed. embedding_parquets/kpi/ et embedding_parquets/train/ stockent les artefacts parquet fixes prêts pour le mining calculés une fois à partir des datasets KPI et d'entraînement. Chaque répertoire iter_<N>/ stocke les artefacts pour une itération d'amélioration DEFT.

Configuration du workflow

Il doit y avoir un fichier appelé <deft_workspace>/specs/workflow.yaml, qui sera la config workflow haut niveau pour l'exécution DEFT complète :

run:
  name: null
  max_iterations: 1

kpi_dataset:
  annotations_path: /abs/path/to/deft_workspace/data/kpi/annotations.json
  media_dir: /abs/path/to/deft_workspace/data/kpi/media

train_dataset:
  annotations_path: /abs/path/to/deft_workspace/data/train/annotations.json
  media_dir: /abs/path/to/deft_workspace/data/train/media

cosmos_reason:
  baseline_model_path: /abs/path/to/deft_workspace/model/reasoner_checkpoint
  base_evaluate_toml: /abs/path/to/deft_workspace/specs/cr_base_evaluate.toml
  base_train_toml: /abs/path/to/deft_workspace/specs/cr_base_train.toml
  continual_model: false

mining:
  embeddings_spec_template: /abs/path/to/deft_workspace/specs/cosmos_embed_inference_template.yaml
  embeddings_modality: both
  cosmos_embed_checkpoint_path: null
  embedding_parquets:
    kpi: null
    train: null
  mining_spec_template: /abs/path/to/deft_workspace/specs/mining_spec_template.yaml
  mine_unique_only: true

run, kpi_dataset, train_dataset, cosmos_reason, et mining sont requis ; les chemins configurés doivent être absolus dans <deft_workspace>. cosmos_reason.baseline_model_path doit être un checkpoint Cosmos Reasoner. Convertissez d'abord un checkpoint Omni natif avec tao-finetune-cosmos-reason. L'option continual_model défaut à false, ce qui commence chaque itération depuis la base. embeddings_modality sélectionne les cibles KPI ; les embeddings train/source incluent toujours le texte et la vidéo. L'option mine_unique_only défaut à true et filtre les chemins train/source précédemment minés des itérations ultérieures.

Écrivez toutes les sorties du workflow sous <deft_workspace>/results ; n'ajoutez pas une autre racine de sortie. Quand run.name est défini, utilisez <deft_workspace>/results/<run.name> et expliquez que baseline/, cosmos_embed_output/, embedding_parquets/, et iter_<N>/ y sont imbriqués. Quand c'est null, créez <deft_workspace>/results/run_<YYYYMMDD_HHMMSS> et enregistrez ce chemin dans deft_state.json afin que la reprise ne le recalcule jamais.

Avant d'exécuter une étape du workflow, validez la config :

"$DEFT_PYTHON" "$DEFT_SKILL_ROOT/scripts/verify_workflow_yaml.py" \
  --workspace "$WORKSPACE" \
  --workflow-yaml "$WORKSPACE/specs/workflow.yaml"

Le validateur vérifie les champs requis, les chemins absolus contenus dans le workspace, embeddings_modality, l'existence des chemins, les baselines Omni, et la compatibilité entre les annotations LLaVA KPI/train et leur media_dir. Chaque annotation a besoin d'un id unique non vide ; sa video doit se résoudre par rapport au répertoire media du dataset. Le template Cosmos Embed doit déclarer un inference.num_gpus positif, que le préflight affiche pour vérification du matériel. mining.cosmos_embed_checkpoint_path accepte null, un chemin absolu local au workspace, ou un id de modèle Hugging Face avec un préfixe hf_model:// optionnel. Les valeurs optionnelles mining.embedding_parquets.kpi et .train doivent être des fichiers Parquet mining-ready absolus existants à l'intérieur du workspace avec des colonnes filepath, embedding, et modality. KPI doit contenir exactement les modalités sélectionnées ; train doit contenir texte et vidéo. Les champs text_embeddings et video_embeddings supprimés sont invalides. Chaque étape suit toujours le comportement de montage de son skill sous-jacent, container ou runner de plateforme.

Si le préflight rejette une base Omni Cosmos3, dites à l'utilisateur que ce workflow requiert un checkpoint Reasoner, demandez-lui de le convertir d'abord avec tao-finetune-cosmos-reason, et quittez sans initialiser le workflow.

Si l'utilisateur ne fournit pas de templates personnalisés Cosmos Reason ou Cosmos Embed, copiez $DEFT_SKILL_ROOT/assets/cr_base_evaluate.toml, $DEFT_SKILL_ROOT/assets/cr_base_train.toml, et $DEFT_SKILL_ROOT/assets/default_cosmos_embed_inference.yaml dans <deft_workspace>/specs/. Utilisez tao-mine-nearest-neighbors pour copier son assets/default_nearest_neighbors.yaml fourni quand l'utilisateur ne fournit pas de template mining. Pointez workflow.yaml vers les copies du workspace. Le template Cosmos Embed fourni demande 8 GPUs ; ne lancez pas jusqu'à ce que le préflight confirme que la plateforme sélectionnée peut satisfaire cette demande, ou que l'utilisateur approuve un template modifié.

Initialisez une exécution une fois après la validation :

"$DEFT_PYTHON" "$DEFT_SKILL_ROOT/scripts/initialize_workflow.py" \
  --workspace "$WORKSPACE" \
  --workflow-yaml "$WORKSPACE/specs/workflow.yaml"

Utilisez le run_dir affiché comme RUN_DIR pour chaque commande ultérieure. Si run.name est null, ne demandez jamais à un autre script de préparation de dériver le répertoire d'exécution à nouveau ; passez --run-dir "$RUN_DIR" afin que toutes les étapes écrivent dans l'exécution initialisée.

N'utilisez pas --force pour une reprise ordinaire. Cela réécrit le snapshot d'état/config mais laisse intentionnellement loop_log.jsonl et tous les artefacts d'étape en place. Utilisez-le seulement pour réparer le snapshot pour la même exécution ; choisissez un nouveau run.name pour un redémarrage propre. Avant de reprendre, exécutez "$DEFT_PYTHON" "$DEFT_SKILL_ROOT/scripts/resume_position.py" --run-dir "$RUN_DIR" et continuez à partir de l'étape signalée.

Évaluation de base

Exécutez l'évaluation de base une fois avant la boucle d'itération DEFT. Cela évalue cosmos_reason.baseline_model_path sur le dataset KPI et produit le premier results.json utilisé par l'analyse d'écarts. Exécutez immédiatement scripts/compute_bcq_accuracy_metrics.py sur ce fichier et stockez baseline/evaluate/bcq_accuracy_metrics.json. Son parser reconnaît yes et no dans les réponses courtes ou libres, incluant la casse et la ponctuation. Il rapporte les faux positifs, faux négatifs, précision, précision équilibrée, et prédictions non analysables. Utilisez references/mining-loop.md pour les commandes exactes, la vérification d'achèvement, et la règle de logging.

Initialiser les embeddings mining

Initialisez les embeddings mining une fois avant la boucle d'itération DEFT. Les datasets KPI et train sont fixes pour l'exécution, donc leurs sorties Cosmos Embed sont réutilisables à travers toutes les itérations.

Utilisez scripts/prepare_cosmos_embed_inference.py pour préparer les specs d'inférence Cosmos Embed depuis workflow.yaml. Le dataset KPI requiert la modalité ou les modalités sélectionnées par mining.embeddings_modality ; le dataset train requiert toujours texte et vidéo. Si l'utilisateur fournit un Parquet de dataset complet sous mining.embedding_parquets.kpi ou .train, le script de préparation l'étape à $RUN_DIR/embedding_parquets/<dataset>/embeddings.parquet et ne génère aucun spec d'inférence pour ce dataset. Lors de l'étapement, il remappre les identifiants d'embedding de texte depuis les fichiers questions de l'exécution source vers la consultation courante par contenu de question ; les embeddings et identifiants vidéo sont préservés. Si la valeur du dataset est null ou omise, le script génère chaque spec de modalité requise pour ce dataset. La réutilisation partielle par modalité n'est pas supportée. Si mining.cosmos_embed_checkpoint_path est un chemin local absolu, le script l'utilise pour les specs générés. Si c'est un id de modèle Hugging Face distant, avec ou sans le préfixe hf_model://, le script le télécharge ou le réutilise sous <deft_workspace>/hf_cache et écrit le chemin local du checkpoint téléchargé dans les specs d'inférence générés. Si le champ est null, le script utilise nvidia/Cosmos-Embed1-224p.

Le script télécharge les checkpoints HF distants avant que Cosmos Embed ne s'exécute car le démarrage de Cosmos Embed peut entrer en race quand inference.num_gpus > 1 et que plusieurs workers tentent de télécharger le même modèle à la fois. Si les deux Parquets de dataset combinés sont fournis, le script de préparation n'a pas besoin du checkpoint et ne le télécharge pas.

Utilisez scripts/prepare_cosmos_embed_inference.py une fois. Cela prépare le dataset KPI et le dataset train :

"$DEFT_PYTHON" "$DEFT_SKILL_ROOT/scripts/prepare_cosmos_embed_inference.py" \
  --workspace "$WORKSPACE" \
  --workflow-yaml "$WORKSPACE/specs/workflow.yaml" \
  --run-dir "$RUN_DIR"

Le script de préparation écrit seulement les specs d'embedding manquantes sous le RUN_DIR initialisé. L'initialisation possède le snapshot $RUN_DIR/workflow.yaml ; cette étape ne dérive pas une nouvelle exécution ou n'écrase pas ce snapshot.

Pour chaque dataset sans un Parquet combiné fourni, le script de préparation écrit tous les specs d'inférence de modalité requise sous cosmos_embed_output/<dataset>/specs/, crée des répertoires bruts de résultats Cosmos Embed, étape les questions de texte comme fichiers pour des jointures stables, et écrit lookup.parquet. Après inférence, le script de conversion rassemble ces sorties de modalité séparées en un fichier orienté mining par dataset. Chaque ligne contient filepath, embedding, et modality :

$RUN_DIR/embedding_parquets/kpi/embeddings.parquet
$RUN_DIR/embedding_parquets/train/embeddings.parquet

Le parquet KPI contient seulement la modalité ou les modalités sélectionnées. Le parquet train contient toujours les deux modalités texte et vidéo.

Exécuter l'inférence Cosmos Embed

Utilisez tao-finetune-cosmos-embed pour chaque spec d'inférence généré. Suivez la validation obligatoire de sortie terminal, réparation de permission, et procédure de conversion dans references/mining-loop.md. N'exécutez pas d'inférence ou de conversion pour un dataset dont le Parquet combiné a été fourni lors de la préparation.

Le Parquet de lookup généré utilise annotation_id pour le id LLaVA original et video_path pour les médias résolus. Ne renommez pas non plus colonne en video_id ; ce champ externe appartient à Cosmos Reason et aux enregistrements d'analyse d'écarts.

Boucle mining DEFT

Exécutez les itérations 1..run.max_iterations. La boucle est mining-only : aucune exécution de branche PAIDF ou video-générée n'est exécutée dans ce skill. Avant l'analyse d'écarts, chaque itération réécrit les valeurs video_id du résultat Cosmos Reason depuis les ids d'annotation LLaVA vers les chemins vidéo KPI résolus et stocke les prédictions préparées dans le répertoire gaps/ de l'itération. Elle exécute ensuite l'analyse d'écarts, construit un parquet cible de modalité sélectionnée, le mine contre la source train texte/vidéo combinée en une exécution tao-mine-nearest-neighbors, convertit les lignes minées en annotations LLaVA, fusionne les annotations, entraîne Cosmos Reason, évalue le checkpoint entraîné, calcule les métriques de précision BCQ de cette évaluation, et supprime les checkpoints d'entraînement reprenables tout en préservant les exports safetensors. À la fin de la boucle, générez le rapport de précision au niveau de l'exécution et incluez son tableau baseline/itération dans la réponse finale de l'agent. Voir references/mining-loop.md pour les commandes exactes et les critères d'achèvement.

Critères d'achèvement

Dépannage

L'id de prédiction ne correspond pas à une annotation : Confirmez que l'évaluation a utilisé les mêmes annotations KPI configurées par kpi_dataset.annotations_path. Chaque video_id de résultat Cosmos Reason doit correspondre à un id d'annotation LLaVA ou un chemin d'annotation video déjà résolu.

Aucun embedding cible n'a correspondu : Vérifiez que gaps/predictions.json et les chemins video_id d'analyse d'écarts correspondent aux chemins médias KPI LLaVA utilisés lors de la préparation d'embedding. Le mode texte requiert aussi que le texte de la question corresponde après suppression de <video> et du trailing "Answer with yes or no."

Les voisins minés ne se joignent pas à la consultation train : Confirmez que chaque filepath miné existe dans embedding_parquets/train/embeddings.parquet. Sa modality détermine si le chemin doit correspondre au filepath lookup.parquet train pour le texte ou video_path pour la vidéo.

Le répertoire d'exécution paraît imbriqué sous results/<run.name> : C'est attendu. run.name est le nom du répertoire d'exécution sous <deft_workspace>/results ; tous les artefacts baseline, embedding et itération y sont imbriqués.

Les permissions de sortie Docker ou les chemins d'état Cosmos Reason échouent : Arrêtez et suivez les contrats de réparation de permission et TAO status locaux d'étape dans references/mining-loop.md.

Le nombre de prédictions non analysables est différent de zéro : Rapportez le nombre à l'utilisateur et inspectez les réponses brutes correspondantes de results.json. Ces prédictions comptent comme incorrectes en précision et rappel de classe ; le script de métriques ne les supprime pas silencieusement. Une vérité de base non analysable arrête le calcul des métriques car la classe attendue est indéfinie.

*Cosmos Reason signale No space left on device pour `/dev/shm/nccl-** : C'est la mémoire partagée du container, pas la capacité disque ordinaire. Pour Docker local, exécutez l'action Cosmos Reason viatao-run-on-dockeret exigez--shm-size=8g --ulimit memlock=-1 --ulimit stack=67108864`. Confirmez ces flags dans le job soumis avant de réessayer. Les autres plateformes doivent fournir des paramètres équivalents de mémoire partagée et memlock.