tao-launch-workflow

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

単独でインストールした場合：このセッションが TAO skill bank プラグインによって初期化されていない場合は、まず tao-setup スキルを実行してください（ホストの事前確認、認証情報、スキル間の検出）。

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

直接呼び出す場合は、Step 0 またはヘルパーを実行する前に、 references/platform-preflight.md の完全なチェックアウト確認を実行してください。個別にインストールしたスキルには共有スクリプトがありません。確認に失敗した場合は停止してください。すべてのヘルパーには、確認済みの TAO_SKILL_BANK_PATH を使用してください。

Step 0 — 実行モード：カードパック（最初に確認）

この会話内で複数段階のアプリケーションワークフローを実行する前に、 コンパイル済みのカードパックがアプリケーションスキルと同じ場所にあるか確認してください。

ls "${TAO_SKILL_BANK_PATH}/skills/applications/<skill>/cards/" 2>/dev/null

• パックがある場合 → トークン効率のよい方法を優先します。パックの driver.sh はワークフローを段階ごとに新しいセッションで実行します（会話内での実行より 74～91%低コストであることが測定されており、小規模モデルで検証済みの唯一のモードです）。 パックの README.md で必要な環境変数を確認し、 起動レビューのためにこのゲートの項目 1～9 を完了してから、会話内で各段階を実行する代わりに パックのドライバーをデタッチして起動してください。ドライバーのログと 実行ディレクトリの進捗マークで監視します。
• パックがない場合 → このゲートを通じて通常どおり実行します。ワークフローを 繰り返し実行する場合は、強力なモデルを使って一度パックをコンパイルすることを提案してください。詳細は skills/core/tao-token-efficient-execution を参照してください（作成用プロンプトとコントラクト）。

カードパスで置き換えられるのは、会話内での段階実行のみです。このゲートは省略できません。パックドライバーの起動は副作用を伴う作業であり、同じ起動レビューの確認が必要です。

クイックスタート

プラットフォームヘルパーを実行し、プラットフォームと監視方法の希望を尋ねてから、認証情報を尋ねる前に、選択したプラットフォームの詳細ヘルパーを実行してください。

必須の起動ゲート

このゲートはモデルに依存しません。副作用を伴う作業を起動する前に、すべての TAO モデル、データアクション、アプリケーションワークフローに適用してください。

起動前の確認に合格するまでは、ランナースクリプト、起動スクリプト、互換性シム、ワークスペースフォルダー、状態ファイル、ログを作成したり、依存関係のインストールによる副作用を発生させたりしないでください。

次のすべてを満たした場合にのみ、事前確認に合格します。

1. パッケージ化されたプラットフォームヘルパーから実行プラットフォームが選択されている。
2. プラットフォームの認証情報と、必要な認証情報グループが満たされている。
3. モデル固有の認証情報が満たされている。
4. デフォルトのコンテナイメージがパッケージ化されたモデル／アクションのメタデータから解決され、ユーザーに提示され、確認されているか、明示的な image=<override> で置き換えられている。
5. 起動ホストからプラットフォームのアクセス確認に成功している。
6. データセット入力が具体的な仕様キーに対応付けられ、選択したプラットフォームの視点から検証されている。
7. モデル／ワークフロースキルで必須となるコンピュート構成の項目が判明している。
8. 選択したデータ／プラットフォーム経路で必要なローカルツールが揃っているか、最小限の不足依存関係をインストールすることをユーザーが承認し、事前確認を再実行している。
9. イメージ、プラットフォーム、データセット、コンピュート構成、予想実行時間、生成またはデフォルトの設定変更を含む起動レビューが提示され、ユーザーが確認している。AutoML の場合、デフォルトを使う場合でも、起動レビューで推奨の件数／予算、最大同時実行数、アルゴリズム、メトリック、方向、検索対象のパラメーター／範囲を明示する必要があります。

項目が一つでも不足している場合は、不足している情報を尋ね、成果物を生成する前に停止してください。これは AutoML、通常の train／eval／infer／export／TRT、DEFT／アプリケーションのワークフローに適用されます。

