tao-finetune-clip

CLIP

スタンドアロンでインストールしますか？ CLIP standalone setupを読み、tao-setupを実行する前、またはCLIPアクションを起動する前に、バンクのチェックアウトを確認してください。

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

仕様の構築にデフォルトのNGC事前学習済みチェックポイントは必要ありませんが、チェックポイントが未設定の場合の動作はアクションによって異なります。検証修正済みのPyTorchイメージでは、export.checkpoint: nullを指定すると、選択したCLIPアーキテクチャをエクスポートし、事前学習済みの重みが利用できない場合は重みが初期化されることがあります。inference.checkpoint: nullを指定すると事前学習済みの重みが読み込まれるとは限りません。現在のclip inferenceはチェックポイントローダーにNoneを渡して呼び出すため、埋め込み抽出の前に失敗します。PyTorchでの推論、チェックポイントを使用する評価／エクスポート、再開、再学習の各フローでは、親トレーニングの出力から正確なチェックポイントを特定して渡してください。現在の実行で生成された信頼できるTAOチェックポイント、または既知の親ジョブのチェックポイントを使用する場合は、PyTorch 2.6でLightningチェックポイントのメタデータを読み込めるよう、チェックポイントに依存するPyTorchアクションでTORCH_FORCE_NO_WEIGHTS_ONLY_LOAD=1を設定してください。信頼できないチェックポイントに対しては設定しないでください。

サポートされているアクション：train、evaluate、inference、export、gen_trt_engine。

Train Action Policy

このモデルはモデルレイヤーで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は有効ですが、スキーマが生成されるまでこのモデルでは実行できないことを報告してください。

パッケージに含まれるCLIPのトレーニング用スキーマでは、train.optim.vision_lrとtrain.optim.text_lrがデフォルトのAutoML探索パラメーターとして有効になっています。スモークテストでは、ベイズアルゴリズムを使って推奨数を2つにし、学習率の範囲を狭くして探索規模を小さくしてください。

PAS ファインチューニング手法の統合

新しい PAS DEFT 実行ごとに、ユーザーがまだ手法を選択していない場合は、 相互に排他的な選択肢を尋ねます。

Fine-tuning method: LoRA (default) or full-parameter SFT?

この LoRA をデフォルトとする契約は PAS に適用されます。スタンドアロン CLIP トレーニングでは、 パッケージ化された SFT の画像およびテンプレートの動作が維持され、LoRA はデフォルトになりません。 PAS の画像機能やこの選択表をスタンドアロン CLIP に適用しないでください。

PAS 手法	有効化	無効化	PAS の画像サポート
全パラメーター SFT	両方のエンコーダーのフリーズフラグを false に設定し、peft.enabled: false にする	LoRA を選択する	対応
LoRA（デフォルトの選択）	peft.enabled: true、peft.method: lora、およびネストされた vision／text アダプターブロックを設定する	peft.enabled: false に設定し、SFT 設定を使用する	SigLIP2 で対応。ターゲットには q_proj、k_proj、v_proj、out_proj を使用する

画像機能のプローブは、起動を伴う docker run であるため、実行前に承認概要に含めてください。 ドキュメント、イメージタグ、または認識されない Hydra オーバーライドは、LoRA サポートの証明にはなりません。 プローブで完全なアダプター契約（有効化フラグ／設定、ターゲットモジュール、 ランク、アルファ、ドロップアウト、チェックポイントの動作）が確認できない場合は、 そのイメージで LoRA は未サポートと報告し、実行内容を確定する前に停止してください。

evaluate、inference、export、デプロイフローなどのトレーニング以外のアクションは、このモデルスキルで扱います。実行ごとの automl_policy オーバーライドによってモデルのメタデータは変わりません。

手順

NVIDIA TAO CLIP のジョブ（トレーニング、評価、埋め込み推論、ONNX エクスポート、TensorRT エンジン生成）には、このスキルを使用します。まず要求されたアクションを特定し、次に references/skill_info.yaml を読んでイメージ、コマンド、データソースの接続方法を確認します。続いて、パッケージ化されている場合は references/spec_template_<action>.yaml でアクションのデフォルト設定を、schemas/<action>.schema.json でパラメーターのメタデータを確認します。完全な仕様の形式には references/spec_template.yaml を、TensorRT アクションには references/tao-deploy-clip.md を使用します。

