tao-train-image-classification

Classification PyT

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

PyTorch による画像分類です。蒸留とデプロイ向けの量子化に対応し、幅広いバックボーン（FAN、EfficientNet、ResNet など）をサポートします。

バックボーンの重みには model.backbone.pretrained_backbone_path を、モデル全体には train.pretrained_model_path を設定してください。

TAO Deploy の TensorRT アクション（gen_trt_engine、TensorRT evaluate、TensorRT inference）については、まず references/tao-deploy-image-classification.md をお読みください。デプロイ仕様のテンプレートは、このスキルの 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 があることを前提にしないでください。メンテナーはスキルバンクのパッケージ化前にスキーマとテンプレートを再生成します。

Train アクションのポリシー

このモデルはモデルレイヤーで AutoML が有効になっています。train ステージのリクエストを処理する前に、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 を指定して、train アクションを tao-skill-bank:tao-run-automl 経由で実行してください。データセット、仕様、出力ディレクトリ、GPU／プラットフォーム設定、親チェックポイント、automl_policy については、ワークフロー／アプリケーション側のオーバーライドを維持してください。automl_policy: off の場合、またはパッケージ化された train スキーマ／テンプレートが不足している場合にのみ、モデルの直接トレーニングを使用してください。スキーマが不足している場合は、AutoML は有効ですが、スキーマが生成されるまでこのモデルでは実行できないことを報告してください。

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

トレーニング要件

• データセットの種類： image_classification
• 形式： classification_pyt
• 監視メトリック： val_acc_1
• AutoML の train スコープ： 通常の train 検索から distill.teacher.* パラメーターを除外してください。これらのフィールドは個別の distill アクション用です。統合生成スキーマに含まれていても、classification_pyt train の動作には影響しません。

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

アクション	仕様キー	ソース	ファイル	リスト？
distill	dataset.train_dataset.images_dir	train_datasets	images_train.tar.gz	いいえ
distill	dataset.classes_file	train_datasets	classes.txt	いいえ
distill	dataset.val_dataset.images_dir	eval_dataset	images_val.tar.gz	いいえ
evaluate	dataset.val_dataset.images_dir	eval_dataset	images_val.tar.gz	いいえ
evaluate	dataset.classes_file	eval_dataset	classes.txt	いいえ
evaluate	dataset.test_dataset.images_dir	inference_dataset	images_test.tar.gz	いいえ
export	dataset.root_dir	train_datasets		いいえ
inference	dataset.val_dataset.images_dir	eval_dataset	images_val.tar.gz	いいえ
inference	dataset.classes_file	eval_dataset	classes.txt	いいえ
inference	dataset.test_dataset.images_dir	inference_dataset	images_test.tar.gz	いいえ
quantize	dataset.train_dataset.images_dir	train_datasets	images_train.tar.gz	いいえ
quantize	dataset.classes_file	train_datasets	classes.txt	いいえ
quantize	dataset.val_dataset.images_dir	eval_dataset	images_val.tar.gz	いいえ
quantize	dataset.quant_calibration_dataset.images_dir	calibration_dataset	images_train.tar.gz	いいえ
train	dataset.train_dataset.images_dir	train_datasets	images_train.tar.gz	いいえ
train	dataset.classes_file	train_datasets	classes.txt	いいえ
train	dataset.val_dataset.images_dir	eval_dataset	images_val.tar.gz	いいえ

典型的な仕様オーバーライド

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

TRAIN_IMAGES_DIR = "/workspace/data/extracted/train/images_train"
VAL_IMAGES_DIR = "/workspace/data/extracted/val/images_val"
TEST_IMAGES_DIR = "/workspace/data/extracted/test/images_test"
CLASSES_FILE = "/workspace/data/s3/classes.txt"
WRITABLE_RESULTS_DIR = "/results"   # must be a writable bind, not the image CWD

