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 間の仕様の引き渡し、拡張データセットを使った 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)

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

• フェーズ 1 → フェーズ 2：仕様ファイルと最良チェックポイントを引き渡します。ブリッジはフェーズ 1 の HP を specs/baseline_spec.yaml にディープマージし、チェックポイントを ${RESULTS_DIR}/baseline/train/ にコピーして、deft_state.json に事前入力します。これにより DEFT はベースライントレーニングをスキップし、ベースライン推論 → 評価 → RCA → イテレーション 1 から再開します。DEFT は通常のトレーニングのままです（automl_policy: off は維持されます）。
• フェーズ 2 → フェーズ 3：トレーニング CSV（train_combined_iter${N_final}.csv）とイテレーション最良チェックポイントを引き渡します。各レコメンデーションの train.pretrained_model_path にチェックポイントを設定することで、フェーズ 3 はフェーズ 2 の最良モデルからファインチューニングします。フェーズ 3 の最良チェックポイントが成果物となります。フェーズ 3 の後に別途再トレーニングを行うことはありません。

両方の引き渡しの正確な手順、コード、DEFT がこの引き渡しを尊重する仕組みについては、references/phase-handoffs.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 × レコメンデーションあたりのトレーニング時間）＋フェーズ 2（M 回の反復 × 反復あたりのコスト）＋フェーズ 3（N_automl × レコメンデーションあたりのトレーニング時間）。

フェーズ 2 では独立したベースライントレーニングはありません。フェーズ 1 の最良チェックポイントを DEFT のベースラインとして再利用するため、ベースラインのコストは追加の再トレーニングではなく、フェーズ 1 の N_automl 回のトレーニングに含まれます。開始前にこの点をユーザーに伝えてください。通常はフェーズ 2 の反復が引き続きコストの大部分を占めます（各反復に SDG と再トレーニングが含まれるため）が、フェーズ 1 とフェーズ 3 も、それぞれ単一 GPU のマシンで数時間かかります。分単位の所要時間を推測するのではなく、ユーザーの環境についてのジョブごとの見積もり（ある場合）を使用してください。フェーズごとの項目の内訳については、references/pitfalls-and-quality-checks.md の**「計算予算」**を参照してください。

---

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

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

ユーザーは、フェーズ間で確認を求められることを明確に望んでいません。DEFT ループ内の ## Pre-Flight Summary ゲートは、（すべての値がこの統合ゲートで事前に提供される）質問なしの表示ステップになります。Phase 1 と Phase 3 における tao-run-automl の共通起動プリフライトも同様です。

サマリーを表示する前に、エージェントはすべての下流スキルのプリフライトセクションを開いて全文を読み、そこに指定された読み取り専用チェックをすべて実行し、各チェックの結果を提示する必要があります。サマリーには必須のセクションが9つあります（ワークスペース／ホスト／プラットフォーム／ネットワーク、認証情報の状態、コンテナーイメージ、データセット表、Phase 1 の設定、Phase 2 の設定、Phase 3 の設定、コンピュートの見積もり、確認行）。ゲートの後は、収集した値を渡して、下流の対話型ゲートをすべて抑制します。ゲート通過後に一時停止が許されるのは、下流スキルで回避できない実行中のハードストップ安全ゲートのみです。

references/consolidated-preflight.md を参照してください。プリフライトで読むべきセクションの全リスト、必須の DEFT ## Pre-Flight 実行、9セクションのサマリーに含める正確な内容、ゲート抑制のための値の受け渡し、スキルバンクのバージョンがまだゲート抑制に対応していない場合の手順が記載されています。

