tao-run-automl

TAO AutoML

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

次の要素を組み合わせて、TAO モデルのハイパーパラメーターを自動最適化します。

1. skills/models/<model_skill>/ にある選択したモデルスキル。
2. skills/platform/<platform>/ にある選択したプラットフォームスキル。
3. AutoMLRunner。推奨値を生成し、選択したアクションのジョブを起動し、メトリクスを抽出して、結果をオプティマイザーにフィードバックします。

モデルのメタデータ、プラットフォームの事前チェック、データの可視性、認証情報、イメージの選択、コンピュート構成がすべて確認できるまで、起動しないでください。

実行ランタイム — 厳格なゲート

推奨値の生成、ベースライン評価、各推奨値の評価、および最終評価はすべて、デフォルトで選択したモデルアクションの解決済み container_image 内で実行されます。トレーニング環境をセットアップする前に、モデルスキルからこの値を解決してください。ローカルのチェックポイントや Hugging Face のモデル ID も、このルールを変更しません。

明示的に要求された場合に限り、venv ベースのモデル実行を使用してください。local-docker、ローカル GPU、Python、pyproject.toml から venv モードを推測してはなりません。指定がない場合、実行環境はコンテナです。tao_automl、TAO SDK、またはプラットフォームアダプター用のホスト／コントローラーの venv はコントロールプレーン専用です。子モデルアクションは、解決済みのコンテナイメージ内で実行してください。

リファレンスマップ

• references/skill_info.yaml：このワークフローの構造化メタデータです。
• 詳細リファレンスは分割されています。前提条件とサポート確認については automl-preflight-concepts.md、探索ポリシーについては automl-intent-algorithms.md、蒸留／枝刈り／量子化アルゴリズムの十分性と、今後の圧縮探索ロードマップについては automl-compression-literature.md、ランナー／API／WandB の詳細については automl-runner-configuration.md、フック、再開、注意点については automl-advanced-monitoring.md、会話例については automl-examples.md、繰り返し適用する安全性確認については automl-common-pitfalls.md を参照してください。detailed-guide.md はマップにすぎません。
• skills/models/<network>/SKILL.md：モデル固有のデータセット要件、メトリクス、HPO に関する注意事項、チェックポイントの引き継ぎ、既知の障害です。
• skills/models/<network>/references/skill_info.yaml：アクションの契約、コンテナイメージ、入力、出力、アップロード対象外、mode です。
• skills/platform/<platform>/SKILL.md：選択したプラットフォームの事前チェック、認証情報、リソース構成、モニタリング、キャンセルです。
• skills/core/tao-launch-workflow/SKILL.md：プラットフォーム、認証情報、データセットの可視性、イメージの確認、ユーザー確認の共通受付パターンです。

事前チェック

1. 共通の起動受付を実行します。ユーザーがプラットフォームを選択していない場合は、選択を尋ねてください。Brev、SLURM、Kubernetes、Docker はいずれも同等の選択肢です。
2. ランナーファイルを生成する前に、選択したプラットフォームスキルの事前チェックを実行します。
3. nvidia-tao-automl のインポートを確認します。

python -c "import tao_automl; from tao_automl.runner import AutoMLRunner; print('OK')"

次に、選択したプラットフォームの SDK コンストラクターを確認します。tao_automl をインポートできても、プラットフォームのバックエンドがインストールされている証明にはなりません（例：docker パッケージがない場合、DockerSDK() は CredentialError を発生させます）。automl-preflight-concepts.md を参照してください。

不足している場合は、versions.yaml に記載された正確なインストールコマンドを提示し、インストール前に確認を求めてください。

SB="${TAO_SKILL_BANK_PATH:-~/tao-skill-bank}"
pip install "$($SB/scripts/resolve_versions_key.py wheels.tao_automl_<platform>)"

有効なプラットフォームホイールのキーは tao_automl_brev、tao_automl_slurm、tao_automl_kubernetes、tao_automl_docker、tao_automl_all です。すべてのバックエンドが必要な開発マシンに限り、all を使用してください。LLM ガイド付きアルゴリズムをユーザーが要求した場合に限り、,llm を追加してください。

モデルサポートゲート

実行のたびに、以下を行います。

