tao-finetune-clip

CLIP

ゼロショットおよびファインチューニングによる画像分類、画像とテキストの検索、埋め込み抽出に対応する Contrastive Language-Image Pre-training モデルです。ファインチューニングでは、CLIP の共有画像・テキスト埋め込み空間を、ドメイン固有の画像・キャプションデータに適応させます。

デフォルトの NGC 事前学習済みチェックポイントは必要ありません。train.pretrained_model_path、evaluate.checkpoint、inference.checkpoint、export.checkpoint が未設定の場合、TAO は SigLIP2/OpenCLIP の各バリアントでは HuggingFace から、Radio-CLIP では torch.hub から事前学習済み重みを読み込みます。そのため、初回の使用時にはネットワークアクセスまたはローカルミラーが必要です。

対応アクション：train、evaluate、inference、export、gen_trt_engine

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 schema／template がない場合に限り、モデルの直接トレーニングを使用してください。schema がない場合は、AutoML は有効ですが、schema が生成されるまではこのモデルで実行できないことを報告してください。

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

手順

トレーニング、評価、埋め込み推論、ONNX エクスポート、TensorRT エンジン生成など、NVIDIA TAO CLIP のジョブでこのスキルを使用します。まず、リクエストされたアクションを特定し、そのアクションで必要な参照ファイルのみを読み込みます。デフォルトパラメーターには defaults.json、アクション／データソースの設定には config.json、spec の全体構造には references/spec_template.yaml、SDK のメタデータには references/model_info.yaml を使用します。

データセットを使用するアクションでは、必要な画像、キャプション、リスト、またはプロンプトのファイルをユーザーから受け取り、解決したパスを spec_overrides に設定します。export と gen_trt_engine では、上流ジョブが利用可能な場合は親アーティファクトを推定し、利用できない場合はチェックポイント、ONNX、またはエンジンのパスを明示的に指定するよう求めます。gen_trt_engine、TensorRT の evaluate、TensorRT の inference は、TAO Deploy イメージで実行します。

TAO Deploy の TensorRT アクション（gen_trt_engine、TensorRT の evaluate、TensorRT の inference）では、最初に references/tao-deploy-clip.md を読み込んでください。Deploy の spec template は、このスキルの references/ フォルダーにあり、spec_template_deploy_*.yaml というプレフィックスが付いています。

トレーニング要件

• データセットタイプ： image_text
• 形式： カスタムの画像／キャプションフォルダーまたは WebDataset シャード
• モニタリング指標： val/t2i_mAP

対応モデル

• SigLIP2： siglip2-so400m-patch16-256（デフォルト）、siglip2-so400m-patch14-224、siglip2-so400m-patch14-384、siglip2-so400m-patch16-384、siglip2-so400m-patch16-512、siglip2-so400m-patch16-naflex
• Radio-CLIP： c-radio_v3-b、c-radio_v3-l、c-radio_v3-h、c-radio_v3-g
• OpenCLIP / NV-CLIP： ViT-L-14-SigLIP-CLIPA-224、ViT-L-14-SigLIP-CLIPA-336、ViT-H-14-SigLIP-CLIPA-224、ViT-H-14-SigLIP-CLIPA-336、ViT-H-14-SigLIP-CLIPA-574

Radio-CLIP では、model.adaptor_name に siglip または clip を設定する必要があります。

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

アクション	Spec Key	ソース	ファイル	リスト？
train	dataset.train.datasets	train_datasets	image_dir: images.tar.gz, image_list_file: image_list.txt, caption_dir: captions.tar.gz	はい
train	dataset.train.wds.root_dir	train_wds_dataset	.tar シャードを含むルートディレクトリ	いいえ
train	dataset.train.wds.shard_list_file	train_wds_dataset	シャードパスを列挙した shards.txt	いいえ
train	dataset.val.datasets	eval_dataset	image_dir: images.tar.gz, image_list_file: image_list.txt, caption_dir: captions.tar.gz	はい
evaluate	dataset.val.datasets	eval_dataset	image_dir: images.tar.gz, image_list_file: image_list.txt, caption_dir: captions.tar.gz	はい
inference	inference.datasets	inference_dataset	image_dir: images.tar.gz	はい
inference	inference.text_file	inference_dataset	prompts.txt	いいえ
export	export.checkpoint	親の train ジョブまたは明示的に指定したチェックポイント	checkpoint .pth。事前学習済みモデルのエクスポートでは任意	いいえ
gen_trt_engine	gen_trt_engine.onnx_file	親の export ジョブまたは明示的に指定した ONNX	clip_model.onnx	いいえ

カスタム学習では、dataset.train.type: custom を設定し、dataset.train.datasets のエントリーを指定します。画像ファイルとキャプションファイルのベース名は一致している必要があります。caption_file_suffix のデフォルト値は .txt で、image_list_file は任意です。

