tao-finetune-cosmos-reason

Cosmos3 TAO トレーニング

モデル向けフロントエンドは共有のものを1つだけ維持します。バックエンドのイメージフィールドと契約パスは references/skill_info.yaml の backend_contracts にあります。イメージのリテラル値は versions.yaml から付与され、参照先のバックエンド YAML がネイティブのランタイムスキーマを定義します。両者を相互に変換してはいけません。

必須のランタイム情報

トレーニングを計画する前に、以下をすべて収集してください。履歴、別のユーザー、以前のジョブ、イメージ、または開発者のチェックアウトからパスを推測してはいけません。

• base_model_path_or_uri。Hugging Face のモデル ID または URL の場合、ブランチやタグなどの任意の分かりやすい base_model_revision を受け付けます。省略された場合は main を解決し、ユーザーにコミット SHA を尋ねてはいけません。Hub API を通じて選択した参照を読み取り専用で不変のコミットに解決し、モデル ID、要求された参照、解決された SHA をプランに固定します。完全なローカルスナップショットにはリビジョンは不要で、ファイルのフィンガープリントによって固定されます。
• Cosmos3-Nano の場合、入力チェックポイントの model_type を明示します。選択肢は qwen3_vl または cosmos3_omni です。ユーザーが指定していない場合は、計画前に一度だけ尋ねてください。config.json、モデル ID、パス名、または以前の実行から選択を推測してはいけません。2つの選択肢を平易な言葉で説明してください。qwen3_vl は互換性のある Hugging Face チェックポイントをそのまま使用します。一方、cosmos3_omni はトレーニング前に、正確な Qwen3-VL safetensors への不変な変換が必要です。回答は base_model_format として記録します。Cosmos3-Edge は、解決されたモデル ID から cosmos3_edge と推定されるため、Nano 専用のこの選択肢は提示しません。
• 通常の情報収集で Omni の準備に関する実装フィールドを提示してはいけません。Nano では Qwen/Qwen3-VL-8B-Instruct を使用し、両方の Hub モデルを不変のコミットに解決して、選択されたバックエンドに同梱されたコンバーターを実行します。Framework では cosmos_framework.scripts.convert_model_to_vlm_safetensors を使用します。Cosmos-RL では、固定された分離コンバーターランタイムで cosmos_rl.model_preparation.vlm_safetensors を使用します。明示的に指定された prepared_checkpoint_path またはドナーは検証しますが、デフォルトで指定を求めてはいけません。
• hf_model://nvidia/Cosmos3-Nano を直接受け付けます。ゲート付きまたはプライベートなモデルを解決できない場合は、セッション環境で HF_TOKEN を設定するようユーザーにのみ求めてください。SHA を調べるよう求めたり、トークン値をチャットで尋ねたりしてはいけません。
• 明示的な動画サンプリング方式：均一な nframes または fps のいずれかです。FPS 方式では min_frames と max_frames も設定できます。どちらの方式でも、選択したバックエンドでサポートされているクリップ時間、リサイズ、ピクセル予算の各フィールドを設定できます。
• 会話形式またはタスク対応の動画教師あり学習用のトレーニング／検証アノテーションパスとメディアルート、および任意のタスク選択。
• 比較を行う場合は、backend を明示します。cosmos-framework または cosmos-rl を指定してください。
• training_mode：dense または peft。PEFT の場合は、rank、alpha、dropout、target modules、bias、RS-LoRA、modules-to-save、および adapter precision も必要です。
• ユーザー所有の results_dir、checkpoint_dir、cache_dir。SLURM の場合は、sqsh_cache_dir、ssh_key_path、マウント、およびスケジューラー設定も必要です。
• ランタイムの優先順：計算環境から読み取り可能な sqsh_path、明示的なイメージ、次に references/skill_info.yaml 内の選択されたバックエンドのイメージです。SLURM では、sqsh_cache_dir 内で一度だけ再利用または変換します。SQSH のファイル名とイメージタグを比較したり、ソースの由来／SHA を尋ねたりしてはいけません。
• リポジトリパス、コミット／ツリー、ブランチ、ベースイメージ、ビルドコンテキスト、およびタイムスタンプは、明示的な source-build にのみ必要な高度な入力です。references/cosmos-backend-operations.md を参照してください。ランタイム選択からビルドを推測してはいけません。

プランナーは元の各パスを保持し、アクセス可能な realpath を報告します。必須パスがない場合は失敗します。指定された SQSH が存在しない場合は失敗します。SQSH が省略されている場合は、同梱イメージを選択します。過去のフォールバックパスやイメージは使用できません。

