tao-run-platform

TAO Execution SDK

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

この SDK は、ジョブハンドル、S3 I/O のラッピング、プラットフォーム固有の機能（SLURM/Lustre キュー、Kubernetes Jobs、ローカル Docker でのデバッグ、Brev インスタンスの再利用）を必要とするユーザー向けの任意の Python レイヤーです。ほとんどの TAO スキルは docker run だけで実行でき、SDK は不要です。次の場合は SDK を使用してください。

• ステータスのポーリングや、時間の経過に伴うログのストリーミングに使う Job ハンドルが必要な場合。
• エントリーポイントに組み込まれた、S3 対応の入力ダウンロード／出力アップロードが必要な場合。
• 複数のジョブを連結し、状態を永続化したい場合。

事前確認

このプラットフォームを使用する前に nvidia-tao-sdk[all] をインストールしてください。[all] エクストラによって、プラットフォーム固有の依存関係（Brev、S3 ユーティリティなど）がすべてインストールされます。インストールされていない場合は、アクティブな Python 環境にデフォルトでインストールし、インポート確認を再実行してください。

python -c "import tao_sdk" 2>/dev/null || {
  echo "Installing missing Python requirement: nvidia-tao-sdk[all]"
  python -m pip install "nvidia-tao-sdk[all]"
}
python -c "import tao_sdk"

パッケージインデックスは環境ごとに異なります。runner/container には、動作する pip 設定（例：~/.pip/pip.conf、PIP_INDEX_URL、PIP_EXTRA_INDEX_URL、プロキシ）があることを想定しています。インデックスまたはネットワークの問題でインストールに失敗する場合は、runner のセットアップの問題です。このスキルはレジストリに依存しない設計です。

不足している pip 要件はデフォルトで自動的にインストールされ、実行ログに報告されます。pip 以外の要件やシステム要件については、通常の事前確認で失敗を検出し、ユーザーに見える形で対処方法を提示する必要があります。

セットアップ

認証情報は環境変数から取得します。セッション環境から読み込まれるため、起動前にシェルでエクスポートしてください。

from tao_sdk.platforms.brev   import BrevSDK     # Brev GPU instances

sdk = BrevSDK()      # reads BREV_API_TOKEN (optional — falls back to brev login)

SDK は初回使用時に認証情報を遅延検証します。必須の環境変数が不足している場合は、明確なメッセージを含む CredentialError を発生させます。必須の環境変数は次のとおりです。

プラットフォーム	必須	任意
Brev	—（手動での brev login も使用可能）	BREV_API_TOKEN
S3 I/O（すべてのプラットフォーム）	S3_BUCKET_NAME、ACCESS_KEY、SECRET_KEY	S3_ENDPOINT_URL、CLOUD_REGION
コンテナー環境	NGC_KEY	HF_TOKEN

エージェントが認証情報の値を読み取ることはありません。[ -n "$VAR_NAME" ] で存在を確認するだけです。

ワークフロー起動時の確認

TAO ワークフローまたはアクションを起動する場合は、まずユーザーの目的を確認してください。次に、認証情報や起動の詳細を尋ねる前に、プラットフォームとモニタリングの設定を確認してください。サポート対象のプラットフォームの選択肢は、プラットフォームのドキュメントやフォルダーをスキャンせず、パッケージに含まれるヘルパーから取得してください。

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

次のように尋ねてください。

1. このワークフローを実行するサポート対象のプラットフォームはどれですか？
2. 長時間のモニタリングを有効にしますか？デフォルトは有効です。有効にすると、長時間の PENDING キュー待ちも含め、終端状態になるまでエージェントが接続を維持し、ステータスを報告します。
3. ステータス更新の間隔を何分にしますか？デフォルトは 5 分です。

モデル／アクションが判明したら、パッケージに含まれるメタデータからデフォルトのコンテナーイメージを解決し、runner ファイルを作成する前に、ユーザーに確認するか image=<override> を指定するよう依頼してください。

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