事前確認で障害要因が解消された場合は、元のユーザーリクエストを忘れずに追跡してください。修正後、該当する事前確認を再実行し、そのリクエストの達成に向けて続行してください。ユーザーが修正のみを明示的に依頼した場合を除き、「障害要因を解消しました」の時点で停止しないでください。

4 つの動詞による実行契約

起動ゲートを通過し、生成モデル／データスキルが仕様バンドル（スキーマ：tao-artifacts）を作成したら、実行は厳密に 4 つの動詞で行います。各プラットフォームスキルは、ネイティブ CLI 上でこれらを実装します。バンクには 5 つ（tao-run-on-docker、-slurm、-kubernetes、-brev、-virtualenv）が含まれており、外部からインストールしたプラットフォームスキルも同じ契約に加わります（§ 外部プラットフォームスキル）。それ以外にプラットフォーム固有のものはありません。 $BANK = ${TAO_SKILL_BANK_PATH}。

• submit(spec-bundle) — まずデータに関する問いを解決します。入力がすでに計算フレームから読み取り可能な場合（ローカルパス、既存のマウント。インプレースでのティア A、一般的なローカル環境であり、エアギャップ環境で唯一該当するケース）は、ステージングするものはありません。ティア A を記録して次に進みます。フレームが一致しない場合（リモート URI、ホスト間のパス、PTM の取得、ティア C の結果アップロード）に限り、tao-data-io を呼び出します。次に、redact_secrets.py lint で組み立てたコマンドをリントし、この順序でレコードを開いて起動します。

  BANK="$TAO_SKILL_BANK_PATH"
  if ! JOB_ID=$("$BANK/scripts/tao_job_record.py" open --platform <p> --image <img> \
    --network-arch <arch> --action <action> --storage-tier <A|B|C> --results-root <root>); then
    echo "TAO job-record creation failed; do not submit" >&2; exit 1
  fi
  [ -n "$JOB_ID" ] || { echo "TAO job-record returned no ID; do not submit" >&2; exit 1; }
  # <native launch, naming the backend object after $JOB_ID>
  "$BANK/scripts/tao_job_record.py" mark "$JOB_ID" --state RUNNING --backend-ref <ref>
  

• status(id) — ネイティブバックエンドをポーリングし、固定の語彙 PENDING RUNNING COMPLETE ERROR CANCELED UNKNOWN に対応付けます。ネイティブのサブ状態（ImagePullBackOff、PENDING-resources、slurm の COMPLETING）は、遷移の message に含めます。「何が実行中か」をレコードから読み取らず、バックエンドをポーリングしてください。
• logs(id, tail) — ネイティブのログ取得です。
• cancel(id) — ネイティブのキャンセルと孤児の後処理を行い、その後 mark <id> --state CANCELED を実行します。

レコードを作成してから起動することが、順序に関する不変条件です。 open は起動前に ID を発行し、results_dir を紐付けます。また、発行された ID は起動で使用できる唯一のハンドルです。ゲートまたは open を経ずに送信しても ID がないため、起動できません。これにより、コンテキストが途切れても実行を復旧できます。バックエンドのオブジェクト（K8s の TTL や docker の --rm によって後から削除される可能性があります）が作成される前に、results_dir が記録されるためです。

生成元の仕様バンドルで execution が宣言されている場合、そのモデルスキルを再利用するすべてのアプリケーションで、モデルが所有するアクションの意味として維持してください。選択したプラットフォームがライフサイクルを処理します。アプリケーションは、そのコマンドを独自のランチャーにコピーしてはいけません。プラットフォームに依存しない前処理／後処理コマンド、ランタイムの証明、ヘルパーの依存関係、分散実行の意図、完了の証拠は、生成元の仕様バンドルに含めます。スケジューラーの構文、マウント、シークレット、タイムアウト、ランク、子プロセスの終了状態の保持は、引き続きプラットフォーム側の責任です。

外部プラットフォームスキル

レジストリもインターフェイスファイルもありません。プラットフォームスキルは4 つの動詞を文書化することで契約を宣言し、初回使用前に内容を読んで検証します。ネイティブのプリミティブのみを備えたスキルは、対応関係を推定して使用できます（バンクの不変条件は引き続き適用されます。対応関係は起動レビューに記載し、うまくいった内容を保存してください）。ルールと、同等機能がない場合の最低限の必須要件： references/external-platforms.md。