データセットを使用するアクションでは、ユーザーから必要な画像、キャプション、リスト、またはプロンプトのファイルを受け取り、解決したパスを spec_overrides に設定します。ローカル Docker 実行では、展開済みのフォルダーをコンテナにマウントし、image_dir／caption_dir にそのフォルダーを指定します。データソースが .tar.gz アーカイブを提供する場合は、コンテナ内で CLIP コマンドを実行する前に展開してください。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 の仕様テンプレートは、このスキルの references/ フォルダーにあり、spec_template_deploy_*.yaml というプレフィックスが付いています。

トレーニング要件

• データセットの種類： image_text
• 形式： カスタムの画像／キャプションフォルダー、または WebDataset シャード
• モニタリング指標： キャプションを対応付けた検索では val/t2i_mAP、 PAS メタデータの照合では val/pas/overall_mAP

PAS の AutoML 目的関数を選択する前、またはトレーニングと評価を比較する前に、 PAS 指標のガイダンスを読んでください。PAS の検証ログには val/pas/{easy,medium,hard,overall}_{mAP,rank1,rank5} が記録されます。スタンドアロン PAS evaluate では test/* スカラーではなく CSV が出力されます。同条件で比較するには、同じチェックポイントと 検証サブセットを使用し、evaluate.pas_ground_truth_mode: scalar_attributes を設定して、 nvidia_pas_metadata_metrics_weighted_aggregate.csv を確認してください。

サポート対象モデル

• 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: c-radio_v3-b、c-radio_v3-l、c-radio_v3-h、c-radio_v3-g
• 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 を使用する場合は、model.adaptor_name に siglip または clip を設定する必要があります。

タワーの mode の仕様では、OpenCLIP は full / frozen をサポートしますが、 lora はサポートしません。バックボーンサポートを参照してください。

LoRA と保持正則化

LoRA 仕様または PEFT AutoML の探索空間を構築する前に、 タワーごとのフィールド、デフォルト値、バックボーンのターゲットモジュール、 数値範囲、タワーの enabled から mode への移行、エンコーダーの凍結の優先順位について、 CLIP PEFT ガイダンスを確認してください。peft と regularization は 仕様のトップレベルブロックです。選択したランタイムの設定仕様を使用してください。

タワーの mode の仕様で PEFT を有効にすると、タワーのモードが model.freeze_*_encoder より優先されます。frozen はタワーを凍結し、full はタワーを学習し、 lora はバックボーンを凍結したままアダプターを学習します。競合する凍結フラグを削除し、 タワーごとの学習可能なパラメーター数を確認してください。

LoRA チェックポイントにはモデル全体が含まれるため、モデル全体のストレージ容量を見込んでください。 保持正則化では、GPU 上に完全に凍結された教師モデルを追加し、教師モデルのフォワードパスを実行します。 推奨される SigLIP2 PAS の実行では、保持損失の検証がまだ完了していないため、 regularization.enabled: false のままにしてください。 教師モデルはチェックポイントから除外されます。

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

アクション	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 は任意です。

一部の画像だけを使って推論を実行するには、選択した画像のみを別のディレクトリに配置し、inference.datasets[].image_dir にそのディレクトリを設定します。

ネイティブの CLIP 画像・キャプションデータセットを利用できない場合、画像分類データを CLIP データとして黙って扱わないでください。ユーザーが配線のみの検証フォールバックを明示的に許可した場合は、クラスラベルからキャプションファイルを生成し、キャプションがラベルから生成されたことを明記したうえで、各画像とキャプションのベース名を同じにしてください。image_list_file がない場合、TAO カスタムローダーは設定された画像ディレクトリをスキャンして画像ファイルを探します。リストファイルを指定しない場合は、検証用フォルダーをフラットな構成にしてください。

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 を使用します。

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

データセットを使用するアクションでは、データソースのオーバーライドが必須です。Per-Action Dataset Requirements テーブルに従ってパスを構成し、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 のバリアントが書き込まれます。

チェックポイントに依存するアクションでは、親 train ジョブのモデル固有チェックポイントリゾルバーの出力を使用してください。CLIP のトレーニングでは、model_epoch_000_step_00020.pth などのチェックポイントと、clip_latest.pth シンボリックリンクが書き込まれます。evaluate.checkpoint、inference.checkpoint、export.checkpoint、train.resume_training_checkpoint_path には、解決されたチェックポイントを正確に指定してください。clip_latest.pth は、ユーザーが明示的に最新のものを求めた場合にのみ使用してください。

LoRA チェックポイントの場合、PyTorch の evaluate、inference、export の各仕様では、トレーニング時のモデル設定とトップレベルの peft ブロック全体を保持してください。これらの仕様を構成する前に、チェックポイントの設定を確認してください。アクションのデフォルト設定だけでは PEFT が反映されません。

解決されたチェックポイントが信頼済みの TAO 出力である場合、チェックポイントを使用する PyTorch の evaluate、inference、export、およびトレーニング再開は、TORCH_FORCE_NO_WEIGHTS_ONLY_LOAD=1 を設定して実行してください。PyTorch 2.6 では、デフォルトでチェックポイントの読み込みが weights-only モードになり、NumPy のスカラー型メタデータを含む CLIP Lightning チェックポイントが拒否される場合があります。

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.engine／_text.engine ファイルを検出できます。TensorRT による完全な検索評価、または画像とテキストの TensorRT 推論を行うには、export.encoder_type: separate でエクスポートし、clip gen_trt_engine を 2 回実行します。まず clip_model_vision.onnx から _vision.engine で終わるエンジンを作成し、次に同じディレクトリ内で clip_model_text.onnx から対応する _text.engine を作成します。画像のみの TensorRT 推論では、_vision.engine だけを作成すれば十分であり、inference.text_file は null にする必要があります。TensorRT の evaluate とテキスト推論にはテキスト対応エンジンが必要です。ビジョンエンジンしかない場合、テキスト埋め込みを抽出できないため、デプロイ評価は失敗します。

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

重要なパラメーター

• model.type：バックボーンのファミリーと解像度です。ViT-L-14-SigLIP-CLIPA-224 など、TAO に登録されている CLIP モデル ID を使用してください。AutoML のスモークテストでは、一覧にある OpenCLIP / NV-CLIP ID を優先してください。現在の TAO コンテナーレジストリでは、これらの ID がサポート対象の拡張アダプター経由で処理されるためです。
• 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 です。これらのフラグは、peft.enabled: false の場合にエンコーダーを凍結するかどうかを制御します。タワーの mode 契約で PEFT が有効になっている場合は、設定が異なっていても peft.vision.mode / peft.text.mode が優先されます。full はエンコーダーを学習し、frozen は凍結し、lora はアダプターを学習します。PEFT の優先順位を参照し、競合する凍結フラグを削除してください。
• 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 を使用してください。

16GB 以上という推奨値には、regularization.enabled: true によって作成される追加のフルサイズ教師モデルは含まれていません。正則化をテストする場合は、その 2 つ目のモデルとフォワードパスの中間データ用に VRAM を確保し、実際のバックボーンとバッチサイズでピークメモリー使用量とステップ時間を測定してください。必要に応じて dataset.train.batch_size を減らすか、より大容量の GPU を使用してください。追加のメモリー使用量はモデルの常駐データ型によって異なります。train.precision: fp16 を指定しても、教師モデルの重みが半精度で格納されるとは限りません。

エラーパターン

CLIP のエラー症状と対処法の一覧（CUDA OOM、NaN 損失、検索品質、データセットの形式／サイズ、Radio-CLIP とモデル ID の検証、ONNX の外部データ、TensorRT の形状不一致、PyTorch 2.6 のチェックポイント読み込み、null チェックポイントでの推論、TensorRT のテキスト／検索エラー、attention_mask の処理、spec/schema のマージエラー）については、references/error-patterns.md を参照してください。

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

生成されたランナーが create_job() の前に SDK ヘルパーを使用して適用する、パッケージ化されたモデル固有のアクション／spec フィールド／推論関数のマッピングと、parent_job_id の解決ルールについては、references/spec-param-inference.md を参照してください。

デプロイ

• tao-deploy-clip