tao-run-deft-aoi

スキル：tao-run-deft-aoi

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

実行契約

これは文章形式の手順ではなく、ディスク上の状態に基づくステートマシンとして扱ってください。

1. ユーザーが明示したすべての値を保持してください。epoch 1 は num_epochs=1、iteration 1 は max_iterations=1 を意味します。ヒューリスティックまたは仕様のデフォルト値を適用できるのは、ユーザーが該当パラメーターを指定していない場合に限ります。事前フライト概要には、各実行パラメーターの出所（user、spec、または default）を表示してください。お客様が指定したメトリクス名、演算子、目標値、単位、評価者、制約を保持してください。承認済みの metric_contract を、評価、チェックポイントの選択、完了判定、レポート作成における唯一の基準としてください。
2. ユーザーが概要を承認した後、PYTHON=$(bash scripts/deft_python.sh) を設定し、事前確認で確定した正確な GPU モデル／メモリ、--network-mode の確定値、アクティベーションの出所、選択した絶対パスの Python を渡して、"$PYTHON" scripts/init_deft_state.py により deft_state.json を一度だけ初期化してください。生成された execution_policy は不変の実行状態です。再開時に手作業で作成したり、再初期化したりしないでください。
3. 起動時、コンテキストの圧縮後、各ステージの前、および完了を宣言する前に、"$PYTHON" scripts/deft_context.py --state ... --stage ... を実行してください。永続化された next_stage に加え、状態ファイルの status、current_iteration、iterations.*.status、stage_completed、最新の events エントリーを使って再開してください。アシスタントの文章や、状態に記録されていない成果物から進捗を推測しないでください。
4. DEFT オーバーレイを読んだ後、対応する基盤スキルを呼び出してください。読み取れていない、または欠落しているステージ参照や、失敗したスキル呼び出しを、推測したシェルコマンド、インライン Python、別の出力ツリー、または KPI セットから捏造したデータで置き換えないでください。
5. 初期化後は、インストール／取得／ログイン／コンテナーのコマンドを "$PYTHON" scripts/deft_exec.py --state ... -- <command> 経由で実行してください。エアギャップモードでは外部への通信とインストールが拒否され、オフライン用フラグが挿入され、プルが禁止されます。選択したプラットフォームでも、同等のポリシーを適用してください。
6. 各ステージは必ず "$PYTHON" scripts/commit_stage.py でコミットしてください。このスクリプトは、ステージに必要な入力を検証し、deft_state.json 内の再開用スナップショットと順序付きの events 配列をアトミックに更新します。インライン Python、jq、ヒアドキュメント、エディターを使って状態ファイルを編集しないでください。証拠が却下された場合は修正し、状態を捏造しないでください。evaluate では、メトリクス結果、チェックポイント、推論 CSV、しきい値を commit_stage.py に直接渡してください。実行したステージには、バックエンドの経過時間またはホストタイマーで計測した正の --duration-sec を渡してください。ドキュメントに記載された --skip では 0 を記録できます。負の所要時間は常に却下されます。
7. "$PYTHON" scripts/finalize_run.py が引き継ぎ用成果物を作成し、loop_stop を正常にコミットしたうえで、deft_state.json を新たに読み込み、status == "complete"、iterations.baseline.status == "complete"、および最終イテレーションの status == "complete" を確認してから、ループの完了を宣言してください。チェックポイント、推論 CSV、レポート、またはアシスタントのメッセージだけでは、完了の証拠になりません。

コンテキストの管理

• 必要なタイミングで参照を読み込みます。状態を読み直し、現在のステージで指定されたセクションだけを読んで作業します。 すべての参照や基盤となるスキルを事前に読み込んだり、cat したり、スキルツリーを再帰的に一覧表示したり、現在のコンテキストにすでに含まれている参照を読み直したりしないでください。
• 学習、推論、Docker、SDG の大量の出力はファイルにリダイレクトします。確認するのは末尾 40 行まで、または 1 行のステータス／成果物チェックに限ります。仕様書、状態ファイル、ループログ、生成スクリプト全体を会話に出力しないでください。
• Skill ツールの呼び出しで読み込まれるのはステージの指示であり、バックグラウンドのオーケストレーターが起動するわけではありません。呼び出しが戻ったら、親プロセスですぐに、文書化されたステージを続行します。Skill ツールのプロセスを待つためにスリープしたり、ポーリングしたりしないでください。実際のバックグラウンド Docker 作業では、PID を保存し、30 秒以内の間隔でポーリングします。
• Pre-Flight の開始時に、依存関係を確認する前にネットワークモードを確定します。references/air-gap.md（エアギャップモードの場合）または references/network-bootstrap.md（ネットワーク接続モードの場合）のいずれか一方だけを読みます。エアギャップでの実行時に、ネットワークブートストラップを読み込まないでください。

