physical-ai-defect-image-generation

Physical AI 不良画像生成ワークフローオーケストレーター

目次

• サポート対象のフロー
• 曖昧さの解消（完全な表は references/disambiguation.md にあります）
• ステップ 0：フローとクックブックの選択、入力の収集
• 共通の前提条件（詳細版は references/preconditions.md にあります）
• フローの手順（各フローの項目と詳細は references/flows/ にあります）
• OSMO のモニタリング
• サポートファイル

AOI（Automated Optical Inspection）データセット向けの不良画像生成、拡張、ラベリングのエンドツーエンドオーケストレーションです。各フローには、すべてのステップを非対話形式で連結する標準の OSMO ワークフロー YAML が assets/configs/ にあります。assets/cookbooks/ のユースケース別クックブックには、PCBA の usd2roi／画像編集設定と、PCBA、金属表面、ガラス検査向けの AnomalyGen トレーニング設定があります。このスキルではフローの選択、データの受け渡し、送信コマンドを管理します。各コンポーネントの内部処理については、それぞれの SKILL.md を参照してください。

サポート対象のフロー

フロー	エントリーポイント	OSMO YAML	ステップ	ユースケース
Day 0 — テクスチャ不良	CAD シーン USD（pcba_target.yaml がクックブックに付属）	texture_defect_generation_day0.yaml	usd2roi（scan_grid ＋ セルごとの ROI クロップ）→ 画像編集による拡張（nvidia/Qwen-Image-Edit-NVPCB-OVSL2SL）→ ファインチューニングまたはパススルー → 推論（AnomalyGen のラベル付けをインラインで実行、欠品を含む）	PCBA
Day 0 — 良品画像 (usd2roi + Image-Edit)	CAD シーン USD ＋ 基板ごとの pcba_target.yaml / day0_image.yaml / day0_crop.yaml	good_image_generation.yaml	usd2roi-render（scan_grid ＋ セルごとの ROI クロップ）→ Qwen Image-Edit（OVSL2SL 外観転送）	PCBA クリーン画像セット（ChangeNet の良品半面、ファインチューニング用の陽性例、実写画像とのペアリング）
Day 0 — 構造不良	CAD シーン USD ＋ 基板ごとの pcba_target.yaml	structural_defect_generation.yaml	isaac-render（姿勢不良：shift / tombstone / sideflip）＋コンポーネントごとのクロップ（単一ポッド）→ Qwen Image-Edit（OVSL2SL 照明転送。姿勢の形状は維持）	PCBA 姿勢不良セット、ChangeNet の不良半面
Day 1 — 推論＋ラベリング（実写画像との位置合わせ、デフォルト）	CAD 由来の USD ＋実際の PCBA 写真（どちらも datasets/pcb/assets に付属）	texture_defect_generation_day1_real_alignment.yaml	usd2roi の Day 1 レンダリング → MI 位置合わせ → ROI ごとのクロップ → yq-render 設定 → ファインチューニングまたはパススルー → 推論（AnomalyGen のラベル付けをインラインで実行）	PCBA Day 1 のデフォルト。 usd2roi がサポートする任意の基板の AOI 生スクリーンショット
Day 1 — 推論＋ラベリング（手動 ROI）	事前撮影済みのクリーン画像 ＋ ROI マスク（NGC アーティファクトまたはユーザーのアップロード）	texture_defect_generation_day1_manual_roi.yaml	yq-render 設定 → ファインチューニングまたはパススルー → 推論（AnomalyGen のラベル付けをインラインで実行）	金属表面、ガラス（USD／実写画像フローなし）。PCBA では、事前撮影済み ROI を使った実験をユーザーが明示的に求めた場合に限ります
ファインチューニングのみ	ラベル付きの異常 URL アーティファクト	finetune.yaml	yq-render 設定 → ファインチューニング（validate_dataset → prep_testcase → torchrun）	すべてのユースケース。Day 0 または Day 1 用のチェックポイントを生成します。<dig_url_root>/datasets/<usecase>/raw に生のトレーニングデータが必要です（assets/configs/setup/setup_<usecase>.yaml を参照）。

すべてのフローは OSMO 上で実行されます。Day 0 のフローには image_edit_endpoint が必要です（Qwen Image-Edit OVSL2SL の既存 URL、または references/nim/ からのローカルデプロイ）。ファインチューニングのみのフローでは外部エンドポイントは不要です。

ユーザーの欠陥クラスに適したワークフローを選択する

