tao-train-optical-inspection

光学検査

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

Siamese ネットワークを使用した欠陥検出のための光学検査です。画像ペアを比較して、製造上の欠陥、異常、品質上の問題を検出します。

事前学習済みの Siamese 重みには、train.pretrained_model_path を設定してください。

TAO Deploy の TensorRT アクション（gen_trt_engine、TensorRT の evaluate、TensorRT の inference）については、まず references/tao-deploy-optical-inspection.md をお読みください。親の PyT コンテナーでは optical_inspection gen_trt_engine は公開されていません。TensorRT エンジンの生成は Deploy 専用です。Deploy の仕様テンプレートは、このスキルの references/ フォルダーにある spec_template_deploy_*.yaml というプレフィックスのファイルです。

データクラスのスキーマ

生成された TAO Core スキーマは schemas/<action>.schema.json にパッケージ化され、利用可能なアクションは schemas/manifest.json に記載されています。各スキーマからは、スキーマ最上位の default フィールドに基づく references/spec_template_<action>.yaml も生成されます。AutoML の有効化は、モデルレイヤーの references/skill_info.yaml にある automl_enabled で宣言されます。あるアクションで AutoML を実行するには、schemas/<action>.schema.json と references/spec_template_<action>.yaml が存在し、解析可能である必要があります。automl_default_parameters、automl_disabled_parameters、デフォルト値、最小値／最大値の範囲、列挙値、オプションの重み、数式条件、依存関係、よく使われるパラメーターには、パッケージに含まれる選択済みアクションのスキーマを使用してください。実行時に ~/tao-core があることを前提としないでください。メンテナーはスキルバンクのパッケージ化前に、スキーマとテンプレートを再生成します。

トレーニングアクションのポリシー

このモデルでは、モデルレイヤーで AutoML が有効になっています。トレーニング段階のリクエストを処理する前に、references/skill_info.yaml を読み込み、明示的な automl_policy 値、またはユーザーのワークフローリクエストから実行時の設定を決定してください。デフォルトでは automl_policy: on を使用し、新しい起動プロンプトで提示するのは on と off のみです。「AutoML をオフにする」「AutoML を無効にする」「HPO を使わない」「通常のトレーニング」などの表現は、今回の実行に限り automl_policy: off として扱ってください。automl_policy: on、automl_enabled: true、および schemas/train.schema.json と references/spec_template_train.yaml の両方がパッケージに含まれている場合、デフォルトで、このモデルの skill_dir を指定して tao-skill-bank:tao-run-automl 経由で train アクションを実行してください。データセット、仕様、出力ディレクトリー、GPU／プラットフォーム設定、親チェックポイント、automl_policy に関するワークフロー／アプリケーション側の設定は維持してください。直接モデルをトレーニングするのは、automl_policy: off の場合、またはパッケージに train のスキーマ／テンプレートがない場合に限ります。スキーマがない場合は、AutoML は有効ですが、スキーマが生成されるまではこのモデルで実行できないことを報告してください。

evaluate、inference、export、Deploy フローなどのトレーニング以外のアクションは、このモデルのスキル内で実行します。実行ごとの automl_policy 設定でモデルのメタデータが変更されることはありません。

トレーニング要件

• データセットタイプ： optical_inspection
• フォーマット： default
• AutoML トレーニング指標： val_acc、direction=maximize
• 単独評価指標： test_acc、direction=maximize

アクションごとのデータセット要件

アクション	スペックキー	ソース	ファイル	リスト?
evaluate	dataset.test_dataset.images_dir	eval_dataset	images.tar.gz	No
evaluate	dataset.test_dataset.csv_path	eval_dataset	dataset.csv	No
inference	dataset.infer_dataset.images_dir	inference_dataset	images.tar.gz	No
inference	dataset.infer_dataset.csv_path	inference_dataset	dataset.csv	No
train	dataset.train_dataset.images_dir	train_datasets	images.tar.gz	No
train	dataset.train_dataset.csv_path	train_datasets	dataset.csv	No
train	dataset.validation_dataset.images_dir	eval_dataset	images.tar.gz	No
train	dataset.validation_dataset.csv_path	eval_dataset	dataset.csv	No
train	dataset.test_dataset.images_dir	eval_dataset	images.tar.gz	No
train	dataset.test_dataset.csv_path	eval_dataset	dataset.csv	No

images.tar.gz は転送用アーティファクトです。ステージング/展開後、 dataset.*_dataset.images_dir は、golden/ と CSV で使用されるボードディレクトリを 直接含む内側のディレクトリを指している必要があります。

dataset.csv の仕様

Optical Inspection ローダーは、列名を使って CSV を読み込み、各シャム比較の両側を次のように構成します。

<images_dir>/<input_path>/<object_name>_<lighting><image_ext>
<images_dir>/<golden_path>/<object_name>_<lighting><image_ext>

