tao-run-automl

TAO AutoML スキル

任意の TAO ネットワークで、自動ハイパーパラメーター最適化（HPO）を実行します。エージェントは AutoMLRunner を使用します。これは、推奨値の生成、トレーニングジョブの起動、メトリクスの抽出、結果のオプティマイザーへのフィードバックまで、処理全体を管理する単一のインターフェイスです。

ランナーはプラットフォームに依存しません。標準的な SDK 形式（create_job、get_job_status、get_job_logs、get_failure_analysis）を実装する任意のオブジェクトを受け取り、それらのメソッドを呼び出します。ジョブを実行したい環境に適した SDK を選択してください。

SDK	AutoML での用途
LeptonSDK	DGX Cloud でのマルチノードスイープ。マネージドスケジューリングに対応
BrevSDK	Brev インスタンスでのコスト最適化スイープ（推奨ごとに単一インスタンス。複数 GPU に対応）。複数の認証情報または複数のワークスペースを持つアカウントでは、create_job に cloud_cred_id= と workspace_group_id= を渡す必要があります。詳しくは skills/platform/tao-run-on-brev/SKILL.md を参照してください。
SlurmSDK	キューやクォータのある共有 HPC クラスターでの大規模なスイープ
KubernetesSDK	NVIDIA GPU Operator を使用する EKS／GKE／AKS／オンプレミスクラスターでのスイープ
DockerSDK	ローカルでのデバッグ、または単一ホストでのスイープ

推奨ごとのマルチノード実行は Lepton、SLURM、K8s で機能します（各推奨は N ノードの分散トレーニングジョブです）。Brev とローカル Docker は推奨ごとに単一ホストです。1 台のホスト内でのマルチ GPU 実行（gpu_count > 1）には対応しますが、1 つの推奨を複数のホストにまたがって実行することはできません。

ワークフロー：（1）ユーザーの意図の解析と事前確認、（2）アルゴリズムの選択、（3）設定と実行、（4）監視・再開・ステータスの照会、（5）結果の解釈。各ステップの詳細は、以下にリンクされているリファレンスを参照してください。失敗時の注意点：references/pitfalls.md。やり取りの例：references/examples.md。セットアップの詳細：references/prerequisites.md。

事前確認

このスキルには nvidia-tao-automl が必要です（依存関係として nvidia-tao-sdk もインストールされます）。どちらも公開 PyPI で提供されており、固定バージョンは versions.yaml（wheels.tao_automl_*）に記載されています。scripts/resolve_versions_key.py を使って解決します。使用するプラットフォームエクストラを選択してください。

python -c "import tao_automl" 2>/dev/null || {
  SB="${TAO_SKILL_BANK_PATH:?}"
  echo "MISSING: nvidia-tao-automl not installed. Pick the platform extra you need:"
  echo "  pip install \"$($SB/scripts/resolve_versions_key.py wheels.tao_automl_lepton)\"      # DGX Cloud / Lepton"
  echo "  pip install \"$($SB/scripts/resolve_versions_key.py wheels.tao_automl_slurm)\"       # on-prem SLURM cluster"
  echo "  pip install \"$($SB/scripts/resolve_versions_key.py wheels.tao_automl_kubernetes)\"  # K8s (EKS / GKE / on-prem)"
  echo "  pip install \"$($SB/scripts/resolve_versions_key.py wheels.tao_automl_docker)\"      # local Docker daemon"
  echo "  pip install \"$($SB/scripts/resolve_versions_key.py wheels.tao_automl_brev)\"        # Brev GPU instances"
  echo "  pip install \"$($SB/scripts/resolve_versions_key.py wheels.tao_automl_all)\"         # all 5 platforms"
  echo "  (append ,llm or ,wandb to the extra for agentic-search or experiment-tracking deps)"
  exit 1
}

（チェックアウトしたリポジトリを使ったローカル開発の場合：pip install -e '~/tao-run-automl[lepton]'。）不足している場合、エージェントは Bash 経由でインストールを許可するようユーザーに求め、その後、続行前に事前確認を再実行します。