障害分析と再試行

status が ERROR に達したら、再試行の前にログの末尾を読み、障害を分類してください。インフラ障害は再試行できます（新しいレコードを作成し、--retry-of を指定して最大 10 回）。プログラム障害は再試行できません。すべての基準、2 つの判断が必要なケース（デバイス側のアサート、下流のトレースバック）、およびターン終了後のポーラーのルール： references/failure-analysis-retry.md。

最初の質問

ユーザーが実行したい内容を確認したら、次に、実行するプラットフォームを尋ねます。選択肢は、このセッションにインストールされているプラットフォームスキルから確認してください。名前と説明（tao-run-on-docker、-slurm、-kubernetes、-brev、-virtualenv、および公式のbrev-cliスキルなど、外部からインストールされたもの）をすでに確認できます。プラットフォームを一元管理するレジストリはありません。ランタイムにコアのルータースキルしか表示されない場合は、${TAO_SKILL_BANK_PATH}の下にあるskills/platform/tao-run-on-*/SKILL.mdのフロントマター（名前と1行の説明）を読み、バンクのプラットフォームスキルを一覧表示してください。

続けて、次のことを尋ねます。

• このワークフローの実行に対応しているプラットフォームのうち、どれを使いますか？
• このチャットで実行状況を監視しますか？監視する場合は、起動後もバックエンドやジョブのログをポーリングし、ジョブが完了または失敗するか、ユーザーが停止を求めるまで、進捗を報告し続けます。ジョブが数時間または数日間キューに入ったままでも同様です。無効にした場合は、ジョブを起動してジョブ ID とログのパスを伝えた後、ポーリングを停止します。デフォルト：チャットで監視します。
• どのくらいの頻度で状況を報告しますか？デフォルト：5分ごと。スモークテストでは1～2分ごと、通常のトレーニングでは5分ごと、長時間の実行では10～15分ごとにします。

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

監視が有効な場合、ポーリングが何度か行われた、またはジョブがまだPENDINGであるという理由だけで、最終要約を送信してはいけません。ターンを継続し、終端状態になるか、ユーザーが明示的に停止または切り離しを求めるまで、status_interval_minutesごとに状況を送信してください。ランタイム環境でチャットのターンを継続できない場合は、そのことを明確に伝え、永続的な監視手段またはログのパスを提示してください。ターン終了後もチャットで更新が続くかのように示してはいけません。

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

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

受付に必要な入力が不足している場合は、references/intake-prompts.mdの正確なプロンプト形式で尋ねてください（一つにまとめて質問し、具体例を示し、デフォルトを独自に作らないでください）。

実装バックエンドの解決

モデルの所有元を特定した後、選択したモデルのreferences/skill_info.yamlを確認してください。backend_contractsが宣言されている場合は、イメージを選択したり仕様を作成したりする前に、実装バックエンドを解決してください。明示的に指定されたバックエンドがモデルまたはアクションに対応している場合は、それを優先します。それ以外の場合は、パッケージ化されたbackend_selectionポリシーを適用し、その判断理由を示してください。選択されたバックエンドのメタデータは、skill_info.yamlで指定されたイメージを使用します。参照先のバックエンドコントラクトは、エントリーポイント、設定スキーマ、データマッピング、トポロジ、チェックポイント形式、出力レイアウト、状況報告の動作を定義します。複数のバックエンドを持つフロントエンドで、レガシーなトップレベルのイメージへのフォールバックを使用してはいけません。また、あるバックエンドを別のバックエンドのバージョンとして扱ってはいけません。

アクション、バックエンド、ワークロードのヒントをモデルリゾルバーに渡してください。メタデータにバックエンドプランナーが宣言されている場合は、それを使用してください。たとえば、共有のCosmosフロントエンドでは、scripts/cosmos_workflow.py planを使って、バックエンド固有のTOMLと起動シーケンスを生成します。

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

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