欠陥クラス	ワークフロー	仕組み
クリーン／良好／スキャングリッド／normal_img + cad_mask のペア	good_image_generation.yaml	usd2roi-render + Qwen Image-Edit
テクスチャ欠陥（はんだブリッジ、傷、変色）および部品欠落（AnomalyGen がネイティブに処理するものであり、構造欠陥ではありません）	texture_defect_generation_day0.yaml	Qwen Image-Edit + AnomalyGen AMP/SDG
構造／姿勢の欠陥（墓石、ずれ、側面反転）	structural_defect_generation.yaml	IsaacSim による姿勢摂動
実画像での Day 1 推論 + ラベリング	texture_defect_generation_day1_real_alignment.yaml（PCBA のデフォルト）または texture_defect_generation_day1_manual_roi.yaml（金属／ガラスの場合。事前にキャプチャした ROI の使用／アライメントのスキップをユーザーが明示的に求めた場合に限り PCBA でも使用）	usd2roi による Day 1 の位置合わせ（real-alignment）または直接推論（manual-ROI）

ChangeNet のゴールデン／欠陥ペア：同じ --set name= を指定して good_image_generation.yaml + structural_defect_generation.yaml を送信します（2 件送信してペアにする規約）。

Day 0 と Day 1 の後続処理の構成は共通です：Jinja 条件で制御される finetune-job（use_pretrained_checkpoint=true の場合は省略）に続いて anomaly-infer が実行されます。Day 0 ではその前に usd2roi-render + augment-image-edit が追加されます。Day 1 は <dig_url_root>/datasets/<usecase>/raw から開始します。各ステージの詳細については、それぞれのフローの手順ガイドをご覧ください。

ユーザーの意図 → パラメーターの対応

すべての OV フローは 2 段階です：crop_max_emit=N は最終的なセルごとのクロップ数（ステージ 2）の上限を設定し、render_patches=N はスキャングリッドの生パッチ数（ステージ 1）の上限を設定します（各パッチから複数のクロップが生成されます）。「N 枚の画像を生成」を render_patches=N に自動的に対応付けてはいけません（ステージが違います）。structural_defect_generation.yaml には crop_max_emit がありません（コンポーネントごとにクロップ 1 つのため、render_patches を使用します）。また、texture_defect_generation_day1_real_alignment.yaml にもありません（cookbook の crop.classes ホワイトリストで絞り込みます）。全パラメーターの表、スモークテストのレシピ、デフォルト値、注意事項については references/knob_mapping.md をご覧ください。

構造欠陥のサイズ設定（crop_max_emit パラメーターはありません）

構造欠陥の出力は render_patches に対して非線形です。フレーム数を 2 倍にしてもクロップ数は 2 倍ではなく約 1.6～1.7 倍になります。crop_max_emit（効果なし）や render_patches=0（失敗します）は使用しないでください。検証済みの生成数表と目標サイズの計算式については、references/flows/structural_defect_generation.md の §「出力サイズの設定」をご覧ください。「N 枚の画像を生成」のように曖昧な依頼には、AskUserQuestion を通じて調整用の表を提示してください。

---

曖昧さの解消：確定する前に曖昧な依頼を確認する

指定が不十分なプロンプト（「画像を何枚か生成して」「PCBA フローを実行して」「欠陥を作って」など）を、フロー／ユースケース／パラメーターの対応付けを黙って仮定して解決してはいけません。意図が曖昧な場合は、送信する前にいったん止まり、AskUserQuestion を使って候補となる解釈（相互に排他的な 2～4 個の選択肢）を提示してください。結果を左右する選択事項を明確にします：どのフローか、どのユースケースか、枚数はどのステージの数か、ファインチューニングかパススルーか。

確認不要の確定済みデフォルト：PCBA Day 1 → real-alignment、基板 → 0603_H100、image-edit エンドポイント → ローカルクラスターサービス（references/nim/）、use_pretrained_checkpoint=true、Day 1 real-alignment の default_spatial_dependency=cad（CAD マスクを利用できない場合に限り free にフォールバックします。references/flows/texture_defect_generation_day1_real_alignment.md をご覧ください）。

dig_url_root だけは例外です。黙ってデフォルトを適用してはいけません。 初回（メモリーに記録がない場合）は、送信／osmo data upload／preflight_urls.sh の実行前に、必ず AskUserQuestion を通じてユーザーに確認してください。s3://osmo-workflows/dig は確認用の候補であり、自動選択してはいけません（そこに保存すると約 80 GB 以上になります）。以降の実行では、記憶した値を黙って再利用できます。ステップ 0 とメモリールール（§4）をご覧ください。