前提条件

AutoML を実行する前に、以下のすべてを満たしてください。各プラットフォームの認証情報の絞り込み、データセット URI の形式、バンク構造のツリー、インストールコマンドの詳細については、references/prerequisites.md を参照してください。

1. 共通の起動前チェック — まず tao-launch-workflow のインテークパターンを実行してください。選択したプラットフォームの認証情報、アクセスチェック、データセットの可視性、モデルの認証情報、コンテナイメージの確認、コンピュート構成が整うまで、AutoML はランナーファイル、ワークスペース、状態ファイル、ログ、互換性シムを作成したり、依存関係をインストールしたりしてはなりません。これにより、SSH、ストレージ、イメージ、認証情報の設定不足が原因の偽の推奨失敗で、予算を浪費するのを防げます。
2. SDK の認証情報 — ~/.config/tao/.env から読み込まれる環境変数（スキルバンクの SessionStart フックによって自動読み込みされます）。scripts/list_tao_platforms.py --platform <platform> --format text を使ってプラットフォームごとに必要な変数を絞り込み、一覧に記載されたものだけを尋ねてください（URI が s3:// を使う場合に限り S3、コンテナの取得には NGC_KEY）。エージェントは値を読み取りません。[ -n "$VAR_NAME" ] で存在のみを確認します。SDK は引数なしで構築してください（例：LeptonSDK()）。
3. データセット — コンピュートバックエンドからアクセス可能である必要があります。URI 形式はプラットフォームによって異なります（Lepton は s3://...、SLURM は絶対共有パス、Azure は azure://...、Docker はローカルパスです。aws://... は決して生成しないでください）。データセットのルートまたは正確な spec キーのパスを受け付け、custom.train_dataset.annotation_path= のようにユーザーが指定したキーはそのまま保持してください。ファイルが同じ親ディレクトリにあることを強制してはなりません。
4. スキルバンクが利用可能 — ランナーには明示的な skill_dir（<bank-root>/models/<network> への絶対パス。環境変数へのフォールバックなし）が必要です。エージェントがワークフローを読み込んだものと同じバンクルートを使用してください。重要：AutoML には、パッケージ化された有効な <bank-root>/models/<network>/schemas/train.schema.json が必要です。これは AutoML のサポート判定ゲートであり、automl_enabled パラメーター、デフォルト値、範囲、選択肢、重み、人気度メタデータを定義します。実行時に ~/tao-core が存在することを前提としてはなりません。パッケージ化された train スキーマがない場合、そのモデルでは AutoML を実行しないでください。references/spec_template_<action>.yaml は、非 TAO-Core モデル（cosmos-rl、clip）では必須で、TAO Core／Hydra ベースのモデル（DINO、BEVFusion）では任意です。
5. 必要なプラットフォーム用の追加パッケージを指定して nvidia-tao-automl をインストールしてください（公開 PyPI。バージョンは versions.yaml で固定）。インストールコマンドは、上記の Preflight ブロックまたは references/prerequisites.md にあるものを使用してください。エージェント型アルゴリズムの場合は、追加パッケージに ,llm を追加してください。

セットアップを確認します：

python3 -c "from tao_automl.runner import AutoMLRunner; print('OK')"
python3 -c "from tao_automl.brain.llm_brain import LLMBrain; print('LLM OK')"   # optional, LLM features
python3 -c "import wandb; print('WandB OK')"                                    # optional, WandB

---

概念：TAO AutoML とは？

TAO AutoML は、「異なるハイパーパラメーター値を試す → 学習する → 結果を比較する → 繰り返す」というサイクルを自動化します。対象のネットワーク（network_arch）、探索するハイパーパラメーター（モデルスキルとスキーマから選択）、最適化するメトリクス（モデルスキルまたはユーザーのリクエストから選択）、試行回数（予算）を指定します。すると、探索アルゴリズム（Bayesian、Hyperband、LLM など）がハイパーパラメーター値を選び、SDK が対象とするバックエンドで実際の学習ジョブを起動します。学習ログから結果のメトリクスを読み取り、それをアルゴリズムにフィードバックして有効な設定を学習させ、予算が尽きるまで繰り返し、見つかった最良の設定を返します。