このスキルを使用する場面

ユーザーが NVIDIA TAO VisualChangeNet / ChangeNet PCB 検査モデルの DEFT AOI 改善ループ全体を実行するようエージェントに依頼した場合に、このスキルを使用します。対象となる工程は、ベースライン評価、RCA、合成欠陥生成、データマイニング、再学習、およびデプロイの可否判定です。KPI 目標を達成するまで繰り返します。

• 「DEFT ループを実行して」
• 「設定した品質指標が目標を満たすまでファインチューニングして」
• 「制約を維持しながら、顧客定義の指標を最適化して」
• 「RCA と合成欠陥を使って、AOI ChangeNet モデルを改善して」
• 「デプロイ KPI が目標を満たすまで学習を繰り返して」

単独の TAO 学習、1 回限りの推論、汎用的な異常生成、RCA のみの分析には、このスキルを使用しないでください。ユーザーがその工程だけを求めている場合は、該当するエージェントを直接使用します。

ベースモデル

このループでは、エンドツーエンドの C-RADIOv2-B または凍結された DINOv3 バックボーンを使用して、NVIDIA TAO Visual ChangeNet の分類を行います。アーキテクチャは specs/baseline_spec.yaml で定義されています。バックボーンのバリアント、ステージング、HF_TOKEN、マウント規則は references/visual-changenet.md で管理します。仕様は常に、ローカルにマウントされたファイルを指します。コンテナのプルは NGC_KEY によって制御されます。SigLIP のマイニングは references/tao-mine-aoi-images.md で管理します。AnomalyGen のアセットとネットワーク／エアギャップの規則は references/tao-generate-anomalies.md と references/air-gap.md で管理します。ベースアセットの一覧はコンテナが管理します。このワークフローでは、--model_sizes 2B を明示的に指定して、ブートストラップで Text2Image 2B を使用します。

AutoML ポリシーの学習

DEFT AOI は、反復的なデータ改善ループ、再トレーニングの頻度、KPI チェックポイントの選択を担います。このワークフローに限り、基盤となる Visual ChangeNet モデルのメタデータで automl_enabled: true が設定されていても、モデルレベルの AutoML は無効にしてください。

automl_policy: off は Visual ChangeNet スキルの呼び出しに渡すワークフロー引数です（親が Skill ツール経由で tao-skill-bank:tao-train-visual-changenet を呼び出す際に渡す値）。TAO spec のフィールドではありません。次の 2 つのケースがあります。

• docker run visual_changenet train -e <spec> を直接実行する場合（このワークフローで実際にインライン実行する方法）：対応は不要です。TAO エントリーポイントはデフォルトで通常のトレーニングを実行します。AutoML は SDK がオーケストレーションする別のコードパスにあります。実質的に、直接実行する docker run はすべて、すでに automl_policy: off になっています。
• SDK によるオーケストレーションでディスパッチする場合（SDK がコマンドを組み立てる Brev／SLURM／k8s）：VisualChangeNetSDK.train(...) または同等のランナー引数に automl_policy: off を渡してください。SDK はこの値を使い、AutoML ラッパーではなく通常のトレーニングコマンドを選択します。

spec YAML に automl_policy や workflow キーを決して追加しないでください。 TAO の Hydra ExperimentConfig スキーマはこれらのキーを認識しないため、次のエラーが発生し、設定のマージ時にトレーニングジョブが失敗します。 Error merging '<spec>.yaml' with schema: Key 'workflow' not in 'ExperimentConfig' これはワークフローレベルでのみ適用するオーバーライドです。モデルのメタデータは変更せず、このポリシーを他のワークフローに適用しないでください。

実行開始時の確認

ユーザーがこのワークフローの実行を希望すると確認したら、どの対応プラットフォームで実行する予定かを尋ねてください。インストール済みのプラットフォームスキル（tao-run-on-docker / -slurm / -kubernetes / -brev、および外部プラットフォームがあればそのスキル）から実行プラットフォームを確認します。コアルータースキルのみが表示されるランタイムでは、skills/platform/tao-run-on-*/SKILL.md のフロントマターを読んでください。

