physical-ai-video-data-augmentation

Physical AI Video Data Augmentation Workflow Orchestrator

OSMO で VDA を実行するためのデフォルトのワークフロースキルです。フローの選択、事前チェック、キャッシュの準備状況、推論パスの決定、送信時の補間、監視、出力の取得を担当します。コンポーネントスキルは参照専用です。

目的

事前チェックから出力のダウンロードまで、エンドツーエンドの VDA ワークフローを安全かつ再現可能な形で実行します。

コンテナー内部の調整のみを目的とする質問には、このスキルを使用しないでください。

前提条件

事前チェックまたは送信を実行する前に、以下を確認してください。必須のシークレットが不足している場合は、scripts/preflight_credentials.sh から USER_INPUT_REQUIRED: が返されます。

要件	満たす方法	用途
NGC API キー（任意）	NGC_API_KEY、NGC_CLI_API_KEY、または NVIDIA_API_KEY／OPENAI_API_KEY／VLM_API_KEY／LLM_API_KEY に設定された互換性のある nvapi-* トークン	nvcr_io の認証情報の更新と NGC REST スコープのプローブに任意で使用します。デフォルトの VDA イメージ参照は、ワークフローのレジストリプローブで検証されます
Hugging Face トークン	HF_TOKEN（または HUGGING_FACE_HUB_TOKEN）、または ~/.cache/huggingface/token にキャッシュされたトークン	OSMO の hf_token 認証情報を作成し、アクセス制限のある Cosmos／SeedVR の重みを取得します
OSMO CLI アクセス	PATH 上の osmo にログインし、デフォルトプロファイルと、storage_url に一致する登録済み DATA 認証情報プロファイルを設定します	ワークフローの送信と監視、およびオブジェクトの一覧表示とダウンロードに使用します
GPU プール	osmo pool list --mode free に ONLINE のプールが 1 つ以上あり、POD_TEMPLATE に GPU の許容設定／セレクターが含まれていること	スケジューリングの設定とワーカータスクに使用します

任意（厳密な NGC 組織／チームのプローブでのみ使用）：NGC_ORG と NGC_TEAM（または NGC_CLI_ORG／NGC_CLI_TEAM）。外部 VLM／LLM エンドポイントキーは事前チェックではなく、個別に検証されます。

キーの取り扱いに関するルール：nvapi-* トークンは nvcr_io で正式にサポートされる入力です。トークンのプレフィックスだけを根拠に拒否しないでください。信頼できる情報源として、ワークフローのレジストリプローブ結果を使用してください。

手順

1. ユーザーの意図に基づいて、ワークフロー（auto_labeling、augmentation_and_al、e2e、e2e_super_resolution）を選択します。
2. 実行アクションを開始する前に、暫定的な実行時間の概要を提示します。
3. 送信前に、事前チェックと準備状況の確認を実行します。
4. アクティブなデータセットバックエンドから送信時の値を導き出します（storage_url を推測してはいけません）。
5. 補間値を明示してワークフローを送信し、完了まで監視します。
6. 出力を取得し、拡張フローについては並べて比較した証拠を提示して、タスクの結果を要約します。

スクリプトの実行には run_script(...) を使用してください。標準的な例：

run_script("bash scripts/preflight_credentials.sh --workflow assets/configs/osmo/augmentation_and_al.yaml")
run_script("python3 scripts/pre_submit_guard.py --workflow assets/configs/osmo/auto_labeling.yaml")
run_script("bash scripts/prepare_demo_assets.sh /srv/sdg/data/vda_inputs")

利用可能なスクリプト

引数の詳細は、各スクリプトの --help を参照してください。

スクリプト	役割
scripts/preflight_credentials.sh	シークレット／コントロールプレーンの事前チェックとワークフローイメージのアクセス確認
scripts/pre_submit_guard.py	送信時の補間、キャッシュ、データセットの安全性チェック
scripts/prepare_demo_assets.sh	デフォルトのデモパス用のデモ動画の取得とフラット化
scripts/generate_configs.py	セットアップ時の設定ファイルとクックブック投影の生成
scripts/cosmos_worker.sh	拡張ワーカーの実行
scripts/pl_original_worker.sh	元動画の自動ラベリングワーカーの実行
scripts/pl_augmented_worker.sh	拡張動画の自動ラベリングワーカーの実行
scripts/osmo_barrier.py	マルチノードのバリア同期
scripts/stage_run_artifacts.sh	実行出力一式と入力動画のローカルミラー
scripts/render_side_by_side.sh	ローカルの成果物から並列比較レンダリングを作成

