tao-finetune-clip

CLIP

单独安装？ 请阅读 CLIP 单独安装指南，并在运行 tao-setup 或启动 CLIP 操作之前验证 bank checkout。

用于零样本和微调图像分类、图文检索及嵌入提取的对比式语言-图像预训练模型。微调可将 CLIP 共享的图像-文本嵌入空间适配到特定领域的图像-说明数据。

构建 spec 不需要默认的 NGC 预训练检查点，但未设置检查点时的行为取决于具体操作。在修复验证问题的 PyTorch 镜像中，export.checkpoint: null 会导出所选的 CLIP 架构；如果预训练权重不可用，则可能会初始化权重。不要假设 inference.checkpoint: null 会加载预训练权重：当前 clip inference 会使用 None 调用检查点加载器，并在提取嵌入之前失败。对于 PyTorch 推理、基于检查点的评估/导出、恢复训练和重新训练流程，请从上游训练输出中解析并传入确切的检查点。对于由当前运行或已知上游任务生成的可信 TAO 检查点，请在依赖检查点的 PyTorch 操作上设置 TORCH_FORCE_NO_WEIGHTS_ONLY_LOAD=1，以便 PyTorch 2.6 加载 Lightning 检查点元数据；不要对不可信的检查点设置此变量。

支持的操作：train、evaluate、inference、export、gen_trt_engine。

训练操作策略

该模型在模型层启用了 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 时，默认通过 tao-skill-bank:tao-run-automl 执行训练操作，并使用此模型的 skill_dir。保留工作流/应用的覆盖设置，包括数据集、spec、输出目录、GPU/平台设置、上游检查点和 automl_policy。仅当 automl_policy: off 或缺少已打包的训练 schema/template 时，才直接训练模型；如果缺少 schema/template，请说明 AutoML 已启用，但在生成 schema 之前无法用于此模型。

已打包的 CLIP 训练 schema 将 train.optim.vision_lr 和 train.optim.text_lr 设为默认 AutoML 搜索参数。对于冒烟测试，请使用贝叶斯算法、两次推荐和较窄的 LR 范围，以缩小搜索规模。

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。如果探测未提供完整的适配器契约（启用标志/配置、目标模块、秩、alpha、dropout、检查点行为），则报告该图像不支持 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 查看完整的规范结构，并使用 references/tao-deploy-clip.md 了解 TensorRT 操作。

对于依赖数据集的操作，请向用户收集所需的图像、字幕、列表或提示词文件，并将解析后的路径放入 spec_overrides。对于本地 Docker 运行，将解压后的文件夹挂载到容器中，并将 image_dir / caption_dir 指向这些文件夹；如果数据源提供 .tar.gz 存档，则在运行容器内的 CLIP 命令前先解压。对于 export 和 gen_trt_engine，若上游作业可用，则从中推断父级产物；否则须明确指定检查点、ONNX 或引擎路径。在 TAO Deploy 图像中运行 gen_trt_engine、TensorRT evaluate 和 TensorRT inference。