1. モデルの SKILL.md と references/skill_info.yaml を読みます。
2. モデルの automl_enabled: true を確認するか、モデルのスキルが選択したアクションを AutoML に明示的にルーティングしていることを確認します。
3. <skill_dir>/schemas/<action>.schema.json が存在し、解析できることを確認します。これが AutoML の探索空間ゲートです。
4. Cosmos-RL や CLIP など、TAO-Core 以外のモデルでは、さらに references/spec_template_<action>.yaml が必要です。これがない場合、ランナーにはアクションのデフォルト設定がすべて揃いません。
5. いずれかのゲートを通過できない場合、探索空間を独自に作成してはいけません。不足しているパッケージ成果物を報告します。

入力

ランナーの構築前に、以下を収集します。

入力	要件
model_skill	skills/models/ 配下にある、解決済みのモデルスキルディレクトリ。network_arch などのユーザー指定エイリアスは、まずパッケージ済みのスキルディレクトリに解決します。
network_arch	解決済みのモデルスキルのメタデータから読み取ります。
action	最適化するアクション。パッケージ済みのスキーマ／テンプレートがある train、evaluate、inference、distill、prune、quantize のいずれかです。
platform	サポート対象の TAO プラットフォームスキルのいずれかです。
train_dataset / eval_dataset / アクション入力	モデル固有の spec キーとレイアウトを使用します。train 以外のアクションでは、親モデル／教師モデルのチェックポイント、キャリブレーションデータ、またはプルーニング済み成果物が必要になる場合もあります。
results_root	プラットフォームに適したローカル、Lustre、または S3 のパスです。
gpu_count、num_nodes	モデルとプラットフォームの制限を守ります。
container_image	モデルのメタデータと versions.yaml を使って解決し、ユーザーに提示します。
automl_algorithm	ユーザーが別のアルゴリズムを指定するか、モデルスキルが別のアルゴリズムを推奨しない限り、デフォルトは bayesian です。
metric、direction	モデルスキルの検証指標／タスク指標を優先します。
automl_budget	アルゴリズムに応じて必要となる、推奨数、最大エポック数／ラング数、同時実行数、または個体数です。

シークレット値を尋ねてはいけません。必須の環境変数は [ -n "$VAR_NAME" ] && echo SET || echo UNSET で確認します。

起動前レビューゲート

推奨ジョブを起動する前に、具体的な起動レビューを提示し、ユーザーの確認を得ます。このゲートは、AutoML に対応するすべてのモデル／ネットワークに対するすべての AutoML 実行に適用されます。Cosmos 固有のものではなく、単一のモデルスキルに限定してはいけません。プラットフォームとイメージのプリフライトに合格している場合も適用されます。レビューには、以下を含める必要があります。

• モデル／ネットワーク、プラットフォーム、イメージ、GPU／ノード構成、結果／ワークスペースのルート
• データセットモードと具体的な spec キー。低コストで取得できる場合は、train／eval のサンプル数も含めます
• アルゴリズム、予算、最大同時実行ジョブ数、指標、方向
• 探索可能なパラメーターと範囲。ユーザーが探索空間を明示的に指定していない場合は、デフォルト値も含めます
• 初回起動バッチ用に生成された正確な推奨設定。推奨ジョブを送信する前に、レビュー専用のステップで生成します
• 推奨ごとの推定実行時間と合計予想所要時間、およびその推定に用いた前提
• プリフライト後の eval ジョブによる自動ベースラインのジョブ ID、指標値、結果パス。または、モデルに実行可能な evaluate アクションがないか、検証データがない場合は、その明示的な阻害要因
• 選択した最良のチェックポイント／モデルに対する AutoML 後の最終評価計画。指標、データセット、記録先のパスを含めます

推定時間がユーザーの指定した上限を超える場合、または通常の対話的な実行より大幅に長い場合は、起動前に推奨数、エポック数、データセットのサイズ、検証頻度、または探索空間を減らすかどうかを確認します。数日かかる見積もりをログに隠してはいけません。

自動ベースライン評価ジョブ