各「試行」は**推奨（rec）**と呼ばれます。1 rec は、特定のハイパーパラメーター一式を使った学習の全実行を指します。

---

クイックサポートクエリ

ユーザーが AutoML でサポートされているモデル／ネットワークを尋ねた場合は、AutoML モードで同梱のモデル一覧ヘルパーを実行します。AutoML の有効化はモデルレベルのメタデータです（skills/models/<network>/references/skill_info.yaml に automl_enabled: true と記載されています）。ワークフローレベルではありません。ヘルパーはそのメタデータを読み取り、モデルに解析可能な学習データクラスのスキーマが同梱されているかどうかも検証します。

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

以下の互換性ラッパーも使用できます。同じロジックに処理を委任します。

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

出力に含まれる両方のセクションを返します。実行可能な AutoML モデルと、AutoML は有効だがスキーマが同梱されていないため実行できないモデルです。サポートのルールは次のとおりです。AutoML はモデルレベルで有効化されます。AutoML を実行するには、さらに skills/models/<network>/schemas/train.schema.json が同梱され、有効である必要があります。

---

Step 1: ユーザーの意図を解析する

ユーザーが AutoML のカスタマイズを明示的に依頼するか、カスタマイズの提案に同意しない限り、クイックスタートでの実行をデフォルトとします。通常の「AutoML を実行して」というリクエストに対して、アルゴリズム、予算、探索空間の選択を必須入力として提示しないでください。

学習可能なモデルスキルに到達するワークフロー／アプリケーションはすべて、選択されたモデルの automl_enabled メタデータを確認する必要があります。値が true の場合、実行／ワークフロー設定で automl_policy: off が指定されているか、ユーザーが通常の単一学習の実行を明示的に求めていない限り、この AutoML ワークフローをデフォルトの学習パスとして使用します。これにより、各アプリケーションスキルに許可リストを重複して持たせることなく、tao-train-single-step、DEFT、および今後のワークフロー全体で AutoML の有効化を拡張できます。

デフォルト実行の入力項目を抽出し、クイックスタートのデフォルトを適用します。必須フィールドの完全な一覧表（network_arch、platform、データセット URI／直接指定する spec パス、image、metric、direction、skill_dir、long_running_enabled、status_interval_minutes、認証情報、コンピュート構成、LLM のエンドポイント／モデル／キーの 3 項目）、クイックスタートのデフォルト（bayesian、推奨値 10 件、ハイパーパラメーター／範囲は None、モニタリング間隔は 5 分）、わかりやすい実行開始時の確認用プロンプト一覧、カスタマイズ時のみ使用するフィールド、クイックスタートのランナー構成、メトリック選択のベストプラクティスは、すべて references/intake-and-inputs.md に記載されています。

常に適用される重要なゲーティングポリシー：

• 必須フィールドが 1 つでも欠けている場合は、ユーザーに確認してください。データセットパス、スキルバンクのパス、認証情報、またはモデルスキルが必須としているハードウェアを推測してはいけません。
• image：デフォルトを解決してユーザーに提示し、AutoML ランナーを作成する前に、確認を得るか image=<override> の指定を求めます。
• direction：メトリック名が暗黙のルール「loss を含む場合は最小化、それ以外は最大化」と異なる場合にのみ必要です。
• llm_endpoint、llm_model、llm_api_key：llm／hybrid／autoresearch では必ず確認してください。コードのデフォルト値 https://integrate.api.nvidia.com/v1 は 404 を返すため、常に llm_endpoint を明示的に渡します。