対応フロー

フロー	OSMO YAML	グループの順序	代表的な用途
augmentation_and_al	assets/configs/osmo/augmentation_and_al.yaml	setup -> augmentation -> auto_labeling_augmented	1 つ以上の動画を拡張してから、拡張後の出力に自動ラベル付けを行います
auto_labeling	assets/configs/osmo/auto_labeling.yaml	setup -> auto_labeling	元の動画のみにラベル付けを行います
e2e	assets/configs/osmo/e2e.yaml	setup -> (auto_labeling_original + augmentation) -> auto_labeling_augmented	スループットを最優先するフローです
e2e_super_resolution	assets/configs/osmo/e2e_super_resolution.yaml	setup -> auto_labeling_original -> augmentation -> auto_labeling_augmented	拡張前に SR のゲートを設ける逐次フローです

後方互換性のため、レガシーエイリアス assets/configs/osmo/augmentation_and_pl.yaml も引き続き使用できます。

ユーザーのリクエストに適したワークフローを選択する

ユーザーの意図	ワークフロー
「ソース動画にラベルを付けて」／「PL のみ」／「拡張なし」	auto_labeling
「拡張動画を作成してラベルを付けて」	augmentation_and_al
「パイプライン全体をすばやく実行して」	e2e
「パイプライン全体を実行して、まず SR 強化済みの元動画をゲートに通して」	e2e_super_resolution

判別：曖昧なリクエストは確定前に確認する

自律的に進めることを基本とし、不足情報によって実行が妨げられる場合にのみ質問します。

自律的に設定する既定値（質問しないでください）

• データセットのソースが指定されていない場合は、VDA デモの手順（scripts/prepare_demo_assets.sh）を実行し、dataset=vda-demo を使用して続行します。
• フローが明示されていない場合は、augmentation_and_al を既定値として使用します。
• エンドポイントのモードが指定されていない場合は、クラスター内の永続的な NIM の再利用を既定とし、正常でない場合は NIM のデプロイまたは修復を自動で行います。
• キャッシュがない場合は、setup_model_cache.yaml を実行し、送信前のガードを再実行して、成功したら自動的に続行します。
• ステージが正常に完了したら、すぐに次のステージへ進みます。「準備ができたらお知らせください」など、承認を求めて一時停止しないでください。

判別のために一時停止する条件

不足している入力	重要な理由	質問
プリフライトから USER_INPUT_REQUIRED が返された	必須のシークレットがありません	不足している値だけを正確に尋ね、実行を妨げている問題を解消する簡潔な質問を 1 つします
アクティブなデータセット／アップロードルートからストレージバックエンドのプレフィックスを特定できない	スキームを誤ると、実行時にストレージ認証が一致しません	「今回の実行で使用する、バックエンド固有のルートプレフィックスは何ですか？」
オンラインの GPU プール／プラットフォームを選択できない	ワークフローでセットアップ／ワーカーをスケジュールできません	「この実行の対象となる GPU プール／プラットフォームはどれですか？」

判別の質問をしない場合

• ユーザーがシーンプロファイルの変更を明示的に求めていない限り、クックブックについて質問しないでください。
• 外部エンドポイントを既定で提案しないでください。
• A/B キャッシュ戦略について質問しないでください。自動キャッシュセットアップを既定とします。
• 既存の NIM をスケールダウンするよう求めないでください。これは禁止されています。
• 入力がない場合に、動画を捏造、スクレイピング、またはランダムに生成しないでください。
• ユーザーが別のデータセットを明示的にリクエストしない限り、VDA 以外のデモソース（Carline の適応用アセットなど）を使用しないでください。

ステップ 0：フローを選択して入力を収集する

入力動画のポリシー（必須）

• ユーザーが提供した動画入力（データセット URL、ローカルパス、アップロードフォルダー）は、常に第一の選択肢として維持してください。
• 明示的に指定されたユーザーの動画を、デモアセットやその他のソースに置き換えないでください。
• 動画入力が指定されていない場合は、追加のソース選択に関する質問をせず、scripts/prepare_demo_assets.sh（HF データセットフロー）を使用して VDA デモアセットをデフォルトで使用してください。
• ユーザーが入力動画またはデータセットを明示的に指定した場合は、デモアセットではなく、その入力を優先して使用してください。
• デフォルトのデモパスでは、VDA デモアセット（nvidia/video-data-augmentation-demo）のみを使用してください。
• ユーザーが明示的に希望しない限り、任意のウェブ動画のダウンロードやプレースホルダー動画を提案しないでください。