プラットフォームを選択した後、選択したプラットフォームスキルの ## Credentials セクションと references/skill_info.yaml（required_credentials / credential_groups）を読んでください。

認証情報の値を尋ねたり、表示したりしないでください。環境変数が設定されているかどうかだけを確認します（[ -n "$VAR" ] && echo SET || echo UNSET）。未設定の場合は、ユーザーがエクスポートするか、ユーザーが承認した環境ファイル（~/.tao/secrets.env、~/.config/tao/.env、またはユーザーが指定したファイル）に記述できるよう、環境変数名を伝えてください。ファイルは set -a; source /path/to/.env; set +a で読み込みます。実行時にそのファイルが作成または書き込みされることはありません。

エージェントの動作

ユーザーによる確認ゲートは、事前確認の1つだけです。 Pre-Flight Summary （references/preflight.md → Pre-Flight Summary を参照）を表示し、その後 STOP して、ユーザーが「go」「yes」 「looks good」など、明示的に承認するまで待ちます。その承認前に、副作用を伴うステップ （docker run、トレーニング、SDG、${RESULTS_DIR}/ 配下の変更）を開始してはいけません。 仕様の読み込み、ファイルの一覧表示、docker image inspect、サマリーテーブルへの情報入力は問題ありません。 「自律的」とは、このゲートの後の動作を指し、前の動作を指すものではありません。 ユーザーの最初のプロンプトが 緊急に聞こえても（「すぐ実行して」「進めて」など）、ゲートを省略してはいけません。 承認前にユーザーが確認する必要がある成果物は、サマリーそのものです。

ゲート通過後は、スキルが完全に自律して動作します。 確認を求めず、ループ全体を実行します。 ステップの途中で一時停止してはいけません。「続けてもよいですか？」とは尋ねず、そのまま続行します。 回復不能なエラーでステップが失敗した場合、またはハードストップゲートが作動した場合に限り停止します。 ユーザーが進捗を把握できるよう、各ステップの節目で1行の状況更新を表示します。

自動モードが必須です。 ゲート通過後のループでは、副作用を伴う呼び出し（docker run、${RESULTS_DIR}/ への書き込み）が 継続的に発生します。自動承認／権限確認バイパスモードが有効でない場合、最初のプロンプトで停止します。 承認前に自動モード（shift+tab）を有効にするよう、Pre-Flight Summary でユーザーに伝えてください。

ブロッカーからの復旧。 ユーザー確認ゲートの前に、deft_python.sh を使って、インストール済みの ホストインタープリターから完全なものを選択します。該当するものがない場合は、すでに選択されている ネットワークモードのリファレンスだけに従います。エアギャップモードでは、パッケージマネージャーのコマンドを 実行せずにハードストップします。ネットワークを有効にしたブートストラップは references/network-bootstrap.md に分離されています。 references/air-gap.md のネットワークモードごとの分岐に従い、許可された取得とディレクトリ作成は 承認後の作業として記録するか、エアギャップモードでステージ済みのアセットを検証します。承認後は、 回復可能なブロッカーを自分で解消し、作業中だった Pre-Flight のステップから再開します （<blocker> cleared → resuming step N）。 自分で解消できない場合に限り停止します（ワークスペース／仕様／CSV／認証情報の不足、 プールが空、データリーク）。修正は新たなユーザー確認ゲートではありません。

ゼロ以外の終了コードに関するルール。 変更のない失敗コマンドを繰り返してはいけません。また、試行錯誤で文書化されていない CLI／モジュールのパスに 切り替えてはいけません。最終エラーブロック（コンテナーのバナーだけではありません）を読み、読み込まれたステージの リファレンス／基盤となるスキルと照合し、根拠に基づいて1か所修正してから、文書化された検証を再実行します。 リファレンスに失敗への対処方法が記載されていない場合は、独自に縮小したワークフローを試すのではなく、 status=error を記録して停止します。

計画の改訂。 最初のサマリーを表示した後に実行パラメーターが変更された場合（ユーザーによる制限時間の設定、エポック数の上書き、max_iterations の変更など）は、 必ず Pre-Flight を再実行し、更新したサマリーを表示してから続行します。

ワークフロー

次の順序でループを実行します（詳細は references/pipeline-and-state.md → パイプライン + ステージ実行を参照してください）。

