tao-run-deft-aoi

スキル：tao-run-deft-aoi

このスキルを使用するタイミング

NVIDIA TAO VisualChangeNet / ChangeNet の PCB 検査モデルに対して、ベースライン評価、RCA、事前生成済み合成欠陥の取り込み、データマイニング、再トレーニング、KPI 目標を満たすまでのデプロイ判定を含む、DEFT AOI の改善ループ全体をエージェントに実行させたい場合に、このスキルを使用します。この EA バリアントでは、AnomalyGen をインラインで実行しません。顧客が NG/OK のペアを別途事前生成し、<workspace>/augmentation/anomalygen/ 以下に配置します。

• 「DEFT ループを実行して」
• 「recall=100% で FAR < 0.1% になるまでファインチューニングして」
• 「RCA と合成欠陥を使って AOI ChangeNet モデルを改善して」
• 「false accept rate が目標を満たすまでトレーニングを反復して」

単独の TAO トレーニング、単発の推論、汎用的な異常生成、RCA のみの分析には、このスキルを使用しないでください。ユーザーがそのステップだけを依頼した場合は、該当するエージェントを直接使用してください。

ベースモデル

このループでは、NVIDIA C-RADIOv2-B バックボーンを使用してエンドツーエンドでファインチューニングする、NVIDIA TAO Visual ChangeNet の分類モデルを使用します。アーキテクチャは specs/baseline_spec.yaml で定義されており、このファイルを信頼できる唯一の情報源とします。事前学習済みウェイトはすべて HuggingFace から取得します（HF_TOKEN が必要です）。NGC_API_KEY_* はコンテナのプルのみを制御します。ChangeNet バックボーンの解決と、model.backbone.pretrained_backbone_path に対するステージ済みファイル／HF URL のフォールバックは、references/visual-changenet.md の管轄です。k-NN マイニング用の SigLIP は、references/tao-mine-aoi-images.md の管轄です。この EA バリアントでは、AnomalyGen 側のチェックポイントは必要ありません。 事前生成済みの合成ペアは <workspace>/augmentation/anomalygen/{reconstructed_image,original_image}/ から直接取り込みます。詳しくは references/pipeline.md のパイプラインのステップ 3 を参照してください。

AutoML トレーニングポリシー

DEFT AOI は、反復的なデータ改善ループ、再トレーニングの実施頻度、KPI チェックポイントの選択を管理します。このワークフローでは、基盤となる Visual ChangeNet モデルのメタデータで automl_enabled: true が設定されていても、モデルレベルの AutoML を無効にしてください。ベースラインと反復的な再トレーニングを含む、Visual ChangeNet のすべてのトレーニングステージを、実行時オーバーライド automl_policy: off（通常のトレーニング）を指定して実行します。これはワークフローレベルのオーバーライドであり、モデルのメタデータを変更しないでください。また、このポリシーを他のワークフローに適用しないでください。

起動時の確認事項

ユーザーがこのワークフローの実行を確認したら、使用予定の対応プラットフォームを尋ねてください。次を使用してプラットフォームの選択肢を生成します。

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

プラットフォームを選択した後、次を実行します。

${TAO_SKILL_BANK_PATH:-~/tao-skills-external}/scripts/list_tao_platforms.py \
  --skill-bank ${TAO_SKILL_BANK_PATH:-~/tao-skills-external} \
  --platform <platform> --format text

そのプラットフォームに関連する認証情報と、選択したワークフローで必要となるモデル固有の認証情報のみを尋ねてください。

エージェントの動作

ユーザーによる確認が必要なのは、実行前の確認の1回だけです。 実行前サマリー（references/pre-flight.md の Pre-Flight Summary を参照）を表示してから停止し、ユーザーが「go」、「yes」、「looks good」など、明示的に承認するまで待ってください。その承認前に、副作用を伴う処理（docker run、トレーニング、SDG、${RESULTS_DIR}/ 以下の変更）を開始しないでください。仕様の読み込み、ファイルの一覧表示、docker image inspect、サマリーテーブルの作成は問題ありません。「自律的」とは、この確認の後の動作を指し、確認前の動作を指すものではありません。 ユーザーの最初の依頼が緊急に聞こえる場合（「すぐ実行して」、「進めて」など）でも、確認を省略しないでください。承認前にユーザーが確認する必要がある成果物は、サマリーそのものです。