---

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	ホールドアウトデータです。KPI テストセット（<workspace>/kpi/testing_set.csv）を使ってはいけません。このセットは DEFT の最終レポート用に予約されています
metric	FAR @ 100% recall（推奨）または val_loss	references/pitfalls-and-quality-checks.md のメトリクスの落とし穴を参照してください。ChangeNet AOI はクラス不均衡で、val_loss だけではモード崩壊を起こす可能性があります
algorithm	bayesian	コンピュートに制約がある場合は LLM-brain または autoresearch
automl_max_recommendations	AOI では 5～10	推奨数が多いほど HP は向上しますが、コンピュート量も線形に増加します
spec_overrides	エポック数／batch_size を固定し、オプティマイザー関連の HP のみをスイープします	そうしないと、AutoML が長時間のトレーニング設定を選び、Phase 2 の予算を超過する可能性があります

スイープが完了すると、AutoML の result["best"]["specs"] が最良のハイパーパラメーター辞書になります。

Phase 2 への引き継ぎ

Phase 1 では、最良のspecと最良のチェックポイントという2つの成果物を引き継ぎます。DEFT のベースラインステップで同じ HP を使って再トレーニングするのはコンピュートの無駄です。代わりに、Phase 1 の出力で DEFT のベースライン状態を事前に設定し、DEFT がベースライン推論 → 評価 → RCA → iter 1 の順で開始するようにします。これは、spec のマージ結果を書き込む → baseline/train/ に事前設定する → ベースラインが完了済みの状態で deft_state.json を初期化する → DEFT を呼び出す、という4段階のブリッジです。その後、最良のチェックポイントの品質を確認します（クラスごとの予測件数を確認し、ゼロショット ChangeNet と比較します）。

逐語的な手順1～4（cp コマンドと deft_state.json の事前設定コードを含む）および品質チェックのチェックリストについては、references/phase-handoffs.md を参照してください。

---

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

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

DEFT ループの baseline-train サブステップはスキップされます。 フェーズ 1 では、最適な HP でトレーニングされたチェックポイントがすでに生成されており、フェーズ 1 の引き継ぎ（references/phase-handoffs.md を参照）によって ${RESULTS_DIR}/baseline/train/ と ${RESULTS_DIR}/deft_state.json が事前に設定されているため、DEFT はベースライン推論 → 評価 → RCA → iter 1 から再開します。DEFT ループの残りは変更せずに実行されます。automl_policy: off の不変条件は変更しないでください。

DEFT ループが担当するもの：Pre-Flight Summary の表示ステップ（新たにユーザーの承認を求めるものではありません。上記の統合 Pre-Flight が唯一の承認ステップです。DEFT のサマリーには事前設定された baseline/train/ のソースが引き続き記録され、再度確認を求めてはなりません）、事前設定されたチェックポイントでのベースライン推論 → 評価 → RCA、各イテレーションでの RCA → ルーティング → SDG → マイニング → アセンブル → トレーニングの一連の処理、KPI の判定と停止条件、および ${RESULTS_DIR}/ のレイアウト（deft_state.json、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
初期仕様	<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 エポックのみとなります。その結果、val_loss は iter1 に比べて 0.03～0.05 悪化し、_pick_best のセーフティネットによって、ひそかに iter の勝者へロールバックされます。出力先は ${RESULTS_DIR}/final_automl/ です。この探索で得られた勝者チェックポイントが、パイプラインの納品物となります。探索後、フェーズ 3 のチェックポイントを deft_state.json の iterations.final_automl に登録し、prepare_inference_spec.py を再実行して、引き継ぎ時にそのチェックポイントが認識されるようにします（フェーズ 3 で性能が悪化した場合は、ループの最良チェックポイントにフォールバックします）。

ウォームスタートが必須である理由とトレードオフの詳細、spec_overrides の選択コード、フェーズ 3 の出力を DEFT レポートに戻す正確な 2 ステップの設定方法、性能悪化時の安全上の注意については、references/phase-handoffs.md を参照してください。

落とし穴と品質チェック

これらは両方の AutoML フェーズに適用されます。エージェントの動作に組み込んでください。一度貼り付けるだけでは不十分です。詳細は references/pitfalls-and-quality-checks.md に記載されています。要点は次のとおりです。