AutoML スクリプトを生成する前に、共通の実行前チェックを使ってプラットフォームへのアクセスとデータセットの可視性を確認してください。SLURM の場合、これは少なくとも 1 台のログインホストへのパスワードなし SSH 接続と、必須の各アノテーション／メディアパスに対するリモートでの test -e チェックを意味します。コンテナーイメージの確認も同様に行います。確認済みの学習イメージは AutoMLRunner.run(..., image=chosen_image, ...) または SDK アダプターの create_job(..., image=chosen_image, ...) に渡す必要があります。暗黙のデフォルトに頼らないでください。また、モデルスキルに記載されているモデル固有のアノテーション内容チェックも実行します。実行前チェックに失敗した場合は、すぐに失敗するランナーを作成せず、問題の解消手順を提示して停止します。必須のアノテーションフィールドが不足している場合は、AutoML の推奨に関する問題ではなく、実行前チェックの失敗です。

カスタマイズの確認： 必須のクイックスタート項目がそろった後で、カスタマイズを簡潔に提案してもかまいません。ユーザーが断った場合は、デフォルトのまま進めます。カスタマイズを選択した場合は、references/intake-and-inputs.md に記載されているカスタマイズ時のみ使用するフィールドを提示します。 必須：AutoML を設定する前に、生成されたデータクラスのスキーマを読んでください。 選択したモデル／アクションについて、${TAO_SKILL_BANK_PATH:-~/tao-skills-external}/models/<network>/schemas/train.schema.json と .../schemas/manifest.json を読んでください。AutoML は、train.schema.json がパッケージに含まれ、有効な場合にのみ実行できます。手書きのメモ、古い runner スクリプト、ローカルの ~/tao-core チェックアウトを代わりに使用しないでください。スキーマが見つからない場合は停止し、スキーマが生成されて配布されるまでは AutoML が有効でも実行できないことを報告してください。automl_default_parameters、automl_disabled_parameters、パラメーターごとのデフォルト値、範囲、列挙値、option_weights、math_cond、depends_on、parent_param、popular の正しい情報源として、スキーマ JSON を使用してください。automl_hyperparameters=None の場合、runner はスキーマで automl_enabled=True とマークされたすべてのパラメーターを検出します。ネットワークごとに対象は異なるため、ここにハードコードしないでください。

以下の必須ルールは、すべての実行の前提条件です。全文、コードパターン、根拠については references/mandatory-rules.md を参照してください。

• LLM ベースのアルゴリズムでは、プロンプトの設定が必須です（llm、hybrid、autoresearch）。スクリプトを生成する前に、llm_endpoint、llm_model、llm_api_key を解決してください（優先順位はリファレンスに記載）。有効な LLM 設定がない場合、brain は警告なしにランダムサンプリングへフォールバックし、GPU 予算を無駄にします。
• 必須：スクリプトを生成する前にモデルのスキルを読んでください — <bank-root>/models/<network>/SKILL.md を読み、その トレーニング要件、アクションごとのデータセット要件、一般的な設定の上書き、AutoML／HPO に関する注意事項、エラーパターンを適用してください。モデル固有の知識をハードコードしないでください。
• 必須：この AutoML スキルにモデル固有の定数を含めないでください — ハイパーパラメーター名、範囲、デフォルト値、メトリクス名、データセットのレイアウト、設定の上書きキー、画像、メトリクスの正規表現は、ここではなくスキーマとモデルのスキルに記載してください。
• 必須：タイムスタンプ付きのワークスペースフォルダーを使用してください — 常に workspace_path の末尾に datetime.now().strftime("%Y%m%d_%H%M%S") を付加してください。フラットなパスは使用しないでください。
• 必須：事前チェックの通過後、新しい AutoML リクエストごとに新しい runner を作成してください — リクエストを新規に受けるたびに、一意のタイムスタンプを付けて、新しい runner スクリプト、ログ、PID ファイル、SDK の state_file、workspace_path を作成してください。ユーザーが再開／続行／復旧／確認を明示的に求めた場合にのみ、既存の実行を再開してください。

メトリクスの選択に関するベストプラクティス： 学習損失は、小規模なファインチューニング用データセットでは過学習するため、安価な学習損失よりも、モデルのスキルで推奨されている検証メトリクスまたはタスクメトリクスを優先してください。検証用の代理指標を使用する場合は、そのメトリクスが出力されるよう、モデルのスキルで必須とされている検証関連の spec_overrides も適用してください。eval_fn を使った実際のタスクメトリクスが最も正確ですが、試行ごとのコストが増加します。詳細は references/intake-and-inputs.md を参照してください。

