tao-launch-workflow

TAO ワークフロー起動時の確認事項

TAO ワークフローまたはモデルアクションを起動する前に、このスキルを使用してください。

クイックスタート

プラットフォームヘルパーを実行し、プラットフォームとモニタリングの設定を尋ねてから、認証情報を尋ねる前に、選択したプラットフォームの詳細ヘルパーを実行します。

起動時の必須ゲート

起動前チェックに合格するまで、ランナースクリプト、起動スクリプト、互換性シム、ワークスペースフォルダー、状態ファイル、ログ、依存関係のインストールによる副作用を作成してはいけません。

起動前チェックに合格するには、次のすべてを満たす必要があります。

1. パッケージ化されたプラットフォームヘルパーから実行プラットフォームが選択されている。
2. プラットフォームの認証情報と必要な認証情報グループが揃っている。
3. モデル固有の認証情報が揃っている。
4. パッケージ化されたモデル／アクションのメタデータからデフォルトのコンテナイメージが解決され、ユーザーに提示され、確認されているか、明示的な image=<override> で置き換えられている。
5. 起動ホストからのプラットフォームアクセスチェックが成功している。
6. データセット入力が具体的な spec キーに対応付けられ、選択したプラットフォームの視点から検証されている。
7. モデル／ワークフロースキルで必要とされるコンピューティング構成の項目がわかっている。

いずれかの項目が不足している場合は、不足している入力を尋ね、アーティファクトを生成する前に停止してください。これは AutoML、通常の train/eval/infer/export/TRT、DEFT／アプリケーションのワークフローに適用されます。

最初に尋ねること

ユーザーが実行したい内容を確認したら、パッケージ化されたヘルパーを使って実行プラットフォームを尋ねます。選択肢を作るために、プラットフォームのドキュメント、スキルフォルダー、設定フォルダーをスキャンしてはいけません。

${TAO_SKILL_BANK_PATH:-~/tao-skills-external}/scripts/list_tao_platforms.py \
  --skill-bank ${TAO_SKILL_BANK_PATH:-~/tao-skills-external} --format text

次に、以下を尋ねます。

• このワークフローを実行する、サポート対象のプラットフォームはどれですか？
• このチャットで実行をモニタリングしますか？モニタリングを有効にすると、起動後もバックエンド／ジョブのログをポーリングし、ジョブが完了または失敗するか、停止を依頼されるまで進捗を報告します。ジョブが数時間または数日間キューに入ったままの場合も同様です。無効にすると、ジョブを起動し、ジョブ ID／ログパスをお伝えして、ポーリングを停止します。デフォルト：チャットでモニタリングします。
• ステータスはどのくらいの頻度で投稿しますか？デフォルト：5 分ごとです。スモークテストでは 1～2 分ごと、通常のトレーニングでは 5 分ごと、長時間の実行では 10～15 分ごとを指定してください。

ユーザーがデフォルトを受け入れた場合は、long_running_enabled=true と status_interval_minutes=5 を使用します。

モニタリングが有効な場合、何度かポーリングしたという理由や、ジョブがまだ PENDING であるという理由だけで最終サマリーを送信してはいけません。ターンを継続し、終端状態になるか、ユーザーが明示的に停止／切り離しを依頼するまで、status_interval_minutes ごとにステータスを通知します。ランタイム環境がチャットのターンを開いたままにできない場合は、その旨を明確に伝え、永続的なウォッチャー／ログのパスを提示してください。ターン終了後もチャットの更新が続くかのように示してはいけません。

最終回答のルール：final 応答を送信すると、チャット側のモニタリングは終了します。long_running_enabled=true で、起動したジョブがまだ終端状態ではない間は、進行中の更新としてステータスメッセージを送信し、エージェントはポーリングを続けなければなりません。ワークフローが終端状態に達した場合、ユーザーがモニタリングの切り離し／停止を明示的に依頼した場合、またはランタイムが実際にターンを開いたままにできない場合にのみ、最終応答を送信してください。最後の場合は、ランタイムの制限であることを伝え、永続的なステータス確認コマンド／ログパスを正確に提示してください。

入力不足時のプロンプト形式

起動に必要な入力を尋ねる際は、具体例と、両方のデータセット入力方式を含めてください。「データセットルート」だけを尋ねてはいけません。

この構成を使用し、選択したモデル／アクションに合わせて spec キーを調整してください。

I need these launch inputs before I can create specs or runner files:

1. Execution platform: lepton, brev, slurm, local-docker, or kubernetes.

2. Dataset inputs. You can provide either mode:
   A) Root mode: give train/eval roots and I map required files automatically.
      Example Cosmos-RL:
      train_root=/lustre/fsw/.../cosmos/train
      -> custom.train_dataset.annotation_path=train_root/annotations.json
      -> custom.train_dataset.media_path=train_root
   B) Direct spec mode: give the exact config/spec parameters yourself.
      Example:
      custom.train_dataset.annotation_path=/lustre/fsw/.../train_annotations.json
      custom.train_dataset.media_path=/lustre/fsw/.../videos_train.tar.gz
      custom.val_dataset.annotation_path=/lustre/fsw/.../eval_annotations.json
      custom.val_dataset.media_path=/lustre/fsw/.../eval_videos/

   Platform examples:
   - SLURM/Lustre: /lustre/fsw/.../data/train or lustre:///lustre/fsw/.../data/train
   - Lepton/Brev/Kubernetes: s3://bucket/path/train and s3://bucket/path/eval
   - local-docker: /data/tao/<model>/train or file:///data/tao/<model>/eval