WDS 学習では、dataset.train.type: wds を設定し、dataset.train.wds.root_dir または dataset.train.wds.shard_list_file の少なくとも一方を指定します。root_dir は再帰的に検索され、.tar シャードが検出されます。shard_list_file は、1 行に 1 つのシャードパスを記述したテキストファイルです。相対パスは、root_dir も指定されている場合は root_dir を基準に、それ以外の場合はリストファイルのディレクトリを基準に解決されます。検証／評価データには、引き続き dataset.val.datasets を介してカスタム形式を使用します。

典型的な Spec Overrides

データセットを使用するアクションでは、データソースのオーバーライドが必須です。「アクションごとのデータセット要件」表に基づいてパスを組み立て、spec_overrides に含めてください。推論では、inference.datasets または inference.text_file の少なくとも一方を指定します。

S3_TRAIN = "s3://bucket/data/train"
S3_WDS = "s3://bucket/data/wds"
S3_EVAL = "s3://bucket/data/eval"
S3_INFER = "s3://bucket/data/infer"

train、カスタムデータセット：

{
    "train.num_epochs": 10,
    "dataset.train.type": "custom",
    "dataset.train.datasets": [{"image_dir": f"{S3_TRAIN}/images.tar.gz", "image_list_file": f"{S3_TRAIN}/image_list.txt", "caption_dir": f"{S3_TRAIN}/captions.tar.gz"}],
    "dataset.val.datasets": [{"image_dir": f"{S3_EVAL}/images.tar.gz", "image_list_file": f"{S3_EVAL}/image_list.txt", "caption_dir": f"{S3_EVAL}/captions.tar.gz"}],
}

train、WDS データセット：

{
    "train.num_epochs": 10,
    "dataset.train.type": "wds",
    "dataset.train.wds.root_dir": f"{S3_WDS}",
    "dataset.train.wds.shard_list_file": f"{S3_WDS}/shards.txt",
    "dataset.train.wds.samples_per_shard": 10000,
    "dataset.val.datasets": [{"image_dir": f"{S3_EVAL}/images.tar.gz", "image_list_file": f"{S3_EVAL}/image_list.txt", "caption_dir": f"{S3_EVAL}/captions.tar.gz"}],
}

evaluate：

{
    "dataset.val.datasets": [{"image_dir": f"{S3_EVAL}/images.tar.gz", "image_list_file": f"{S3_EVAL}/image_list.txt", "caption_dir": f"{S3_EVAL}/captions.tar.gz"}],
}

事前学習済み重みを使用したゼロショット評価では、evaluate.checkpoint を未設定のままにします。TensorRT 評価では、evaluate.checkpoint の代わりに evaluate.trt_engine を設定します。

inference：

{
    "inference.datasets": [{"image_dir": f"{S3_INFER}/images.tar.gz"}],
    "inference.text_file": f"{S3_INFER}/prompts.txt",
}

推論では、results_dir の下に image_embeddings.h5 および／または text_embeddings.h5 が書き込まれます。保存された埋め込みは L2 正規化されています。

export：

{
    "export.onnx_file": "${results_dir}/export/clip_model.onnx",
    "export.encoder_type": "combined",
    "export.batch_size": -1,
}

デプロイ時に独立したビジョンエンコーダーとテキストエンコーダーを使用する場合は、export.encoder_type: separate を設定します。分離エクスポートでは、ベースの export.onnx_file から派生した _vision.onnx と _text.onnx のファイルが書き込まれます。

gen_trt_engine：

{
    "gen_trt_engine.onnx_file": "${results_dir}/export/clip_model.onnx",
    "gen_trt_engine.trt_engine": "${results_dir}/deploy/clip_model.engine",
    "gen_trt_engine.batch_size": -1,
    "gen_trt_engine.tensorrt.data_type": "fp16",
    "gen_trt_engine.tensorrt.min_batch_size": 1,
    "gen_trt_engine.tensorrt.opt_batch_size": 1,
    "gen_trt_engine.tensorrt.max_batch_size": 16,
}

評価データセット

学習では任意です。指定すると、検証間隔ごとに検証メトリクスが計算されます。evaluate では必須です。

デプロイワークフロー

このスキルでは、gen_trt_engine をデプロイアクションとして公開します。生成された SDK ランナーでは、model_info["actions"]["gen_trt_engine"] を使用し、PyTorch 学習イメージではなく TAO Deploy イメージで実行します。コンテナ内のコマンドは clip gen_trt_engine -e {config_path} です。TAO Launcher を直接使用する場合、同じアクションは tao deploy clip gen_trt_engine -e /path/to/spec.yaml と記述します。

TAO Deploy は、統合形式と分離エンコーダー形式の両方をサポートします。分離エンコーダーの場合は、_vision または _text を付けないベースパスを gen_trt_engine.onnx_file と gen_trt_engine.trt_engine に渡します。TAO は、ビジョン／テキストのファイルに付けるサフィックスを検出するか、書き込みます。

