tao-run-automl-deft-pipeline

AutoML + DEFT パイプライン

既存の2つのスキルに委任して3つのフェーズを順に実行する、ワークフロー連携スキルです。HPO には tao-run-automl を、反復的なデータ改善ループには DEFT 適用スキル（AOI の場合はデフォルトで tao-run-deft-aoi、AOI 以外の場合は他の skills/applications/deft-* スキル）を使用します。

このスキルは AutoML や DEFT を再実装しません。担うのは、HPO 仕様の入力、AutoML と DEFT 間での仕様の受け渡し、そしてデータ拡張後のデータセットで AutoML を再実行するための連携部分のみです。

このスキルを適用する場合

• ユーザーが「AOI ワークフローを実行して」や「AOI ChangeNet モデルを改善して」と依頼した場合は、tao-run-deft-aoi を直接使うのではなく、デフォルトでこのスキルを使用します。DEFT のみのループは、このパイプラインの内部ステージです。
• ユーザーが同じモデル／データセットに AutoML と DEFT を連続して適用したい場合
• ユーザーが「両端で AutoML」「HP を調整してから DEFT」「DEFT をウォームスタート」「DEFT の前後に AutoML」と言った場合
• ユーザーが AutoML で調整済みの仕様を持っていて、それを DEFT に渡す方法を尋ねた場合

このスキルを適用しない場合

• ユーザーが DEFT ループのみを明示的に依頼した場合（「DEFT ループだけを実行して」「AutoML はスキップして」）→ tao-run-deft-aoi を直接使用します
• ユーザーが後続の DEFT なしで AutoML のみを実行したい場合 → tao-run-automl を直接使用します
• ユーザーがゼロショット評価、RAG、または学習以外のワークフローを行っている場合

---

基本的な考え方

Phase 1 (AutoML baseline)        Phase 2 (DEFT loop, plain train)        Phase 3 (AutoML refinement)
─────────────────────────        ────────────────────────────────        ───────────────────────────
specs/baseline_spec.yaml         (Phase 1 winner pre-seeds baseline      ${RESULTS_DIR}/iter${N}/dataset/
train/base/training_set.csv       — DEFT skips its baseline train)       train_combined_iter${N}.csv
        │                                       │                                       │
        ▼                                       ▼                                       ▼
[ AutoML HPO sweep ]               [ DEFT: baseline-inference → RCA       [ AutoML HPO sweep ]
   N recommendations                 → iter 1..N (plain retrain) ]        re-tunes HPs against the
   pick best by val_loss / FAR      RCA / route / SDG / mining             DEFT-augmented dataset
        │                                       │                                       │
        ▼                                       ▼                                       ▼
best HPs spec + ckpt ─────►      DEFT-augmented CSV ───────────►        final best checkpoint
                                 + iter winner checkpoint               (the deliverable; no
                                 (Phase 3 warm-starts from it)           further retrain)

引き渡しは次のとおりです。

• フェーズ 1 → フェーズ 2：仕様ファイルと最良のチェックポイントを渡します。DEFT のベースラインステップで同じ HP を再学習すると計算リソースが無駄になるため、この連携処理ではフェーズ 1 の最良の HP を baseline_spec.yaml にディープマージし、最良のチェックポイントを DEFT が想定するファイル名で ${RESULTS_DIR}/baseline/train/ にコピーします。また、deft_state.json と loop_log.jsonl を事前に設定し、DEFT がベースライン推論 → 評価 → RCA → イテレーション 1 から再開するようにします。DEFT 自体は通常の学習のままです（automl_policy: off を維持）。4 ステップの手順は references/handoff.md にそのまま記載されています。
• フェーズ 2 → フェーズ 3：学習 CSVとイテレーションで選ばれた最良のチェックポイントを渡します。CSV（train_combined_iter${N_final}.csv）は AutoML の学習データです。チェックポイント（deft_state.json の iterations.<best>.best_ckpt_path）は各レコメンデーションの train.pretrained_model_path に設定するため、フェーズ 3 はスクラッチからではなく、フェーズ 2 で選ばれた最良のモデルからファインチューニングします。このウォームスタートを行わないと、フェーズ 3 はイテレーションで選ばれた最良のモデルより性能が低下することがよくあります。フェーズ 3 で得られる最良のチェックポイントが最終成果物となり、フェーズ 3 の後に個別の再学習は行いません。詳しくは references/handoff.md を参照してください。