1. 事前確認。 references/preflight.md のチェックをすべて実行します。ワークスペース、仕様、CSV、チェックポイント、コンテナイメージを解決します。自力で解決できない入力が不足している場合に限り、ハードストップします（「## エージェントの動作」→ ブロッカーの解消を参照してください）。
2. ベースライン。 deft_state.json の iterations.baseline.stage_completed == "train" がすでに成立し、best_ckpt_path が既存のファイルを指している場合（上流の automl-deft-pipeline がフェーズ 1 の AutoML の最良モデルで事前設定します。フェーズ 1 → フェーズ 2 の引き継ぎを参照してください）、train のサブステップをスキップし、事前設定されたチェックポイントに対して inference -> evaluate から再開します。それ以外の場合は、tao-skill-bank:tao-train-visual-changenet スキルを呼び出して train -> inference -> evaluate を実行します。承認済みの契約と評価器を使用して評価します（references/metric-contract.md を参照してください）。いずれの場合も、その後 tao-skill-bank:tao-analyze-gaps-visual-changenet を呼び出して rca を実行します。DEFT ループ固有の引数については、まず references/visual-changenet.md、references/metric-contract.md、references/tao-analyze-gaps-visual-changenet.md を読んでください。
3. 反復。 各反復で、max_iterations に達するまでパイプラインのステップ 1～7 を実行します。ステップ間で deft_state.json を再度読み込み、stage_completed の値から続行してください。状態全体を出力してはいけません。
4. KPI 目標に達するか max_iterations に達したら、対応する理由を指定して "$PYTHON" scripts/finalize_run.py を実行し、停止します。ハードストップとなる失敗はエラーとしてコミットし、成功した loop_stop として再分類してはいけません。
5. 自動でレンダリングします。 scripts/init_deft_state.py が初期の results/DEFT_Loop_Report.html を書き出します。その後、成功した commit_stage.py の呼び出しごとに、scripts/render_report.py で実装された決定論的なレポートフックによってレポートが更新されます。そのため、親コンテキストが飽和している場合でも、loop_stop のコミットによって最終レポートが生成されます。フックがエラーを報告した場合は、指定されたプレゼンテーション入力を修正したうえで、"$PYTHON" scripts/render_report.py --results-dir "${RESULTS_DIR}" を直接実行してください。レポート HTML を手書きしてはいけません。