トリガーの全一覧、質問文の作成方法、および質問しない例外については、references/disambiguation.md をご覧ください。曖昧な依頼に対する AskUserQuestion の選択肢を組み立てる前に読み込んでください。

ステップ 0：フロー、クックブックを選択し、入力を収集する

このステップの前に、依頼が曖昧な場合（例：「画像を生成して」「PCBA フローを実行して」「欠陥を出して」）、いったん停止し、上記の曖昧さ解消用チートシートを実行してください。AskUserQuestion を使って解釈候補を提示し、ユーザーに選んでもらいます。ユーザーが実際に選択していない、重要な前提となるデフォルトを自動で選ばないでください。

初回利用時の確認

このユーザーのメモリーに記録がない場合は、事前確認／osmo／kubectl／osmo data upload を実行する前に、最初に確認する設定に関する質問をすべて、1 回の AskUserQuestion 呼び出しで尋ねてください。回答をメモリー（§4）に保存してから、次に進みます。以下を含めてください。

• dig_url_root — 必ずユーザーに確認し、自動で選択しないでください。確認用の候補として s3://osmo-workflows/dig を提示してください。それ以外の場合は、ユーザーが独自の OSMO 対応ストレージプレフィックスを指定します。約 80 GB 以上のデータはここに保存されます。以前に確認済みの値をメモリーから呼び出す以外に、回避手段はありません。
• デフォルトの OSMO --pool — osmo profile list → pool.accessible から候補を提示します。
• Pod テンプレートの確認 — osmo config show POD_TEMPLATE が 403 を返す場合に限ります（正確な質問は §2 を参照）。
• 画像編集エンドポイント — Day 0 のみ：オプション A（既存の URL）またはオプション B（ローカル NIM をデプロイ）。

以降の会話では、メモリーからこれらの値を読み込み、質問せずに使用します。フローごとの選択（ユースケース、チェックポイントかファインチューニングか、ボード、調整項目）は毎回確認します。以下を参照してください。

事前チェックの順序（初回ゲートの後）

§1 preflight_credentials.sh → §2 preflight_pod_template.sh → §3 preflight_urls.sh <flow> <usecase> → §4 実行スタンプを生成します。実行頻度：§1 と §2 は会話ごとに一度だけのゲートで、会話をまたいでメモリーにキャッシュされます（references/preconditions.md の §4a を参照）。メモリーに検証済み／ユーザー確認済みと記録されている場合はスキップしてください。§3 は送信のたびに実行します（フローによって異なります）。§4 はエージェントの担当です。送信ごとに新しい $STAMP を使用してください。

Pod テンプレートの適用は 2 層で行います。送信前の preflight_pod_template.sh ゲート（§2）と、すべての OV およびトレーニングタスクで Pod 内で実行するランタイム事前チェック（/usr/share/nvidia/nvoptix.bin がない場合、または /dev/shm が 16 GiB 未満の場合は即時失敗）です。§2 を通過したにもかかわらずランタイムチェックが失敗した場合、テンプレートがパッチで変更されています。physical-ai-infrastructure-setup-and-resilient-scaling に案内してください。認証情報／URL アーティファクトが不足している場合は、まず setup/setup_<case>.yaml と setup/setup_pretrained.yaml を送信することを提案してください。

次に、1 つのメッセージでユーザーに確認します。フローごとの選択肢のみを尋ねてください（上記の初回ゲートですでに dig_url_root、プール、Pod テンプレート、エンドポイントの設定を確認済みです。これらはメモリーから取得してください）。

1. ユースケース — PCBA（Day 0 + pcb クックブックを使用）、金属表面（Day 1 + metal_surface クックブックを使用）、ガラス（Day 1 + glass クックブックを使用）、またはカスタムですか？
2. チェックポイントはありますか？ — ある場合（use_pretrained_checkpoint=true）、<dig_url_root>/models/<usecase> を使用し、checkpoint_step を指定してください。ない場合は、<dig_url_root>/datasets/<usecase>/raw からファインチューニングします。
3. Local-NIM プールの容量確認（Day 0 Option B のみ）— kubectl apply の前に、physical-ai-infrastructure-setup-and-resilient-scaling を使って Total Capacity を確認してください。Total Capacity < 2 の場合、NIM と DIG を同時に実行できません。ユーザーに GPU を追加するか Option A に切り替えるよう依頼してください。image_edit_model は常に nvidia/Qwen-Image-Edit-NVPCB-OVSL2SL を使用し、汎用の qwen-image-edit は使用しません。
4. ユーザー設定をメモリーに保存 — 初回ゲートの後（および、文書化されたデフォルトから外れる送信を行った後）、重要な選択（dig_url_root、OSMO プール、デフォルトのボード、画像編集エンドポイント、Pod テンプレートの状態、osmo-admin のロール）を保存してください。image_edit_model（固定値。保存すると設定がずれる可能性があります）や一時的な状態（STAMP、単発の anomaly_types_json）は決して保存しないでください。全項目は **references/preconditions.md §4a「Memory rules」**を参照してください。新しい会話の開始時には、関連するメモリーを読み込み、設定を表に出さず適用してください。