"$TAO_SKILL_BANK_PATH/scripts/resolve_tao_image.py" \
  --skill-bank "$TAO_SKILL_BANK_PATH" \
  --model <network> --action <action> --backend <auto-or-explicit> \
  --workload <workload-hint> --format text

手動で確認する場合は、パッケージに含まれる $TAO_SKILL_BANK_PATH/skills/models/<network>/references/skill_info.yamlを読みます。 ヘルパーを利用できない場合は、起動する前に停止してください。イメージのフィールドは、次の順序で解決します。

1. backend_contracts.<selected-backend>.container_image（存在する場合）
2. actions.<action>.container_image
3. actions.<action>.image
4. トップレベルのcontainer_image
5. トップレベルのimage

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

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

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

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

認証情報のフィルタリング

ユーザーがプラットフォームを選択した後、選択したスキル自体の## Credentialsセクション、および存在する場合はreferences/skill_info.yaml（required_credentials、credential_groups、optional_credentials）から、そのプラットフォームのみの認証情報リストを取得します。起動前チェック（check_tao_launch_preflight.py）は、同じプラットフォーム別のskill_info.yamlを読み取り、認証情報のゲートを適用します。認証情報を必要としないプラットフォーム（Dockerなど）では、説明文だけが提供される場合があります。その場合は、Preflightセクションを参照してください。

そのプラットフォームで実際に必要な認証情報と、選択したモデルのスキルで必要なモデル固有の認証情報のみを求めます。SLURM、Kubernetes、DockerではBrevの認証情報を求めないでください。Brev、Kubernetes、DockerではSLURMの認証情報を求めないでください。S3の認証情報を求めるのは、選択したプラットフォームとデータセット／結果のURIでs3://へのアクセスが必要な場合のみです。 認証情報は、プロセス環境変数や、~/.tao/secrets.env、~/.config/tao/.envなどのユーザーが承認したシークレット環境ファイルにすでに存在する場合があります。そのようなファイルは必要な場合にのみ読み込み、内容を表示、grep、cat、貼り付け、またはログに記録してはいけません。確認するのは変数の有無のみです。

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

ヘルパーの出力に「Required credential groups」セクションが含まれる場合は、先に進む前に各グループから1つずつ認証情報を満たしてください。求める値については、ヘルパーの説明と「How to get it」の記載を使って説明します。

SLURMの場合、ユーザーへの確認ではまずSSH_KEY_PATHを尋ねてください。ユーザーがすでにSSHエージェントを使用していると述べた場合にのみ、SSH_AUTH_SOCKに触れてください。

依存関係の解決

必要なCLI／ライブラリが見つからない場合は、何が不足しているのか、なぜ必要なのかを正確に伝えてから、インストールする前にユーザーへ確認してください。例：

• S3のデータセットまたは結果のパス → awsなど、S3に対応したクライアントが必要です。
• ローカルのDockerパス → Docker CLIと、設定済みのDockerネットワークが必要です。

ユーザーの承認を得てインストールした後、同じ起動前チェックを再実行してください。チェックの失敗後、再実行までの間にランナーファイルを作成したり、ジョブを起動したりしてはいけません。

実行時のダウンロード

実行時のダウンロードに関する規則は、references/runtime-downloads.mdに従ってください。ローカルのチェックポイントがあるからといって、パッケージがキャッシュされているとは限りません。

データセットの受け入れ

データセットは、次のいずれかの方法で指定できます。

• データセットルートモード： ユーザーが train／eval／calibration のルートを指定し、モデルスキルが規約に従って必要なファイルを割り当てます。Cosmos-RL の train の例： custom.train_dataset.annotation_path=<root>/annotations.json および custom.train_dataset.media_path=<root>。
• 直接指定モード： アノテーション、メディアアーカイブ、動画、または画像フォルダーが異なる場所にある場合に、ユーザーが正確な spec キーのパスを指定します。例のように、それらのキーをそのまま保持します。 custom.train_dataset.annotation_path=<TRAIN_ANNOTATION_PATH> および custom.train_dataset.media_path=<TRAIN_MEDIA_PATH>。

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

