Visual ChangeNet-Classification - NVIDIA 文档

Visual ChangeNet-Classification 是 NVIDIA 开发的分类变化检测模型，包含在 TAO 中。Visual ChangeNet 支持以下任务

训练
评估
推理
导出

这些任务可以使用命令行上的以下约定从 TAO Launcher 调用

复制
已复制！

            
            tao model visual_changenet <sub_task> <args_per_subtask>

其中 args_per_subtask 是给定子任务所需的命令行参数。每个子任务将在以下章节中详细解释。

VisualChangeNet 的数据输入

VisualChangeNet-Classification 要求以图像和 CSV 文件的形式提供数据。有关 VisualChangeNet-Classification 的输入数据格式的更多信息，请参阅数据标注格式页面，其输入数据格式与光学检测相同。

创建训练实验规范文件

配置自定义数据集

本节提供了使用上述数据集格式训练 VisualChangeNet-Classification 的示例配置和命令。

这是一个使用 NVIDIA 的 FAN Hybrid 主干网络训练 VisualChangeNet-Classification 模型的示例规范文件，使用了数据标注格式。

复制
已复制！

            
            encryption_key: tlt_encode
task: classify
train:
  pretrained_model_path: /path/to/pretrained/model.pth
  resume_training_checkpoint_path: null
  classify:
    loss: "ce"
    cls_weight: [1.0, 10.0]
  num_epochs: 10
  num_nodes: 1
  validation_interval: 5
  checkpoint_interval: 5
  seed: 1234
  optim:
    lr: 0.0001
    optim: "adamw"
    policy: "linear"
    momentum: 0.9
    weight_decay: 0.01
  results_dir: "${results_dir}/train"
  tensorboard:
    enabled: True
results_dir: /path/to/experiment_results
model:
  backbone:
    type: "fan_small_12_p4_hybrid"
    pretrained_backbone_path: null
    freeze_backbone: False
  decode_head:
    feature_strides: [4, 8, 16, 16]
  classify:
    train_margin_euclid: 2.0
    eval_margin: 0.005
    embedding_vectors: 5
    embed_dec: 30
    difference_module: 'learnable'
    learnable_difference_modules: 4
dataset:
  classify:
    train_dataset:
      csv_path: /path/to/train.csv
      images_dir: /path/to/img_dir
    validation_dataset:
      csv_path: /path/to/val.csv
      images_dir: /path/to/img_dir
    test_dataset:
      csv_path: /path/to/test.csv
      images_dir: /path/to/img_dir
    infer_dataset:
      csv_path: /path/to/infer.csv
      images_dir: /path/to/img_dir
    image_ext: .jpg
    batch_size: 16
    workers: 2
    fpratio_sampling: 0.2
    num_input: 4
    input_map:
      LowAngleLight: 0
      SolderLight: 1
      UniformLight: 2
      WhiteLight: 3
    concat_type: linear
    grid_map:
      x: 2
      y: 2
    image_width: 128
    image_height: 128
    augmentation_config:
      rgb_input_mean: [0.485, 0.456, 0.406]
      rgb_input_std: [0.229, 0.224, 0.225]
    num_classes: 2
evaluate:
  checkpoint: "???"
inference:
  checkpoint: "???"
export:
  gpu_id: 0
  checkpoint: "???"
  onnx_file: "???"
  input_width: 128
  input_height: 512

参数	数据类型	默认值	描述	支持的值
`model`	字典配置	–	模型架构的配置
`dataset`	字典配置	–	数据集的配置
`训练`	字典配置	–	训练任务的配置
`评估`	字典配置	–	评估任务的配置
`推理`	字典配置	–	推理任务的配置
`encryption_key`	字符串	无	用于加密和解密模型文件的加密密钥
`results_dir`	字符串	/results	保存实验结果的目录
`导出`	字典配置	–	ONNX 导出任务的配置
`task`	字符串	classify	指示变化检测任务的标志。支持两个任务：‘segment’ 和 ‘classify’，分别用于分割和分类

