tao-finetune-cosmos-reason

Cosmos-RL

動画推論タスクにおける nvidia/Cosmos-Reason2-8B の教師ありファインチューニング（SFT）です。事前学習済みの重みは NGC ではなく HuggingFace から取得します。これはゲート付きモデルのため、HF_TOKEN が必要です。

GPU 数には dp_shard_size、ノード数には dp_replicate_size を使用する FSDP ベースの並列処理を使用します（標準の num_gpus／num_nodes は使用しません）。

使用するタイミング

動画に関する質問応答や動画推論のために、Cosmos-Reason2-8B をトレーニング、評価、量子化、または推論実行するときに、このスキルを使用します。基本的なワークフローは、HF_TOKEN によるアクセス制限を確認し、video_fps のアノテーションをサンプリングし、仕様テンプレートを読み込み、以下の重要なトレーニング用オーバーライドを適用してから、プラットフォームスキル（または有効な場合は AutoML）を通じて起動することです。

データクラスのスキーマ

生成された TAO Core スキーマは schemas/<action>.schema.json にパッケージ化され、利用可能なアクションは schemas/manifest.json に記載されています。生成された各スキーマからは、スキーマのトップレベルにある default フィールドをもとに references/spec_template_<action>.yaml も生成されます。AutoML の有効化は、モデルレイヤーの references/skill_info.yaml で automl_enabled により宣言されます。AutoML を実行するには、schemas/train.schema.json と references/spec_template_train.yaml が存在し、正しく解析できる必要があります。automl_default_parameters、automl_disabled_parameters、デフォルト値、最小値／最大値の境界、列挙値、オプションの重み、数式条件、依存関係、よく使用されるパラメーターには、パッケージ済みのトレーニングスキーマを使用してください。実行時に ~/tao-core が存在することを前提にしないでください。メンテナーはスキルバンクをパッケージ化する前に、スキーマ／テンプレートを再生成してください。

トレーニングアクションのポリシー

このモデルでは、モデルレイヤーで AutoML が有効になっています。トレーニング段階のリクエストを処理する前に、references/skill_info.yaml を読み、明示的な automl_policy の値、またはユーザーのワークフローリクエストから実行時のオーバーライドを判断してください。「AutoML をオフにする」「AutoML を無効にする」「HPO なし」「通常のトレーニング」のような表現は、この実行に限り automl_policy: off として扱います。それ以外の場合は、デフォルトで auto とします。automl_policy: auto、automl_enabled: true、schemas/train.schema.json と references/spec_template_train.yaml の両方がパッケージに含まれている場合、モデルの skill_dir を指定して、デフォルトで tao-skill-bank:tao-run-automl を通じてトレーニングアクションを実行してください。データセット、仕様、出力ディレクトリ、GPU／プラットフォーム設定、親チェックポイント、automl_policy に関するワークフロー／アプリケーションのオーバーライドは保持してください。モデルの直接トレーニングを使用するのは、automl_policy: off の場合、またはパッケージ済みのトレーニングスキーマ／テンプレートがない場合に限ります。スキーマがない場合は、AutoML が有効ではあるものの、スキーマが生成されるまでこのモデルでは実行できないことを報告してください。

evaluate、inference、export、デプロイの各フローなど、トレーニング以外のアクションはこのモデルスキル内で実行します。実行ごとの automl_policy オーバーライドによって、モデルのメタデータが変更されることはありません。

認証情報

• HF_TOKEN（必須）：HuggingFace アクセストークンです。ユーザーは https://huggingface.co/nvidia/Cosmos-Reason2-8B でモデルの利用規約に同意し、読み取りアクセス権を持つトークンを用意する必要があります。docker_env_var としてコンテナに渡されます。

データセット

データセットのタイプは llava 形式の vlm で、受け付けるインテントは training、evaluation、testing です。入力には、データセットのルート（ルートモードでは <root>/annotations.json と <root> をメディアパスとして対応付けます）または spec キーへの直接パス（アノテーションとメディアが別々の場所にある場合）を指定できます。train／AutoML／evaluate を開始する前にアノテーション JSON をサンプル確認し、各レコードに video_fps が含まれていることを必須としてください。video_fps がないと、ジョブの開始後に Cosmos-RL SFT ローダーが Error processing sample: 'video_fps' で失敗します。これがない場合は runner の生成前に停止し、アノテーションファイルを修正するようユーザーに依頼してください。torchrun の実行中にこの問題を見つけるために AutoML を開始してはいけません。

学習要件の全容、起動時の確認事項（spec キーのオプション、ルートモードのマッピング、コンテナイメージの確認、check_tao_launch_preflight.py の呼び出し）、Per-Action Dataset Requirements 表、直接上書きの例を含む data_sources のマッピング、評価データセット／自動分割のポリシーについては、references/datasets.md を参照してください。

Spec の構築

cosmos-rl は mode: config です。必ず references/spec_template_train.yaml（evaluate の場合は spec_template_evaluate.yaml）を基に開始してください。yaml.safe_load(...) で読み込み、その上にユーザーのオーバーライドを適用します。モデルが使用する spec は、フラットなドット区切りキーではなくネストされた dict です。ドット区切りのオーバーライド表記はネストされた spec 内のパスを示すため、パスをたどって末端に値を代入してください。データソースのオーバーライドはすべてのアクションで必須であり、references/datasets.md の Per-Action Dataset Requirements 表に基づいて作成してください。

