tao-train-visual-changenet

Visual ChangeNet

独立安装？ 如果此会话不是由 TAO skill bank 插件初始化的，请先运行 tao-setup 技能（主机预检、凭据、跨技能发现）。

Visual ChangeNet 是用于视觉检测和缺陷检测的 TAO Toolkit 模型。它支持两项任务：

• 分类 — 使用孪生式架构进行二元图像分类，该架构采用共享骨干网络（C-RADIO ViT）和可学习的差异模块。比较图像对，将缺陷分类为 PASS/NO_PASS。
• 分割 — 使用 ViT-Large NVDINOv2 骨干网络进行像素级变化分割。比较前后图像对，生成二元变化掩码。

分类支持公开的 C-RADIOv2-B 骨干网络和六种冻结的 DINOv3 变体。选择 DINOv3 前，请阅读 references/dinov3-backbones.md；其中 包含准确的变体映射、冻结要求、Hugging Face 访问规则 和本地暂存覆盖说明。对于 C-RADIO，请使用随附的 scripts/stage_backbone.py 和 references/local-docker.md 中的挂载配置。

分割规格使用 model.backbone.type: vit_large_nvdinov2 和 NVDINOv2 检查点系列。请确保检查点架构与骨干网络类型一致：NV_DINOV2_518_16_256.ckpt 与打包的分割模板兼容，但不得与 fan_small_12_p4_hybrid 一起使用。如果 切换到其他分割骨干网络，请使用匹配的检查点，或将 model.backbone.pretrained_backbone_path 留空，以使用默认初始化。

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、默认值、最小值/最大值界限、枚举、选项权重、数学条件、依赖项和热门参数，请使用打包的训练架构。不要期望运行时存在 ~/tao-core；维护者会在打包技能库之前重新生成架构和模板。

训练操作策略

此模型在模型层启用了 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。保留工作流／应用对数据集、规格文件、输出目录、GPU／平台设置、父检查点和 automl_policy 的覆盖设置。仅当 automl_policy: off 或缺少已打包的训练 schema／模板时，才直接进行模型训练；若缺少 schema，请说明此模型已启用 AutoML，但在生成 schema 前无法运行 AutoML。

检查点保留是一项编排策略，而不是 HPO 参数。两个已打包的训练模板都默认将 train.checkpointer.enable_topk 和 train.checkpointer.replace_periodic 设为 false，以保留由 train.checkpoint_interval 控制的定期保存。启用 AutoML 检查点保留后，AutoML 运行器会将这两个标志都设为 true，以 min 模式监控 val_loss，并使用 save_top_k: 1；这会以单个最佳检查点取代定期保存序列。禁用 AutoML 检查点保留后，请勿设置有界保留覆盖项，以保留定期检查点行为。

此模型技能声明的非训练操作（evaluate、inference、export、quantize、segment_evaluate 和 segment_inference）仍由此模型技能负责。在 schemas/manifest.json 中打包对应条目之前，不要将 segment_export 或 segment_quantize 列为可运行的父技能操作。当前父技能的 references/skill_info.yaml 未声明 prune 和 retrain；除非元数据扩展并加入相应的操作接线和 schema，否则不要将它们列为可运行的父技能操作。每次运行的 automl_policy 覆盖设置不会更改模型元数据。

对于 TAO Deploy TensorRT 操作（classify 和 segment 变体的 gen_trt_engine、TensorRT evaluate 和 TensorRT inference），请先阅读 references/tao-deploy-visual-changenet.md。Deploy 规格模板位于此技能的 references/ 文件夹中，文件名前缀为 spec_template_deploy_*.yaml。 Deploy 需要将已导出的 ONNX 工件作为 parent_model。如果不存在 ONNX 工件，且主技能未提供 export 操作，请说明 Deploy 受阻，不要虚构工件。

训练要求

Visual ChangeNet 有两种不同的任务模式，各自使用不同的数据集类型和数据源结构。

分类

• 数据集类型： visual_changenet_classify
• 格式： 默认
• 接受的数据集意图： 训练、评估、测试、校准
• 监控指标： val_loss
• 独立评估指标： test_acc（也会输出 test_fpr、test_fnr 和 defect_acc）。AutoML 必须依据训练 val_loss 对推荐方案进行排序；仅使用 test_acc 验证选定的检查点能否成功加载和评估。不要期望 evaluate 操作输出 val_loss。