ローカル Docker の場合は、S3 アーカイブをダウンロードして先に展開し、展開したクラスルートフォルダーをdataset.*.images_dirに指定してください。ローカル Docker の仕様にimages_train.tar.gz、images_val.tar.gz、images_test.tar.gzを直接渡さないでください。スキルのメタデータでは、これらの入力はフォルダーとして宣言されています。

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

{
    "train.num_epochs": 2,
    "train.validation_interval": 2,
    "train.checkpoint_interval": 2,
    "train.num_gpus": 1,
    "dataset.train_dataset.images_dir": TRAIN_IMAGES_DIR,
    "dataset.classes_file": CLASSES_FILE,
    "dataset.val_dataset.images_dir": VAL_IMAGES_DIR,
    "dataset.root_dir": WRITABLE_RESULTS_DIR,
}

dataset.root_dirは、export だけでなくtrain にも必須です。CLDatasetはセットアップ中にroot_dirへclasses.txtを書き込むため、書き込み可能なバインドマウントを指定する必要があります（結果用マウントが自然な選択です）。仕様テンプレートではデフォルト値が''になっているため、書き込み先がコンテナーの作業ディレクトリになります。root コンテナーでは書き込みが成功しますが、root 以外のユーザーに切り替えるランナーでは失敗します。

PermissionError: [Errno 13] Permission denied: 'classes.txt'
  .../classification_pyt/dataloader/dataset.py, in CLDataset.__init__

ローカル Docker ランチャーは、書き込み可能な結果用バインドがある場合、ホストの UID:GID を使用します。そのため、dataset.root_dirが設定されていないと、root 以外のユーザーでのトレーニングはここで失敗します。

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

{
    "export.input_height": 224,
    "export.input_width": 224,
    "dataset.root_dir": "/workspace/data/extracted",
}

gen_trt_engine：

{
    "gen_trt_engine.tensorrt.data_type": "fp16",
}

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

{
    "dataset.batch_size": 1,
    "dataset.val_dataset.images_dir": VAL_IMAGES_DIR,
    "dataset.classes_file": CLASSES_FILE,
    "dataset.test_dataset.images_dir": TEST_IMAGES_DIR,
}

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

{
    "dataset.train_dataset.images_dir": TRAIN_IMAGES_DIR,
    "dataset.classes_file": CLASSES_FILE,
    "dataset.val_dataset.images_dir": VAL_IMAGES_DIR,
    "train.optim.policy": "step",
}

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

{
    "dataset.val_dataset.images_dir": VAL_IMAGES_DIR,
    "dataset.classes_file": CLASSES_FILE,
    "dataset.test_dataset.images_dir": TEST_IMAGES_DIR,
}

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

{
    "dataset.train_dataset.images_dir": TRAIN_IMAGES_DIR,
    "dataset.classes_file": CLASSES_FILE,
    "dataset.val_dataset.images_dir": VAL_IMAGES_DIR,
    "dataset.quant_calibration_dataset.images_dir": TRAIN_IMAGES_DIR,
}

評価用データセット

任意です。検証用画像は、トレーニング画像とは別の tar ファイルで提供されます。別個のimages_test.tar.gzが用意されていない小規模なスモークテスト用データセットでは、dataset.test_dataset.images_dirに検証用アーカイブを指定してください。これにより、evaluate と inference でもチェックポイントの受け渡しをテストできます。

重要なパラメーター

• dataset.num_classes：クラス数です。デフォルトは20です。画像のtarball内のサブディレクトリ数と一致している必要があります。
• model.backbone.type：デフォルトはfan_small_12_p4_hybridです。サポートされているバックボーンとそのheadのin_channels（model_params_mapping.pyより）：FAN：fan_tiny、fan_small_12_p4_hybrid、fan_base_16_p4_hybrid、fan_large_16_p4_hybrid。GCViT：gcvit_tinyからgcvit_largeまで。FasterViT：fastervit_0からfastervit_6まで。ViT/EVA/DINO：vit_large_patch14_dinov2、eva02_large_patch14など。SigLIP-CLIPA：ViT-H-14-SigLIP-CLIPA-224など。一部のバックボーンではデフォルト以外の入力解像度（384、512、768）が必要です。
• dataset.classes_file：クラス名を列挙したclasses.txtへのパスです。
• train.optim.lr：学習率です。デフォルトは6e-5です。
• dataset.img_size：入力画像のサイズです。デフォルトは224です。
• dataset.batch_size：GPUあたりのバッチサイズです。デフォルトは8です。