Nano チェックポイントのモデルタイプ選択

選択された base_model_format をユーザーの決定として扱い、提供されたローカルチェックポイントの config.json.model_type と一致することを確認してください。不一致の場合は失敗となり、ソースチェックポイントのラベルを付け直したり書き換えたりする許可ではありません。

qwen3_vl の場合、完全に互換性のある Hugging Face Nano チェックポイントをフィンガープリントして直接使用してください。cosmos3_omni の場合、起動レビューで Cosmos-RL が互換チェックポイントを自動的に準備することをユーザーに伝え、計画された出力パスを明示し、ソースチェックポイントを変更せずに保持してください。ユーザーにアーキテクチャドナー、準備イメージ、または準備 SQSH を要求しないでください。バックエンドが所有する準備ステップは、選択されたプラットフォームのユーザー所有の checkpoint_dir の下に検証済みの qwen3_vl チェックポイントを出力します:

• Docker: ローカル Docker ホストの checkpoint_dir。
• SLURM: コンピュートノードで検証された共有 checkpoint_dir。明示的なコンテナマウントでカバーされます。変換は SLURM/Pyxis 契約を通じて実行してください。変換されたチェックポイントをコントローラーローカルストレージに書き込まないでください。

高度な上書きが明示的に指定されていない限り、パッケージ化された Nano アーキテクチャマッピングと選択されたバックエンドランタイムを使用してください。ソース、アーキテクチャマッピング、変換された config/tokenizer/processor/index/shards、および変換の来歴をフィンガープリントしてください。変換の前に、封印されたプランのバックエンドネイティブのトレーニングフィールドと VLM_SAFETENSORS_PATH を、選択されたコンテナ内の計画された変換済みチェックポイントにバインドしてください。封印されたプランを変更せずに、トレーニングの前にその正確な出力を検証してください。元の Omni/Hugging Face パスは来歴のみとして残り、ランタイムモデルパスとして決して残ってはなりません。再利用は、正確なターゲットが完全に一致する変換来歴を持ち、同じ検証に合格する場合にのみ許可されます。

公開 Cosmos3-Edge チェックポイント契約

公開モデルを、解決された不変リビジョンまたはローカルスナップショットで受け入れてください。2 つ目のチェックポイントを要求しないでください。 references/skill_info.yaml と references/cosmos-framework-backend.yaml からモデル対応のランタイムデフォルトを適用し、個別のモデルとプロセッサプロファイルのフィンガープリント、および各デフォルト/上書きの由来を保持してください。

バックエンドの選択

最初に scripts/cosmos_workflow.py resolve を実行してください。

リクエスト	自動選択
Cosmos3-Nano プレーントレーニング	Cosmos-RL (互換性デフォルト)
Cosmos3-Nano AutoML/HPO	Cosmos-RL
Nano Framework-DCP エクスポート	Cosmos Framework
明示的なバックエンドなしの Nano 評価/推論/マイクロサービス	Cosmos-RL
Nano 量子化	Cosmos-RL
Cosmos3-Edge トレーニング/エクスポート/評価/推論/マイクロサービス	Cosmos Framework

明示的にサポートされたバックエンドが優先されるため、ユーザーはモデルの所有権を変更せずに Nano トレーニング用の Cosmos Framework を選択できます。比較実行は auto を拒否するため、実験の両側が意図的に強制されます。 Framework でトレーニングされたチェックポイントは、ネイティブの正確なキーエクスポーターを使用し、次にリポジトリベースの TAO 評価アダプターを使用します。これは Framework を Cosmos-RL バージョンにするものではありません。

評価の取り込みと継承

すべての evaluate アクションに対して scripts/evaluation_workflow.py を実行し、references/cosmos-reason-evaluate.md に完全に従ってください。親トレーニングプランは、継承可能なすべてのモデル、データセット、プロンプト、前処理、精度、チェックポイント、およびスコアリングフィールドを所有します。ユーザーにそれらを繰り返し尋ねないでください。ヘルパーの required_user_inputs について一度だけ尋ね、その automated_actions を実行し、チェックサムが有効な ready=true プランのみを起動してください。Cosmos-RL ポリシーチェックポイントには出力された cosmos_rl_checkpoint_pre_action が必要であり、Framework DCP 入力には出力されたエクスポート事前アクションが必要です。ready プランには検証済みの spec_bundle.execution が含まれており、それを変更せずに選択されたプラットフォームに渡してください。Cosmos はランタイムアテステーションと評価設定を所有し、プラットフォームは起動を所有します。

Framework のチェックポイント事前アクション