训练

参数	数据类型	默认值	描述	支持的值
`num_gpus`	无符号整数	1	用于分布式训练的 GPU 数量	>0
`gpu_ids`	List[int]	[0]	用于分布式训练的 GPU 索引
`seed`	无符号整数	1234	用于 random、NumPy 和 torch 的随机种子	>0
`num_epochs`	无符号整数	10	运行实验的总 epoch 数	>0
`checkpoint_interval`	无符号整数	1	保存检查点的 epoch 间隔	>0
`validation_interval`	无符号整数	1	运行验证的 epoch 间隔	>0
`resume_training_checkpoint_path`	字符串		从中恢复训练的中间 PyTorch Lightning 检查点
`results_dir`	字符串	/results/train	保存训练结果的目录
`classify`	字典字符串列表	无 ce	`classify` 字典包含 VisualChangeNet 分类管道的可配置参数，参数如下 * `loss`：用于分类训练的损失函数。 * `cls_weights`：用于不平衡数据集分布的交叉熵损失的权重。
`segment`	字典字符串列表	无 ce [0.5, 0.5, 0.5, 0.8, 1.0]	`segment` 字典包含 VisualChangeNet 分割管道的可配置参数，参数如下 * `loss`：用于分割训练的损失函数。 * `weights`：当 multi_scale_train 为 “True” 时，用于计算训练期间多尺度分割损失的权重列表
`num_nodes`	无符号整数	1	节点数。如果该值大于 1，则启用多节点。
`pretrained_model_path`	字符串	–	用于初始化端到端模型权重的预训练模型检查点路径。
`optim`	字典配置	无	包含 VisualChangeNet 优化器的可配置参数，详见 optim 部分。
`tensorboard`	字典配置	无 True	使用包含可配置参数的字典启用 TensorBoard 可视化 * `enabled`：启用 TensorBoard 的标志。

optim

复制
已复制！

            
            optim:
  lr: 0.0001
  optim: "adamw"
  policy: "linear"
  momentum: 0.9
  weight_decay: 0.01

参数	数据类型	默认值	描述	支持的值
`lr`	浮点数	0.0005	学习率	>=0.0
`optim`	字符串	adamw
`policy`	字符串	linear	学习率调度器 * `linear`：LambdaLR 按乘法因子减小 `lr`。 * `step`：StepLR 在每个 `num_epochs`//3 时将 `lr` 减小 0.1	linear/step
`momentum`	浮点数	0.9	AdamW 优化器的动量
`weight_decay`	浮点数	0.1	权重衰减系数
`monitor_name`	字符串	val_loss	用于保存 top-k 检查点的监视器名称。

以下示例 model 配置提供了更改用于训练的 VisualChangeNet-Classification 架构的选项。VisualChangeNet-Classification 支持两种模型架构。架构 1 仅利用 FAN 主干网络的最后一个特征图，使用欧几里得距离进行对比学习。架构 2 利用 VisualChangeNet-Classification 可学习的差异模块，在 3 个特征分辨率下针对 4 个不同的特征，以最小化交叉熵损失。

复制
已复制！

            
            model:
  backbone:
    type: "fan_small_12_p4_hybrid"
    pretrained_backbone_path: null
    freeze_backbone: False
  decode_head:
    feature_strides: [4, 8, 16, 16]
    align_corner: False
  classify:
    train_margin_euclid: 2.0
    eval_margin: 0.005
    embedding_vectors: 5
    embed_dec: 30
    difference_module: 'learnable'
    learnable_difference_modules: 4

参数 数据类型 默认值 描述 支持的值

backbone

字典
字符串

布尔值
布尔值

无

无
False
False

一个字典，包含 VisualChangeNet-Classification 主干网络的以下可配置参数
* type：要使用的主干网络的名称