• メトリックの落とし穴 — AOI にはクラス不均衡があります。 ChangeNet AOI データセットは PASS が大半を占める（90% 以上）ため、val_loss の最良モデルがモード崩壊したモデルである可能性があります。FAR @ 100%-recall を直接優先するか、pred_counts の健全性チェックで val_loss を検証するか、FAR @ 100%-recall で上位 K 個を評価してから選択してください。バランスの取れたタスクや回帰タスクでは、val_loss で問題ありません。
• 実行ごとのばらつき。 AutoML では、同じ HP 設定でも 2～3 倍のばらつきが生じることがあります。最良モデルが次点のモデルより不自然なほど優れている場合は、仕様を Phase 2 に確定する前に、新しいシードで再実行してください。
• データのクリーン性（データリーク）。 どちらの AutoML フェーズでも、KPI テストセット（<workspace>/kpi/testing_set.csv）とは別の検証セットを使用します。このテストセットは DEFT の最終レポート用に確保されています。Phase 3 では拡張 CSV で学習しますが、検証セットは同じものを使用するため、Phase 1 と Phase 3 の数値を比較できます。
• 計算予算。 Phase 1 は N_automl × per-rec train、Phase 2 は M_iter × (RCA + SDG + mining + retrain)（通常、最も大きな予算が必要です）、Phase 3 は拡張データセットで N_automl × per-rec train です。実行時間の見積もりを伝える前に、ユーザーにジョブあたりの所要時間を確認してください。

---

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

「AOI ワークフローを実行」から新たに開始する場合、エージェントはユーザーに 3 フェーズの計画（Phase 1 AutoML ベースライン → Phase 2 DEFT ループ → Phase 3 AutoML 改良）を提示し、総コストの構成（最初に追加のベースライン再学習はなく、最後にも追加の再学習はありません）を説明し、実行時間の見積もりに必要なユーザーの実行あたりの所要時間を尋ねて、承認を待ちます。確認を得た後は、Phase 1 を呼び出し、統合した仕様を書き込み、deft_state.json を事前に初期化し、すべての入力を事前に指定して DEFT ループを呼び出した後、Phase 3 を呼び出します。後続のスキルで復旧不能なハードストップが発生しない限り、それ以上の中断はありません。最後に、ベースライン AutoML の最良モデル → DEFT iter 1 → ... → DEFT iter N_final → Phase 3 の最良モデルという推移を要約します。

顧客に提示するメッセージブロックの完全な文面と、確認後の正確な呼び出し手順については、references/quick-start-example.md を参照してください。

AOI 以外の DEFT の適用

同じ 3 フェーズのパターンを、他の DEFT スキルにも適用できます。次の項目を置き換えてください。

• network_arch を該当するモデルに置き換える
• Phase 2 で呼び出す DEFT スキル
• 「最良 HP 仕様ファイル」と「最良 HP チェックポイント」のパス規約を、対象の DEFT スキルが想定するものに置き換える
• Phase 3 の拡張 CSV のパスを、対象の DEFT スキルが生成するものに置き換える

ハンドオフの形式は同一です。Phase 1 は 仕様 + チェックポイント を出力し（チェックポイントは DEFT のベースラインを事前に初期化します）、Phase 2 は両方を受け取って拡張データセットを出力し、Phase 3 は最終チェックポイントを出力します。Phase 1 → Phase 2 のベースラインスキップ機構は汎用的です。再開可能なベースライン状態を公開する DEFT 形式のループであれば、同じ方法で初期化できます。

---

関連項目

• 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/consolidated-preflight.md — 単一ゲートの事前チェックの全体
• references/phase-handoffs.md — 両方のハンドオフ、ベースラインの事前初期化、Phase 3 のウォームスタートの完全な記載
• references/pitfalls-and-quality-checks.md — メトリックの落とし穴、実行ごとのばらつき、データリーク、計算予算
• references/quick-start-example.md — 顧客向けの実例メッセージ