すべてのパイプラインステージは親コンテキスト内で直接実行します。基盤となる tao-skill-bank:* スキルを Skill ツールから直接呼び出し、そのうえで対応する references/*.md ファイルに記載された DEFT ループ規約を適用してください。対応する Skill ツールを利用できないものの、Docker、スキルのソースツリー、ステージ参照モジュールが存在する場合は、references/scripts-and-agents.md に記載された直接コンテナのフォールバックを使用してください。最初のフォールバックステージの前に、execution_path=direct-container をトランスクリプトに記録し、各フォールバックステージについて、対応する基盤スキル名と実際に使用した直接コマンドを正確に記録してください。同じ deft_state.json、アーティファクト、スクリプトによるレポートの規約を維持してください。HTML のレンダリングは委任しません。

同梱スクリプトの使用

各ツール呼び出しで PYTHON=$(bash <skill_root>/scripts/deft_python.sh) を設定し、 続けて "$PYTHON" <skill_root>/scripts/<name>.py を使用します。パス引数はすべて、 事前に絶対ホストパスへ解決してください。各ステージの前に deft_context.py を、 外部実行には deft_exec.py を、状態の書き込みにはすべて commit_stage.py を使用します。 スクリプトの呼び出し、自動レポートフック、ステージのマッピング、直接コンテナの フォールバック、パスの不変条件については、references/scripts-and-agents.md を参照してください。

ステージ参照モジュール

各パイプラインステージは、バンク内の基盤スキルのいずれかに対応します。一致する references/*.md ファイルでは、そのスキルの汎用的な手順に DEFT ループの規約（マウント、出力ディレクトリ、commit_stage.py の引数）を追加します。現在のステージに関連するセクションだけを読み、その後、Skill ツールまたは文書化された直接コンテナの代替手段を使ってスキルを呼び出してください。すべてのステージ参照を事前に読み込んではいけません。 参照ファイルが見つからない場合は、処理を中止して、プラグインを再インストールするようユーザーに依頼してください。ステージ→参照→スキル→所有権の全対応表は references/scripts-and-agents.md → ステージ参照モジュール にあります。ステージは次のとおりです。train／evaluate（references/visual-changenet.md）、anomalygen（references/tao-generate-anomalies.md）、rca（references/tao-analyze-gaps-visual-changenet.md）、routing（references/tao-route-visual-changenet-samples.md）、data_mining（references/tao-mine-aoi-images.md）。

パスの規則（不変条件）。 ホスト側のアーティファクトの絶対パスは ${RESULTS_DIR} 配下に記録してください。ChangeNet の直接コンテナでは、 "$WORKSPACE:/data/workspace" と "$RESULTS_DIR:/results" をマウントしてください。仕様では /results/baseline/<stage> または /results/iterN/<stage> を使用します。その他のステージでは、 それぞれの参照モジュールで必須とされるワークスペースのマウントを維持してください。実行 ディレクトリを /results/iterN に再マッピングしてはいけません。

データ、事前確認、パイプライン、状態の参照情報

トピック	参照先	内容
エアギャップの有効化とオフライン実行	references/air-gap.md	グローバルモードのトリガー、優先順位、禁止されているネットワーク操作、ステージング済みアセットの要件、事前確認の証跡
独自データの使用、データ契約、出力レイアウト、拡張プール	references/data-layout.md	公開 AOI データセットがないこと、<workspace> の入力ツリー全体、ChangeNet で必須となる CSV の 4 列スキーマ、${RESULTS_DIR}/ の出力ツリー、2 つのソースからなるマイニングプールの表
顧客指標の契約と評価器アダプター	references/metric-contract.md	主要指標のスキーマ、比較方向、評価器の JSON、制約、evaluate のコミット、互換性の動作
事前確認、デフォルト値、事前確認サマリーテンプレート、実行時間の見積もり	references/preflight.md	順序が定められた 10 項目の事前確認、必須入力の max_iterations、すべてのデフォルト値、事前確認サマリー表全体と入力用コマンド、反復ごとの実行時間の見積もり
パイプラインの手順、状態、ステージの実行、レポート、実行時の動作	references/pipeline-and-state.md	ベースラインの事前シード／学習スキップのロジック、7 つの反復パイプライン手順、deft_state.json のスナップショットとイベントのスキーマ、ステージ後の確認、反復ごとの HTML レンダリング、ループ終了時の手順
同梱スクリプト、レポートフック、ステージモジュール、AutoML の落とし穴	references/scripts-and-agents.md	利用可能なスクリプトの表、決定論的なレポートレンダラーとコミット後フック、ステージ参照モジュールの表、パス規則の不変条件、AutoML ポリシーの仕様に関する落とし穴

必須入力 — max_iterations。 デフォルト値はありません。指定されていない場合はユーザーに確認し、指定を得るまでは事前確認を先に進めてはいけません。ユーザーが代わりに時間制限を指定した場合は、references/preflight.md に記載された反復ごとの実行時間を使って max_iterations の推定値に換算し、確認のためその推定値を提示してください。その他の実行パラメーターにはデフォルト値があります。デフォルト値があるパラメーターについては、決して質問してはいけません。デフォルト値の一覧と、ユーザーが唯一の確認ゲートで承認する事前確認サマリーの全体は references/preflight.md にあります。

ゲート

完全な Pre-Flight（references/preflight.md）を実行し、Pre-Flight の概要を出力してから、唯一のユーザー承認ゲートで停止します。承認後、references/pipeline-and-state.md に詳述されているベースライン（事前シード／学習スキップのロジックを含む）と、7 ステップの反復パイプラインを実行します。

次の場合はハードストップし、自動再試行を行わないでください。いずれかのステージが status=error である場合、学習データと検証データのリークがある場合、マイニングプールが存在しないか行数が 0 の場合、CSV の存在確認に失敗した場合、サイレントドロップが発生した場合、AMP の割り当てに不一致がある場合、PAIDF と互換性のない AnomalyGen のファインチューニング済みチェックポイントがある場合、AnomalyGen Guardrail のチェックポイントが存在しない場合、または SDG のログでスクリーニングが無効と示されている場合です。KPI 目標の達成、max_iterations への到達、または復旧不能なゲートの発生のいずれかでループを停止します。どの終了経路でも、commit_stage.py を通じて loop_stop をコミットし、その後、references/pipeline-and-state.md のループ終了シーケンスに従います。