Framework の評価、推論、またはマイクロサービスのアクションを実行する前に、 scripts/framework_checkpoint_action.py plan と、そこから出力される prepare および verify の各ステップを実行してください。references/cosmos-backend-operations.md に従い、 ユーザーに DCP を手動でエクスポートするよう決して依頼しないでください。SLURM では、 workflow_contract.action_helper_dependencies で宣言されたヘルパーの依存関係セットのみを ステージングしてください。プラットフォームが閉じたバンドルを検証します。検証済みの action_model_path のみを使用し、一致する完全なエクスポートのみを再利用して、 事前アクション、マニフェスト、フィンガープリント、および独立した子の結果を記録してください。

必須ゲート

これらのステージを順番に実行し、出力を永続化してください。

1. モデル／バックエンド／アクションを解決し、選択したバックエンドのコントラクトを読み込みます。
2. 認証情報は存在の有無のみを確認します。認証情報の値を読み取ったり、永続化したりしてはいけません。トークンは必要とする操作に限って要求します。
3. 必須のインテーク順序に従って、ツール、ストレージ、パス、ランタイムの選択を検証します。既存の SQSH モードとパッケージ済みイメージモードでは、ソースのゲートをスキップします。
4. 明示的に source-build が指定された場合に限り、クリーンなソースを検証／ビルドし、/opt/tao/image-provenance.json を確認します。ホストのソースをトレーニングにマウントしてはいけません。
5. Nano チェックポイントのモデルタイプを明示的に選択する要件を適用します。選択が cosmos3_omni の場合、起動レビューで変換とプラットフォーム管理の出力パスを示し、承認後、選択したクリーンなバックエンドイメージにパッケージされた共有 TAO 統合エントリーポイントを通じてモデルを準備します。URI／モデル ID の参照は、不変の Hub コミットに自動的に解決します。テンソル／設定キーを完全一致で検証し、モデル、トークナイザー、プロセッサー、重みインデックス、すべてのシャード、来歴のフィンガープリントを取得します。トレーニングには元のソースパスではなく、検証済みの変換後パスを割り当てます。
6. 入力、件数、重複、重なり、タスク、ID を検証します。バイトハッシュを行わないリクエストでは、両方の高速フィンガープリントフラグを選択します。メタデータはハッシュ化したまま、重み／メディアのペイロードにはパス＋サイズを使用します。 割り当て済みの計算ノードから、解決済みの入力を再度確認します。 SLURM ストレージが起動ホストにマウントされていない場合は、cosmos_workflow.py にチェックイン済みの cosmos_common.py インスペクターを SSH 経由でログインホストにストリーミングさせます。これは stdin から実行され、リモートの realpath 値を保持し、リモートスクリプトやソースオーバーレイを作成しません。SSH ベースの起動ホストでは、ローカルの Lustre、sbatch、srun を必須にしてはいけません。この高コストな入力検査は plan 動詞で正確に 1 回だけ実行し、ローカルの --plan-artifact <path> を渡して、残りの起動動詞に備えて解決済みリクエストと検査結果を封印します。
7. 構造化されたデータセットコントラクトから動画ランタイムを解決し、references/cosmos-reproducibility-gates.md のすべてのプロファイルゲートを適用します。 Cosmos-RL の auto は、video_conversation ではソースに組み込み済みの pynv-device-rgbp を、task_aware_video_reasoning では system-pyav を選択します。 Framework は torchcodec-cuda-on-demand を選択します。すべてのデフォルト設定では、ディスクへの事前ウォームアップを行わず、ランク単位のオンデマンドメモリを上限付きで使用します。メディアの繰り返し検証では、レコード、明示的なバッチ、重み付け、プロンプト、前処理を維持する場合に限り、バックエンドネイティブのグループ化シャーダーと検証専用キャッシュを使用できます。バッチサイズ 1 との同等性を緩和するスループット設定には、ユーザーの承認が必要です。
8. バックエンドネイティブの TOML、環境、トポロジー、プリフライトコマンド、同等性データ、ランタイムプロファイル、メタデータを生成します。完全な仕様にはサンプル数の上限を含めません。読み取り専用の preflight、レビュー後の materialize、render-slurm では、同じ封印済み --plan-artifact を再利用し、元の入力を繰り返し指定してはいけません。検証済みの計算環境内でアトミックにマテリアライズし、コンテナパスは明示的なマウントのみから導出し、ソースパッチをクラスターにコピーしてはいけません。診断用サブセットは明示的なオプトインとし、起動の前提条件にしてはいけません。
9. SLURM では、提供済み／導出済みの SQSH を再利用するか、GPU サブミット前に選択したイメージを 1 回変換します。SQSH の SHA とソースの来歴は、ランタイムゲートではありません。 Omni の準備が必要な場合は、SQSH のファイルシステムを検査し、共有 TAO ランチャー、ネイティブ Framework コンバーター、/opt/tao/framework-converter-runtime.json が含まれていなければ拒否します。ランタイム成果物には validation_mode=imported_converter_module が報告されている必要があります。これは、イメージのビルド中に分離されたコンバーターの推移的な依存関係グラフがインポートされたことを証明します。ファイルが存在するだけでは不十分です。 トレーニング割り当て内で、Pyxis／Enroot、マウント、Python／パッケージ、デコーダー、GPU、CUDA、NCCL、ストレージを検証します。
10. 要求されたトレーニングジョブを直接起動します。ユーザーが明示的に要求しない限り、別個のスモークジョブをサブミットしてはいけません。Cosmos-RL の VLM トレーニングでは、パディングを考慮した attention_mask を出力し、最初の backward パス後かつ最初のオプティマイザー更新前に視覚勾配コントラクトを実行する、パッケージ済みソースを必須とします。ビジョンエンコーダー、視覚プロジェクター、言語モデル、言語ヘッドについて、総数／学習可能数／凍結数と勾配ノルムを永続化します。学習可能な視覚コンポーネントに勾配がない場合、ノルムが有限値でない場合、またはノルムがゼロの場合は、直ちに失敗させます。明示的に凍結された視覚コンポーネントは、失敗ではなく適用対象外として報告します。
11. 完全な仕様を 1 回マテリアライズし、同じ計画アーティファクトからジョブをレンダリングする前に、計算環境内でその SHA256 を検証します。スケジューラーと構造化された TAO の状態を終端結果まで監視し、スケジューラーの状態とは独立して子プロセスの終了コードを保持します。完了を報告するには、子プロセスの終了コードがゼロであること、構造化された SUCCESS、有限値の全体／トレーニング／検証損失、チェックポイントの完了、最終評価指標が必須です。
12. scripts/evaluation_workflow.py で評価を解決します。ファインチューニングの成果物を正確に引き継ぎ、残りのユーザー入力のみを収集して、バックエンド管理の自動チェックポイント事前アクションを実行し、ready=true を必須とします。 Cosmos-RL では、cosmos_rl_checkpoint_action.py で選択した HF エクスポートを検証し、そのマニフェストを使って解決を再実行してから、選択したプラットフォームを通じて出力された spec-bundle をサブミットします。ネイティブポリシーディレクトリを選択したり、ライフサイクルをアプリケーション管理のランチャーにコピーしたり、結果／状態変数を即興で設定したりしてはいけません。 選択したチェックポイントを、同一のプロンプト、前処理、生成、正規化、タスクスコアリングで評価します。最終指標は scripts/extract_cosmos_metrics.py で抽出します。