每项操作的数据集要求（分类）

以下 quantize 和 gen_trt_engine 行仅描述 TAO 规范的数据要求。除非 references/skill_info.yaml 或 deploy/skill_info.yaml 中声明了相应操作，否则它们不是父技能的操作。

操作	规范键	来源	文件	是否列表？
train	dataset.classify.train_dataset.images_dir	train_datasets	images.tar.gz	否
train	dataset.classify.train_dataset.csv_path	train_datasets	dataset.csv	否
train	dataset.classify.validation_dataset.images_dir	eval_dataset	images.tar.gz	否
train	dataset.classify.validation_dataset.csv_path	eval_dataset	dataset.csv	否
quantize	dataset.classify.train_dataset.images_dir	train_datasets	images.tar.gz	否
quantize	dataset.classify.train_dataset.csv_path	train_datasets	dataset.csv	否
quantize	dataset.classify.validation_dataset.images_dir	eval_dataset	images.tar.gz	否
quantize	dataset.classify.validation_dataset.csv_path	eval_dataset	dataset.csv	否
quantize	dataset.classify.quant_calibration_dataset.images_dir	train_datasets	images.tar.gz	否
evaluate	dataset.classify.validation_dataset.images_dir	eval_dataset	images.tar.gz	否
evaluate	dataset.classify.validation_dataset.csv_path	eval_dataset	dataset.csv	否
evaluate	dataset.classify.test_dataset.images_dir	eval_dataset	images.tar.gz	否
evaluate	dataset.classify.test_dataset.csv_path	eval_dataset	dataset.csv	否
inference	dataset.classify.infer_dataset.images_dir	inference_dataset	images.tar.gz	否
inference	dataset.classify.infer_dataset.csv_path	inference_dataset	dataset.csv	否
gen_trt_engine	gen_trt_engine.tensorrt.calibration.cal_image_dir	calibration_dataset	images.tar.gz	是

分割

• 数据集类型： visual_changenet_segment
• 格式： 默认
• 接受的数据集意图： training、calibration
• 监控指标： val_loss

分割任务使用成对的目录结构（A/、B/、list/、label/），而非 CSV + 图像。root_dir 规范键指向包含全部四个子目录的顶层目录。

每个数据集所需文件： A.tar.gz、B.tar.gz、list.tar.gz、label.tar.gz

每项操作的数据集要求（分割）

以下 quantize 和 gen_trt_engine 行仅描述 TAO 规范的数据要求。除非 references/skill_info.yaml 或 deploy/skill_info.yaml 中声明了相应操作，否则它们不是父技能的操作。

操作	规范键	来源	文件	是否列表？
train	dataset.segment.root_dir	train_datasets	（根目录）	否
quantize	dataset.segment.root_dir	train_datasets	（根目录）	否
quantize	dataset.segment.quant_calibration_dataset.images_dir	train_datasets	（根目录）	否
evaluate	dataset.segment.root_dir	train_datasets	（根目录）	否
inference	dataset.segment.root_dir	train_datasets	（根目录）	否
gen_trt_engine	dataset.segment.root_dir	train_datasets	（根目录）	否
gen_trt_engine	gen_trt_engine.tensorrt.calibration.cal_image_dir	calibration_dataset	images.tar.gz	是

典型的规格覆盖

每项操作都必须覆盖数据源 — Agent 必须根据上方的“各操作数据集要求”表构造数据源路径，并将其包含在 spec_overrides 中。

S3_TRAIN = "s3://bucket/data/train"
S3_EVAL = "s3://bucket/data/eval"

train（classify，必需数据源）：

{
    "train.num_epochs": 30,
    "train.checkpoint_interval": 10,
    "train.validation_interval": 10,
    "train.num_gpus": 1,
    "train.use_distributed_sampler": False,
    "train.sync_batchnorm": False,
    "dataset.classify.train_dataset.images_dir": f"{S3_TRAIN}/images.tar.gz",
    "dataset.classify.train_dataset.csv_path": f"{S3_TRAIN}/dataset.csv",
    "dataset.classify.validation_dataset.images_dir": f"{S3_EVAL}/images.tar.gz",
    "dataset.classify.validation_dataset.csv_path": f"{S3_EVAL}/dataset.csv",
}