TensorRT 評価には evaluate.trt_engine を、TensorRT による埋め込み抽出には inference.trt_engine を使用します。これらの TensorRT 処理も TAO Deploy イメージで実行します。TAO Launcher を直接使用する場合、これらは tao deploy clip evaluate および tao deploy clip inference と記述します。

TAO Deploy のリファレンス全文：tao-deploy-clip。

重要なパラメーター

• model.type：バックボーンのファミリーと解像度です。デプロイには、固定解像度のSigLIP2/OpenCLIPバリアントを使用してください。
• model.adaptor_name：Radio-CLIPで必須です。siglipまたはclipを設定してください。
• model.image_size：学習時の画像変換解像度です。選択した固定解像度のバックボーンに合わせてください。
• train.num_epochs：CLIPのファインチューニングは早く収束することがよくあります。ドメイン適応では10～20エポックから開始し、検証損失が改善し続けている場合にのみ増やしてください。
• train.optim.vision_lr / train.optim.text_lr：2つのエンコーダーの学習率です。CLIPは高い学習率に敏感なため、損失が不安定な場合は両方を下げてください。
• model.freeze_vision_encoder / model.freeze_text_encoder：デフォルトはfalseです。データセットが小さい場合や、片方のモダリティだけを適応させる場合は、一方のエンコーダーを凍結すると効果的です。
• train.loss_type：SigLIP2とRadio-CLIPにはsiglipを推奨します。CLIP形式のソフトマックス損失にはclipを使用してください。
• export.encoder_type：combinedは1つのONNXグラフをエクスポートします。separateは独立した視覚グラフとテキストグラフをエクスポートします。
• gen_trt_engine.tensorrt.data_type：TensorRTのデプロイではfp16とfp32をサポートしています。

ハードウェア

小規模なデータセットであれば、単一GPUで学習できます。画像が10万枚を超えるデータセットや大規模なバックボーンには、4基以上のGPUを使用してください。小規模な実行や固定解像度での実行ではGPUごとに16GB以上のVRAMを使用し、Radio-CLIPや高解像度のOpenCLIPバリアントには、より大容量のGPUを使用してください。

エラーパターン

CUDAのメモリ不足：dataset.train.batch_size、dataset.val.batch_size、またはTensorRTのopt/maxバッチサイズを下げてください。エクスポートまたはデプロイでは、export.input_heightとexport.input_widthが選択した固定解像度のバックボーンと一致しているか確認してください。

NaN損失：ファインチューニングには学習率が高すぎます。train.optim.vision_lrとtrain.optim.text_lrを下げ、train.optim.warmup_stepsを増やし、キャプションが空でない有効なテキストであることを確認してください。

検索または分類の品質がゼロ：キャプションとプロンプトが対象のラベル語彙に一致しているか確認してください。CLIPは画像とテキストの埋め込みを比較するため、プロンプトの文言が重要です。

データセットのサイズがバッチサイズの合計より小さい：バッチサイズの合計はbatch_size * num_gpusです。データセット、特に検証データのサンプル数がこれより少ない場合は、dataset.val.batch_sizeまたはdataset.train.batch_sizeを下げてください。

Radio-CLIPの設定検証エラー：model.adaptor_nameを明示的にsiglipまたはclipに設定してください。

Naflexのエクスポート失敗：現在のTAOドキュメントでは、siglip2-so400m-patch16-naflexは学習専用であり、ONNXやTensorRTにはエクスポートできません。siglip2-so400m-patch16-384など、固定解像度のバリアントを使用してください。

ONNXの外部データが見つからない：2 GBを超えるモデルは、ONNXファイルと外部データファイルをエクスポートします。両方のファイルを同じディレクトリに置き、gen_trt_engineの実行前に外部データファイルの名前を変更しないでください。

TensorRTの形状不一致：動的バッチのエクスポートを使用する場合は、すべての入力に対してmin/opt/maxの形状プロファイルを指定してください。テキストのシーケンス長はトークナイザーの長さと一致させる必要があります。一般的には、CLIPトークナイザーで77、SigLIP2トークナイザーで64です。

attention_maskの警告：互換性のため、エクスポートされたグラフでは現在attention_maskを受け付けていますが、TAOはその値を無視し、今後のリリースで削除する可能性があります。マスクの値に依存する新しい直接ONNX推論コードは作成しないでください。

spec.yamlとスキーマのマージエラー：Hydra/OmegaConfの設定検証エラーです。よくある原因は、num_epochsまたはnum_gpusをtrain.*の下ではなくspecのルートに置くことや、学習画像サイズ（model.image_size）とエクスポートの寸法（export.input_heightおよびexport.input_width）を混同することです。

Spec Param／親モデルの推論

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

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

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

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