3. Container image. I will resolve the default from packaged model metadata and
   show it before launch, for example:
   default image for <model>/<action>: <resolved container image>
   Use this image, or provide image=<override> to pin a different TAO build.

4. Compute shape required by the model, for example GPUs/nodes.

5. Required credentials from platform/model docs, for example HF_TOKEN for
   gated Hugging Face models.

6. Monitoring preference. By default I monitor in this chat and post progress
   every 5 minutes; choose 1-2 minutes for smoke tests or 10-15 minutes for
   long training.

コンテナーイメージの確認

仕様、ランナースクリプト、ワークスペース、ログ、状態ファイルを作成する前、またはジョブを送信する前に、選択したモデル／アクションのイメージを解決します。

${TAO_SKILL_BANK_PATH:-~/tao-skills-external}/scripts/resolve_tao_image.py \
  --skill-bank ${TAO_SKILL_BANK_PATH:-~/tao-skills-external} \
  --model <network> --action <action> --format text

ヘルパーを利用できない場合は、SkillBank().get_model_config(network_arch) を通じて skills/models/<network>/config.json を読み込みます。イメージフィールドは次の順序で解決します。

1. actions.<action>.container_image
2. actions.<action>.image
3. トップレベルの container_image
4. トップレベルの image

正確なイメージを提示し、次のように確認します。

Container image for <network>/<action>:
default=<resolved image>

Use this image, or provide image=<override>?

ユーザーが承認した場合は、解決したイメージをジョブの image として渡します。ユーザーが別のイメージを指定した場合は、空でないイメージ参照を必須とし、その値を渡します。デフォルトのイメージで黙って起動してはいけません。この確認は、トレーニング、AutoML の推奨、評価、推論、エクスポート、TensorRT エンジンの生成、および TAO コンテナーを送信するアプリケーションワークフローに適用されます。

認証情報の絞り込み

ユーザーがプラットフォームを選択した後、そのプラットフォームに限った認証情報の一覧を取得します。

${TAO_SKILL_BANK_PATH:-~/tao-skills-external}/scripts/list_tao_platforms.py \
  --skill-bank ${TAO_SKILL_BANK_PATH:-~/tao-skills-external} \
  --platform <platform> --format text

このコマンドが返す認証情報と、選択したモデルのスキルに固有の認証情報だけを尋ねます。SLURM、Kubernetes、ローカル Docker の場合、Lepton の認証情報を尋ねてはいけません。Lepton、Brev、Kubernetes、ローカル Docker の場合、SLURM の認証情報を尋ねてはいけません。選択したプラットフォームとデータセット／結果の URI で s3:// へのアクセスが必要な場合にのみ、S3 の認証情報を尋ねます。

初回起動時の確認では、必須の認証情報と必須の認証情報グループだけを尋ねます。ヘルパーの「任意の認証情報／設定」セクションは参考情報として扱います。only_when 条件に該当する場合、選択したワークフローを進めるのにその値が必要な場合、またはユーザーが設定のカスタマイズを希望した場合を除き、それらの値を要求しないでください。

ヘルパーの出力に「必須の認証情報グループ」セクションが含まれている場合は、処理を進める前に各グループから1つずつ認証情報を用意します。ヘルパーの説明と「取得方法」のテキストを使って、求める各値を説明してください。

SLURM の場合、ユーザー向けのプロンプトではまず SSH_KEY_PATH を尋ねます。ユーザーがすでに SSH エージェントを使用していると述べた場合にのみ、SSH_AUTH_SOCK に言及してください。

データセットの確認

データセットの入力は、次のどちらのモードでも受け付けます。

• データセットルートモード： ユーザーが train／eval／calibration のルートを指定し、モデルのスキルが規約に基づいて必要なファイルを割り当てます。Cosmos-RL の train の例： custom.train_dataset.annotation_path=<root>/annotations.json および custom.train_dataset.media_path=<root>。
• 直接指定モード： アノテーション、メディアアーカイブ、動画、画像フォルダーの保存場所がそれぞれ異なる場合、ユーザーが正確な仕様キーのパスを指定します。たとえば、次のようにキーをそのまま保持します。 custom.train_dataset.annotation_path=/lustre/.../train_annotations.json および custom.train_dataset.media_path=/lustre/.../videos.tar.gz。

選択したプラットフォームに合ったデータセットの例を尋ねます。