input_path と golden_path には絶対パスも指定でき、ローダーは絶対パスの場合に images_dir を置き換えて使用します。ステージング後も可搬性が保たれるため、相対ディレクトリを推奨します。どちらのパス列にもファイル名を含めず、object_name に照明サフィックスや拡張子を含めないでください。

列	型	必須	使用可能な値と意味
input_path	文字列のディレクトリパス	はい	images_dir からの相対パス、または絶対パスで指定する、基板／撮影対象のコンポーネントディレクトリです。
golden_path	文字列のディレクトリパス	はい	images_dir からの相対パス、または絶対パスで指定する、ゴールデン／参照コンポーネントディレクトリです。
label	文字列	はい	大文字小文字を区別して完全一致する PASS は、欠陥なし（クラス 0）を意味します。それ以外の空でない欠陥名は、欠陥あり（クラス 1）を意味します。例：missing、shift、excess_solder、lifted_lead、polarity、tombstone、upside down。ローダーが欠陥として誤って処理するため、pass は無効です。
object_name	文字列のファイル名のベース部分	はい	C1018@1 などのコンポーネント識別子です。ディレクトリ、_SolderLight、.jpg は含めないでください。ローダーはこの列を文字列として扱うため、数値のような識別子も文字列形式のまま保持されます。

追加のメタデータ列は使用できますが、このローダーでは無視されます。空の値は無効です。実際の本番環境の構成に基づく完全な行の例を示します。

input_path,golden_path,label,object_name
690-5G190-0510-001P1/AOI_B/FXLH_690-5G190-0510-001P1_30332_P_AOI_B_20230317130332/PerComponent,golden/images/690-5G190-0510-001P1BOT/,PASS,C1018@1

標準の 4 照明構成では、各行につき 8 個のファイルが必要です。

<images_dir>/
├── golden/images/690-2G133-0210-000BOT/
│   ├── R821@1_LowAngleLight.jpg
│   ├── R821@1_SolderLight.jpg
│   ├── R821@1_UniformLight.jpg
│   └── R821@1_WhiteLight.jpg
└── 690-2G133-0210-000/AOI_B/<capture>/PerComponent/
    ├── R821@1_LowAngleLight.jpg
    ├── R821@1_SolderLight.jpg
    ├── R821@1_UniformLight.jpg
    └── R821@1_WhiteLight.jpg

次の 3 つの選択フィールドは、互いに一致している必要があります。

• input_map のキーは、ファイル名に使われる照明サフィックスと完全に一致します。現在のローダーの動作では、YAML キーの挿入順に処理され、整数値ではソートされません。値が連続し、順序が一致するようにしてください（0..N-1）。
• num_input は input_map のエントリ数と一致する必要があります。ローダーはすべてのキーを開くため、値が一致しなくてもファイルリストは制限されず、テンソル／エクスポートの形状不一致が発生します。
• concat_type: linear は、キーの順序に沿って入力を画像の高さ方向に積み重ねます。128×128 の入力が 4 つの場合、512×128 のテンソルが生成されます。grid_map は無視されます。
• concat_type: grid では、num_input が偶数であり、grid_map.x * grid_map.y == num_input である必要があります。配置はキーの順序に沿った行優先です。標準の 2 x 2 マップでは、LowAngle は左上、Solder は右上、Uniform は左下、White は右下になります。

データセットに *_SolderLight.jpg のみが実際に含まれる場合は、num_input: 1、input_map: {SolderLight: 0}、concat_type: linear を使用してください。3 種類のバリエーションがない場合に、4 つの入力を宣言しないでください。

学習、評価、推論の前に、spec と同じデータセット設定を使って、パッケージに含まれる事前チェックを実行してください。

python3 skills/models/tao-train-optical-inspection/scripts/validate_dataset.py \
  --csv /data/optical-inspection/train/dataset.csv \
  --images-dir /data/optical-inspection/train/images \
  --num-input 4 \
  --concat-type grid \
  --grid-x 2 --grid-y 2

カスタムマップを使う場合は、YAML のキー順に --input-map LIGHT=INDEX を繰り返し指定し、spec の --image-ext を渡してください。バリデーターは、列の欠落、PASS の大文字小文字の誤り、解決できない行ディレクトリ、各 CSV 行番号とともに照明ファイルの欠落をすべて報告します。2 行のパススタブフィクスチャは tests/fixtures/dataset/valid/ にあります。これは仕様を検証するもので、PCB の学習データではありません。

このスキルバンクからは、公開済みの Optical Inspection サンプルデータセットは見つかりません。製品または組織のデータセット所有者から変換済み AOI データを入手し、コンテナにマウントされたパスにステージングしてください。コミット済みのバリデータフィクスチャをモデルの学習に使用しないでください。