train（segment，必需数据源）：

{
    "train.num_epochs": 30,
    "train.checkpoint_interval": 10,
    "train.validation_interval": 10,
    "train.num_gpus": 1,
    "train.use_distributed_sampler": False,
    "train.sync_batchnorm": False,
    "dataset.segment.root_dir": f"{S3_TRAIN}",
}

export（classify）：

{
    "export.input_height": 896,
    "export.input_width": 224,
}

export（segment）：

{
    "export.input_height": 224,
    "export.input_width": 224,
}

quantize（classify，必需数据源）：

{
    "dataset.classify.train_dataset.images_dir": f"{S3_TRAIN}/images.tar.gz",
    "dataset.classify.train_dataset.csv_path": f"{S3_TRAIN}/dataset.csv",
    "dataset.classify.validation_dataset.images_dir": f"{S3_EVAL}/images.tar.gz",
    "dataset.classify.validation_dataset.csv_path": f"{S3_EVAL}/dataset.csv",
    "dataset.classify.quant_calibration_dataset.images_dir": f"{S3_TRAIN}/images.tar.gz",
}

evaluate（classify，必需数据源）：

{
    "dataset.classify.validation_dataset.images_dir": f"{S3_EVAL}/images.tar.gz",
    "dataset.classify.validation_dataset.csv_path": f"{S3_EVAL}/dataset.csv",
    "dataset.classify.test_dataset.images_dir": f"{S3_EVAL}/images.tar.gz",
    "dataset.classify.test_dataset.csv_path": f"{S3_EVAL}/dataset.csv",
}

inference（classify，必需数据源）：

{
    "dataset.classify.infer_dataset.images_dir": f"{S3_EVAL}/images.tar.gz",
    "dataset.classify.infer_dataset.csv_path": f"{S3_EVAL}/dataset.csv",
}

gen_trt_engine（classify，必需数据源）：

{
    "gen_trt_engine.tensorrt.calibration.cal_image_dir": [f"{S3_TRAIN}/images.tar.gz"],
}

quantize（segment，必需数据源）：

{
    "dataset.segment.root_dir": f"{S3_TRAIN}",
    "dataset.segment.quant_calibration_dataset.images_dir": f"{S3_TRAIN}",
}

evaluate（segment，必需数据源）：

{
    "dataset.segment.root_dir": f"{S3_TRAIN}",
}

inference（segment，必需数据源）：

{
    "dataset.segment.root_dir": f"{S3_TRAIN}",
}

gen_trt_engine（segment，必需数据源）：

{
    "dataset.segment.root_dir": f"{S3_TRAIN}",
    "gen_trt_engine.tensorrt.calibration.cal_image_dir": [f"{S3_TRAIN}/images.tar.gz"],
}

通过本地 Docker 运行

使用固定版本的 TAO pyt 镜像，并直接调用 visual_changenet <train|evaluate|inference|export|quantize>。必须设置 --shm-size=8g，并将 C-RADIO .safetensors 挂载到 /data/pretrained_models/C-RADIOv2_B.safetensors；checkpoint/results_dir 可在命令行中覆盖。完整的 docker run 命令、挂载项和覆盖项请参阅 references/local-docker.md。

任务

Classify（默认）

使用以下操作：train、evaluate、inference。默认模板：references/spec_template_train.yaml。evaluate / inference 需要使用 results_dir 下此前通过 7.1 版 train 得到的 checkpoint — NGC 上没有预训练的 7.1 classify checkpoint（7.0 时代的 visual_changenet_nvpcb_trainable_v1.0 在 7.1 上加载时会因 radio.* KeyError 而失败）。在全新的工作区中，先从公开主干网络开始训练；不要尝试下载 NGC full_model classify checkpoint，也不要硬编码 NGC 组织名。

Segment

使用技能操作名称 segment_train、segment_evaluate 和 segment_inference。直接调用本地 Docker 时，在规格中设置 task: segment，并运行 TAO CLI 子命令 train、evaluate 和 inference。架构驱动的操作模板为 references/spec_template_segment_train.yaml、 references/spec_template_segment_evaluate.yaml 和 references/spec_template_segment_inference.yaml；精简的直接 Docker 示例模板为 references/spec_template_segment.yaml。