テンプレートの読み込み後にオーバーライドを適用するパターンと、train（policy.model_max_length=81920、dp_shard_size／dp_replicate_size、LoRA の lora_alpha／r／lora_dropout を含む）、evaluate、quantize、inference の一般的なオーバーライドブロックの全容については、references/spec-construction.md を参照してください。また、custom.val_dataset の末端キーは、デフォルトの spec オブジェクトに存在しない場合でも有効であるという注意事項も記載されています。

重要なオーバーライド（Train）

テンプレートのデフォルト値が誤っているキー、または省略すると実行モードが変わってしまうキーは次のとおりです。

パラメーター	テンプレートのデフォルト	必須値	理由
policy.model_name_or_path	nvidia/Cosmos-Reason2-8B	hf_model://nvidia/Cosmos-Reason2-8B（またはローカルのチェックポイント）	ベアな HF ID を指定すると、cosmos-rl は実行時に HF Hub から取得します。hf_model:// URI 形式では、学習コマンドの開始前に重みが事前ダウンロードされます
policy.model_max_length	40960	40960 以上を維持	約40k未満にすると、動画入力で vision_embeds の形状が不一致になります
train.train_batch_per_replica	32	train.train_policy.mini_batch の任意の倍数	不一致の場合、即座に AssertionError が発生します
train.train_policy.type	"sft"	SFT ワークフローでは "sft" を維持	エージェントの再生成時に削除されると、cosmos-rl が RL モードに切り替わり、ロールアウトレプリカが割り当てられ、マルチノード実行が試みられ、num_nodes=1 の場合にホスト名エラーが発生します

パラメーター

train.train_batch_per_replica は train.train_policy.mini_batch で割り切れる必要があります。動画 SFT では policy.model_max_length を40960以上にする必要があります。policy.parallelism.dp_shard_size はノードあたりの GPU 数、dp_replicate_size はノード数と一致させてください。custom.vision.fps と custom.vision.nframes は相互排他的です（いずれか一方だけを設定してください）。Cosmos-RL モデルは8Bパラメーターで、複数 GPU による FSDP シャーディングの効果が期待できます。推奨構成は 8x A100 または H100（各80GB）です。

学習ループ、モデルとポリシー、並列処理（マルチノードのガイダンスとプラットフォームスキルへのポインターを含む）、最適化とデータ読み込み、ビジョンエンコーダー（fps と nframes の詳細、decord／torchvision の失敗モードを含む）、チェックポイント、検証、ロギング、ハードウェアに関する完全なパラメーターリファレンスは、references/parameters.md を参照してください。

評価

評価器は、トップレベルキーが dataset、model、task、evaluation、vision、generation、metrics、results、num_gpus、results_dir の フラットな TOML 設定を読み込みます。タスクタイプは ""（汎用評価器。二値の yes/no 分類を自動検出し、TP/FP/TN/FN/正解率/適合率/再現率/F1 を計算）または "its_directionality"（左／右／直進。衝突検出には使用しないでください）です。references/skill_info.yaml の actions.evaluate ブロックで入力と出力を定義しています。SDK からの呼び出しについては skills/platform/tao-run-platform/SKILL.md を参照してください。

設定フォーマットの詳細、タスクタイプに関する注意事項、LoRA 評価（spec_overrides 経由のチェックポイントパス指定と model.enable_lora／model.base_model_path、アダプターのマージ動作）、選択的ダウンロード（メディアの一部を取得する {annotation, format, keys}）、結果フォーマットとメトリクスについては、references/evaluate.md を参照してください。

エラーパターン

よくある失敗には、train 中の CUDA OOM（mini_batch を減らすか、dp_shard_size を増やしてください）、LoRA 評価中の OOM、NaN loss、vision_embeds の形状不一致（model_max_length を 40960 に増やしてください）、train_batch_per_replica が mini_batch で割り切れない問題、train_batch_per_replica がランクごとのサンプル数を上回る問題（0 ステップでクラッシュし、'NoneType' object has no attribute 'state_dict' が発生）、fps／total_pixels の変更後に古いデータセットキャッシュが残る問題、ゲート付きリポジトリの認証ループなどがあります。

各エラーパターンの詳しい診断と修正方法については、references/troubleshooting.md を参照してください。

DEFT のサポートと親モデルの推論

Cosmos-RL は、動画 QA タスク向けの DEFT ワークフロー契約を実装しています（config.json と workflow/deft/deft.md を参照）。scripts/analyze_gaps.py によるギャップ分析では、cosmos-rl の results.json を読み込み、.lower().strip() の適用後に完全一致で予測を比較し、失敗事例の parquet を出力します。そのため、評価プロンプトでは短く制約された回答を強制する必要があります。モデル固有の親モデル推論マッピング（evaluate／inference／quantize／train の spec フィールドから推論関数への対応、チェックポイントのメタデータ、parent_job_id の処理）は config.json ではなく、リファレンスに記載されています。

ギャップ分析の詳細と制限事項、および親モデル推論の完全なマッピング表については、references/deft-and-inference-mappings.md を参照してください。