• SLURM：/lustre/fsw/portfolios/<team>/<your-dir>/data/<model>/train のような共有クラスターパス（<your-dir> はクラスタ上のユーザーごとのディレクトリ）、または /lustre/... 配下の直接指定パス。
• Lepton、Brev、Kubernetes：通常は s3://bucket/path/train と s3://bucket/path/eval。ただし、プラットフォームプロファイルで共有ストレージがマウントされている場合を除きます。
• ローカル Docker：/data/tao/<model>/train のように Docker ホストから参照できるローカルパス、または予定しているコンテナーマウント内から参照できる直接指定パス。

「データセットルート」だけが受け付け可能な入力だと決めつけないでください。直接指定パスが提供された場合は、デフォルトのファイル名を追加するのではなく、指定された正確な仕様パスを検証します。

プラットフォームの事前確認

起動用アーティファクトを作成する前に、選択したプラットフォームの事前確認を実行してください。

必要な入力が揃っている場合は、パッケージ化された事前確認ヘルパーを優先してください。

${TAO_SKILL_BANK_PATH:-~/tao-skills-external}/scripts/check_tao_launch_preflight.py \
  --skill-bank ${TAO_SKILL_BANK_PATH:-~/tao-skills-external} \
  --platform <platform> \
  --path train_annotation=<path> \
  --path train_media=<path>

ユーザーが指定した正確な直接指定の仕様パスを渡してください。ルートモードの入力の場合は、まずモデルで必要なファイルを展開し、具体的なアノテーション／メディアパスをヘルパーに渡してください。

モデルスキルにアノテーションレベルで必須のフィールドが記載されている場合は、--json-required-field <path-label>=<field>[,<field>...] を使って渡してください。これにより、最初のトレーニングコンテナ内ではなく、事前確認の段階でスキーマ／データの内容に関する問題が検出されます。たとえば、Cosmos-RL train/AutoML では、--json-required-field train_annotation=video_fps と --json-required-field val_annotation=video_fps が必要です。

実際の起動では --skip-platform-access を使用しないでください。このフラグは、環境のドライラン確認、またはユーザーがプラットフォームとストレージへのアクセスを明示的に手動で証明済みの場合にのみ使用します。ヘルパーがリモート API、CLI、クラスター、またはオブジェクトストアへのアクセスを検証できない場合は、事前確認を失敗とみなし、起動用アーティファクトを生成しないでください。

SLURM の場合：

1. SLURM_USER、SLURM_HOSTNAME、SLURM_PARTITION と、SSH_KEY_PATH または SSH_AUTH_SOCK のいずれかを必須とします。実行時の値には、選択したプラットフォームヘルパーの Resource defaults を使用してください。パッケージ化された SLURM のデフォルト設定では、SLURM_TIME_HOURS=4 と SLURM_TIMEOUT_HOURS=3.8 でランチャーを生成してください。4 時間のパーティション一覧に対して、12 時間のデフォルト値を決して独自に設定しないでください。耐久性を高めるため、オーケストレーターを nohup またはバックグラウンドで起動してもかまいませんが、それだけではチャットでの監視要件を満たしません。起動後は、終端状態になるか、明示的にデタッチするまで、チャット側でフォアグラウンドのポーリングループを維持してください。
2. カンマ区切りの SLURM_HOSTNAME を分割し、可能であればホストを名前解決して、少なくとも 1 台のホストでパスワードなしの ssh -o BatchMode=yes が必要です。
3. SSH に失敗した場合、同等の選択肢を複数提示しないでください。SSH_KEY_PATH=/path/to/private_key を求め、パスワードなしで接続できるよう、次の手順を示してください。必要に応じて ssh-keygen -t ed25519 -N "" -f ~/.ssh/id_ed25519 で鍵を作成し、ssh-copy-id -i ~/.ssh/id_ed25519.pub <SLURM_USER>@<login-host> でインストールします。ssh-keyscan -H <login-host> >> ~/.ssh/known_hosts でホストを信頼し、chmod 600 ~/.ssh/id_ed25519 を設定して、ssh -o BatchMode=yes -i ~/.ssh/id_ed25519 <SLURM_USER>@<login-host> 'hostname' で確認します。その後、SSH_KEY_PATH=~/.ssh/id_ed25519 を指定して再実行してください。
4. SSH の確認に合格したら、リモートログインホスト上で test -e または同等の読み取り専用コマンドを使って、データセットのアノテーション／メディアパスを検証してください。
5. その後に限り、ランナースクリプト、仕様、ワークスペースを作成するか、ジョブを送信してください。

ローカル Docker の場合は、起動用アーティファクトを書き込む前に Docker／GPU へのアクセスとローカルのデータセットパスを検証してください。Lepton、Brev、Kubernetes の場合は、起動用アーティファクトを書き込む前に API またはクラスターへのアクセス、オブジェクトストレージの認証情報、および s3:// 入力を読み取れることを示す aws s3 ls を検証してください。これらのリモートプラットフォーム上のマウント済み共有ストレージまたは PVC パスについては、ジョブ環境にパスがマウントされていることを手動で証明する必要があります。ヘルパーは、検証されていないリモートマウントパスを受け入れず、フェイルクローズします。