tao-train-visual-changenet

Visual ChangeNet

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

Visual ChangeNet は、目視検査と欠陥検出のための TAO Toolkit モデルです。次の 2 つのタスクに対応しています。

• 分類 — 共有バックボーン（C-RADIO ViT）と学習可能な差分モジュールを備えたシャム型アーキテクチャを使用する、二値画像分類です。画像ペアを比較し、欠陥を PASS／NO_PASS に分類します。
• セグメンテーション — ViT-Large NVDINOv2 バックボーンを使用する、ピクセルレベルの変化セグメンテーションです。変更前と変更後の画像ペアを比較し、二値の変化マスクを生成します。

分類では、公開されている C-RADIOv2-B バックボーンと、6 種類の凍結された DINOv3 バリアントに対応しています。DINOv3 を選択する前に references/dinov3-backbones.md をお読みください。正確なバリアントの対応表、凍結要件、Hugging Face のアクセスルール、ローカルステージングのオーバーレイが記載されています。C-RADIO には、同梱の scripts/stage_backbone.py と references/local-docker.md に記載されたマウントを使用してください。

セグメンテーションの仕様では model.backbone.type: vit_large_nvdinov2 と NVDINOv2 チェックポイントファミリーを使用します。チェックポイントのアーキテクチャはバックボーンの種類と一致させてください。NV_DINOV2_518_16_256.ckpt はパッケージ化されたセグメンテーション用テンプレートと互換性がありますが、fan_small_12_p4_hybrid には使用できません。別のセグメンテーション用バックボーンに切り替える場合は、対応するチェックポイントを使用するか、デフォルトの初期化を使用するために model.backbone.pretrained_backbone_path を空のままにしてください。

データクラススキーマ

生成された TAO Core スキーマは schemas/<action>.schema.json にパッケージ化されており、利用可能なアクションは schemas/manifest.json に記載されています。各生成スキーマは、スキーマのトップレベルの default フィールドから references/spec_template_<action>.yaml も生成します。AutoML の有効化は、automl_enabled を使って references/skill_info.yaml のモデル層で宣言します。AutoML を実行するには、schemas/train.schema.json と references/spec_template_train.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 経由で実行してください。データセット、仕様ファイル、出力ディレクトリ、GPU／プラットフォーム設定、親チェックポイント、automl_policy に関するワークフロー／アプリケーションのオーバーライドは維持してください。直接モデル学習を使用するのは、automl_policy: off の場合、またはパッケージに学習スキーマ／テンプレートがない場合に限ってください。スキーマがない場合は、AutoML は有効ですが、スキーマが生成されるまでこのモデルでは実行できないと報告してください。

チェックポイントの保持はオーケストレーションポリシーであり、HPO パラメーターではありません。パッケージに含まれる両方の学習テンプレートでは、train.checkpointer.enable_topk と train.checkpointer.replace_periodic のデフォルトが false であり、train.checkpoint_interval で制御される定期保存を維持します。AutoML のチェックポイント保持が有効な場合、AutoML ランナーは両方のフラグを true に設定し、val_loss を min モードで監視し、save_top_k: 1 を使用します。これにより、定期保存の系列は最良のチェックポイント 1 つに置き換わります。AutoML のチェックポイント保持が無効な場合は、定期的なチェックポイントの動作を維持するため、保持数に上限を設けるオーバーライドは設定しないでください。

このモデルスキルで宣言されている学習以外のアクション（evaluate、inference、export、quantize、segment_evaluate、segment_inference）は、このモデルスキル内で実行してください。schemas/manifest.json に対応するエントリーがパッケージされるまでは、segment_export や segment_quantize を親スキルで実行可能なアクションとして提示しないでください。現在の親 references/skill_info.yaml では prune と retrain は宣言されていません。対応するアクション配線とスキーマでメタデータが拡張されない限り、これらを親スキルで実行可能なアクションとして提示しないでください。実行ごとの automl_policy オーバーライドによって、モデルのメタデータが変わることはありません。

TAO Deploy の TensorRT アクション（gen_trt_engine、TensorRT の evaluate、および classify と segment の各バリアントにおける TensorRT の inference）では、最初に references/tao-deploy-visual-changenet.md を読んでください。Deploy の仕様テンプレートは、このスキルの references/ フォルダー内にあり、spec_template_deploy_*.yaml というプレフィックスが付いています。 Deploy には、parent_model としてエクスポート済みの ONNX アーティファクトが必要です。ONNX アーティファクトがなく、メインスキルで export アクションが公開されていない場合は、アーティファクトを捏造せず、deploy は実行不能と報告してください。

学習要件

Visual ChangeNet には、それぞれ異なるデータセットタイプとデータソース構造を持つ、2 つの独立したタスクモードがあります。