不足している値のみを収集してください。

1. データセットソース（明示的に指定された dataset_url またはローカルのアップロードフォルダーを優先します。指定がなければ VDA デモアセットをデフォルトで使用して続行します）。
2. フロー（auto_labeling、augmentation_and_al、e2e、e2e_super_resolution）。指定がなければ augmentation_and_al をデフォルトで使用します。
3. すべての VDA リソースの OSMO gpu_platform（選択肢が明確な場合は ONLINE のプラットフォームを自動選択し、有効な選択肢がない場合にのみ確認してください）。
4. エンドポイントモード（明示的に上書きされない限り、クラスター内の NIM を再利用またはデプロイするのをデフォルトとします）。

gpu_platform を推測しないでください（例：microk8s）。osmo pool list --mode free に表示される現在のプラットフォームラベル（例：gpu）をそのまま使用してください。

各送信の前に実行スタンプを生成してください。

STAMP=$(cat /proc/sys/kernel/random/uuid | cut -c1-8)
RUN_ID="run-$STAMP"

実行時間の概要（実行前に必須）

変更を伴うコマンド（osmo credential set、NIM のインストール／修復、キャッシュワークフローの送信、または対象の VDA ワークフローの送信）を実行する前に、ユーザーに短い ETA の概要を提示してください。

簡潔にまとめ（短い段落 1 つ、または箇条書き 4～6 項目）、次の内容を含めてください。

• コールドスタート（NIM／キャッシュがない状態）かウォームスタート（NIM／キャッシュがすでに正常な状態）か。
• 主なフェーズとおおよその所要時間。
• 選択したワークフローの予想合計時間の範囲。

ベースラインの所要時間（MicroK8s + OSMO の実行で確認された値）：

フェーズ	通常の所要時間
認証情報 + 事前チェック	約 1～2 分
NIM のデプロイ／ダウンロード／ウォームアップ（必要な場合）	約 10～15 分
デモアセットのダウンロード／アップロード（デモパスの場合）	約 1～3 分
モデルキャッシュの作成（必要な場合）	約 15～25 分
ワークフローの送信 + キュー待機／開始	約 1～3 分

送信後のワークフロー実行時間の範囲：

フロー	通常の実行時間
auto_labeling	約 6～15 分
augmentation_and_al	約 20～35 分
e2e	約 22～40 分
e2e_super_resolution	約 25～45 分

コールドスタートのエンドツーエンド実行は通常約 45～80 分、ウォームスタートは動画の長さとフローに応じて通常約 20～45 分です。

共通の前提条件（すべてのフロー）

1. 認証情報とコントロールプレーンの事前確認

   bash scripts/preflight_credentials.sh --workflow assets/configs/osmo/<mode>.yaml
   

   外部への通信が制限されている場合：

   bash scripts/preflight_credentials.sh --no-probe --workflow assets/configs/osmo/<mode>.yaml
   

   事前確認にワークロード内の .env は必要ありません。実行時の値の展開には、--set-string 1つのリストで渡す送信時の値（dataset、run_id、gpu_platform、video、storage_url、skills_dir）を使用します。

   --workflow を渡すと、指定されたワークフローのイメージ参照（workflow.groups[].tasks[].image）について、匿名のベアラーアクセスを使用し、認証情報が渡されている場合はそれをフォールバックとして、プルアクセスを検証します。 環境変数で新しいNGC/HFシークレットが渡された場合、事前確認では既存の nvcr_io / hf_token があれば自動的に更新します。新しい環境変数のシークレットが渡されていない場合でも強制的に上書きするには、--refresh を使用します：

   bash scripts/preflight_credentials.sh --workflow assets/configs/osmo/<mode>.yaml --refresh
   

   出力に USER_INPUT_REQUIRED: が含まれている場合は、問題を解消するための簡潔な質問を1つだけして、そこで停止します。

   ワークフローイメージが 401/403 を返した場合は、一覧にあるイメージ参照のプローブ確認後にレジストリアクセスの失敗を報告してください。特定のキー種別（例：nvapi-*）が全面的にサポートされていないとは断言しないでください。