プラットフォーム、イメージ、認証情報、データ、モデルの事前チェックに合格した後、AutoML の推奨ジョブを送信する前に、選択した検証／評価データを使ってモデルの評価アクションを 1 回実行します。これは必須の AutoML セットアップであり、ユーザーに尋ねる任意の「事前学習済みモデルの評価」ではありません。AutoML の学習実行で使用するものと同じベースモデルまたはチェックポイント、モデルスキルの評価仕様／テンプレート、選択したプラットフォームの通常のジョブ送信経路を使用してください。モデルスキルが学習時よりも小さい評価用の形状を推奨している場合は、その形状を使用し、起動レビューで明記してください。

確認を求める前に、評価指標の値を起動レビューで共有してください。開始時のチェックポイントがあるものの、ベースラインを生成できない場合（パッケージ化された評価アクションがない、評価データセットがない、評価ジョブが失敗したなど）は、トレーニング損失のみの実行に黙って切り替えるのではなく、停止してブロッカーを報告してください。

スクラッチから学習する場合は、ベースラインを利用不可として記録し、そのまま続行してください。空のチェックポイントを評価しないでください。

最終評価はランナーが担当します。評価を実行できる場合は、final_eval_fn(best_rec, train_job_id) を AutoMLRunner.run に渡してください。そうすると、結果に result["final_evaluation"] が含まれます。コールバック、チェックポイント、ベースライン、スクラッチからの学習に関するルールについては、automl-preflight-concepts.md を参照してください。

依存関係とデータの事前チェック

選択したワークフローでオブジェクトストレージまたはプラットフォーム CLI が必要なのにツールがない場合は、不足している依存関係を報告し、続行する前に正確なインストールコマンドを提示してください。ユーザーの承認後、scripts/check_tao_launch_preflight.py を --install-missing-tools とともに再実行し、必要最小限のパッケージをインストールして、直ちにパスの検証を再試行してください。S3 パスの場合は、ランナーのアーティファクトを作成する前に、起動プラットフォームから認証情報とパスの読み取り可能性の両方を検証してください。

学習の各試行で大きなメディアアーカイブやディレクトリを読み込むモデルでは、データセットを実行プラットフォームからアクセスできるストレージに一度だけステージングまたは展開し、すべての推奨仕様でそのステージング先パスを指定してください。入手可能な場合は、ソース URI、ステージング先パス、バイト数／ファイル数の証拠、タイムスタンプを <workspace>/evaluations/data_staging.json に記録してください。ステージングできない場合は、起動前レビューに S3 I/O が繰り返し発生するリスクを含め、それを前提に長時間の AutoML 実行予算を使う前に確認を求めてください。

モデルスキルにサンプル数に応じた制約が定義されている場合は、起動前に適用してください。選択したデータセットと GPU シャード数で学習ステップが 0 になるバッチサイズの推奨をすべて拒否するか、上限を設けてください。生成した推奨を送信する前に、それぞれについて scripts/check_tao_launch_preflight.py --effective-batch-limit train_annotation=<batch_size>,<shard_count> を使用してください。後になって有効バッチサイズに対してデータが少なすぎるため推奨が失敗した場合は、無効な設定として分類してください。残りの予算がある場合に限り、置き換えるか調整し、最終サマリーで修正内容を報告してください。 トレーニングサンプル数がアノテーションファイルまたは簡易的なマニフェスト読み取りから判明している場合は、automl_settings["train_sample_count"] として AutoMLRunner.run に渡してください。これにより、ランナーはジョブを送信する前に実行不可能な推奨に上限を設け、その調整を result["history"][i]["adjustments"] に記録できます。

アルゴリズムの方針

アルゴリズム	適した用途	必須の調整項目
bayesian	予算が少～中程度で、パラメーター数が少ない場合のデフォルトです。	num_recommendations、メトリック、方向
hyperband、asha	構成が多く、初期段階の試行コストが低い場合です。ASHA は並列実行に適しています。	max_epochs、reduction_factor、任意の max_concurrent
bohb、dehb	マルチフィデリティ予算を使った、ベイズ探索と進化的探索の混合です。	Hyperband と同じ初期段階の予算項目
pbt	学習中にスケジュールを変化させる必要がある、長時間の学習です。	集団と世代の予算
llm、hybrid、autoresearch	ユーザーが、構成済みエンドポイントを使った LLM ガイド付き探索を明示的に希望している場合です。	LLM エンドポイントの設定と予算

