⚡

视觉变化网络Skill tao-train-visual-changenet

该技能用于训练、评估、导出和运行 Visual ChangeNet（视觉变化网络）模型，支持 PCB/AOI 缺陷检测中的二值图像分类（PASS/NO_PASS）与变化分割任务。通过 Siamese 架构和预训练 C-RADIO/NVDINOv2 backbone，实现图像对比较与缺陷检测。关键词：Visual ChangeNet、AOI缺陷检测、PCB检测、二值分类、变化分割、TAO Toolkit、模型训练。

工业缺陷检测 0 次安装 1 次浏览 更新于 9/6/2026

Visual ChangeNet（视觉变化网络）

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

Visual ChangeNet 是 TAO Toolkit 的视觉检查与缺陷检测模型，支持两个任务：

  • 分类（Classify）：采用带共享主干（C-RADIO ViT）和可学习差异模块的 Siamese 架构，比较图像对并给出 PASS/NO_PASS 二分类结果。
  • 分割（Segment）：以 ViT-Large NVDINOv2 为主干，比较前后图像对生成像素级二值变化掩膜。

主干权重为公共的 HuggingFace 模型 nvidia/C-RADIOv2-B（文件 model.safetensors，约 393 MB）。TAO 容器不会自动从 HF URL 下载权重 —— ptm_utils.load_pretrained_weights() 会把 pretrained_backbone_path 直接传给 torch.load/safetensors，传入 https://... 或 repo id 会触发 FileNotFoundError 并很快失败。因此启动前需要先在 CPU 环境用附带脚本把权重准备好（脚本幂等，重复执行复用已下载文件）：

python3 skills/models/tao-train-visual-changenet/scripts/stage_backbone.py --workspace <workspace>
# 生成 <workspace>/pretrained_models/C-RADIOv2_B.safetensors

这是公共下载，不需要 NGC 凭据。之后将文件挂载进容器，并在 spec 中设置 model.backbone.pretrained_backbone_path 指向容器内路径。

Segment 任务使用 model.backbone.type: vit_large_nvdinov2 和 NVDINOv2 checkpoint 族。checkpoint 架构必须与 backbone 类型匹配（NV_DINOV2_518_16_256.ckpt 与打包的 segment 模板兼容），不要与 fan_small_12_p4_hybrid 混用；切换 backbone 时应使用对应 checkpoint，或将 pretrained_backbone_path 留空以便默认初始化。

数据类 Schema

生成的 TAO Core schema 打包在 schemas/<action>.schema.json，schemas/manifest.json 列出可用 action；每个 schema 的顶层 default 字段会输出 references/spec_template_<action>.yaml。AutoML 启用状态在 references/skill_info.yaml 的模型层通过 automl_enabled 声明，可运行仍需 schemas/train.schema.json 和 references/spec_template_train.yaml 存在并可解析。

训练动作策略

该模型在模型层启用了 AutoML。处理任何 train 请求前，请阅读 references/skill_info.yaml，根据显式 automl_policy 或用户请求解决运行覆盖。默认使用 automl_policy: on，只暴露 on/off。当 automl_policy: on 且 automl_enabled: true，且 schema/template 都存在时，默认将训练路由到 tao-skill-bank:tao-run-automl 并传入本模型的 skill_dir。当 automl_policy: off 或 schema/template 缺失时，走直接训练模式，并在缺失时提示 AutoML 启用但不可运行。

Checkpoint 保留属于编排策略而非 HPO 参数。打包的训练模板默认 train.checkpointer.enable_topk 和 replace_periodic 为 false，保留周期保存 checkpoint；AutoML 开启保留时会监控 val_loss（min 模式）并将 save_top_k 设为 1。

非训练动作（evaluate、inference、export、quantize、segment_evaluate、segment_inference）留在本模型技能中。不要把 segment_export 或 segment_quantize 作为可运行的父级动作。Prune 和 retrain 未在当前元数据中声明，不要展示。