Classify

• データセットタイプ： visual_changenet_classify
• 形式： default
• 受け付けるデータセットの用途： training、evaluation、testing、calibration
• 監視メトリック： val_loss
• 単独の evaluate メトリック： test_acc（test_fpr、test_fnr、defect_acc も出力されます）。AutoML では、学習時の val_loss に基づいて推奨結果を順位付けしてください。選択したチェックポイントが正常に読み込まれ、評価されることの確認にのみ test_acc を使用してください。evaluate アクションが val_loss を出力するとは想定しないでください。

アクション別データセット要件 (Classify)

以下の quantize と gen_trt_engine の行は、TAO 仕様のデータ要件のみを記述しています。対応するアクションが references/skill_info.yaml または deploy/skill_info.yaml で宣言されていない限り、これらは親スキルのアクションではありません。

アクション	仕様キー	ソース	ファイル	リスト?
train	dataset.classify.train_dataset.images_dir	train_datasets	images.tar.gz	いいえ
train	dataset.classify.train_dataset.csv_path	train_datasets	dataset.csv	いいえ
train	dataset.classify.validation_dataset.images_dir	eval_dataset	images.tar.gz	いいえ
train	dataset.classify.validation_dataset.csv_path	eval_dataset	dataset.csv	いいえ
quantize	dataset.classify.train_dataset.images_dir	train_datasets	images.tar.gz	いいえ
quantize	dataset.classify.train_dataset.csv_path	train_datasets	dataset.csv	いいえ
quantize	dataset.classify.validation_dataset.images_dir	eval_dataset	images.tar.gz	いいえ
quantize	dataset.classify.validation_dataset.csv_path	eval_dataset	dataset.csv	いいえ
quantize	dataset.classify.quant_calibration_dataset.images_dir	train_datasets	images.tar.gz	いいえ
evaluate	dataset.classify.validation_dataset.images_dir	eval_dataset	images.tar.gz	いいえ
evaluate	dataset.classify.validation_dataset.csv_path	eval_dataset	dataset.csv	いいえ
evaluate	dataset.classify.test_dataset.images_dir	eval_dataset	images.tar.gz	いいえ
evaluate	dataset.classify.test_dataset.csv_path	eval_dataset	dataset.csv	いいえ
inference	dataset.classify.infer_dataset.images_dir	inference_dataset	images.tar.gz	いいえ
inference	dataset.classify.infer_dataset.csv_path	inference_dataset	dataset.csv	いいえ
gen_trt_engine	gen_trt_engine.tensorrt.calibration.cal_image_dir	calibration_dataset	images.tar.gz	はい

Segment

• データセットタイプ: visual_changenet_segment
• フォーマット: default
• 受け入れ可能なデータセットインテント: training、calibration
• 監視メトリクス: val_loss

Segment は CSV + 画像ではなく、ペア化されたディレクトリ構造 (A/、B/、list/、label/) を使用します。root_dir 仕様キーは、4 つのサブディレクトリすべてを含む最上位ディレクトリを指します。

データセットごとに必要なファイル: A.tar.gz、B.tar.gz、list.tar.gz、label.tar.gz

アクション別データセット要件 (Segment)

以下の quantize と gen_trt_engine の行は、TAO 仕様のデータ要件のみを記述しています。対応するアクションが references/skill_info.yaml または deploy/skill_info.yaml で宣言されていない限り、これらは親スキルのアクションではありません。

アクション	仕様キー	ソース	ファイル	リスト?
train	dataset.segment.root_dir	train_datasets	(ルートディレクトリ)	いいえ
quantize	dataset.segment.root_dir	train_datasets	(ルートディレクトリ)	いいえ
quantize	dataset.segment.quant_calibration_dataset.images_dir	train_datasets	(ルートディレクトリ)	いいえ
evaluate	dataset.segment.root_dir	train_datasets	(ルートディレクトリ)	いいえ
inference	dataset.segment.root_dir	train_datasets	(ルートディレクトリ)	いいえ
gen_trt_engine	dataset.segment.root_dir	train_datasets	(ルートディレクトリ)	いいえ
gen_trt_engine	gen_trt_engine.tensorrt.calibration.cal_image_dir	calibration_dataset	images.tar.gz	はい

一般的な仕様のオーバーライド

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

S3_TRAIN = "s3://bucket/data/train"
S3_EVAL = "s3://bucket/data/eval"

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

{
    "train.num_epochs": 30,
    "train.checkpoint_interval": 10,
    "train.validation_interval": 10,
    "train.num_gpus": 1,
    "train.use_distributed_sampler": False,
    "train.sync_batchnorm": False,
    "dataset.classify.train_dataset.images_dir": f"{S3_TRAIN}/images.tar.gz",
    "dataset.classify.train_dataset.csv_path": f"{S3_TRAIN}/dataset.csv",
    "dataset.classify.validation_dataset.images_dir": f"{S3_EVAL}/images.tar.gz",
    "dataset.classify.validation_dataset.csv_path": f"{S3_EVAL}/dataset.csv",
}

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