2. ストレージの値展開ポリシー

   storage_url は、今回の実行で使用する実際のデータセット／アップロードバックエンドから導出する必要があります。

   dataset_url=azure://storiondevxah69/osmo-workflows/datasets/vda-demo
   storage_url=azure://storiondevxah69/osmo-workflows
   dataset=vda-demo
   

   S3以外のバックエンドで、古い s3:// の値を黙ってデフォルトとして使用しないでください。

3. 推論ポリシー（必須）

   • 正常なクラスター内の永続NIMエンドポイントがあれば、デフォルトで再利用します。
   • 存在しない、または正常でない場合は、自動的にデプロイします。これは前提条件であり、ユーザーが選択するものではありません。停止して確認を求めず、VDA許可リストを指定してインストールを実行します：

   export NIM_SERVICES="qwen3-vl qwen25-14b"
   skills/physical-ai-infrastructure-setup-and-resilient-scaling/components/inference-nim-operator/scripts/install.sh
   

   • エンドポイントの完全なドキュメントとヘルスチェックについては、references/nim/README.md を参照してください。
   • 外部エンドポイントは明示的なリクエストまたは明示的なURLがある場合にのみ使用します。その場合に限り、クラスター内へのデプロイを省略します。
   • 認証情報の有無から外部モードを推測しないでください。
   • GPUを空けるために、既存のNIMをスケールダウンしたり削除したりしないでください。

4. 準備状況の確認

   osmo pool list --mode free
   osmo config show POD_TEMPLATE
   python3 scripts/pre_submit_guard.py --workflow assets/configs/osmo/<mode>.yaml
   

5. キャッシュの自動修復

   pre_submit_guard.py がキャッシュの失敗を報告した場合、デフォルトの対応として次を実行します：

   osmo workflow submit assets/configs/osmo/setup_model_cache.yaml \
     --set-string storage_url=<backend-prefix> path=data
   

   次に pre_submit_guard.py を再実行し、成功してから対象のVDAフローを送信します。バックエンド／プレフィックスが不明確な場合、またはキャッシュの設定に失敗した場合に限り、ユーザーに確認します。

6. スケジューリングポリシー

   VDAテンプレートでは、ユーザーワークロードに system プールへの依存を設けず、セットアップとワーカーを gpu_platform 上でスケジュールします。

送信（すべてのフロー）

すべてのフローで送信時の形式は同じで、変更するのはワークフローYAMLのみです。要求されたフローのYAMLを選び、以下のコマンドを実行してください。フローごとの詳細な手順（ステージマトリクスとフローの詳細）は、リンク先のリファレンスに記載されています。

フロー	ワークフローYAML	詳細な手順
拡張＋自動ラベリング	assets/configs/osmo/augmentation_and_al.yaml	references/flows/augmentation_and_al.md
自動ラベリングのみ	assets/configs/osmo/auto_labeling.yaml	references/flows/auto_labeling.md
E2E（並列）	assets/configs/osmo/e2e.yaml	references/flows/e2e.md
E2E（超解像ゲート付き）	assets/configs/osmo/e2e_super_resolution.yaml	references/flows/e2e_super_resolution.md

SKILLS_DIR="$(cd "$(git rev-parse --show-toplevel)/skills/physical-ai-video-data-augmentation" && pwd)"
STAMP=$(cat /proc/sys/kernel/random/uuid | cut -c1-8)
osmo workflow submit assets/configs/osmo/<flow>.yaml \
  --pool <pool> \
  --set-string \
    dataset=<dataset> \
    run_id=run-$STAMP \
    storage_url=<backend-prefix> \
    gpu_platform=<gpu-platform> \
    video=<video-stem> \
    cosmos_model_cache_url=<backend-prefix>/data/models/cosmos_transfer \
    auto_labeling_model_cache_url=<backend-prefix>/data/models/auto_labeling \
    skills_dir="$SKILLS_DIR"

互換性に関する注意：

• --set-string フラグは必ず1つだけ使用し、その後にすべてのキーと値のペアを渡してください。
• 同じコマンド内で --set / --set-string フラグを繰り返さないでください。一部のOSMOビルドでは最後の指定しか適用されません。
• 1つの送信コマンドで --set と --set-string を併用しないでください。
• OSMO環境間でネストしたテンプレートの値展開に差異が生じないよう、明示的な *_model_cache_url の値を渡してください。
• フラグの組み合わせを総当たりで試さないでください。この形式をそのまま使用してください。

共通の任意指定オーバーライド（同じ --set-string リストにキーと値のペアを追加してください）：