確認後は、スキルが完全に自律的に動作します。 確認を求めずにループ全体を実行してください。ステップ間で一時停止しないでください。「続けてもよいですか？」と尋ねず、そのまま続行してください。回復不能なエラーが発生した場合、または強制停止条件に該当した場合に限り、停止してください。進捗を把握できるよう、各ステップの節目で1行のステータス更新を表示してください。

ワークフロー

次の順序でループを実行します。詳細は、各ステップで参照するファイルに記載されています。

1. 事前チェック。 references/pre-flight.md に記載されたすべてのチェックを実行します。ワークスペース、仕様、CSV、チェックポイント、コンテナイメージを確認し、事前生成プールを一度ステージングして、事前チェックの概要を出力します。入力が不足している場合は、そこで停止します。
2. ベースライン。 deft_state.json の iterations.baseline.stage_completed == "train" がすでに設定され、best_ckpt_path が既存ファイルを指している場合（上流の tao-run-automl-deft-pipeline は、フェーズ 1 の AutoML の勝者からこれらを事前設定します。フェーズ 1 からフェーズ 2 への引き継ぎを参照）、train サブステップをスキップし、事前設定されたチェックポイントに対して inference -> evaluate から再開します。それ以外の場合は、tao-skill-bank:tao-train-visual-changenet スキルを呼び出して train -> inference -> evaluate を実行します。いずれの場合も、その後 tao-skill-bank:tao-analyze-gaps-visual-changenet を呼び出して rca を実行します。DEFT ループ固有の引数（マウント、出力ディレクトリ、deft_state.json の更新）については、まず references/visual-changenet.md と references/tao-analyze-gaps-visual-changenet.md を読んでください。
3. 反復。 max_iterations まで、references/pipeline.md のパイプラインのステップ 1～7 を実行します。各ステップの間に、ディスクから results/loop_log.jsonl の末尾と results/deft_state.json を読み直します。正とするのはディスク上の内容です。
4. 停止。 KPI 目標の達成、max_iterations への到達、またはハードストップ条件（サイレントドロップ、AMP 割り当ての不一致、train/val のリーク）のいずれかで停止します。ハードストップ時に自動で再試行してはいけません。
5. レポートの生成。 各反復の完了後とループ終了時に、agents/reporter.md に従って reporter サブエージェントを起動し、results/DEFT_Loop_Report.html を生成します。ステージごとの生成は行いません。各ステージですでに loop_log.jsonl に 1 行追加されており、末尾を監視するユーザーにはこれで十分です。HTML レポートには 1 反復分の状態が含まれます。反復ごとに 1 回生成することで、ループあたりのトークンコストをステージ数ではなく反復数に対しておおむね線形に保てます。インラインで生成してはいけません。