* pretrained_backbone_path：预训练主干网络权重文件的路径
* freeze_backbone：是否在训练期间冻结主干网络权重
* feat_downsample：是否在 FAN 主干网络配置中下采样最后一个特征图

fan_tiny_8_p4_hybrid
fan_large_16_p4_hybrid
fan_small_12_p4_hybrid
fan_base_16_p4_hybrid
vit_large_nvdinov2

decode_head

字典

布尔值
列表
字典
列表

无

False
[4, 8, 16, 16]

256

一个字典，包含解码器的以下可配置参数

* align_corners：如果设置为 True，则输入和输出张量将通过其角像素的中心点对齐，从而保留角像素的值。
* feature_strides：不同主干网络的下采样特征步幅。
* decoder_params：包含以下网络参数

* embed_dims：嵌入维度

True, False

classify

字典
字符串

无
2.0

5
30
learnable
4

一个字典，包含 VisualChangeNet-Classification 模型的以下可配置参数
* train_margin_euclid：对比学习的训练边距阈值（适用于架构 1）
* eval_margin：评估边距阈值
* embedding_vectors：计算欧几里得距离之前，每个输入图像的输出嵌入维度（适用于架构 1）
* embed_dec：Transformer 解码器 MLP 嵌入维度（适用于架构 2）
* difference_module：使用的差异模块类型（适用于两种架构）
* learnable_difference_modules：可学习差异模块的数量（适用于架构 2）

>0
>0
>0
>0
Euclidean, learnable
<4

数据集

dataset 参数定义数据集来源、训练批次大小、数据增强和预处理。下面提供了一个 dataset 示例。

复制
已复制！

            
            dataset:
  classify:
    train_dataset:
      csv_path: /path/to/train.csv
      images_dir: /path/to/img_dir
    validation_dataset:
      csv_path: /path/to/val.csv
      images_dir: /path/to/img_dir
    test_dataset:
      csv_path: /path/to/test.csv
      images_dir: /path/to/img_dir
    infer_dataset:
      csv_path: /path/to/infer.csv
      images_dir: /path/to/img_dir
    image_ext: .jpg
    batch_size: 16
    workers: 2
    fpratio_sampling: 0.2
    num_input: 4
    input_map:
      LowAngleLight: 0
      SolderLight: 1
      UniformLight: 2
      WhiteLight: 3
    concat_type: linear
    grid_map:
      x: 2
      y: 2
    image_width: 128
    image_height: 128
    augmentation_config:
      rgb_input_mean: [0.485, 0.456, 0.406]
      rgb_input_std: [0.229, 0.224, 0.225]
    num_classes: 2

* 有关指定照明条件的更多信息，请参阅数据集标注格式定义。

参数	数据类型	默认值	描述	支持的值
`segment`	字典	–	`segment` 包含分割数据加载器的数据集配置
`classify`	字典	–	`classify` 包含分类数据加载器的数据集配置，详见 classify 部分。

classify

参数	数据类型	默认值	描述	支持的值
`train_dataset`	字典	–	训练数据集的图像目录和 CSV 文件路径
`validation_dataset`	字典	–	验证数据集的图像目录和 CSV 文件路径
`test_dataset`	字典	–	测试数据集的图像目录和 CSV 文件路径
`infer_dataset`	字典	–	推理数据集的图像目录和 CSV 文件路径
`image_ext`	字符串	.jpg	数据集中图像的文件扩展名	字符串
`batch_size`	整数	32	每个批次的样本数	字符串
`workers`	整数	8	用于数据加载的工作进程数
`fpratio_sampling`	整数	0.1	要采样的假阳性示例的比率	>0
`num_input`	整数	4	每个输入图像的照明条件数*	>0
`input_map`	字典	–	照明条件到指定串联顺序的索引的映射*
`concat_type`	字符串	linear	用于不同图像照明条件的串联类型	linear, grid
`grid_map`	字典字典字典配置	无无无	定义网格尺寸以将图像串联为网格的参数 * x：沿 x 轴的图像数量 * y：沿 y 轴的图像数量	字典
`input_width`	整数	100	输入图像的宽度	>0
`input_height`	整数	100	输入图像的高度	>0
`num_classes`	整数	2	数据集中的类别数	>1
`augmentation_config`	字典	无	包含各种数据增强设置的字典，详细信息请参阅 augmentation 部分。