2つではなく3つのフェーズを実行する理由

• フェーズ 1 のみでは、元の学習データ分布に対する適切な HP を見つけられますが、モデルには DEFT が解消するよう設計された分布上のギャップが残ります。
• フェーズ 2 のみ（DEFT のみ）ではギャップを解消できますが、specs/baseline_spec.yaml に手動で設定された HP が使われます。通常、それらは最適ではありません。
• フェーズ 3 のみでは拡張データセットに対して AutoML を実行できますが、調整済みのベースラインがなければ DEFT ループの反復コストが高くなります（収束が遅くなり、KPI 達成に必要な反復回数が増えます）。

3つすべてを実行すると、AutoML がまず元データに対して低コストで一度調整し、DEFT が妥当な HP で大規模なデータ改善を行い、その後、データがより充実した状態で AutoML が再度調整します。最終的にデプロイする FAR／再現率にとって、3つの中で最も重要なのはフェーズ 3 です。

事前に把握しておくべきコスト

このパイプラインは順次実行されます。合計の実時間は、およそフェーズ 1（N_automl × 1レコメンデーションあたりの学習時間）+ フェーズ 2（M 回のイテレーション × 1イテレーションあたりのコスト）+ フェーズ 3（N_automl × 1レコメンデーションあたりの学習時間）です。

フェーズ 2 ではベースライン学習を別途行いません。フェーズ 1 の最良のチェックポイントを DEFT のベースラインとして再利用するため、ベースラインのコストは追加の再学習ではなく、フェーズ 1 の N_automl 回の学習に含まれます。開始前にこの点をユーザーに伝えてください。通常、フェーズ 2 のイテレーションがコストの大半を占めます（各イテレーションに SDG と再学習が含まれるため）が、単一 GPU のマシンではフェーズ 1 とフェーズ 3 もそれぞれ数時間かかります。分単位の時間を推測するのではなく、ユーザーの環境に基づくジョブごとの見積もり（ユーザーが提示している場合）を使用してください。フェーズごとのコストの内訳は references/pitfalls.md を参照してください。

統合プレフライト — 3つのフェーズに共通する1つのゲート

パイプラインにユーザーゲートは1つだけです。 副作用を伴うあらゆる操作（docker pull、docker login、下流スキルに委任されたジョブ起動の呼び出し、${RESULTS_DIR}/ 以下のファイル変更）の前に、エージェントは、すべての下流スキルのプレフライトを包含する、統合プレフライトサマリーを1つ作成する必要があります。ユーザーの承認後は、3つのフェーズすべてを通じて実行が自律的に進み、以降に対話による一時停止はありません。

ユーザーは、フェーズ間で確認を求められることを明確に望んでいません。DEFT ループ独自のインライン ## Pre-Flight Summary ゲートは、質問ゼロの表示ステップ（すべての値を事前に入力済み）となり、Phases 1 と 3 における tao-run-automl の共有起動前プレフライトも同様です。

ゲートを表示する前に、エージェントはすべての下流プレフライトのセクションを最後まで読み、各セクションで指定された読み取り専用チェックをすべて実行し、その結果をサマリーに示す必要があります。DEFT スキルの ## Pre-Flight に記載されたすべての手順を実行することが必須です。手順を1つでも省略した場合、統合ゲートは無効となり、パイプラインを先に進めてはなりません。サマリーには、次の内容を順に含める必要があります。（1）ワークスペース／ホスト／プラットフォーム／ネットワーク、（2）認証情報の SET／UNSET 状態、（3）解決済みコンテナイメージ URI と PRESENT／MISSING の状態、（4）データセットの表とリークチェック、（5）Phase 1 の設定、（6）Phase 2 の設定（事前シード済みベースラインのソースを含む）、（7）Phase 3 の設定、（8）計算リソースの見積もり、（9）確認文。ゲート通過後は、収集したすべての値を各下流スキルに渡し、質問事項が残らないようにします。ゲート通過後に許可される一時停止は、実行中の安全性に関するハードストップゲート（DEFT の KPI 回帰ゲートなど）のみです。該当する場合は、サマリーに明記してください。