{
    "train.num_epochs": 30,
    "train.checkpoint_interval": 10,
    "train.validation_interval": 10,
    "train.num_gpus": 1,
    "train.use_distributed_sampler": False,
    "train.sync_batchnorm": False,
    "dataset.segment.root_dir": f"{S3_TRAIN}",
}

export（classify）：

{
    "export.input_height": 896,
    "export.input_width": 224,
}

export（segment）：

{
    "export.input_height": 224,
    "export.input_width": 224,
}

quantize（classify、データソース必須）：

{
    "dataset.classify.train_dataset.images_dir": f"{S3_TRAIN}/images.tar.gz",
    "dataset.classify.train_dataset.csv_path": f"{S3_TRAIN}/dataset.csv",
    "dataset.classify.validation_dataset.images_dir": f"{S3_EVAL}/images.tar.gz",
    "dataset.classify.validation_dataset.csv_path": f"{S3_EVAL}/dataset.csv",
    "dataset.classify.quant_calibration_dataset.images_dir": f"{S3_TRAIN}/images.tar.gz",
}

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

{
    "dataset.classify.validation_dataset.images_dir": f"{S3_EVAL}/images.tar.gz",
    "dataset.classify.validation_dataset.csv_path": f"{S3_EVAL}/dataset.csv",
    "dataset.classify.test_dataset.images_dir": f"{S3_EVAL}/images.tar.gz",
    "dataset.classify.test_dataset.csv_path": f"{S3_EVAL}/dataset.csv",
}

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

{
    "dataset.classify.infer_dataset.images_dir": f"{S3_EVAL}/images.tar.gz",
    "dataset.classify.infer_dataset.csv_path": f"{S3_EVAL}/dataset.csv",
}

gen_trt_engine（classify、データソース必須）：

{
    "gen_trt_engine.tensorrt.calibration.cal_image_dir": [f"{S3_TRAIN}/images.tar.gz"],
}

quantize（segment、データソース必須）：

{
    "dataset.segment.root_dir": f"{S3_TRAIN}",
    "dataset.segment.quant_calibration_dataset.images_dir": f"{S3_TRAIN}",
}

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

{
    "dataset.segment.root_dir": f"{S3_TRAIN}",
}

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

{
    "dataset.segment.root_dir": f"{S3_TRAIN}",
}

gen_trt_engine（segment、データソース必須）：

{
    "dataset.segment.root_dir": f"{S3_TRAIN}",
    "gen_trt_engine.tensorrt.calibration.cal_image_dir": [f"{S3_TRAIN}/images.tar.gz"],
}

ローカル Docker で実行する

固定バージョンの TAO pyt イメージを使用し、visual_changenet <train|evaluate|inference|export|quantize>を直接実行します。--shm-size=8gが必要です。また、C-RADIO .safetensorsを/data/pretrained_models/C-RADIOv2_B.safetensorsにマウントする必要があります。checkpoint/results_dirはコマンドラインでオーバーライドできます。docker runコマンド、マウント、オーバーライドの詳細については、references/local-docker.mdを参照してください。

タスク

Classify（デフォルト）

使用するアクション：train、evaluate、inference。デフォルトのテンプレート：references/spec_template_train.yaml。evaluate／inferenceには、先行する7.1のtrainでresults_dirに保存したチェックポイントが必要です。NGCには7.1のclassify用事前学習済みチェックポイントはありません（7.0時代のvisual_changenet_nvpcb_trainable_v1.0は、7.1で読み込むとradio.*のKeyErrorが発生します）。新しいワークスペースでは、まず公開バックボーンから学習してください。NGCのfull_model classifyチェックポイントをダウンロードしようとせず、NGCの組織名をハードコードしないでください。

Segment

スキルのアクション名はsegment_train、segment_evaluate、segment_inferenceです。ローカル Docker を直接実行する場合は、specでtask: segmentを指定し、TAO CLIのサブコマンドtrain、evaluate、inferenceを実行します。スキーマ駆動型アクションテンプレートはreferences/spec_template_segment_train.yaml、references/spec_template_segment_evaluate.yaml、references/spec_template_segment_inference.yamlです。コンパクトな Docker 直接実行のサンプルテンプレートはreferences/spec_template_segment.yamlです。

セグメンテーションでは、初回実行時にカスタム CUDA 演算（MultiScaleDeformableAttention）をコンパイルする必要があり、約5分かかります。ViT アダプターバックボーンは、マルチスケール特徴抽出にこれらを使用します。