augmentation_config

参数	数据类型	默认值	描述	支持的值
`random_flip`	字典浮点数浮点数 enable	无 0.5 0.5 True	随机垂直和水平翻转数据增强设置。 * `vflip_probability`：垂直翻转的概率。 * `hflip_probability`：水平翻转的概率。 * `enable`：启用或禁用随机翻转数据增强。	>=0.0 >=0.0
`random_rotate`	字典浮点数列表 enable	无 0.5 [90, 180, 270] True	以指定的概率和角度随机旋转图像 * `rotate_probability`：应用随机旋转的概率。 * `angle_list`：要选择的旋转角度列表。 * `enable`：启用或禁用随机旋转数据增强。	>=0.0 >=0.0
`random_color`	字典浮点数浮点数浮点数浮点数 enable 浮点数	无 0.3 0.3 0.3 0.3 True 0.5	对图像应用随机颜色数据增强。 * `brightness`：最大亮度变化因子。 * `contrast`：最大对比度变化因子。 * `saturation`：最大饱和度变化因子。 * `hue`：最大色调变化因子。 * `enabled`：启用或禁用随机颜色数据增强。 * `color_probability`：应用颜色数据增强的概率。	>=0.0 >=0.0 >=0.0 >=0.0 >=0.0
`with_random_crop`	布尔值	True	应用随机裁剪数据增强。	True, False
`with_random_blur`	布尔值	True	应用随机模糊数据增强。	True, False
`rgb_input_mean`	List[float]	[0.485, 0.456, 0.406]	预处理要减去的均值。
`rgb_input_std`	List[float]	[0.229, 0.224, 0.225]	用于除以图像的标准差。
`augment`	布尔值	False	指示是否应用数据增强的标志	True, False

ViT 主干网络的示例 spec 文件

注意

以下 spec 文件仅适用于 TAO 5.3 及更高版本。

复制
已复制！

            
            encryption_key: tlt_encode
task: classify
train:
  pretrained_model_path: /path/to/pretrained/model.pth
  resume_training_checkpoint_path: null
  classify:
    loss: "contrastive"
    cls_weight: [1.0, 10.0]
  num_epochs: 10
  num_nodes: 1
  validation_interval: 5
  checkpoint_interval: 5
  seed: 1234
  optim:
    lr: 0.0001
    optim: "adamw"
    policy: "linear"
    momentum: 0.9
    weight_decay: 0.01
  results_dir: "${results_dir}/train"
  tensorboard:
    enabled: True
results_dir: /path/to/experiment_results
model:
  backbone:
    type: "vit_large_nvdinov2"
    pretrained_backbone_path: /path/to/pretrained/backbone.pth
    freeze_backbone: False
  decode_head:
    feature_strides: [4, 8, 16, 32]
  classify:
    train_margin_euclid: 2.0
    eval_margin: 0.005
    embedding_vectors: 5
    embed_dec: 30
    difference_module: 'euclidean'
    learnable_difference_modules: 4
dataset:
  classify:
    train_dataset:
      csv_path: /path/to/train.csv
      images_dir: /path/to/img_dir
    validation_dataset:
      csv_path: /path/to/val.csv
      images_dir: /path/to/img_dir
    test_dataset:
      csv_path: /path/to/test.csv
      images_dir: /path/to/img_dir
    infer_dataset:
      csv_path: /path/to/infer.csv
      images_dir: /path/to/img_dir
    image_ext: .jpg
    batch_size: 16
    workers: 2
    fpratio_sampling: 0.2
    num_input: 4
    input_map:
      LowAngleLight: 0
      SolderLight: 1
      UniformLight: 2
      WhiteLight: 3
    concat_type: grid
    grid_map:
      x: 2
      y: 2
    image_width: 112
    image_height: 112
    augmentation_config:
      rgb_input_mean: [0.485, 0.456, 0.406]
      rgb_input_std: [0.229, 0.224, 0.225]
    num_classes: 2