各サマリーセクションに必須の正確な内容（GPU メモリの経験則、DEFT ループのデフォルト値、必須入力の原文を含む）、下流ゲートを抑制するための入力、旧バージョンのスキルバンクで独自の STOP ゲートがハードコードされている場合のフォールバックについては、references/preflight.md を参照してください。

---

Phase 1 — AutoML ベースライン

次の入力で tao-skill-bank:tao-run-automl を呼び出します。

入力	AOI のデフォルト値	備考
network_arch	visual-changenet	DEFT ループが想定するモデルと同じです
train_dataset_uri	<workspace>/train/base/training_set.csv	DEFT が使用を開始するものと同じトレーニングセットです
eval_dataset_uri	<workspace>/train/base/validation_set.csv	ホールドアウトデータです。DEFT の最終レポート用に確保されているため、KPI テストセット（<workspace>/kpi/testing_set.csv）を指定してはなりません
metric	FAR @ 100% recall（推奨）または val_loss	references/pitfalls.md を参照してください。ChangeNet AOI はクラス不均衡であり、val_loss だけではモード崩壊が起こる可能性があります
algorithm	bayesian	計算リソースが限られている場合は LLM-brain または autoresearch
automl_max_recommendations	AOI では 5～10	推奨数を増やすほど HP は向上しますが、計算リソースも線形に増加します
spec_overrides	epochs／batch_size を固定し、オプティマイザー関連の HP のみをスイープします	そうしないと AutoML が長時間トレーニングの領域に入り込み、Phase 2 の予算を超過する可能性があります

スイープ完了後、AutoML の result["best"]["specs"] が最良のハイパーパラメーター辞書です。

Phase 2 への引き継ぎ

Phase 1 から引き継ぐ成果物は、最良の spec と最良の checkpoint の2つです。DEFT のベースラインステップで同じ HP を再トレーニングする代わりに、Phase 1 の出力を使って DEFT のベースライン状態を事前シードし、DEFT をベースライン推論 → 評価 → RCA → イテレーション 1 の順に開始します。4つの手順 — 統合済みの baseline_spec_automl.yaml を書き込む、最良のチェックポイントを ${RESULTS_DIR}/baseline/train/ にコピーする、iterations.baseline.stage_completed == "train" で deft_state.json を初期化する（対応する loop_log.jsonl エントリーも追加する）、その後 DEFT を呼び出す — は、正確なコードとともに references/handoff.md に原文のまま記載されています。ループ内の automl_policy: off はそのまま維持されます。

引き渡し前の品質チェック

最良のチェックポイントをホールドアウトセットで簡易評価します。クラスごとの予測数を確認し（1つのクラスに偏っている場合は、2番目または3番目に良いチェックポイントを評価します）、ゼロショット ChangeNet ベースラインと比較します（AutoML がゼロショットを上回らなかった場合は、その結果を提示して停止します）。references/handoff.md を参照してください。

---

フェーズ 2 — DEFT ループ（通常のトレーニング、フェーズ 1 のベースラインを事前設定）

tao-skill-bank:tao-run-deft-aoi を呼び出します（インターフェースの全容については、その SKILL.md を参照してください）。AOI 以外の用途では、対応する DEFT スキルを呼び出します。引き渡しの形式は同じです。