トレーニングに対応するモデルのワークフローでは、通常のトレーニングジョブを作成する前に、モデルレベルの AutoML メタデータを確認してください。

${TAO_SKILL_BANK_PATH:-~/tao-skills-external}/scripts/list_tao_models.py \
  --skill-bank ${TAO_SKILL_BANK_PATH:-~/tao-skills-external} \
  --scope automl --format json

選択したモデルの automl_enabled: true かつ有効なトレーニングスキーマがある場合は、デフォルトで skills/applications/tao-run-automl を使用してトレーニングを実行し、automl_policy: on を指定してください。ワークフローで AutoML を使用しないのは、実行設定に automl_policy: off が含まれる場合、ユーザーが通常の実行を明示的に求めた場合、またはモデルのメタデータで AutoML が有効になっているものの、トレーニングスキーマがまだパッケージに含まれていない場合に限ります。

プラットフォームを選択したら、認証情報フィルターを取得してください。

${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 では SLURM_USER と SLURM_HOSTNAME が必要ですが、Brev の認証情報は不要です。Kubernetes とローカル Docker では、Brev または SLURM の認証情報は不要です。S3 キーなどのストレージ認証情報は、選択したプラットフォームおよびデータ／結果の URI で必要な場合に限って尋ねてください。

コア API

すべてのプラットフォーム SDK は、同じコア構造を実装しています。

sdk.create_job(image, command, gpu_count=1, env_vars=None, inputs=None, outputs=None, **kwargs) -> Job
sdk.get_job_status(job_id) -> JobStatus
sdk.get_job_logs(job_id, tail=None) -> str
sdk.cancel_job(job_id) -> bool
sdk.get_failure_analysis(job_id) -> dict | None
sdk.get_job_results_dir(job_id) -> str
sdk.check_path(remote_path) -> bool
sdk.list_path(remote_path) -> list[str]

Brev 固有：

• sdk.delete_instance(instance_id) — 一時インスタンスをクリーンアップします。
• sdk.list_instances() — アクティブなインスタンスを一覧表示します。

ジョブの送信

エージェントは create_job を呼び出す前に、必ず build_entrypoint を使ってコンテナーコマンドを構築します。エージェントは skill_info.yaml からアクションのスキーマ（command、mode、config_format、inputs、outputs、upload_excludes）を読み取り、それらのフィールドを kwargs として渡します。次に build_entrypoint が、以下を組み込みます。

1. コンテナー内の script_runner ランタイム（base64 の heredoc としてインライン化されるため、コンテナーに tao_sdk をインストールする必要はありません）。
2. コンテナー内の実行時に、宣言された入力をダウンロードし（S3 / HF-Hub / NGC）、{config_path} にリモート URI をローカルパスに書き換えた spec ファイルを書き込み、ユーザーコマンドを実行して、出力をアップロードする CLI 呼び出し。

出力先は、SDK が挿入する環境変数から実行時に解決されます（下記「出力先」参照）。プラットフォーム SDK の create_job は、生成されたコマンドを そのまま 実行します。inputs/outputs kwargs はなく、暗黙的なラップも行いません。データフローはエージェントのコードで確認できます。

出力先（実行時に解決 — エージェント側で管理する必要はありません）

SDK は TAO_JOB_ID（Job.id と一致）をコンテナー環境変数に挿入します。また、永続マウントがアタッチされている場合は TAO_RESULTS_ROOT も挿入します。コンテナー内では、script_runner が出力先を解決します。

コンテナー環境変数	結果
TAO_RESULTS_ROOT が設定済み（Lustre / PVC / bind / NFS）	出力先は {TAO_RESULTS_ROOT}/<job_id>/<key>/ です。アップロードは行いません
S3_BUCKET_NAME が設定済み（クラウド、マウントなし）	出力先は s3://{bucket}/results/<job_id>/<key>/ です。実行終了時にアップロードされます
どちらも未設定	出力先は /results/<job_id>/<key>/（コンテナー内の一時保存）です。実行終了時に大きな警告が表示されます

プラットフォームごとのポリシー：

SDK	挿入される内容
SlurmSDK	TAO_RESULTS_ROOT={SLURM_BASE_RESULTS_DIR}/results（常に Lustre を使用し、S3 は使用しません。GPU がアイドル状態のときにスケジューラーによって強制終了されるのを避けるためです）
KubernetesSDK / DockerSDK / BrevSDK	マウント先が /results の場合は TAO_RESULTS_ROOT=/results、それ以外は S3 にフォールバックします

カスタムの出力先を指定する場合、エージェントは出力 spec のキーに s3://... URI または絶対パスを直接設定できます。明示的な値は自動入力された値より優先されます。それ以外の場合、cosmos-rl の output_dir: "output" や DINO の空の results_dir のような、モデルに自然なデフォルト値は script_runner によって自動的に書き換えられます。

spec はネストされた dict であり、フラットなドット区切りキーではありません

これは spec を構築するときに最もよくある間違いです。skill_info.yaml の inputs: / outputs: ブロックに表示されるドット区切りの表記（例：section.subsection.key）は、ネストされた spec 内のパスであり、script_runner はそのパスをたどって値を検索します。spec 自体の構造ではありません。spec はモデルのコンテナーが想定する構造（通常はネストされた TOML/YAML）を反映します。

# ✓ CORRECT — nested dicts
specs = {
    "section": {
        "subsection": {"key": "value"},
    },
}

# ✗ WRONG — flat top-level key with dots. TOML/YAML emits this as a
# quoted bare-string key, the model sees an empty `section` table, and
# any input declared at "section.subsection.key" silently fails to
# download because _get_nested(specs, "section.subsection.key") → None.
specs = {
    "section.subsection.key": "value",
}

2 つの構造は表面的には似ていますが、意味は異なります。判断に迷った場合は、モデルの references/ ディレクトリ（デフォルトの spec TOML や YAML など）を開いてください。そこに、spec dict がそのまま反映すべきネストされた構造が記載されています。skill_info.yaml の inputs: / outputs: 宣言は、ネストされた spec 内のパスであり、キー名ではありません。

スペック / 引数の構築

スキルのアクションは、skill_info.yaml の actions.<action>.mode フィールドで設定メカニズムを宣言します。mode が存在しない場合は無効なメタデータとして扱い、デフォルトを推測するのではなくスキルを修正してください。まず actions.<action>.mode を読み取り、それに対応する引数の形式を build_entrypoint に渡します:

宣言された mode	エージェントが渡すもの
config	スペックキー付きの inputs / outputs を伴う specs=...。ヘルパーがスペックファイルを書き込み、URI を書き換え、コマンドを実行します
args	任意でスペックキー付きの inputs / outputs を伴う args=...。ヘルパーが CLI 引数をコマンドテンプレートに代入します
passthrough	パスキー付きの inputs=... および / または outputs=...。ヘルパーが指定されたパスにダウンロードし、コマンドを実行し、指定された出力をアップロードします

メタデータが存在しないことから mode を推測しないでください。mode が存在しない場合、スキルのコントラクトは古くなっています。

mode ごとの構築戦略、推奨される判断順序、およびスペック駆動のジョブ (設定ファイル) とパスキー付きのジョブ (設定ファイルなし) の build_entrypoint の実例については、references/spec-construction.md を参照してください。

コンテナイメージの解決

スキルはイメージをキー (tao_toolkit.pyt) または絶対 URI (nvcr.io/...) のいずれかで宣言します。両方を扱うには resolve_container_image() を使用します:

from tao_sdk.versions import resolve_container_image
image = resolve_container_image(skill_info["container_image"])

内部的には versions.yaml を走査してキーを探します。絶対 URI はそのまま返されます。

モニタリング

status = sdk.get_job_status(job.id)
print(status.status)   # Pending, Running, Complete, Error, Canceled
print(status.message)  # platform-specific detail

logs = sdk.get_job_logs(job.id, tail=200)
print(logs)

失敗時には、get_failure_analysis() が根本原因を分類します:

analysis = sdk.get_failure_analysis(job.id)
if analysis:
    print(analysis["err_class"])   # ERR_PROGRAM, ERR_INFRA, etc.
    print(analysis["suggestion"])  # human-readable fix
    for event in analysis.get("job_failure_by_node_event", []):
        print(event["node_event_name"], event["message"])  # OOM, GPU error, etc.

ポーリングパターン

ユーザーが監視したいインタラクティブな実行の場合:

import time
status_interval_minutes = status_interval_minutes or 5
while True:
    status = sdk.get_job_status(job.id)
    if status.status in ("Complete", "Error", "Canceled"):
        break
    print(f"  {status.status}")
    time.sleep(status_interval_minutes * 60)

if status.status == "Error":
    print(sdk.get_job_logs(job.id, tail=100))
    print(sdk.get_failure_analysis(job.id))

長時間実行のモニタリングが有効な場合、30 分経過したからといって、あるいは変化のないポーリングが数回続いたからといって停止しないでください。ジョブが完了、失敗、キャンセルされるか、ユーザーがデタッチ / 停止を要求するまで、status_interval_minutes ごとに更新を出し続けてください。チャット / ランタイムをそれほど長く開いたままにできない場合は、その旨を明示し、手動でステータスを更新するための永続的なワークフロー / ログのパスを提供してください。

終端状態に達していない監視対象ジョブに対して最終応答を使用しないでください。ターンを終了するとチャットのウォッチャーがデタッチされます。終端状態に達していないステータスメッセージは進行中の更新として扱い、ポーリングを続けてください。最終化するのは、終端状態、ユーザーによる明示的なデタッチ / 停止、またはそれ以上のポーリングを妨げる実際のランタイム制限の場合のみです。

バックグラウンド実行の場合は、job.id と state_file のパスを永続化し、後で同じ SDK を構築して get_job_status(job_id) を呼び出すことで再アタッチします — ジョブの状態はディスク上のストアから読み取られます。

オーケストレーションパターン

多段階のワークフロー、並列スイープ、および ActionWorkflow による実行フォルダーの永続性については、references/orchestration-patterns.md にあります。create_job 呼び出しの連鎖、パラメータのスイープ、またはコンテキストの中断をまたいだ実行状態の永続化を行う前に、これを読んでください。

データセットユーティリティ

スキルに記載されたファイル名がユーザーのレイアウトと一致しない場合は、データセットを一覧表示して確認します:

assert sdk.check_path("s3://my-bucket/coco/")
files = sdk.list_path("s3://my-bucket/coco/train/")
# Use the actual paths to set spec fields.

S3 パスの場合、// を避けるために連結時に末尾のスラッシュを削除します:

base = dataset_uri.rstrip("/")
specs["dataset"]["train_csv"] = f"{base}/train.csv"   # nested — see "spec is nested dicts"

プラットフォーム固有の注意事項

プラットフォームごとの動作、kwargs、および認証情報のスコープについては、references/platform-notes.md を参照してください: Brev (instance_id/gpu_type/cloud_cred_id/workspace_group_id、準備完了待ちのタイムアウト)、SLURM (SSH 経由の sbatch、Lustre パス、キューのデフォルト)、Kubernetes (kubeconfig、GPU Operator)、およびローカル Docker (シングルホスト、マルチ GPU)。

エラーパターン

SDK エラー → 根本原因 → 修正のマッピングは references/error-patterns.md にあります。CredentialError、イメージプルの失敗、Pending のまま固まったジョブなどに遭遇したときに読んでください — 各エントリは例外のテキストを根本原因に対応付けています。

SDK が行わないこと

SDK は、スキルの読み取りや解釈、AutoML の単独実行、仕様の内容の決定、プラットフォームの選択、複数ステップのワークフローのオーケストレーションを行いません。これらはエージェントの責任です。モデルレベルの AutoML ポリシー（automl_enabled: true → automl_policy: off が設定されている場合、またはユーザーが通常の単一実行を求めている場合を除き、skills/applications/tao-run-automl）を含む、スコープに関するガードレールの詳細は references/scope.md を参照してください。