質問する前に、該当するフローのリファレンスを確認してください。ほとんどの値には適切なデフォルトがあります。Day 1 のルーティング：PCBA のデフォルトは real_alignment です。金属／ガラスには USD フローがないため、常に manual_roi を使用します。アライメントをスキップしたいと明示的に依頼されない限り、PCBA で「手動か real-alignment か」をユーザーに尋ねないでください。

共通の前提条件（すべてのフロー）

クイックリファレンスです。詳細版：references/preconditions.md。

1. OSMO 認証情報とトークン — 会話ごとに1回実行します。ワークスペースに .env がある場合は、まず読み込んでください（set -a; . ./.env; set +a）。これにより HF_TOKEN がエクスポートされます。scripts/preflight_credentials.sh を実行します。正式な確認項目は、OSMO の認証情報 hf-token がプロビジョニングされていることです（イメージは nvcr.io/nvidia/ で公開されているため、レジストリの認証情報は不要です）。外部への接続が制限されたシェルでは --no-probe を指定します。references/preconditions.md §1 を参照してください。

2. Pod テンプレート — 会話ごとに1回実行し、会話をまたいでメモリーにキャッシュします（Step 0 §6 を参照）。メモリーにクラスターの確認済み／ユーザー確認済み／409 によるスキップが記録されている場合はスキップします。それ以外の場合は scripts/preflight_pod_template.sh を実行し、終了コードに応じて分岐します（0=確認済み／1=インフラスキルでパッチ適用／2=ユーザーに確認（HTTP 403）／3=スキップ（HTTP 409）／4=環境を修正）。分岐の詳細とプロンプトは references/preconditions.md §2 を参照してください。

3. 必須 URL アーティファクト — 送信の前に毎回確認します。DIG_URL_ROOT=<dig_url_root> scripts/preflight_urls.sh <flow> <usecase> [variant] を実行します。不足がある場合は、まず該当する setup/setup_<case>.yaml と setup/setup_pretrained.yaml を送信してください（OSMO のセットアップワークフロー）。references/setup.md を参照してください。**問題を回避するためにアセットをローカルにダウンロードしないでください。セットアップで認証情報のエラーが発生した場合は、ユーザーに修正を依頼し、OSMO で再送信してください。**フローごとのチェックリスト：

   フロー	ユースケース	<dig_url_root> 配下の必須 URL アーティファクト
   Day 0 — テクスチャ欠陥	PCBA	models/pretrained、models/pcb、datasets/pcb/raw、datasets/pcb/assets
   Day 0 — 良品画像	PCBA	datasets/pcb/assets のみ
   Day 0 — 構造欠陥	PCBA	datasets/pcb/assets のみ
   Day 1	金属表面	models/pretrained、models/metal_surface、datasets/metal_surface/raw
   Day 1	ガラス	models/pretrained、models/glass、datasets/glass/raw
   Day 1 実写真アライメント	PCBA	Day 1 PCBA と datasets/pcb/assets
   ファインチューニングのみ	任意	models/pretrained、datasets/<usecase>/raw

   組み込みの usecase 値は pcb、metal_surface、glass です。references/preconditions.md §3 を参照してください。

4. 名前の付与 — 送信の前に毎回 $STAMP=$(cat /proc/sys/kernel/random/uuid | cut -c1-8) を再生成し、--set name=<flow>-$STAMP を指定します。本番用 YAML には name のデフォルト値がありません。references/preconditions.md §4 を参照してください。

5. ガラスのケース（UC3）— Roboflow zip — setup_glass.yaml の場合のみ必要です。まず mobile_screen.zip を OSMO URL プレフィックスにアップロードし、--set uc3_zip_url_root=<prefix> を指定します。詳細な手順：references/setup.md §「ガラスのケース（UC3）」。

---

フローの手順