DEFT ループの baseline-train サブステップはスキップします。 フェーズ 1 では、最良の HP でトレーニングされたチェックポイントがすでに生成されています。また、フェーズ 1 の引き渡し（上記参照）で ${RESULTS_DIR}/baseline/train/ と ${RESULTS_DIR}/deft_state.json が事前に設定されているため、DEFT は baseline inference → evaluate → RCA → iter 1 から再開します。DEFT ループの残りは変更せず実行します。automl_policy: off の不変条件は変更しないでください。

DEFT ループが担当する処理は次のとおりです。

• Pre-Flight Summary の表示ステップ — 新たなユーザー確認ゲートではありません。 Consolidated Pre-Flight（上記）が唯一のゲートです。DEFT のサマリーは、事前設定された baseline/train/ のソースを監査証跡として引き続き表示しますが、すべての入力は統合ゲートですでに収集済みのため、再度確認を求めてはいけません。
• 事前設定されたチェックポイントに対する Baseline inference → evaluate → RCA、および各反復での完全な RCA → routing → SDG → mining → assemble → train サイクル。
• KPI のゲーティングと停止条件、${RESULTS_DIR}/ のレイアウト、deft_state.json、loop_log.jsonl、DEFT_Loop_Report.html。

ループ終了後（KPI を満たした場合、または max_iterations に到達した場合）、deft_state.json から次の 2 つの値を取得します。

• iterations.<best>.best_ckpt_path — ループで最良の通常トレーニングチェックポイント
• 最終反復のラベル N_final — 拡張トレーニング CSV の場所を特定するために使用します

DEFT ループが復旧不能なゲートで強制停止した場合は、フェーズ 3 をスキップしてください。AutoML に渡せる、検証済みの拡張 CSV はありません。

---

フェーズ 3 — DEFT で拡張したデータセットでの AutoML による改善

tao-skill-bank:tao-run-automl を再度呼び出し、拡張トレーニング CSV をトレーニングデータセットとして、前回と同じホールドアウト検証 CSV を使用し、フェーズ 2 の反復で最良だったチェックポイントをウォームスタートとして指定します。

入力	AOI の値
network_arch	visual-changenet
train_dataset_uri	${RESULTS_DIR}/iter${N_final}/dataset/train_combined_iter${N_final}.csv
eval_dataset_uri	フェーズ 1 と同じ（<workspace>/train/base/validation_set.csv）— 公平に比較できるよう条件を揃えます
metric	フェーズ 1 と同じメトリック
algorithm	フェーズ 1 と同じアルゴリズム
automl_max_recommendations	5〜10
初期 spec	<workspace>/specs/baseline_spec_automl.yaml（フェーズ 1 の最良モデル）から開始します。これにより、強力な中心点を基準に探索を改善できます
ウォームスタートチェックポイント	${RESULTS_DIR}/deft_state.json の iterations.<best>.best_ckpt_path — spec_overrides["train"]["pretrained_model_path"] にこのパスを設定します。各フェーズ 3 の推奨設定は、スクラッチからトレーニングするのではなく、フェーズ 2 の最良モデルからファインチューニングします。

ウォームスタートは必須です。ウォームスタートがない場合、各推奨設定はランダム初期化から始まり、再収束までに 10〜20 エポックしか使えません。その結果、フェーズ 3 の val_loss は iter1 と比べて 0.03〜0.05 悪化し、_pick_best のセーフティネットがフェーズ 2 の最良モデルに黙ってロールバックするため、フェーズ 3 の計算リソースが無駄になります。最小の far_pct の反復を選択し、以前の final_automl を除外する具体的な spec_overrides コード、広範囲な探索とのトレードオフ、${RESULTS_DIR}/final_automl/ への出力、さらに iterations.final_automl を介してフェーズ 3 のチェックポイントを DEFT レポートに連携し（_pick_best の性能低下に対するセーフティネットを使用）、prepare_inference_spec.py を再実行する手順については、すべて references/handoff.md に記載されています。

落とし穴と品質チェック

これらは両方の AutoML フェーズに適用されます。エージェントの動作に組み込み、一度貼り付けるだけで済ませないでください。詳細は references/pitfalls.md を参照してください。

