Cosmos-RL

Ajustement supervisé (SFT) de nvidia/Cosmos-Reason2-8B sur des tâches de raisonnement vidéo. Les poids pré-entraînés proviennent de HuggingFace, non de NGC. C'est un modèle gated — nécessite HF_TOKEN.

Utilise le parallélisme basé sur FSDP avec dp_shard_size pour le nombre de GPU et dp_replicate_size pour le nombre de nœuds (pas les standards num_gpus/num_nodes).

When to Use

Utilise cette skill pour entraîner, évaluer, quantifier ou exécuter l'inférence sur Cosmos-Reason2-8B pour la réponse à des questions vidéo et le raisonnement vidéo. Le workflow principal est : confirmer le gating HF_TOKEN, sampler les annotations pour video_fps, charger le template spec, appliquer les overrides d'entraînement critiques ci-dessous, puis lancer via la skill platform (ou AutoML si activé).

Dataclass Schemas

Les schémas TAO Core générés sont empaquetés dans schemas/<action>.schema.json, avec schemas/manifest.json listant les actions disponibles. Chaque schéma généré émet également references/spec_template_<action>.yaml à partir du champ default du top-level du schéma. L'activation d'AutoML est déclarée au niveau du modèle dans references/skill_info.yaml via automl_enabled. AutoML exécutable nécessite toujours que schemas/train.schema.json et references/spec_template_train.yaml existent et se parsent. Utilise le schéma d'entraînement empaqueté pour automl_default_parameters, automl_disabled_parameters, les defaults, les limites min/max, les enums, les poids d'options, les conditions mathématiques, les dépendances et les paramètres populaires. Ne t'attends pas à ~/tao-core à l'exécution ; les mainteneurs régénèrent les schémas/templates avant d'empaqueter la skill bank.

Train Action Policy

Ce modèle est activé pour AutoML au niveau du modèle. Avant de traiter toute requête au stade d'entraînement, lis references/skill_info.yaml et résous l'override d'exécution soit à partir d'une valeur automl_policy explicite, soit à partir de la requête de workflow de l'utilisateur. Traite les phrases comme « turn off AutoML », « disable AutoML », « no HPO » ou « plain training » comme automl_policy: off pour cette exécution uniquement ; sinon défaut à auto. Quand automl_policy: auto, automl_enabled: true, et que schemas/train.schema.json et references/spec_template_train.yaml sont empaquetés, route l'action d'entraînement via tao-skill-bank:tao-run-automl par défaut avec le skill_dir de ce modèle. Préserve les overrides workflow/application pour les datasets, specs, répertoires de sortie, paramètres GPU/platform, checkpoints parents, et automl_policy. Utilise l'entraînement direct du modèle uniquement quand automl_policy: off ou que le schéma/template d'entraînement empaqueté manque ; dans le cas de schéma manquant, signale qu'AutoML est activé mais non exécutable pour ce modèle jusqu'à ce que les schémas soient générés.

Les actions non-entraînement comme evaluate, inference, export et les flows de déploiement restent dans cette skill modèle. L'override automl_policy par exécution ne change pas les métadonnées du modèle.

Credentials

• HF_TOKEN (requis) : token d'accès HuggingFace. L'utilisateur doit accepter l'accord du modèle à https://huggingface.co/nvidia/Cosmos-Reason2-8B et fournir un token avec accès en lecture. Passé au conteneur comme docker_env_var.

Datasets

Le type de dataset est vlm au format llava ; les intents acceptées sont training, evaluation et testing. Les entrées peuvent être des racines de dataset (le mode root mappe <root>/annotations.json plus <root> comme chemin média) ou des chemins spec-key directs (quand les annotations et le média vivent à des emplacements différents). Avant de lancer train/AutoML/evaluate, sampler le JSON d'annotations et requérir video_fps dans chaque record — l'absence de video_fps fait échouer le loader SFT de Cosmos-RL avec Error processing sample: 'video_fps' après le démarrage du job. Arrête avant la génération du runner si c'est absent et demande à l'utilisateur de corriger les fichiers d'annotations ; ne démarre pas AutoML pour découvrir cela dans torchrun.