evaluate または inference では、選択したアクションのプロンプト、デコード、前処理、または実行時設定の調整項目を対象に、ベイズ探索／BFBO スタイルの探索をデフォルトとして使用します。アクションの出力やログに含まれるタスクメトリックを使用し、メトリック名が曖昧な場合は direction を明示的に設定します。重みを更新しないアクションに、学習損失についての前提を適用しないでください。

distill では、蒸留アクションがエポックベースの最適化を行い、チェックポイントを書き出す場合、学習と同様の方針を使用します。単発の prune と quantize では、アクションスキーマ／モデルスキルでエポックに相当する項目またはキャリブレーション予算の項目が宣言されていて、hyperband／asha／bohb／dehb が有効な場合を除き、bayesian または bfbo をデフォルトとして使用します。圧縮アクションの完了後に、後続の evaluate／inference アクションで選択したメトリックを計算する必要がある場合は、eval_fn を使用します。

一般的なデフォルトよりも、モデルスキルの推奨を優先してください。モデルスキルで起動、検証、またはチェックポイントのコストが短時間の試行を支配するとされている場合は、ASHA または Hyperband を避けてください。

仕様と探索空間

仕様はネストされた辞書として構築します。モデルスキルで読みやすさのためにパスがドット表記で示されている場合は、パスをたどってネストされたリーフに値を割り当ててください。フラットなドット区切り文字列を仕様のキーとして保存しないでください。

選択したアクションのパッケージ済みスキーマを、次の項目に使用します。

• automl_default_parameters
• automl_disabled_parameters
• 有効な最小値／最大値の範囲
• 列挙型、オプションの重み、条件、依存関係、一般的なパラメーター

ユーザーが指定した探索空間は、スキーマの制約内に収める必要があります。離散的な選択肢を持つ整数の調整項目では、モデルスキルで指定されている場合、単純なリストではなく、スキーマで必須とされる整数オプションの形式を含めてください。

モデルスキルでランチャーがデータソースを導出できるとされている場合を除き、データソースのオーバーライドは必須です。データセットで注釈／メディアへの直接パスが使用されている場合は、ユーザーが指定した仕様のキーを正確に保持してください。

メトリックの方針

学習損失は低コストですが、誤解を招くことがあります。モデルスキルのタスクメトリックを優先してください。次のいずれかを使用します。

• ログメトリック：metric=<name>、direction=maximize|minimize。
• metric_extractor(logs, metric_name)：デフォルトのリゾルバーが曖昧な場合に、モデルのログを解析します。
• eval_fn(rec, train_job_id)：ユーザーが下流タスクのメトリックを希望する場合に、推奨ごとにモデルの evaluate アクションを実行します。

モデルスキルで明示的に定義されていない限り、kpi をメトリックに対応付けないでください。

最終レポートでは、ベースラインのメトリック、各推奨のメトリック、選択された最良のメトリックを比較し、調整による影響をユーザーが確認できるようにする必要があります。実際のタスクメトリックの計算に eval_fn が必要なモデルスキルでは、ユーザーが代理メトリックの使用を明示的に了承していない限り、都合のよい学習損失を最適化するのではなく、その評価関数を使用してください。

Runner の構築

選択したプラットフォームの SDK は、事前チェックに合格した後にのみ使用してください。認証情報をコードに埋め込まずに SDK を構築します。

sdk はプラットフォームの SDK オブジェクトです。コンテナーを使用しない venv モデルでは、VirtualEnvSDK(venv_path=..., work_dir=...) を使用します。必ず work_dir を渡してください。デフォルトの ~/.tao_sdk/virtualenv を使用すると、ホームディレクトリが試行のチェックポイントで埋まってしまいます。詳細は automl-runner-configuration.md を参照してください。

import sys
from pathlib import Path
from tao_automl.runner import AutoMLRunner

skill_bank = Path("<absolute-tao-skill-bank>")
model_skill = "<resolved-model-skill-directory>"
skill_dir = skill_bank / "skills" / "models" / model_skill
sys.path.insert(
    0, str(skill_bank / "skills/applications/tao-run-automl/scripts")
)
from resolve_automl_session import validate_session_settings

runner = AutoMLRunner(
    sdk=sdk,
    skill_dir=str(skill_dir),
    action=action,                      # train, distill, prune, quantize, ...
)