マルチGPU／マルチノード

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

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

• マルチGPUのストラテジー：ddp_find_unused_parameters_true
• fsdpはサポートされていません

マルチノード環境変数（オーケストレーターが設定）：WORLD_SIZE、NODE_RANK、MASTER_ADDR、MASTER_PORT、NUM_GPU_PER_NODE。

ハードウェア

最低1 GPU、推奨2 GPUです。GPUあたり16GB以上（V100またはA100）のVRAMが必要です。分類処理は一般に軽量です。ほとんどのバックボーンは224x224の場合、バッチサイズ8で16GBのGPUに十分収まります。

エラーの傾向

CUDAのメモリ不足：batch_sizeを減らすか、より小さなバックボーンを使用してください。

num_classesの不一致：dataset.num_classesが、画像のtarball内の実際のクラスディレクトリおよびclasses.txtと一致していることを確認してください。

空のクラスディレクトリ：classes.txt内の各クラスについて、対応するサブディレクトリに少なくとも1枚の画像が必要です。

Distillのスケジューラーのデフォルト設定：同梱のdistillテンプレートとスキーマでは、 train.optim.policy: stepが使用されています。コンテナの実装が更新されるまでは、 distillのspecではこの設定を維持してください。7.0 PyT distillerは train.optim.policy: linearに対するスケジューラーの間隔を割り当てません。

チェックポイントの引き継ぎ：学習ではmodel_epoch_*.pthチェックポイントと classifier_model_latest.pthシンボリックリンクが生成されます。evaluate、inference、export、quantize、 distill、resumeでは、SDKリゾルバーを通じて対象のエポックチェックポイントを正確に選択してください。latestシンボリックリンクは、ユーザーが明示的にlatestを指定した場合にのみ使用してください。

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

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

TAO Core の classification_pyt.config.json に基づく推論マッピング：

アクション	仕様フィールド	推論関数	意味
distill	distill.pretrained_teacher_model_path	parent_model	親ジョブの結果フォルダーから推論されるモデルファイル
distill	results_dir	output_dir	現在のジョブの結果ディレクトリ
evaluate	evaluate.checkpoint	parent_model	親ジョブの結果フォルダーから推論されるモデルファイル
evaluate	results_dir	output_dir	現在のジョブの結果ディレクトリ
export	export.checkpoint	parent_model	親ジョブの結果フォルダーから推論されるモデルファイル
export	export.onnx_file	create_onnx_file	出力 ONNX パス
export	results_dir	output_dir	現在のジョブの結果ディレクトリ
gen_trt_engine	gen_trt_engine.onnx_file	parent_model	親ジョブの結果フォルダーから推論されるモデルファイル
gen_trt_engine	gen_trt_engine.trt_engine	create_engine_file	出力 TensorRT エンジンパス
gen_trt_engine	results_dir	output_dir	現在のジョブの結果ディレクトリ
inference	inference.checkpoint	parent_model	親ジョブの結果フォルダーから推論されるモデルファイル
inference	inference.trt_engine	parent_model	親ジョブの結果フォルダーから推論されるモデルファイル
inference	results_dir	output_dir	現在のジョブの結果ディレクトリ
quantize	quantize.model_path	parent_model	親ジョブの結果フォルダーから推論されるモデルファイル
quantize	results_dir	output_dir	現在のジョブの結果ディレクトリ
train	model.backbone.pretrained_backbone_path	ptm_if_no_resume_model	再開用チェックポイントがない場合の PTM
train	results_dir	output_dir	現在のジョブの結果ディレクトリ
train	train.pretrained_model_path	ptm_if_no_resume_model	再開用チェックポイントがない場合の 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-image-classification