Voir references/datasets.md pour les exigences d'entraînement complètes, le rappel d'intake de lancement (options spec-key, mappage mode-root, confirmation container-image, et l'invocation check_tao_launch_preflight.py), le tableau Per-Action Dataset Requirements, le mappage data_sources avec des exemples d'override directs, et la politique eval-dataset / auto-split.

Spec Construction

cosmos-rl est mode: config. Commence toujours par references/spec_template_train.yaml (ou spec_template_evaluate.yaml pour evaluate) — charge-le via yaml.safe_load(...) et applique les overrides utilisateur dessus. Le spec que consomme le modèle est nested dicts, pas des clés pointées plates ; la notation d'override pointée dénote des chemins dans le spec imbriqué, donc marche le chemin et assigne à la feuille. Les overrides de source de données sont obligatoires pour chaque action et doivent être construits à partir du tableau Per-Action Dataset Requirements dans references/datasets.md.

Voir references/spec-construction.md pour le pattern load-template-then-override et les blocs d'override typiques complets pour train (incluant policy.model_max_length=81920, dp_shard_size/dp_replicate_size et LoRA lora_alpha/r/lora_dropout), evaluate, quantize et inference, plus la note que les clés feuille de custom.val_dataset sont valides même quand absentes de l'objet spec par défaut.

Critical Overrides (Train)

Ce sont les clés dont les defaults du template sont incorrects ou où l'omission bascule l'exécution dans un mode différent :

Parameters

train.train_batch_per_replica doit être divisible par train.train_policy.mini_batch ; policy.model_max_length doit être 40960 ou plus haut pour SFT vidéo ; policy.parallelism.dp_shard_size doit égaler les GPUs par nœud et dp_replicate_size le nombre de nœuds ; custom.vision.fps et custom.vision.nframes sont mutuellement exclusifs (définis exactement un). Les modèles Cosmos-RL font 8B paramètres et bénéficient du sharding FSDP multi-GPU — recommandé : 8x A100 ou H100 (80GB chacun).

Voir references/parameters.md pour la référence de paramètre complète : boucle d'entraînement, modèle & policy, parallélisme (incluant guidance multi-node et pointeurs skill-platform), optimisation & chargement de données, vision encoders (détails fps vs nframes et le mode défaillance decord/torchvision), checkpointing, validation, logging et hardware.

Evaluate

L'évaluateur lit une config TOML plate avec clés top-level dataset, model, task, evaluation, vision, generation, metrics, results, num_gpus, results_dir. Le type de task est "" (General Evaluator, auto-détecte la classification binaire oui/non et calcule TP/FP/TN/FN/accuracy/precision/recall/F1) ou "its_directionality" (gauche/droite/tout droit ; N'utilise PAS pour la détection de collision). Le bloc actions.evaluate dans references/skill_info.yaml déclare les entrées et sorties ; pour l'invocation SDK voir skills/platform/tao-run-platform/SKILL.md.

Voir references/evaluate.md pour le détail du format-config, les notes task-type, l'évaluation LoRA (chemin checkpoint via spec_overrides avec model.enable_lora/model.base_model_path et comportement de fusion d'adapter), téléchargement sélectif (tirage média partiel {annotation, format, keys}), et le format des résultats et métriques.

Error Patterns

Les défaillances courantes incluent CUDA OOM en train (réduis mini_batch ou augmente dp_shard_size), OOM lors de l'évaluation LoRA, perte NaN, le mismatch de forme vision_embeds (augmente model_max_length à 40960), train_batch_per_replica non divisible par mini_batch, train_batch_per_replica plus grand que les samples par rank (le crash 0-step 'NoneType' object has no attribute 'state_dict'), cache dataset stale après changement fps/total_pixels, et la boucle d'authentification gated-repo.

Voir references/troubleshooting.md pour le diagnostic complet et la correction pour chaque pattern d'erreur.

DEFT Support and Parent-Model Inference

Cosmos-RL implémente le contrat de workflow DEFT pour les tâches de QA vidéo (voir config.json et workflow/deft/deft.md). L'analyse des écarts via scripts/analyze_gaps.py lit results.json de cosmos-rl, compare les prédictions par correspondance de chaîne exacte après .lower().strip(), et émet un parquet des cas d'échec — donc les prompts d'eval doivent forcer des réponses courtes contraintes. Les mappages d'inférence parent-model spécifiques du modèle (évaluer/inférer/quantifier/entraîner les champs spec → fonctions d'inférence, métadonnées checkpoint, et gestion parent_job_id) vivent dans la référence, pas dans config.json.

Voir references/deft-and-inference-mappings.md pour le détail et la limitation de l'analyse des écarts, et la table complète de mappage parent-model inference.