evaluate:
  checkpoint: "???"
inference:
  checkpoint: "???"
export:
  gpu_id: 0
  checkpoint: "???"
  onnx_file: "???"
  input_width: 224
  input_height: 224

训练模型

使用以下命令运行 VisualChangeNet-Classification 训练

复制
已复制！

            
            tao model visual_changenet train [-h] -e <experiment_spec>
                           task=classify
                           [results_dir=<global_results_dir>]
                           [model.<model_option>=<model_option_value>]
                           [dataset.<dataset_option>=<dataset_option_value>]
                           [train.<train_option>=<train_option_value>]
                           [train.gpu_ids=<gpu indices>]
                           [train.num_gpus=<number of gpus>]

必需参数

-e, --experiment_spec_file：实验规范文件的路径。
task：visual_changenet 训练的任务（‘segment’ 或 ‘classify’）。默认值：segment。

可选参数

您可以设置可选参数来覆盖实验规范文件中的选项值。

-h, --help：显示此帮助消息并退出。
model.<model_option>：模型选项。
dataset.<dataset_option>：数据集选项。
train.<train_option>：训练选项。
train.optim.<optim_option>：优化器选项

注意

对于训练、评估和推理，我们为每个相应的任务公开 2 个变量：num_gpus 和 gpu_ids，它们分别默认为 1 和 [0]。如果两者都已传递，但不一致，例如 num_gpus = 1，gpu_ids = [0, 1]，则会修改它们以遵循具有更多 GPU 的设置，例如 num_gpus = 1 -> num_gpus = 2。

检查点和恢复训练

在每个 train.checkpoint_interval，都会保存 PyTorch Lightning 检查点。它被称为 model_epoch_<epoch_num>.pth。它们保存在 train.results_dir 中，如下所示

复制
已复制！

            
            $ ls /results/train

'model_epoch_000.pth'
'model_epoch_001.pth'
'model_epoch_002.pth'
'model_epoch_003.pth'
'model_epoch_004.pth'

最新的检查点也保存为 changenet_model_classify_latest.pth。如果 changenet_model_classify_latest.pth 存在于 train.results_dir 中，则训练会自动从它恢复。如果提供了 train.resume_training_checkpoint_path，则会取代它。

此逻辑的主要含义是，如果您希望从头开始触发全新训练，则可以

创建测试实验规范文件

这是一个用于测试已训练的 VisualChangeNet-Classification 模型的评估和推理的示例规范文件。

复制
已复制！

            
            results_dir: /path/to/experiment_results
task: classify
model:
  backbone:
    type: "fan_small_12_p4_hybrid"
  classify:
    eval_margin: 0.005
dataset:
  classify:
    test_dataset:
      csv_path: /path/to/test.csv
      images_dir: /path/to/img_dir
    infer_dataset:
      csv_path: /path/to/infer.csv
      images_dir: /path/to/img_dir
    image_ext: .jpg
    batch_size: 16
    workers: 2
    num_input: 4
    input_map:
      LowAngleLight: 0
      SolderLight: 1
      UniformLight: 2
      WhiteLight: 3
    concat_type: linear
    grid_map:
      x: 2
      y: 2
    output_shape:
      - 128
      - 128
    augmentation_config:
      rgb_input_mean: [0.485, 0.456, 0.406]
      rgb_input_std: [0.229, 0.224, 0.225]
    num_classes: 2
evaluate:
  checkpoint: /path/to/checkpoint
  results_dir: /results/evaluate