各フローの詳しい手順（グループ図、前提条件、送信コマンドのバリエーション、データの受け渡し、ステージごとのトラブルシューティング）は、references/flows/ にあります。この会話でまだ実行していないフローを送信する前に、エージェントは該当するファイルを読む必要があります。

フロー	ワークフロー YAML	手順
Day 0 — テクスチャ欠陥（PCBA）	assets/configs/texture_defect_generation_day0.yaml	references/flows/texture_defect_generation_day0.md
Day 0 — 良品画像（PCBA）	assets/configs/good_image_generation.yaml	references/flows/good_image_generation.md
Day 0 — 構造欠陥（PCBA）	assets/configs/structural_defect_generation.yaml	references/flows/structural_defect_generation.md
Day 1 — 推論＋ラベル付け（実写真アライメント、デフォルトは PCBA）	assets/configs/texture_defect_generation_day1_real_alignment.yaml	references/flows/texture_defect_generation_day1_real_alignment.md
Day 1 — 推論＋ラベル付け（手動 ROI、金属／ガラス＋PCBA の実験）	assets/configs/texture_defect_generation_day1_manual_roi.yaml	references/flows/texture_defect_generation_day1_manual_roi.md
ファインチューニングのみ	assets/configs/finetune.yaml	references/flows/finetune.md

フローフロー間の不変条件

• use_pretrained_checkpoint=true（デフォルト）→ models/<usecase> に対するパススルーです。false に設定すると、Pod 内に finetune-job グループが挿入されます（Pod 内で yq により Cookbook にパッチを適用し、事前送信レンダリング手順はありません）。
• Day 0 ではセルごとの crop/<MATERIAL>/<cell>/... ツリーを出力します。Day 1 では USD に登録された ROI ごとのクロップを出力します。構造フローではコンポーネントごとのフラットなクロップを出力します。
• ユースケースごとに提供される checkpoint_step と anomaly_types_json のデフォルト値については、references/preconditions.md §「提供されているチェックポイントと anomaly_types_json のデフォルト値」を参照してください。

---

OSMO のモニタリング

このスキルで osmo workflow submit、osmo workflow query、または osmo workflow logs のアクションを実行する前に、references/monitoring.md を読み込んでください。 ポーリング間隔、タスクステータスの解釈、ログ取得をエスカレーションするしきい値、障害分類の振り分け、ユーザーに提示する情報と黙って再試行する情報が定義されています。送信後の監視ループやステータスの概要を記憶から組み立てないでください。各会話でこれらのアクションを初めて実行する際に、必ず再読してください。

osmo workflow query <workflow_id> --format-type json | jq '{status, tasks: [.groups[].tasks[] | {name, status, exit_code}]}'
osmo workflow logs <workflow_id> -t <task_name> -n 200
osmo data download <dig_url_root>/runs/<name>/anomaly ./output/anomaly-<name>/

モニタリングの手順：references/monitoring.md。出力の取得：references/output_retrieval.md。表示：references/output_rendering.md。注意事項：references/troubleshooting.md。

---

応答テンプレート

「プラン／レシピを見せて」というリクエストには、レシピの途中で内容が途切れないよう、以下のラベル付きセクションを含めて最終応答を作成してください。

ワークフロー： <flow name> → assets/configs/<yaml>

事前チェック： scripts/preflight_credentials.sh；scripts/preflight_urls.sh <0|1|finetune> <usecase> [variant]

<dig_url_root> 配下の必須 URL アーティファクト： 選択したフローに応じて「共通の事前条件」§3 に従って列挙してください。

送信コマンド：

STAMP=$(cat /proc/sys/kernel/random/uuid | cut -c1-8)
osmo workflow submit assets/configs/<yaml> --pool <pool> \
  --set name=<flow>-$STAMP dig_url_root=<root> usecase=<usecase> \
        image_edit_endpoint=<endpoint> image_edit_model=nvidia/Qwen-Image-Edit-NVPCB-OVSL2SL \
        checkpoint_step=<step> 'anomaly_types_json=<types>'

モニタリング： 送信を実行する前に references/monitoring.md を読み込み、osmo workflow submit がワークフロー ID を返した後は、そのポーリング間隔とログ取得のしきい値に従ってください。

出力先： <dig_url_root>/runs/<flow>-$STAMP/anomaly/（フローごとの上書き設定については、各フローの手順を参照してください）。

---

補足ファイル

ワークフロー YAML、Cookbook、スクリプトの表、リファレンス、評価、コンポーネントスキルを含む全ファイル一覧は、references/contents.md にあります。トップレベルのディレクトリ：assets/configs/、assets/cookbooks/、scripts/、references/、evals/。