tao-train-visual-changenet

Visual ChangeNet

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

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

主干网络权重（c_radio_v2_vit_base_patch16_224）是 HuggingFace 上的 nvidia/C-RADIOv2-B 模型，以 model.safetensors（约 393 MB）形式分发。TAO 7.0.0-rc 容器不会自动从 HF URL 获取文件 — ptm_utils.load_pretrained_weights() 会直接将 pretrained_backbone_path 的值传给 torch.load(path) / safetensors.torch.load_file(path)。传入 https://huggingface.co/... URL 或仓库 ID 会导致 FileNotFoundError，且几秒内运行就会以 Execution status: FAIL 失败。启动前请先将文件暂存到本地：

python3 -c "from huggingface_hub import hf_hub_download; import shutil; \
shutil.copy(hf_hub_download('nvidia/C-RADIOv2-B', 'model.safetensors'), '<workspace>/backbone/c_radio_v2_b.safetensors')"

将文件挂载到容器中（-v <workspace>/backbone/c_radio_v2_b.safetensors:/data/pretrained_models/C-RADIOv2_B.safetensors），并将 spec 中的 model.backbone.pretrained_backbone_path 设置为容器路径。HF_TOKEN 仅在暂存文件时需要，训练时不需要。

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”、“禁用 AutoML”、“不进行 HPO”或“普通训练”等表述视为仅对本次运行设置 automl_policy: off；否则默认为 auto。当 automl_policy: auto、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 或缺少已打包的训练架构/模板时，才直接进行模型训练；若缺少架构，请说明 AutoML 已启用，但在生成架构之前，此模型无法运行 AutoML。

evaluate、inference、export 和部署流程等非训练操作仍由此模型技能处理。每次运行的 automl_policy 覆盖设置不会更改模型元数据。

对于 TAO Deploy TensorRT 操作（gen_trt_engine、TensorRT evaluate 以及 classify 和 segment 变体的 TensorRT inference），请先阅读 references/tao-deploy-visual-changenet.md。部署 spec 模板位于此技能的 references/ 文件夹中，前缀为 spec_template_deploy_*.yaml。

任务

分类（默认）

使用的操作：train、evaluate、inference。默认模板：references/spec_template_train.yaml。

分割

使用的操作：segment_train、segment_evaluate、segment_inference。默认模板：references/spec_template_segment.yaml。

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

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

数据集、Spec 覆盖项和数据格式

Visual ChangeNet 有两种任务模式，使用不同的数据集类型和数据源结构。分类使用 4 列 CSV（input_path,golden_path,label,object_name）以及一个图像目录；分割则在单个 root_dir 下使用成对目录结构（A/、B/、list/、label/）。每个操作都必须覆盖数据源——Agent 必须构建数据源路径，并将其纳入 spec_overrides。

完整的各操作数据集要求表（分类和分割）、所有 spec 覆盖示例（两种变体的 train、export、quantize、evaluate、inference、gen_trt_engine）、分类 CSV 格式、evaluate/inference 和分割输入字段、光照约定、分割数据布局，以及 input_map 多光照配置，请参阅 references/dataset-and-specs.md。

本地 Docker 调用

如果没有 TAO SDK，请从 versions.yaml 中解析 TAO pyt 镜像，并直接调用 visual_changenet <action>，同时使用 --shm-size=8g，并将骨干网络 .ckpt 挂载为单个文件。完整的 docker run 命令、共享内存要求、骨干网络挂载详情，以及 checkpoint/results_dir 命令行覆盖模式，请参阅 references/local-docker-invocation.md。

参数、硬件和错误模式

关键参数包括 train.validation_interval（默认值为 50，必须 ≤ num_epochs）、train.checkpoint_interval（默认值为 200，必须 ≤ num_epochs）、train.num_epochs（默认值为 100）、model.classify.eval_margin（默认值为 0.3，是主要的精确率/召回率阈值），以及 train.classify.cls_weight（默认值为 [1.0, 10.0]）。最低硬件要求为 1 个 GPU，显存 16GB 以上；生产环境建议使用 8 个 GPU（DDP）。GPU 数量由 TAO 在内部管理——不要设置 gpu_spec_key。

完整的参数参考、硬件指南，以及完整的错误模式目录（找不到 checkpoint、CSV 格式不匹配、图像扩展名不匹配、OOM、评估准确率低、对比损失断言失败、不收敛、仅分割任务的 MultiScaleDeformableAttention 构建、Lightning epoch 配置错误、PYTHONPATH/ModuleNotFoundError，以及 epoch 默认值），请参阅 references/parameters-and-troubleshooting.md。

Spec 参数／父模型推断

模型特定的推断映射应放在此 MD 文件中，而不是 config.json 中。生成的运行器应读取此部分，并在调用 create_job() 前使用 SDK 助手应用这些映射。这与旧版微服务的 infer_params.py 流程一致。

此模型 skill 中的推断映射：

操作	Spec 字段	推断函数	含义
evaluate	results_dir	output_dir	当前任务的结果目录
inference	results_dir	output_dir	当前任务的结果目录
train	results_dir	output_dir	当前任务的结果目录
train	train.resume_training_checkpoint_path	resume_model	从当前任务结果文件夹推断出的模型文件

对于 parent_model 或 parent_model_folder，将上游 train/export/AutoML 子任务 ID 作为 parent_job_id 传入。SDK 会列出父级结果文件夹、筛选 checkpoint 产物，并返回选定的模型文件或文件夹。不要将这些映射加回 config.json，也不要修改生成的运行器脚本来猜测 checkpoint 路径。

部署

• tao-deploy-visual-changenet — 使用 TAO Deploy 生成 TensorRT 引擎、评估 TensorRT 模型并进行 TensorRT 推理的 Visual ChangeNet 部署工作流。