inference:
  checkpoint: /path/to/checkpoint
  results_dir: /results/inference

推理/评估

参数	数据类型	默认值	描述	支持的值
`checkpoint`	字符串		要评估/推理的 PyTorch 模型路径
`trt_engine`	字符串		要推理/评估的 TensorRT 模型路径。应仅与 TAO Deploy 一起使用
`num_gpus`	无符号整数	1	要使用的 GPU 数量	>0
`gpu_ids`	无符号整数	[0]	要使用的 GPU ID
`results_dir`	字符串		实验输出应写入的文件夹路径
`vis_after_n_batches`	无符号整数	1	在多少批次后保存推理/评估可视化结果	>0
`batch_size`	无符号整数		推理/评估的批次大小

评估模型

使用以下命令运行 VisualChangeNet-Classification 评估

复制
已复制！

            
            tao model visual_changenet evaluate [-h] -e <experiment_spec_file>
                           task=classify
                           evaluate.checkpoint=<model to be evaluated>
                           [evaluate.<evaluate_option>=<evaluate_option_value>]
                           [evaluate.gpu_ids=<gpu indices>]
                           [evaluate.num_gpus=<number of gpus>]

Visual ChangeNet Classify 目前不支持多 GPU 评估。

必需参数

-e, --experiment_spec_file：用于设置评估实验的实验规范文件。
evaluate.checkpoint：要评估的 .pth 模型。

可选参数

evaluate.<evaluate_option>：评估选项。

在模型上运行推理

使用以下命令使用 .pth 模型在 VisualChangeNet-Classification 上运行推理

复制
已复制！

            
            tao model visual_changenet inference [-h] -e <experiment_spec_file>
                           task=classify
                           inference.checkpoint=<inference model>
                           [inference.<evaluate_option>=<evaluate_option_value>]
                           [inference.gpu_ids=<gpu indices>]
                           [inference.num_gpus=<number of gpus>]

必需参数

-e, --experiment_spec_file：用于设置评估实验的实验规范文件。
inference.checkpoint：要在其上运行推理的 .pth 模型。

可选参数

inference.<inference_option>：推理选项。

导出模型

这是一个用于导出已训练的 VisualChangeNet 模型的示例规范文件

复制
已复制！

            
            export:
  checkpoint: /path/to/model.pth
  onnx_file: /path/to/model.onnx
  opset_version: 12
  input_channel: 3
  input_width: 128
  input_height: 512
  batch_size: -1

参数	数据类型	默认值	描述	支持的值
`checkpoint`	字符串		要导出的 PyTorch 模型路径
`onnx_file`	字符串		`.onnx` 文件的路径
`opset_version`	无符号整数	12	导出的 ONNX 的 opset 版本	>0
`input_channel`	无符号整数	3	输入通道大小。仅支持值 3。	3
`input_width`	无符号整数	128	输入宽度	>0
`input_height`	无符号整数	512	输入高度	>0
`batch_size`	无符号整数	-1	ONNX 模型的批次大小。如果此值设置为 -1，则导出使用动态批次大小。	>=-1
`gpu_id`	无符号整数	0	要使用的 GPU ID
`on_cpu`	布尔值	False	是否在 CPU 上导出
`verbose`	布尔值	False	打印出网络的易读表示

使用以下命令导出模型

复制
已复制！

            
            tao model visual_changenet export [-h] -e <experiment spec file>
                           task=classify
                           export.checkpoint=<model to export>
                           export.onnx_file=<onnx path>
                           [export.<export_option>=<export_option_value>]

必需参数

-e, --experiment_spec：实验规范文件的路径
export.checkpoint：要导出的 .pth 模型。
export.onnx_file：保存 .etlt 或 .onnx 模型的路径。

可选参数

export.<export_option>：导出选项。

TensorRT 引擎生成、验证和 int8 校准

有关部署，请参阅VisualChangeNet-Classification 的 TAO Deploy 文档。