データセット契約

データセットは、プロジェクト、ベンチマーク、ディレクトリ、ファイル名ではなく、構造によって解決してください。サポートされるファミリーは次のとおりです。

• video_conversation: メディアと、少なくとも 2 つの ShareGPT、LLaVA、または OpenAI 形式の会話ターンを含む JSON 配列。
• task_aware_video_reasoning: メディア、タスク識別子、および会話/応答ターゲットを含む、1 つ以上の item-envelope または配列アノテーションファイル。

dataset_family のデフォルトは auto とし、すべてのアノテーションを検査し、train と validation が同じファミリーに解決されることを必須とします。レコード数、ユニークメディア数、メディアの再利用、拡張子、バイトサイズ分布、タスク/メトリクスのメタデータ、および宣言された width、height、FPS、duration を取得してください。これらの特性とモデル層から、プロセッサ、キャッシュ、リソースプロファイルを選択してください。顧客データセット名で分岐しないでください。

accuracy を宣言するタスクは、決定論的な accuracy に参加します。一般的なバイナリおよび多肢選択式のタスクタイプは認識されます。生成タスクは、宣言されたメトリクスを報告し、理由を付けて集計 accuracy から除外されます。集計 accuracy は、accuracy 定義を持つレコードに対して example で重み付けされます。

Dense および PEFT 契約

Dense SFT には LoRA ブロックがなく、trainable、frozen、total のカウントを報告します。PEFT は、rank、alpha、dropout、targets、bias、RS-LoRA、保存されたモジュール、精度、trainable カウントをバックエンド間で保持します。セマンティクスが一致しない場合はペアをブロックします。