分割首次运行时需要编译自定义 CUDA 算子（MultiScaleDeformableAttention），这大约需要 5 分钟。ViT adapter 主干网络使用这些算子进行多尺度特征提取。

分割的数据集结构不同于 classify — 使用成对目录（A/、B/、list/、label/），而不是 CSV 文件。请参阅默认配置中的 dataset.segment.root_dir。

数据格式

Classify 需要一个 4 列 CSV（input_path,golden_path,label,object_name）以及一个图像目录；segment 使用 dataset.segment.root_dir 下的成对目录结构（A/、B/、list/、label/），而不是 CSV。image_ext字段（默认值为.jpg）必须与实际文件扩展名一致；如果图像为 .png，请设置 dataset.classify.image_ext: .png。通过 dataset.classify.input_map配置多光照输入（每个光照名称映射到一个通道索引），并将dataset.classify.num_input设置为匹配的值。各字段的输入表（classify train/eval/inference、segment）、CSV 列语义、光照和路径拼接约定、segment 目录布局，以及input_map/grid_map示例，请参阅references/data-formats.md`。

预检：验证 classify 数据集（每次运行 classify 前必须执行）

启动 classify train、evaluate 或 inference 作业前，请验证 CSV，确保格式错误的数据集能在主机上 <1s 内触发失败，而不是等到 GPU 容器运行数分钟后才失败（对于单类别训练集，则可能要等到写入检查点后才会失败）。运行：

python3 skills/models/tao-train-visual-changenet/scripts/validate_vcn_dataset.py \
  --csv        <abs path to dataset.csv> \
  --images-dir <abs path to images dir> \
  --mode       train \
  --batch-size <dataset.classify.batch_size> --num-gpus <train.num_gpus>
# --mode: train | evaluate | inference

退出代码为 0 → 启动作业。退出代码为 2 → **修复数据集，不要启动作业。**该脚本会拒绝绝对 CSV 路径、需要按样本提供目录却使用了扁平文件名的情况、单类别训练集，以及批次大小大于数据集的情况。关于每项检查的约定以及 --light / --image-ext 选项，请参见 references/data-formats.md。

重要参数

关键参数包括 train.validation_interval（默认值为 50，必须 ≤ num_epochs）、train.checkpoint_interval（默认值为 200，启用周期性检查点时必须 ≤ num_epochs）、train.num_epochs（默认值为 100）、model.classify.eval_margin（默认值为 0.3，即精确率/召回率阈值）、model.classify.train_margin_euclid（默认值为 2.0）、model.classify.embedding_vectors（默认值为 5）、dataset.classify.batch_size（默认值为 16，必须 > 1）、dataset.classify.fpratio_sampling（默认值为 0.25），以及 train.classify.cls_weight（默认值为 [1.0, 10.0]）。train.checkpointer 字段是固定的生命周期控制项，不是 HPO 搜索参数。硬件要求：至少 1 个 GPU，显存为 16GB+；建议使用 8 个 GPU（DDP）。不要设置 gpu_spec_key（GPU 数量由 TAO 在内部管理）；num_nodes（默认值为 1）用于控制多节点。每个参数的详细说明和硬件信息，请参见 references/tuning-parameters.md。

错误模式

关于未找到检查点、CSV 格式不匹配、图像扩展名不匹配、OOM、评估准确率低、对比损失 AssertionError、evaluate/inference 时检查点加载键不匹配、未收敛、仅分段骨干网络维度不匹配、MultiScaleDeformableAttention OSError、Lightning MisconfigurationException、ModuleNotFoundError: nvidia_tao_pytorch 以及 epoch 默认值，请参见 references/troubleshooting.md 中完整的症状与修复方法列表。

Spec 参数 / 父模型推断

特定模型的父模型映射在 references/skill_info.yaml 的 spec_params 下声明，因此 Agent 会在启动作业前解析检查点，而不是猜测文件名。对于 parent_model 或 parent_model_folder，请将上游 train/export/AutoML 子作业 ID 作为父作业 ID；列出父结果文件夹，筛选检查点产物，然后选择解析出的模型文件或文件夹。每种操作的 spec 字段到推断函数的完整映射表，请参见 references/parent-model-inference.md。

部署

• tao-deploy-visual-changenet