对于 TAO Deploy TensorRT 操作（gen_trt_engine、TensorRT evaluate 和 TensorRT inference），请先阅读 references/tao-deploy-clip.md。部署规范模板位于此技能的 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 会写入 CSV，而不是 test/* 标量。要进行同类比较，请使用相同的检查点和验证子集，设置 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 搜索空间之前，请阅读 CLIP PEFT 指南，了解各塔字段、默认值、 骨干网络目标模块、数值范围、从塔的 enabled 迁移到 mode，以及编码器冻结优先级。peft 和 regularization 是 顶层规格块；请遵循所选运行时的配置契约。

在塔的 mode 契约下启用 PEFT 时，塔模式优先于 model.freeze_*_encoder：frozen 会冻结塔，full 会训练塔，而 lora 会在冻结骨干网络的情况下训练适配器。移除相互冲突的冻结标志，并核实各塔的可训练参数数量。

LoRA 检查点包含完整模型；请为完整模型存储预留空间。 保持正则化会在 GPU 上额外加载一个完整的冻结教师模型，并执行一次教师前向传播。对于推荐的 SigLIP2 PAS 运行，请保持 regularization.enabled: false：保持损失尚未在此类运行中得到充分验证。 教师模型不会包含在检查点中。

各操作的数据集要求

操作	规格键	来源	文件	是否为列表？
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	父训练作业或显式指定的检查点	checkpoint .pth；导出预训练模型时可选	否
gen_trt_engine	gen_trt_engine.onnx_file	父导出作业或显式指定的 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 是一个文本文件，每行列出一个分片路径；相对路径默认相对于列表文件所在目录解析；如果同时提供 root_dir，则相对于 root_dir 解析。验证/评估数据仍使用自定义格式，通过 dataset.val.datasets 配置。

典型规格覆盖项

对于基于数据集的操作，必须覆盖数据源。根据“各操作的数据集要求”表构造路径，并将其包含在 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.trt_engine，而不是 evaluate.checkpoint。

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。分离导出会生成 _vision.onnx 和 _text.onnx 变体，文件名由基础 export.onnx_file 派生。

对于依赖检查点的操作，请使用父级 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 默认会以仅权重模式加载检查点，并可能拒绝包含 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"]，并在 TAO Deploy 镜像中运行，而不是在 PyTorch 训练镜像中运行。容器内的命令为 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：先将 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：主干网络系列和分辨率。请使用已在 TAO 注册的 CLIP 模型 ID，例如 ViT-L-14-SigLIP-CLIPA-224。对于 AutoML 冒烟测试，优先使用列出的 OpenCLIP / NV-CLIP ID，因为当前 TAO 容器注册表会通过受支持的增强适配器处理这些模型。
• model.adaptor_name：Radio-CLIP 必填。设置为 siglip 或 clip。
• model.image_size：训练变换的图像分辨率。请与所选的固定分辨率主干网络保持一致。
• train.num_epochs：CLIP 微调通常能快速收敛。领域适配可从 10-20 个 epoch 开始；只有在验证损失仍在下降时才增加。
• train.optim.vision_lr / train.optim.text_lr：两个编码器的学习率。CLIP 对较高的学习率较为敏感；如果损失不稳定，请同时降低这两个学习率。
• model.freeze_vision_encoder / model.freeze_text_encoder：默认值为 false。当 peft.enabled: false 时，这些标志控制编码器是否冻结。在启用 PEFT 并采用塔的 mode 约定时，peft.vision.mode / peft.text.mode 会覆盖这些标志，即使两者设置不一致：full 表示训练编码器，frozen 表示冻结编码器，lora 表示训练适配器。请参阅 PEFT 优先级，并移除冲突的冻结标志。
• train.loss_type：推荐 SigLIP2 和 Radio-CLIP 使用 siglip。CLIP 风格的 softmax 损失请使用 clip。
• export.encoder_type：combined 导出一个 ONNX 图。separate 分别导出视觉和文本图。
• gen_trt_engine.tensorrt.data_type：TensorRT 部署支持 fp16 和 fp32。

硬件

小型数据集可使用单 GPU 训练。对于图像数量超过 100k 的数据集或大型主干网络，请使用 4 个及以上 GPU。若关闭保留正则化并进行小规模／固定分辨率运行，每个 GPU 至少需要 16GB 显存；对于 Radio-CLIP 或高分辨率 OpenCLIP 变体，请使用显存更大的 GPU。

上述 16GB 及以上显存建议未计入 regularization.enabled: true 时创建的额外完整教师模型。如果要测试正则化，请为第二个模型及其前向传播中间结果预留显存；针对实际使用的主干网络和批大小测量峰值显存与步耗时，并根据需要降低 dataset.train.batch_size 或使用更大的 GPU。额外的显存占用取决于模型的常驻数据类型；仅设置 train.precision: fp16 并不能保证教师模型权重会以半精度存储。

错误模式

完整的 CLIP 错误症状和修复方法列表请参阅 references/error-patterns.md（包括 CUDA OOM、NaN 损失、检索质量、数据集格式／大小、Radio-CLIP 和模型 ID 验证、ONNX 外部数据、TensorRT 形状不匹配、PyTorch 2.6 检查点加载、空检查点推理、TensorRT 文本／检索故障、attention_mask 处理以及规范／模式合并错误）。

规范参数／父模型推理

请参阅 references/spec-param-inference.md，了解打包的、特定于模型的操作／规范字段／推理函数映射。生成的运行器会在调用 create_job() 前使用 SDK 辅助函数应用这些映射，其中还包括 parent_job_id 解析规则。

部署

• tao-deploy-clip