セグメンテーションのデータセット構造はclassifyとは異なり、CSVファイルではなく、ペアのディレクトリ（A/、B/、list/、label/）を使用します。デフォルト値のdataset.segment.root_dirを参照してください。

データ形式

Classifyには、4列のCSV（input_path,golden_path,label,object_name）と画像ディレクトリが必要です。segmentではCSVの代わりに、dataset.segment.root_dir配下にペアのディレクトリ構造（A/、B/、list/、label/）を使用します。image_extフィールド（デフォルトは.jpg）は実際のファイル拡張子と一致している必要があります。画像が.pngの場合は、dataset.classify.image_ext: .pngを設定してください。複数照明の入力はdataset.classify.input_map（各照明名をチャネルインデックスに対応付けます）で設定し、dataset.classify.num_inputもそれに合わせて設定します。各フィールドの入力表（classify train/eval/inference、segment）、CSV列の意味、照明とパス結合の規則、segmentのディレクトリ構成、およびinput_map／grid_mapの例については、references/data-formats.mdを参照してください。

事前確認：分類データセットの検証（分類ジョブを実行する前に毎回必須）

分類の train、evaluate、または inference ジョブを開始する前に、CSVを検証してください。これにより、形式が不正なデータセットを、GPUコンテナの起動から数分後（または、単一クラスの学習セットの場合はチェックポイントの書き込み後）ではなく、ホスト上で1秒未満に検出して失敗させることができます。次を実行します。

python3 skills/models/tao-train-visual-changenet/scripts/validate_vcn_dataset.py \
  --csv        <abs path to dataset.csv> \
  --images-dir <abs path to images dir> \
  --mode       train \
  --batch-size <dataset.classify.batch_size> --num-gpus <train.num_gpus>
# --mode: train | evaluate | inference

終了コード 0 → 実行を開始します。終了コード 2 → データセットを修正し、実行を開始しないでください。 このスクリプトは、絶対パスのCSV、サンプルごとのディレクトリが必要な箇所にあるフラットなファイル名、単一クラスの学習セット、およびデータセットより大きいバッチを拒否します。チェックごとの仕様と --light ／ --image-ext オプションについては、references/data-formats.md を参照してください。

重要なパラメーター

主な設定項目には、train.validation_interval（デフォルトは50、num_epochs 以下である必要があります）、train.checkpoint_interval（デフォルトは200、定期的なチェックポイント保存が有効な場合は num_epochs 以下である必要があります）、train.num_epochs（デフォルトは100）、model.classify.eval_margin（デフォルトは0.3、適合率／再現率のしきい値）、model.classify.train_margin_euclid（デフォルトは2.0）、model.classify.embedding_vectors（デフォルトは5）、dataset.classify.batch_size（デフォルトは16、1より大きい値である必要があります）、dataset.classify.fpratio_sampling（デフォルトは0.25）、および train.classify.cls_weight（デフォルトは [1.0, 10.0]）があります。train.checkpointer フィールドは、HPOの検索パラメーターではなく、固定されたライフサイクル制御項目です。ハードウェア：最低1基の16GB以上のVRAMを搭載したGPUが必要で、8基のGPU（DDP）を推奨します。gpu_spec_key は設定しないでください（GPU数はTAOが内部で管理します）。num_nodes（デフォルトは1）はマルチノードを制御します。各パラメーターの詳しいガイダンスとハードウェアの詳細については、references/tuning-parameters.md を参照してください。

エラーパターン

チェックポイントが見つからない場合、CSV形式が一致しない場合、画像拡張子が一致しない場合、OOM、評価精度が低い場合、対照損失の AssertionError、評価／推論時のチェックポイント読み込みキー不一致、収束しない場合、セグメントのみのバックボーンの次元不一致、MultiScaleDeformableAttention の OSError、Lightning の MisconfigurationException、ModuleNotFoundError: nvidia_tao_pytorch、およびエポック数のデフォルト値については、症状と対処方法の一覧を references/troubleshooting.md で確認してください。

Spec Param ／ 親モデルの推論

モデル固有の親モデルのマッピングは references/skill_info.yaml の spec_params で宣言されているため、エージェントはファイル名を推測するのではなく、ジョブを開始する前にチェックポイントを解決できます。parent_model または parent_model_folder には、上流の学習／エクスポート／AutoML子ジョブのIDを親ジョブIDとして渡してください。親の結果フォルダーを一覧表示し、チェックポイントの成果物を絞り込んで、解決されたモデルファイルまたはフォルダーを選択します。アクションごとのspecフィールドと推論関数の対応表については、references/parent-model-inference.md を参照してください。

デプロイ

• tao-deploy-visual-changenet