workspace_path = Path("<automl_workspace>")
resume = False
# Mandatory fail-closed gate from this skill's bundled scripts directory.
validate_session_settings(
    automl_settings,
    resume=resume,
    workspace=workspace_path if resume else None,
)
result = runner.run(
    workspace_path=str(workspace_path),    # timestamp it to avoid collisions
    automl_settings=automl_settings,       # must contain an explicit session_id
    spec_overrides=spec_overrides,
    automl_hyperparameters=automl_hyperparameters,
    custom_param_ranges=custom_param_ranges,
    metric_extractor=metric_extractor,  # optional
    eval_fn=eval_fn,                    # optional
    final_eval_fn=final_eval_fn,        # optional but required when final eval is runnable
    resume=resume,
)

automl_settings["session_id"] を明示的に設定し、実行ごとに validate_session_settings を呼び出してください。scripts/resolve_automl_session.py new を使って、新しい ID を一度だけ生成します。明示的に要求された場合にのみ再開してください。コントローラーの解決には、scripts/resolve_automl_session.py resolve --workspace <full-run-path> を使用します。状態が存在しない、または曖昧な場合は、ブロッカーとして扱います。新規実行と再開の完全な手順については、references/automl-advanced-monitoring.md の再開に関するセクションを参照してください。

モニタリング

runner のステータス出力と、プラットフォーム SDK の get_job_status、get_job_logs、get_failure_analysis を使用します。実行中のジョブについて、次の情報を報告してください。

• 推奨 ID／試行 ID
• プラットフォームのジョブ ID
• ステータス
• 現在のメトリクス
• これまでの最良メトリクス
• 現在／最良の推奨に選ばれたハイパーパラメーター
• 十分な時間データがある場合は、経過時間と更新後の ETA

失敗した場合は、インフラストラクチャ、データの可視性、イメージ、認証情報、仕様／スキーマ、またはモデルコードのどれに起因するかを分類してください。原因の最小限の修正にとどめ、無効な推奨を繰り返すために追加の予算をひそかに消費しないでください。実行のセットアップ中にブロッカーが解消された場合は、更新された事前チェック／起動レビューを示したうえで、ユーザーに依頼を言い直させることなく、元のタスクを続行してください。

LLM ベースのアルゴリズムでは、実行を有効と判断する前に brain のログを確認してください。LLM の呼び出しが成功したこと、提案が生成されたこと、後続のパラメーター変更の選択に過去のメトリクスが使用されたこと、ログに維持／破棄、または同等のアルゴリズム上の判断が記録されていることを確認します。brain がランダムサンプリングにフォールバックした場合は、有効な LLM ガイド付き実行として扱わず、LLM ワークフローを失敗またはブロックとして分類してください。

結果の引き継ぎ

完了時には、次の情報を提示してください。

1. 選択したメトリクスとその方向に基づき、最良の推奨を特定します。
2. 最良の子ジョブ ID とその結果パスを返します。
3. モデルスキルのチェックポイント／アーティファクトのメタデータと SDK ヘルパーを使って、モデルのチェックポイントまたはアクションアーティファクトを解決します。latest のようなファイル名を推測しないでください。
4. 正確な探索空間、アルゴリズム、予算、メトリクス、プラットフォームを報告します。
5. 自動ベースライン評価のジョブ ID／結果パス／メトリクス、すべての推奨のメトリクス、最終評価のステータス／結果パス／メトリクス、失敗した推奨とその根本原因、経過時間、最終的な実行時の注記を報告します。
6. AutoML + DEFT などのワークフローに渡す場合は、勝者の仕様オーバーライドとチェックポイントを、ワークフローで宣言された引き継ぎフィールドに渡します。
7. デフォルトの保持ポリシーでは、クリーンアップに対応し、安全に削除可能な終了済み試行アーティファクトが削除されたことと、勝者のトレーニングアーティファクトが残っていることを確認します。保護された昇格／再開時の親、または保守的な Hybrid の結果があれば、明示的に報告します。SDK が回収できないリモートバインド、名前付きボリューム、その他の出力経路がある場合は、保持済みのままにせず、最初の試行の前に保持の事前チェックを失敗させる必要があります。

よくある落とし穴

AutoML の実行を開始または復旧する前に、references/automl-common-pitfalls.md を参照してください。