一般的な Spec のオーバーライド

データソースのオーバーライドはすべてのアクションで必須です。エージェントは、必ず上記のアクション別データセット要件表に基づいてデータソースのパスを構成し、spec_overrides に含める必要があります。

TRAIN_ROOT = "/data/optical-inspection/train"
EVAL_ROOT = "/data/optical-inspection/eval"
INFERENCE_ROOT = "/data/optical-inspection/inference"

以下は、データの所有者からデータを取得してステージングした後の、コンテナ内のマウントポイントの例です。ダウンロード先ではありません。

train（必須データソース）：

{
    "train.num_epochs": 30,
    "train.checkpoint_interval": 10,
    "train.validation_interval": 10,
    "train.num_gpus": 1,
    "dataset.batch_size": 8,
    "dataset.train_dataset.images_dir": f"{TRAIN_ROOT}/images",
    "dataset.train_dataset.csv_path": f"{TRAIN_ROOT}/dataset.csv",
    "dataset.validation_dataset.images_dir": f"{EVAL_ROOT}/images",
    "dataset.validation_dataset.csv_path": f"{EVAL_ROOT}/dataset.csv",
    "dataset.test_dataset.images_dir": f"{EVAL_ROOT}/images",
    "dataset.test_dataset.csv_path": f"{EVAL_ROOT}/dataset.csv",
}

evaluate（必須データソース）：

{
    "evaluate.checkpoint": "<selected train/AutoML checkpoint>",
    "dataset.test_dataset.images_dir": f"{EVAL_ROOT}/images",
    "dataset.test_dataset.csv_path": f"{EVAL_ROOT}/dataset.csv",
}

ファイル名を推測するのではなく、後続のアクションにはワークフローのチェックポイントリゾルバーを使用してください。Optical Inspection のスモーク実行では、AutoML によって model_epoch_000_step_00006.pth が生成される場合があります。その後、再開実行によって model_epoch_001_step_00012.pth が生成されることがあります。最良チェックポイントを使用するアクションでは、AutoML の最良の子ジョブで選択されたチェックポイントを使用してください。エポックを指定するアクションでは、要求されたエポック／ステップのチェックポイントを正確に指定してください。「latest」が明示的に要求された場合に限り、最新のチェックポイントを解決してください。

export：

{
    "export.checkpoint": "<selected train/AutoML checkpoint>",
    "export.onnx_file": "/results/optical_inspection.onnx",
    "export.input_width": 128,
    "export.input_height": 512,
    "export.batch_size": 1,
}

inference（必須データソース）：

{
    "inference.checkpoint": "<selected train/AutoML checkpoint>",
    "dataset.infer_dataset.images_dir": f"{INFERENCE_ROOT}/images",
    "dataset.infer_dataset.csv_path": f"{INFERENCE_ROOT}/dataset.csv",
}

データセットの変換

Optical Inspection では、データセットの変換は任意です。データセットがすでに TAO 対応の Optical Inspection 形式である場合は、images.tar.gz と dataset.csv の分割データから直接開始し、変換済みデータに対して train、evaluate、inference および後続のチェックポイント／エクスポート／デプロイのアクションを実行してください。

PyT コンテナでは optical_inspection dataset_convert を使用できますが、このモデルスキルには dataset_convert アクション／テンプレートが含まれていません。このコンバーターでは、未加工の Factory PCB レイアウト（root_dataset_dir、train／val／all の PCB ディレクトリ、golden_csv_dir、project_name、bot_top）が必要です。データの所有者から、未加工の PCB／golden CSV ソースなしで、変換済みの Optical Inspection images.tar.gz と dataset.csv の分割データが提供される場合もあります。架空の PCB データセットを作成しないでください。変換済みデータのみが利用可能な場合、モデル検証レポートでは、データセットの変換を失敗またはブロックではなく not run: preconverted dataset provided と記載してください。

変換済みの転送アーカイブをローカルで使用する場合は、仕様を記述する前に、展開されたディレクトリを確認してください。アーカイブによっては images/ ラッパーディレクトリが展開されることがあります。dataset.*.images_dir には外側のラッパーではなく、golden/ と dataset.csv で参照されるボード／画像フォルダーを含む内側のディレクトリを指定してください。たとえば、.../<split>/images/images を指定します。

製品側で引き続き対応が必要な事項は、ライセンス付きのトレーニング可能なサンプルデータセットの公開と、既存のコンテナの dataset_convert エントリーポイントを独自のスキーマ／テンプレートを備えたスキルアクションとしてパッケージ化することです。どちらも、このドキュメントおよび事前チェックの変更では実装されていません。

評価データセット

任意です。評価データセットには、同じ形式（画像＋CSV）を使用します。

重要なパラメーター