cookbook=<scene_profile> \
vlm_url=<openai_base_url> \
llm_url=<openai_base_url> \
cosmos_model_cache_url=<url> \
auto_labeling_model_cache_url=<url>

自動ラベリングのみのフローには拡張ステージがないため、実行時に cosmos_model_cache_url は省略されます。指定しても問題はなく、すべてのフローで送信時の形式を統一できます。

OSMO のモニタリング

# Workflow status + task states
osmo workflow query <workflow_id> --format-type json \
  | jq '{status, tasks: [.groups[].tasks[] | {name, status, exit_code}]}'

# Logs for a specific task
osmo workflow logs <workflow_id> --task <task_name> -n 200

# Output retrieval
osmo data list --no-pager <output_url>
osmo data download <output_url> <local_dir>/

完了時の成果物については、実行の全出力を必ずワークスペースにコピーしてください。

ROOT="$(git rev-parse --show-toplevel)"
RUN_LOCAL_DIR="$ROOT/media/vda/runs/<run_id>"
mkdir -p "$RUN_LOCAL_DIR"
osmo data download "<storage_url>/datasets/<dataset>-outputs/<run_id>/" "$RUN_LOCAL_DIR/"

2 分を超えることが予想される実行では、少なくとも 2 分ごとにハートビート更新を送信してください。メディアの証拠については、メッセージの吹き出しごとに、単独の MEDIA:<absolute-path> 行を 1 行出力してください。

実行継続に関する要件：

• 作業を続けながら、ハートビートで進捗を報告してください。ハートビートは状況の更新であり、許可を求めるものではありません。
• 成功したステージの間で停止して、承認を待たないでください。
• 停止するのは、作業を妨げる失敗が発生した場合、またはユーザーから明示的な停止・方向転換の指示があった場合に限ります。
• 補間処理で送信に失敗した場合は、同じ標準の単一フラグ形式を使い、値を修正して 1 回再実行してください。場当たり的なフラグの試行を繰り返さないでください。

MEDIA の形式は厳密です：

• 1 行のみ出力してください：MEDIA:/absolute/path/to/file.mp4
• MEDIA: は 1 行内で続けて記載してください（行を分割しないでください）。
• 同じ吹き出しに余分なテキストを含めないでください。
• ディレクティブをコードフェンス、箇条書き、引用符で囲まないでください。
• レンダリングに失敗した場合は、安定したワークスペースパスから 1 回再試行し、その後 PNG にフォールバックしてください。

実行後の比較用証拠（拡張フローで必須）

正常に実行された後の augmentation_and_al、e2e、e2e_super_resolution に適用されます。

完了時に必要な出力（出力 URL だけで終わらせないでください）：

1. すべての出力と入力動画を、ワークスペース内のローカルパスにステージングしてください：

   bash scripts/stage_run_artifacts.sh \
     --storage-url <storage_url> --dataset <dataset> --run-id <run_id> --video <video>
   

2. そのローカル実行コピーから、並べて比較した動画をレンダリングしてください：

   bash scripts/render_side_by_side.sh \
     --run-local-dir "<repo>/media/vda/runs/<run_id>" --dataset <dataset> --video <video>
   

3. ローカル実行コピーから MEDIA を出力し、以下を含めてください：

   • <run_local_dir>/setup_b0/configs/manifest.yaml の拡張の概要（<video>_aug0 の sampled_vars）
   • <run_local_dir>/outputs/pseudo_labeled_augmented/<video>_aug0 の自動ラベリングの概要
   • e2e / e2e_super_resolution の場合、<run_local_dir>/outputs/pseudo_labeled/<video> の元ラベルの概要

ffmpeg を利用できない場合は、同じローカル実行コピーから入力と拡張後の MEDIA を出力し、拡張と自動ラベリングの概要も提示してください。

デモ実行（ユーザー提供の動画がない場合）では、入力が nvidia/video-data-augmentation-demo から取得されたことを明記してください。

関連ファイル

以下の標準の場所を使用してください：

• ワークフロー：assets/configs/osmo/*.yaml
• ランタイムスクリプト：scripts/*.sh、scripts/*.py
• フローの解説：references/flows/*.md
• セットアップとトリアージ：references/setup.md、references/troubleshooting.md
• イメージとエンドポイントポリシー：references/container-images.md、references/nim/README.md
• クックブックの調整：assets/cookbooks/TUNING_GUIDE.md