• SLURM：ユーザーが指定し、割り当てられた計算ノードから検証済みの、明示的な共有クラスターパスを使用します。このスキルには、サイト固有のストレージのデフォルト設定はありません。
• Brev、Kubernetes：プラットフォームプロファイルで共有ストレージをマウントしていない限り、通常は s3://bucket/path/train および s3://bucket/path/eval を使用します。
• ローカル Docker：/data/tao/<model>/train のように Docker ホストから参照できるローカルパス、または予定しているコンテナーマウント内から参照できる直接指定の spec パスを使用します。
• リモート Docker：ローカルのエージェントマシン上のパスではなく、DOCKER_HOST で指定されたリモート Docker ホストから参照できる絶対パスを使用します。

「データセットルート」だけが受け入れ可能な入力だと想定してはいけません。直接指定のパスが提供された場合は、デフォルトのファイル名を追加せず、指定された spec パスを正確に検証します。

プラットフォームの事前チェック

起動用の成果物を作成する前に、選択したプラットフォームの事前チェックを実行します。パッケージ化されたヘルパー scripts/check_tao_launch_preflight.py（--platform <p> --container-image <img> --path <label>=<path> ...）を優先してください。このヘルパーは、認証情報、クライアントツール、プラットフォーム／クラスター／オブジェクトストレージへのアクセス、計算環境からのデータセットパス、GPU／ランタイムの健全性、イメージとアーキテクチャの適合性を検証します。失敗はすべてブロッカーとして扱います。実際の起動で --skip-platform-access を使用してはいけません。

プラットフォームごとの詳細（SLURM の SSH／キー設定とリソースのデフォルト値、docker／remote-docker の GPU とバインドマウントのチェック、Brev／Kubernetes の API とオブジェクトストレージのチェック、アノテーションの content-field チェック、データのステージング）については、references/platform-preflight.md を参照してください。

ランタイムと設定の確認

副作用を伴う起動の前に、簡潔な確認内容を提示します。

• 選択したプラットフォームと正確なコンテナーイメージ
• GPU の ID／数とノード。すでに使用中のため回避した GPU があれば、その情報も含めます。
• データセットルートまたは直接指定の spec パス。利用可能な場合はサンプル数も含めます。
• テンプレートのデフォルト値と異なる、重要なモデル／ワークフローのオーバーライド
• 推定実行時間と、その前提条件
• 監視間隔と、チャット側の監視を接続したままにするかどうか
• モデルで複数のバックエンドを選択できる場合は、実装バックエンドと選択理由

AutoML の場合は、skills/applications/tao-run-automl/SKILL.md の説明に従って、アルゴリズム、メトリック／方向、推奨の予算、探索パラメーター、範囲、生成された推奨事項／デフォルトの詳細も提示します。この確認の後、ユーザーに承認を求めます。ユーザーが制限時間を指定している場合は、それを超過する計画を示し、起動前に具体的な短縮案を提示します。

起動前の確認を「何も起動されませんでした」だけで終えてはいけません。「確定済みの計画を具体化してジョブを送信する準備ができました。続行するには「launch」、「go ahead」、または「yes」と返信してください。」のように、直接的なアクションを促す言葉で締めくくります。次に届いた、曖昧さのない肯定的なチャットメッセージは、計画の具体化、ジョブ記録の作成、ジョブの送信、および事前確認した監視モードを許可するものとします。追加の受付や確認を挟まず、ただちに実行します。

構造化トレーニングメトリクス

モデルの契約で構造化ステータスパスまたはメトリクス抽出器が宣言されている場合は、ネイティブバックエンドと並行してポーリングしてください。スケジューラーやコンテナの完了だけでは、トレーニングの成功結果とはみなせません。モデルの構造化された最終成功レコードを必須とし、具体的なチェックポイントイベントを収集して、最終的なトレーニング損失と、すべてのエポックの検証完了時の損失を返してください。検証のハートビート／バッチメトリクスやトレーニング損失の行を、エポックの検証損失として扱わないでください。ネイティブロガーが作成される前にプロセスが失敗した場合は、パッケージ化されたステータスファイナライザーを呼び出すか、実際のプロセス終了エラーを報告してください。生ログの解析はフォールバックとしてのみ使用してください。