• メトリクスの落とし穴（AOI はクラス不均衡です）。 ChangeNet AOI は PASS が圧倒的に多いため、val_loss を使うと、すべてを PASS と予測して再現率がゼロになるモデルへモード崩壊する可能性があります。FAR @ 100%-recall を直接使うか、pred_counts の健全性チェックで val_loss をゲートするか、FAR @ 100%-recall で top-K を決めてください。バランスの取れたタスクや回帰タスクでは、val_loss で問題ありません。
• 実行ごとのばらつき。 AutoML では、同じ設定でもメトリクスが 2～3 倍変動することがあります。最良の結果が次点より不自然に良く見える場合は、仕様を Phase 2 に確定する前に、新しいシードで再実行してください。
• クリーン性（データリーク）。 どちらの AutoML フェーズでも、KPI テストセット（kpi/testing_set.csv）とは別の検証セットを使用します。KPI テストセットは、DEFT の evaluate ステージまで使用しません。Phase 3 では拡張 CSV で学習しますが、Phase 1 と Phase 3 の数値を比較できるよう、同じ検証セットを使用します。
• 計算予算。 フェーズごとの構成は最初に提示し、実行時間の範囲はユーザーがジョブごとの所要時間を提示してから伝えてください。

---

クイックスタート（AOI の実例）

「AOI ワークフローを実行」から新たに開始する場合、エージェントはユーザーに 3 フェーズのメッセージを提示します（Phase 1 の AutoML ベースライン → Phase 2 の DEFT ループ → Phase 3 の AutoML 改良。コストの説明と「続行してよろしいですか？」で締めくくります）。その後、確認を受けたら tao-run-automl（Phase 1）を呼び出し、統合した仕様を書き込み、deft_state.json に事前シードを設定し、必要な入力をすべて事前指定して tao-run-deft-aoi（Phase 2）を呼び出し、さらに tao-run-automl（Phase 3）を再度呼び出します。後続スキルで復旧不能なハードストップのゲートに到達しない限り、以降は確認のために停止しません。その後、経過（ベースライン AutoML の最良結果 → DEFT iter 1 → ... → DEFT iter N_final → Phase 3 の最良結果）を要約します。

ユーザー向けのメッセージ全文と、確認後の正確な呼び出し手順については、references/quick-start.md を参照してください。

AOI 以外の DEFT アプリケーション

同じ 3 フェーズのパターンを他の DEFT スキルにも適用できます。その場合は、network_arch、Phase 2 の DEFT スキル、仕様およびチェックポイントのパス規約、Phase 3 の拡張 CSV のパスを置き換えてください。引き継ぎの形式（Phase 1 で DEFT のベースラインを事前設定する仕様とチェックポイントを出力し、Phase 2 で拡張データセットを出力し、Phase 3 で最終チェックポイントを出力する）は同一です。また、ベースラインをスキップする仕組みは、再開可能なベースライン状態を持つ DEFT 形式のループであれば汎用的に使用できます。references/quick-start.md を参照してください。

---

関連項目

• tao-skill-bank:tao-run-automl — AutoML インターフェース、アルゴリズム、HP の範囲
• tao-skill-bank:tao-run-deft-aoi — DEFT AOI の全ループ（Phase 2 のデフォルト）
• tao-skill-bank:tao-train-visual-changenet — ChangeNet の学習／評価／推論を行う基盤スキル（AutoML と DEFT の両方で使用）
• その他の skills/applications/deft-* スキル — AOI 以外の Phase 2 の対象
• references/preflight.md — 統合された事前チェックゲートの構築
• references/handoff.md — Phase 1→2 の事前シード設定、Phase 2 の品質チェック、Phase 3 のウォームスタートとレポートの配線
• references/pitfalls.md — メトリクス、ばらつき、データリーク、計算予算に関するガイダンス
• references/quick-start.md — 実例メッセージ全文と AOI 以外のバリエーション