tao-run-platform

TAO Execution SDK

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

• Job ハンドルを使って、ステータスを確認したり、時間をかけてログをストリーミングしたりする場合。
• プラットフォームが API のみの場合（Lepton には docker-run 相当の機能がありません）。
• エントリーポイントに S3 対応の入力ダウンロード／出力アップロードが組み込まれている必要がある場合。
• 複数のジョブを連結し、状態を永続化したい場合。

事前確認

このプラットフォームを使用する前に nvidia-tao-sdk[all] をインストールしてください。[all] エクストラにより、プラットフォーム固有のすべての依存関係（Lepton、Brev、S3 ユーティリティなど）がインストールされます。

python -c "import tao_sdk" 2>/dev/null || {
  echo "MISSING: nvidia-tao-sdk not installed. Run:"
  echo "  pip install nvidia-tao-sdk[all]"
  exit 1
}

パッケージインデックスは環境によって異なります。runner／コンテナには、動作する pip の設定（例：~/.pip/pip.conf、PIP_INDEX_URL、PIP_EXTRA_INDEX_URL、またはプロキシ）が設定されていることを前提としています。インデックスまたはネットワークの問題でインストールに失敗した場合は、runner の設定に関する問題です。このスキルはレジストリに依存しません。

不足している場合、エージェントは Bash によるインストールをユーザーに許可するよう求め、その後、事前確認を再実行します。自動で、かつ通知なしにインストールしてはいけません。

セットアップ

認証情報は環境変数から取得します。これらの変数は ~/.config/tao/.env から読み込まれます（skill bank の SessionStart フックによって自動的に読み込まれます）。

from tao_sdk.platforms.lepton import LeptonSDK   # DGX Cloud
from tao_sdk.platforms.brev   import BrevSDK     # Brev GPU instances

sdk = LeptonSDK()    # reads LEPTON_WORKSPACE_ID, LEPTON_AUTH_TOKEN
# or
sdk = BrevSDK()      # reads BREV_API_TOKEN (optional — falls back to brev login)

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

プラットフォーム	必須	任意
Lepton	LEPTON_WORKSPACE_ID、LEPTON_AUTH_TOKEN	—
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: off が含まれている場合、ユーザーが通常の実行を明示的に求めた場合、またはモデルのメタデータで AutoML が有効とされていてもトレーニングスキーマがまだパッケージ化されていない場合に限り、ワークフローで 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 であり、Lepton の認証情報は必要ありません。Kubernetes とローカル Docker では、Lepton や 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]

Lepton のみ：

• sdk.get_job_replicas(job_id) — pending 状態で停止したジョブのレプリカレベルの診断情報。

Brev のみ：

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

ジョブの送信

エージェントは、create_job を呼び出す前に、必ず build_entrypoint を介してコンテナコマンドを構築します。エージェントは skill_info.yaml からアクションのスキーマ（command、config_format、inputs、outputs、upload_excludes）を読み取り、これらのフィールドを kwargs として渡します。build_entrypoint は、コンテナ内の script_runner ランタイム（base64 heredoc としてインライン化）と、実行時に宣言された入力をダウンロードし、リモート URI をローカルパスに書き換えて {config_path} に spec ファイルを書き込み、ユーザーコマンドを実行して出力をアップロードする CLI 呼び出しを組み込みます。プラットフォーム SDK の create_job は、生成されたコマンドをそのまま実行します。暗黙的なラップは行いません。

build_entrypoint は、渡された内容からモード（config／args／passthrough）を推定します。mode を明示的に渡すことはありません。完全なエントリーポイントの契約、アクション mode ごとの spec／args 構築方法、モード推定表、および resolve_container_image() については、references/job-construction.md を参照してください。出力先（ランタイムの出力先テーブルとプラットフォームごとの注入ポリシー）および「spec はフラットなドット区切りキーではなく、ネストされた dict である」という重要なルールについては、references/outputs.md を参照してください。spec 駆動とパスキー指定の build_entrypoint ＋ create_job の完全な例については、references/examples.md を参照してください。

モニタリング

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)

Pending のまま停止した Lepton ジョブでは、レプリカ診断によって原因（イメージのプル、スケジューリング、マウントエラー）が明らかになります。

for r in sdk.get_job_replicas(job.id):
    issue = r["status"].get("readiness_issue")
    if issue:
        print(issue["reason"], issue["message"])
        # e.g. "InProgress" / "Pulling image"  (normal for big images)
        #      "Failed"     / "ImagePullBackOff" (NGC_KEY problem)
        #      "ConfigError" / "Mount point not found" (bad node)

失敗時には、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"

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

各バックエンド（Lepton、Brev、SLURM、Kubernetes、ローカル Docker）には、それぞれ独自のインポートパス、ストレージモデル、分散トレーニングのオプション、認証情報のスコープ、create_job の kwargs があります。特定のバックエンド向けの runner アーティファクトを生成または起動する前に、プラットフォームごとの詳細についてreferences/platform-notes.mdを参照してください。

エラーのパターン

SDK のエラーから根本原因を特定し、修正するための対応表はreferences/error-patterns.mdにあります。CredentialError、イメージのプル失敗、Pending のまま停止したジョブなどが発生した場合に参照してください。各項目では、例外テキストとその根本原因が対応付けられています。

SDK が行わないこと

スコープ上の制約（スキルの読み込み、HPO、spec に関する意見の提示、自動プラットフォーム選択、ワークフローのオーケストレーションを行わないこと）については、references/scope.mdを参照してください。