---

ステップ 2：アルゴリズムを選択する

デフォルトでは bayesian を使用してください。従来型および LLM／エージェント型アルゴリズムの全一覧（使用する状況、一般的な予算、仕組み）、デフォルトと注意事項のルール、判断ツリーについては references/algorithms.md を参照してください。アルゴリズムガイドは、カスタマイズモードの場合、またはユーザーがアルゴリズムを指定した場合にのみ提示してください。

---

ステップ 3：設定して実行する

references/automl-settings.md にある一般的な例を基に runner を作成してください。内容は、最小構成の例、すべてのオプションを含む完全な例、LLM を活用した例、プログラムによる AutoML API の使用例、automl_settings の全キーを網羅した表、kpi メトリクスの解決方法、LLM アナライザーの環境変数による切り替え、spec_overrides のルールです。

• custom_param_ranges で探索空間を制約します。形式の表、例、モデル固有の探索空間ルールについては references/custom-param-ranges.md を参照してください。
• オプトイン形式の metric_extractor／eval_fn フックと WandB のトラッキングについては references/hooks-and-wandb.md を参照してください。
• LLM／エージェント型の詳細（NLConfigGenerator、スタンドアロンの LLMAnalyzer、5 つの autoresearch エージェントコンポーネント、複数フェーズの研究プログラム）については references/nl-config-and-research.md を参照してください。

モデル固有のハイパーパラメーター、メトリクス抽出器、spec_overrides はすべて、モデルのスキルから取得してください。

---

ステップ 4：進行状況を監視する

runner.run() はすべての推奨が完了するまで処理をブロックします。進行状況を報告するには、on_recommendation / on_result コールバックを使用してください。各推奨には 10～90 分かかります。アップロードに時間がかかっている間に失敗したと判断しないでください。オーケストレーターの実行中にプロセスが停止した場合は、接尾辞を含む完全な workspace_path と resume=True を指定して再起動してください。別のプロセスから進行状況を確認するには、query_status() を使用します。コールバック、再開の動作、query_status() / get_status() の全使用方法については、references/monitoring-and-resume.md を参照してください。

---

ステップ 5：結果を解釈する

runner.run() は、best、progress、history の各キーを持つプレーンな dict を返します。メトリクス値は常にユーザーの元のスケールで表示されます。最良の設定、順位付きの比較表、インサイト、WandB が有効な場合はそのリンク、次のステップを報告してください。結果 dict の完全な構造、報告チェックリスト、すべての推奨が失敗した場合のトリアージについては、references/results.md を参照してください。

---

モデル固有の注意事項

モデル固有の注意事項はここには記載しません。要求された各 network_arch について、<bank-root>/models/<network>/SKILL.md を読み、Training Requirements、Per-Action Dataset Requirements、Typical Spec Overrides、AutoML / HPO Notes、Error Patterns の各セクションを信頼できる情報源として使用してください。

---

よくある落とし穴

skill_dir の誤りや指定漏れ、LLM エンドポイントの誤り（404）、モデル固有のトレーニング失敗、ワークスペースの競合、弱いプロキシメトリクス、暗黙的な方向指定の落とし穴、spec override の入力ミス、スイープ中のオーケストレーター停止、気付かれにくいランダムな LLM 設定、openai の不足、WandB にログが記録されない問題、conda run のバッファリングを含む、繰り返し発生する 15 種類の失敗モードとその対処法を references/pitfalls.md に記載しています。実行の前と実行中に確認してください。

---

会話例

ネットワークの最適化、実際のタスクメトリクスの要求、LLM ガイド付き検索、完全自律型の autoresearch、再開、WandB を使った ASHA への切り替え、目標の説明からの設定生成に関する、代表的なエージェントとユーザーのやり取りについては、references/examples.md を参照してください。