TAO Deploy/TensorRT 动作（gen_trt_engine、TensorRT evaluate/inference）请先阅读 references/tao-deploy-visual-changenet.md。部署需要 ONNX 导出产物作为 parent_model；若不存在且主技能未提供导出动作，应报告部署受阻而非伪造产物。

训练要求

Visual ChangeNet 有两种任务模式，数据集类型与结构不同。

分类（Classify）

  • 数据集类型：visual_changenet_classify
  • 格式：default
  • 可接受意图：training、evaluation、testing、calibration
  • 监控指标：val_loss

分类逐动作数据要求表（简）

train/quantize 需要 train_dataset 和 validation_dataset 的 images_dir 与 csv_path；evaluate 需要 validation/test 的 images_dir 与 csv_path；inference 需要 infer_dataset 的 images_dir 与 csv_path；gen_trt_engine 需要校准图目录。来源为 train_datasets、eval_dataset、inference_dataset、calibration_dataset。

分割（Segment）

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

Segment 使用成对目录结构（A/、B/、list/、label/），不使用 CSV。dataset.segment.root_dir 指向顶层目录。每个数据集需要 A.tar.gz、B.tar.gz、list.tar.gz、label.tar.gz 四个文件。

（略去大量逐行 data source 示例，一般必须从 Per-Action Dataset Requirements table 构造 spec_overrides。）

通过 TAO SDK 运行（可选）

不使用 SDK 时，用固定 TAO pyt 镜像直接调用 visual_changenet <train|evaluate|inference|export|quantize>。需要 --shm-size=8g，挂载 C-RADIO .safetensors 到 /data/pretrained_models/C-RADIOv2_B.safetensors。详见 references/local-docker.md。

任务

分类（默认）

使用动作：train、evaluate、inference。默认模板 references/spec_template_train.yaml。evaluate/inference 需要 7.1 训练出的 checkpoint；没有可用的 NGC pretrained 7.1 分类 checkpoint（7.0 的旧模型在 7.1 上会因 radio.* KeyError 失败），须先训练。

分割

技能动作名：segment_train、segment_evaluate、segment_inference；本地 Docker 运行 TAO CLI 子命令时在 spec 里设置 task: segment。Schema 模板为 spec_template_segment_*.yaml。

分割首次运行需编译自定义 CUDA 算子 MultiScaleDeformableAttention，约 5 分钟。数据集结构为成对目录（前述）。

数据格式

分类需要四列 CSV（input_path,golden_path,label,object_name）加图片目录；分割数据不需要 CSV。image_ext 默认 .jpg，需要匹配实际扩展名；多光源输入通过 input_map 配置，并设 num_input。详见 references/data-formats.md。

预检：验证分类数据集（每次分类运行前强制）

运行脚本 validate_vcn_dataset.py 在主机上校验 CSV。退出码 0 可启动，退出码 2 表示数据有问题，不要启动。脚本会拒绝绝对路径、平铺文件名、单类训练集以及 batch 大于数据集等。

python3 skills/models/tao-train-visual-changenet/scripts/validate_vcn_dataset.py \
  --csv <dataset.csv> --images-dir <images dir> --mode train \
  --batch-size <batch> --num-gpus <gpus>

重要参数

  • 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]）

硬件要求：最小 1 张 16GB+ 显存 GPU，推荐 8 卡 DDP。不要设置 gpu_spec_key。详见 references/tuning-parameters.md。

错误模式

针对 checkpoint 不存在、CSV 格式不匹配、图片扩展名不匹配、OOM、低评估准确率、对比损失 AssertionError、权重加载 key 不匹配、不收敛、segment-only backbone 维度不匹配、MultiScaleDeformableAttention 的 OSError、Lightning MisconfigurationException、ModuleNotFoundError: nvidia_tao_pytorch、epoch 默认值等问题，见 references/troubleshooting.md。

Spec 参数 / Parent Model 推断

references/skill_info.yaml 的 spec_params 声明模型相关的父模型映射，用于在 create_job() 前解析 checkpoint。父模型应传 parent job id，SDK 会列出父结果目录并过滤 checkpoint 产物。详见 references/parent-model-inference.md。

部署

参考 references/tao-deploy-visual-changenet.md。