公平な比較のために、同じ論理モデル、train/validation レコード、メディア、プロンプト、フレーム、シーケンス長、精度、シード、エポック、実効グローバルバッチ、オプティマイザ、学習率、スケジュール、ウォームアップ、weight decay、クリッピング、損失マスキング、validation/checkpoint のケイデンス、評価対象チェックポイント、および生成/正規化設定を強制してください。差異は、等価な構文、避けられない実装上の差異、または無効な不一致として分類してください。無効な不一致はペア全体をブロックします。

メトリクスと完了

必須の主要メトリクスは次のとおりです。

• 完全な実行におけるグローバルに還元されたトークン重み付き学習損失（分子と有効ラベル分母を含む）。
• 最終 validation におけるグローバルに還元されたトークン重み付き損失（分子と有効ラベル分母を含む）。
• リポジトリの評価器による最終 validation メトリクス、およびそれが出力する任意の補助値。評価後の 2 つ目のゲートを追加しないでください。

コンソール行を平均したり、平均をランク付けしたりしないでください。ステップ損失は平均学習損失ではありません。validation ハートビートは最終 validation 損失ではありません。生成の完全一致は、タスクがそれを定義しない限り accuracy ではありません。

ネイティブの Framework コールバックとネイティブの Cosmos-RL ロガーが、早期失敗、checkpoint、進捗、メトリクス、および終端イベントを所有します。ステータスブリッジを配置したり、コンテナ起動時にステータスにパッチを当てたりしないでください。SLURM からの COMPLETED は、子プロセスの終了コードが非ゼロであるか、終端の TAO 状態が成功でない場合、失敗です。

SLURM の不変条件

生成されるジョブでは、Bash、Pyxis 経由の SQSH、デフォルトでの再キューなし、ノードごとにランチャータスク 1 つ、実行時に指定されるログ、およびトレーニング子プロセスの終了コードを使用します。単一ノードの排他的割り当てでは、SBATCH の契約上、要求された CPU 数を維持しますが、トレーニングステップには SLURM が実際に割り当てたすべての CPU を渡し、要求数、割り当て数、ステップ数を記録します。トレーニング子プロセスの実行前に、同じ割り当て内で、プランナーが管理するパッケージ済みランタイムのゲートをトレーニングジョブの最初の Pyxis ステップとして実行します。ゲートが失敗した場合は、独立した子プロセス終了アーティファクトを書き込み、トレーニングをブロックします。生成されるジョブでは SLURM_EXPORT_ENV=ALL を設定し、プラットフォーム側のコンシューマーも引き続き sbatch --export=ALL を使用してサブミットします。各 Pyxis ステップには、プランナーが管理するランタイム変数名も --container-env を通じて渡されるため、イメージに焼き込まれた ENV 値によって、選択されたデコーダー、フレーム転送、キャッシュ、ワーカープロファイルが上書きされることはありません。フレームワークのトポロジーは、シャード＝gpus_per_node、レプリカ＝nodes です。 Cosmos-RL では、ノード 0 にコントローラーを 1 つ配置し、そのポリシーワーカーのトポロジーを使用します。 複数ノードでの実行では、非同期分散チェックポイントを拒否します。

すべてのジョブメタデータレコードは schemas/cosmos-job-metadata.schema.json に対する検証に合格し、認証情報を含めずに、パス、フィンガープリント、ランタイム ID、設定、リソース、状態、出力、タイミングを含める必要があります。ソースの来歴が存在するのは source-build の場合のみです。SQSH SHA は任意であり、ランタイムゲートには使用されません。

ソースに影響する復旧

実行でコードまたはイメージの不具合が明らかになった場合は、該当する経路を停止し、担当リポジトリを変更してテストを追加し、コミットしたうえで、クリーンなチェックアウトからイメージと SQSH の両方を再ビルドし、クリーンで封印済みのプランから、影響を受けるすべてのトレーニングジョブを再起動します。実行中のコンテナーを編集したり、既存のイメージにパッチを適用したり、ソース変更後に古い SQSH を再利用したり、一時的な起動スクリプトを実装として頼ったりしてはいけません。

ソース担当者とテストの対応表として references/cosmos-reproducibility-gates.md を使用してください。

インフラストラクチャの再試行では、起動スキルが障害を分類し、新しい --retry-of レコードを開きます。SLURM は検証済みのノードインベントリと除外情報を提供します。新しいレコードの <action-root>/config/train.toml を指定して cosmos_workflow.py retry-plan を実行してください。これにより、書き込み可能なすべてのパスが付け替えられ、Cosmos リクエストが再封印されます。そのプランをレンダリングしてください。SBATCH にパッチを適用してはいけません。