• model.model_type：Siamese のバリアントです。Siamese、Siamese_3 などを選択できます。
• model.model_backbone：デフォルトは custom です。
• model.embedding_vectors：埋め込み次元数です。デフォルトは 5 です。
• train.optim.lr：学習率です。デフォルトは 5e-4 です。
• dataset.batch_size：トレーニングのバッチサイズです。1 より大きい値にする必要があります。最小限のスモーク実行では 2 以上を使用してください。
• dataset.num_input：比較ごとの入力画像数です。
• dataset.input_map：入力チャンネル／画像ペアのマッピングです。

マルチ GPU／マルチノード

起動方法： Lightning による管理（python プロセスを 1 つ起動し、Lightning がワーカーを起動します）。

Spec キー	説明	デフォルト
train.num_gpus	GPU 数	1
train.gpu_ids	GPU デバイスのインデックス	[0]

• ストラテジー：auto（Lightning が最適なストラテジーを自動的に選択します）
• num_nodes または distributed_strategy の明示的な設定はありません。単一ノードのみです
• Siamese ネットワークは軽量なため、通常は単一 GPU で十分です

ハードウェア

最低 1 GPU、推奨 1 GPU です。GPU あたり 8GB 以上の VRAM が必要です。検査用の Siamese ネットワークは軽量です。単一 GPU で十分です。

エラーパターン

CSV 形式エラー：input_path,golden_path,label,object_name が必要です。起動前に、仕様の images_dir、照明マップ、num_input、連結、グリッド、画像拡張子を指定して scripts/validate_dataset.py を実行してください。

抽出した画像のルートの不一致：train、evaluate、または inference で dataset.csv のパスが見つからない場合は、抽出した images.tar.gz のディレクトリツリーを確認してください。TAO 対応のルートには、golden/ と、CSV で参照されているボードフォルダーが含まれている必要があります。転送されたアーカイブの場合、images/images のように、展開先の 1 つ下の階層にあることがあります。

トレーニングのバッチサイズのアサーション：Optical Inspection のデータローダーは、train に対して dataset.batch_size: 1 を拒否します。通常の実行ではテンプレートのデフォルト値である 8 を維持し、最小限の AutoML スモーク検証では dataset.batch_size: 2 を設定してください。

後続のアクションで PyTorch チェックポイントの読み込みに失敗する場合：同じ信頼できる TAO の train／AutoML ワークフローで生成されたチェックポイントの場合、現在の PyTorch のデフォルト設定によって完全なチェックポイントの読み込みがブロックされるときは、evaluate、inference、export、および resume のジョブで TORCH_FORCE_NO_WEIGHTS_ONLY_LOAD=1 を設定してください。信頼できないチェックポイントには、この環境変数を使用しないでください。

Spec パラメーター／親モデルの推論

モデル固有の推論マッピングは、config.json ではなく、この MD ファイルに記述します。生成されたランナーはこのセクションを読み取り、create_job() の前に SDK ヘルパーを使ってマッピングを適用してください。これは、以前のマイクロサービスの infer_params.py のフローに相当します。

TAO Core の optical_inspection.config.json からの推論マッピング：

アクション	Spec フィールド	推論関数	意味
evaluate	encryption_key	key	暗号化キー
evaluate	evaluate.checkpoint	parent_model	親ジョブの結果フォルダーから推定されるモデルファイル
evaluate	results_dir	output_dir	現在のジョブの結果ディレクトリ
export	encryption_key	key	暗号化キー
export	export.checkpoint	parent_model	親ジョブの結果フォルダーから推定されるモデルファイル
export	export.onnx_file	create_onnx_file	出力 ONNX パス
export	results_dir	output_dir	現在のジョブの結果ディレクトリ
inference	encryption_key	key	暗号化キー
inference	inference.checkpoint	parent_model	親ジョブの結果フォルダーから推定されるモデルファイル
inference	inference.trt_engine	parent_model	親ジョブの結果フォルダーから推定されるモデルファイル
inference	results_dir	output_dir	現在のジョブの結果ディレクトリ
train	encryption_key	key	暗号化キー
train	results_dir	output_dir	現在のジョブの結果ディレクトリ
train	train.pretrained_model_path	ptm_if_no_resume_model	resume チェックポイントがない場合の PTM
train	train.resume_training_checkpoint_path	resume_model	現在のジョブの結果フォルダーから推定されるモデルファイル

parent_model または parent_model_folder には、上流の train／export／AutoML 子ジョブ ID を parent_job_id として渡してください。SDK は親の結果フォルダーを一覧表示し、チェックポイントのアーティファクトを絞り込んで、選択したモデルファイルまたはフォルダーを返します。これらのマッピングを config.json に戻したり、チェックポイントのパスを推測するように生成されたランナースクリプトを変更したりしないでください。

デプロイ

• tao-deploy-optical-inspection