すべてのパイプラインステージは親コンテキスト内でインライン実行します。親は Skill ツールを通じて tao-skill-bank:* スキルを直接呼び出し、対応する references/*.md ファイルに従って DEFT ループの規約を適用します。委譲する作業は HTML レポートの生成のみです。これには新しいコンテキストで reporter サブエージェントを使用し、親のコンテキストが逼迫しているためにループ終了時のレポート生成が気付かれないまま省略されることを防ぎます。

デフォルト値

ユーザーが指定していない場合にのみ設定します。デフォルト値があるパラメーターについて、質問してはいけません。すべてのデフォルト値は references/pre-flight.md に記載されています。

• max_iterations: 3 — top_k_per_target: 5 — min_similarity: 0.9（コサイン類似度のしきい値）
• training_epochs: specs/baseline_spec.yaml の num_epochs。指定がなければ 20
• ワークスペースのルート: ユーザープロンプト。指定がなければ ~/workspace

参照マップ

参照先	内容
references/pre-flight.md	Pre-Flight チェック 1〜11、デフォルト一覧全体、Pre-Flight Summary のテンプレートと唯一のユーザー確認ゲート。ワークスペース／仕様／CSV／チェックポイント／画像の解決、.env と versions.yaml による認証情報の解決、GPU メモリの妥当性確認（48GB では batch_size ≤ 16、24GB では ≤ 8）、一括の事前生成ステージング、リークチェック。
references/pipeline.md	パイプラインのステップ 1〜7 と Augmentation Pool。RCA → ルート設定（事前生成の単一バケットを使用した全ギャップの昇格、filter_by_label: false、AG のファンアウトなし）→ キャッシュ済みマニフェストの読み込み → k-NN マイニング（top_k_per_target、min_similarity 0.9、SDG によるバイパスなし）→ CSV の組み立て → 検証 → ファインチューニング（automl_policy: off）。ソースプールの組み立て、イテレーションごとのマイニング上限、14 列／必須 4 列の CSV スキーマ、ベースラインの学習スキップロジック。
references/stage-execution.md	使用可能なスクリプトの表、ステージ参照モジュール（ステージ→スキルのマップ）、パス規則の不変条件、SKILL／INLINE／AGENT のステージタイプ、ステージ後のチェック、レポート成果物、agents/reporter.md の起動契約。
references/state-logging.md	deft_state.json と loop_log.jsonl の契約、ステージごとに 1 エントリー、ディスクから seq = last_seq + 1 を取得（ディスクを正とし、echo／インライン jq は使用しない）、イテレーションごとおよびループ終了時のレンダリング頻度、ループ終了時のシーケンス（log_stage → align_token_usage → レンダリング → prepare_inference_spec）、停止条件。
references/prepare-for-inference.md	best_model.json と best_model_inference_spec.yaml の契約、および利用側のワークフロー。
references/REPORT_RENDERING.md	agents/reporter.md が従うテンプレートの記入ルール。
references/SCRIPT_USAGE.md	run_script() と直接の python 実行の使い分け、絶対パスの解決。

各ステージの開始時に該当する参照ファイルを読み、その後に作業を進めてください。参照ファイルが見つからない場合は停止し、プラグインを再インストールするようユーザーに依頼してください。汎用的なシェルコマンドで代用しないでください。

データ契約

入力（絶対パスでない限り、すべて <workspace> 以下のパス）：

<workspace>/
├── .env                                     # NGC_API_KEY (nvcr.io/* image pulls), HF_TOKEN (HuggingFace pre-flight pulls). No AnomalyGen credentials required — this EA variant ingests pre-generated pairs.
├── specs/baseline_spec.yaml                 # ChangeNet train/eval spec
├── train/base/
│   ├── training_set.csv                     # seed training rows; ChangeNet 14-column siamese schema
│   └── validation_set.csv                   # held-out rows; checked for leakage against every train CSV
├── kpi/
│   ├── images/                              # KPI test images (real data only — no generated images here)
│   └── testing_set.csv                      # labels live in the CSV
├── augmentation/
│   ├── mining_pool/
│   │   ├── mining_pool.csv                  # append-only production-line samples; paths relative to this dir
│   │   └── images/                          # source images referenced by mining_pool.csv (e.g. *_SolderLight.jpg)
│   └── anomalygen/                          # customer-supplied pre-generated synthetic pairs (this EA variant does not run AnomalyGen)
│       ├── reconstructed_image/             # NG images (will become ChangeNet input_path); flat dir of *.jpg or *.png
│       ├── original_image/                  # OK partner images, same stems as reconstructed_image/ (will become ChangeNet golden_path)
│       └── defect_spec.jsonl                # OPTIONAL — one entry per defect_type if defect-type accounting is wanted in deft_state.json
│                                            # Stems in reconstructed_image/ and original_image/ must match 1-to-1; extensions may differ.
└── results/run_<YYYYMMDD_HHMMSS>/           # created/resumed by this workflow (= ${RESULTS_DIR})

ChangeNet CSV スキーマ（VCN）。 必須列：input_path、golden_path、label、object_name（シャム型変更検出器のため、golden_path のない行は使用できません）。存在する場合は、boardname、スコア、来歴フィールドを保持してください。TAO は画像の完全なパスを {images_dir}/{input_path}/{object_name}_{light}{image_ext} として構築します。input_path はファイルではなくディレクトリです。

出力レイアウト

<workspace> からの相対パス：

results/run_<YYYYMMDD_HHMMSS>/               # = ${RESULTS_DIR}
├── deft_state.json                          # current resume snapshot (schema: references/deft_state.json)
├── loop_log.jsonl                           # append-only stage log; single source of truth
├── DEFT_Loop_Report.html                    # re-rendered after every stage by agents/reporter.md
├── best_model.json                          # inference handoff metadata (see references/prepare-for-inference.md)
├── best_model_inference_spec.yaml           # ready-to-run TAO inference spec built from training config
├── iter${ITER}_summary.md                   # ≤300-word per-iteration summary
├── synth_pool/                              # built ONCE at Pre-Flight step 10 via scripts/prestage_pregen.py
│   ├── manifest.json                        # paths + counts for the loop to reference
│   ├── images/synth_{ng,ok}/                # ChangeNet-staged pre-gen pairs (single copy, shared across iters)
│   ├── sdg_rows.csv                         # 14-col + provenance + filepath; the SDG half of source_pool
│   ├── source_pool.{csv,parquet}            # real (mining_pool) + sdg unified pool with provenance
│   ├── source_embeddings.parquet            # written only when --embed-with-siglip was passed to prestage_pregen.py
│   └── source_embed.log                     # data-services log for the source embedding (if run)
├── baseline/
│   ├── train/                               # TAO train output: model_epoch_<EEE>_step_<SSS>.pth × N, status.json, experiment.yaml, train.log
│   ├── inference/{best_val,latest}/         # per-checkpoint inference.csv + KPI plots from scripts/analyze_kpi.py
│   └── rca_results/<TS>/                    # kpi_gaps.parquet, threshold.txt, weak_samples_breakdown.txt
└── iter${ITER}/
    ├── routing_results/<TS>/                # mining_gaps.parquet, anomalygen_gaps.parquet, routing_summary.txt
    ├── anomalygen/                          # per-iter bookkeeping (just records the synth_pool/manifest.json path)
    │   └── ingest_summary.json              # per-iter audit: which synth_pool manifest was reused, counts at iter start
    ├── mining_filter/
    │   ├── mining_pool.csv                  # top-K-per-target k-NN survivors from synth_pool/source_pool (synth + real subject to same filter)
    │   ├── knn_summary.csv                  # candidate_count, kept_count, rejected_count, similarity_threshold=0.9
    │   ├── target_embeddings.parquet        # embeddings of weak-target images (per-iter — targets change each iter)
    │   └── mining_summary.txt               # per-label breakdown emitted by mining container
    ├── dataset/
    │   ├── train_combined_iter${ITER}.csv
    │   └── train_combined_iter${ITER}_provenance.csv  # source ∈ {base_train, previous_iter_train, mining_pool}
    ├── train/                               # TAO train output for iter${ITER}
    ├── inference/{best_val,latest}/
    └── rca_results/<TS>/                    # next iteration's RCA reads inference/{best_val|latest}/inference.csv

以前の統合 CSV の行には、過去のすべての寄与がすでに含まれています。イテレーション N+1 は、再び train/base/training_set.csv からではなく、train_combined_iter${N}.csv と新しい mining_filter/mining_pool.csv から組み立ててください。

安全性とゲート

• ユーザー確認ゲートは 1 つだけです。 references/pre-flight.md の Pre-Flight Summary が唯一の確認ポイントです。副作用を伴うステップを実行する前に停止し、明示的な承認を待ってください。承認後は自律的に進めます。
• パス規則。 すべてのステージで、${RESULTS_DIR}/iter${ITER}/ 以下の絶対ホストパスに書き込んでください。output: /results/... を指定する設定や、<workspace> の外部を指すパスは拒否してください。references/stage-execution.md の不変条件を参照してください。
• ディスクを正とします。 各ステージの実行前に、loop_log.jsonl の末尾と deft_state.json を読み直してください。scripts/log_stage.py を使ってステージごとに loop_log.jsonl へエントリーを正確に 1 件追加してください（echo／インライン jq は使用しないでください）。references/state-logging.md を参照してください。
• 自動再試行しないハードストップ： 事前生成ディレクトリの欠落／空／未ペア、mining_pool.csv の欠落または 0 行、中間実行中の事前生成データの変更、train/val のリーク（イテレーション中および組み立て後のチェック）、サイレントドロップ、AMP の割り当て不一致、CSV 検証の失敗、参照ファイルの欠落。
• SDG でバイパスしないでください。 合成行にも実データの行と同じ k-NN を適用します。この EA バリアントのループでは、SDG／AnomalyGen コンテナを起動しません。