tao-train-visual-changenet

Visual ChangeNet

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

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

バックボーンの重み（c_radio_v2_vit_base_patch16_224）は HuggingFace の nvidia/C-RADIOv2-B モデルで、model.safetensors（約 393 MB）として配布されています。TAO 7.0.0-rc コンテナーは HF URL から自動取得しません — ptm_utils.load_pretrained_weights() は pretrained_backbone_path の値をそのまま torch.load(path)／safetensors.torch.load_file(path) に渡します。https://huggingface.co/... URL またはリポジトリ ID を渡すと FileNotFoundError が発生し、数秒以内に実行が Execution status: FAIL で失敗します。起動前にファイルをローカルに配置してください。

python3 -c "from huggingface_hub import hf_hub_download; import shutil; \
shutil.copy(hf_hub_download('nvidia/C-RADIOv2-B', 'model.safetensors'), '<workspace>/backbone/c_radio_v2_b.safetensors')"

コンテナーにマウントし（-v <workspace>/backbone/c_radio_v2_b.safetensors:/data/pretrained_models/C-RADIOv2_B.safetensors）、spec の model.backbone.pretrained_backbone_path にコンテナー内のパスを設定します。HF_TOKEN が必要なのは配置時のみで、トレーニング時には不要です。

Dataclass スキーマ

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

Train アクションのポリシー

このモデルでは、モデルレイヤーで AutoML が有効になっています。train ステージのリクエストを処理する前に、references/skill_info.yaml を読み込み、明示的な automl_policy 値またはユーザーのワークフローリクエストから、この実行のオーバーライドを解決してください。「AutoML をオフにする」「AutoML を無効にする」「HPO なし」「通常のトレーニング」のようなフレーズは、この実行に限り automl_policy: off として扱います。それ以外の場合は auto をデフォルトとします。automl_policy: auto、automl_enabled: true、および schemas/train.schema.json と references/spec_template_train.yaml の両方がパッケージ化されている場合は、このモデルの skill_dir を指定して、デフォルトで train アクションを tao-skill-bank:tao-run-automl 経由で実行します。データセット、spec、出力ディレクトリ、GPU／プラットフォーム設定、親チェックポイント、automl_policy に対するワークフロー／アプリケーションのオーバーライドは維持してください。直接モデルをトレーニングするのは、automl_policy: off の場合、またはパッケージ済みの train スキーマ／テンプレートがない場合に限ります。スキーマがない場合は、AutoML が有効であるものの、スキーマが生成されるまではこのモデルで実行できないことを報告してください。

evaluate、inference、export、デプロイフローなどの train 以外のアクションは、このモデルのスキル内で処理します。実行ごとの automl_policy オーバーライドによって、モデルのメタデータは変更されません。

TAO Deploy TensorRT アクション（gen_trt_engine、TensorRT の evaluate、および classify と segment の各バリアントにおける TensorRT の inference）では、最初に references/tao-deploy-visual-changenet.md を読んでください。デプロイ spec テンプレートは、このスキルの references/ フォルダーにあり、spec_template_deploy_*.yaml というプレフィックスが付いています。

タスク

分類（デフォルト）

使用するアクション：train、evaluate、inference。デフォルトのテンプレート：references/spec_template_train.yaml。

セグメント

使用するアクション：segment_train、segment_evaluate、segment_inference。デフォルトのテンプレート：references/spec_template_segment.yaml。

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

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

データセット、Spec のオーバーライド、データ形式

Visual ChangeNet には、データセットの種類とデータソースの構造が異なる 2 つのタスクモードがあります。分類では、4 列の CSV（input_path,golden_path,label,object_name）と画像ディレクトリを使用します。セグメントでは、単一の root_dir 内にペアになったディレクトリ構造（A/、B/、list/、label/）を使用します。データソースのオーバーライドは、すべてのアクションで必須です。エージェントはデータソースのパスを構成し、spec_overrides に含める必要があります。

各アクションのデータセット要件をまとめた表（分類とセグメント）、すべての Spec オーバーライドの例（両方のバリアントにおける train、export、quantize、evaluate、inference、gen_trt_engine）、分類の CSV 形式、evaluate/inference とセグメントの入力フィールド、照明の規則、セグメントのデータレイアウト、input_map による複数照明設定の詳細については、references/dataset-and-specs.md を参照してください。

ローカル Docker の実行

TAO SDK を使用しない場合は、versions.yaml から TAO pyt イメージを解決し、バックボーンの .ckpt を単一ファイルとしてマウントしたうえで、--shm-size=8g を指定して visual_changenet <action> を直接実行します。完全な docker run コマンド、共有メモリの要件、バックボーンのマウント方法、checkpoint/results_dir のコマンドラインオーバーライドのパターンについては、references/local-docker-invocation.md を参照してください。

パラメーター、ハードウェア、エラーパターン

主な設定項目には、train.validation_interval（デフォルトは 50、num_epochs 以下である必要があります）、train.checkpoint_interval（デフォルトは 200、num_epochs 以下である必要があります）、train.num_epochs（デフォルトは 100）、model.classify.eval_margin（デフォルトは 0.3、精度と再現率の主要なしきい値）、train.classify.cls_weight（デフォルトは [1.0, 10.0]）があります。最低限必要なハードウェアは VRAM 16GB 以上の GPU 1 基です。本番環境では GPU 8 基（DDP）を推奨します。GPU 数は TAO によって内部で管理されるため、gpu_spec_key は設定しないでください。

パラメーターの完全なリファレンス、ハードウェアのガイダンス、エラーパターンの全カタログ（チェックポイントが見つからない、CSV 形式の不一致、画像拡張子の不一致、OOM、評価精度の低さ、contrastive-loss のアサーション、収束しない、セグメント限定の MultiScaleDeformableAttention ビルド、Lightning のエポック設定ミス、PYTHONPATH/ModuleNotFoundError、エポックのデフォルト値）については、references/parameters-and-troubleshooting.md を参照してください。

Spec Param / 親モデルの推論

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

このモデルスキルの推論マッピング：

アクション	Spec フィールド	推論関数	意味
evaluate	results_dir	output_dir	現在のジョブの結果ディレクトリ
inference	results_dir	output_dir	現在のジョブの結果ディレクトリ
train	results_dir	output_dir	現在のジョブの結果ディレクトリ
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-visual-changenet — TAO Deploy を使用した、TensorRT エンジンの生成、TensorRT による評価、および TensorRT による推論のための Visual ChangeNet デプロイワークフロー。