| 名称 | tao-train-optical-inspection |
| 描述 | 使用孪生网络进行光学检测，通过比较图像对来检测制造缺陷、异常或质量问题。适用于在AOI/质量控制数据上训练、评估、导出或运行TAO光学检测模型。触发短语包括"训练光学检测"、“AOI缺陷检测”、“孪生缺陷分类器”、“PCB/制造检测”。 |
| 开源协议 | Apache-2.0 compatibility: 需要docker + nvidia-container-toolkit。 metadata: |
| 版本 | “0.1.0” |
| 作者 | NVIDIA Corporation allowed-tools: Read Bash tags: - 缺陷 - 检测 |
光学检测
独立安装？ 如果此会话未由TAO技能库插件初始化，请先运行
tao-setup技能（主机预检、凭据、跨技能发现）。
使用孪生网络进行光学检测，通过比较图像对来检测制造缺陷、异常或质量问题。
设置train.pretrained_model_path以使用预训练的孪生权重。
对于TAO Deploy TensorRT操作（gen_trt_engine、TensorRT evaluate和TensorRT inference），请先阅读references/tao-deploy-optical-inspection.md。父PyT容器不暴露optical_inspection gen_trt_engine；TensorRT引擎生成仅限部署。部署规范模板位于本技能的references/文件夹中，前缀为spec_template_deploy_*.yaml。
数据类模式
生成的TAO Core模式打包在schemas/<action>.schema.json中，schemas/manifest.json列出可用操作。每个生成的模式还会从模式顶层的default字段输出references/spec_template_<action>.yaml。AutoML启用状态在references/skill_info.yaml的模型层通过automl_enabled声明。某个操作的可运行AutoML需要schemas/<action>.schema.json和references/spec_template_<action>.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或打包的训练模式/模板缺失时才使用直接模型训练；在模式缺失的情况下，报告AutoML已启用但无法运行，直到生成模式。
非训练操作（如evaluate、inference、export和部署流程）仍保留在此模型技能中。每次运行的automl_policy覆盖不会更改模型元数据。
训练要求
- 数据集类型： optical_inspection
- 格式： 默认
- 监控指标： val_acc
每个操作的数据集要求
| 操作 | 规范键 | 来源 | 文件 | 列表？ |
|---|---|---|---|---|
| evaluate | dataset.test_dataset.images_dir | eval_dataset | images.tar.gz | 否 |
| evaluate | dataset.test_dataset.csv_path | eval_dataset | dataset.csv | 否 |
| inference | dataset.infer_dataset.images_dir | inference_dataset | images.tar.gz | 否 |
| inference | dataset.infer_dataset.csv_path | inference_dataset | dataset.csv | 否 |
| train | dataset.train_dataset.images_dir | train_datasets | images.tar.gz | 否 |
| train | dataset.train_dataset.csv_path | train_datasets | dataset.csv | 否 |
| train | dataset.validation_dataset.images_dir | eval_dataset | images.tar.gz | 否 |
| train | dataset.validation_dataset.csv_path | eval_dataset | dataset.csv | 否 |
| train | dataset.test_dataset.images_dir | eval_dataset | images.tar.gz | 否 |
| train | dataset.test_dataset.csv_path | eval_dataset | dataset.csv | 否 |
典型规范覆盖
每个操作的数据源覆盖是强制性的——代理必须根据上表的每个操作数据集要求构建数据源路径，并将其包含在spec_overrides中。
S3_TRAIN = "s3://bucket/data/train"
S3_EVAL = "s3://bucket/data/eval"
S3_INFERENCE = "s3://bucket/data/inference"
训练（强制数据源）：
{
"train.num_epochs": 30,
"train.checkpoint_interval": 10,
"train.validation_interval": 10,
"train.num_gpus": 1,
"dataset.batch_size": 8,
"dataset.train_dataset.images_dir": f"{S3_TRAIN}/images.tar.gz",
"dataset.train_dataset.csv_path": f"{S3_TRAIN}/dataset.csv",
"dataset.validation_dataset.images_dir": f"{S3_EVAL}/images.tar.gz",
"dataset.validation_dataset.csv_path": f"{S3_EVAL}/dataset.csv",
"dataset.test_dataset.images_dir": f"{S3_EVAL}/images.tar.gz",
"dataset.test_dataset.csv_path": f"{S3_EVAL}/dataset.csv",
}
评估（强制数据源）：
{
"evaluate.checkpoint": "<选定的训练/AutoML检查点>",
"dataset.test_dataset.images_dir": f"{S3_EVAL}/images.tar.gz",
"dataset.test_dataset.csv_path": f"{S3_EVAL}/dataset.csv",
}
对于下游操作，请使用工作流的检查点解析器，而不是猜测文件名。对于光学检测冒烟测试，AutoML可能生成model_epoch_000_step_00006.pth；恢复后可能生成model_epoch_001_step_00012.pth。最佳检查点操作应使用AutoML最佳子作业的选定检查点，特定轮次操作应传递请求的确切轮次/步骤检查点，只有显式的“最新”请求才应解析为最新检查点。
导出：
{
"export.checkpoint": "<选定的训练/AutoML检查点>",
"export.onnx_file": "/results/optical_inspection.onnx",
"export.input_width": 128,
"export.input_height": 512,
"export.batch_size": 1,
}
推理（强制数据源）：
{
"inference.checkpoint": "<选定的训练/AutoML检查点>",
"dataset.infer_dataset.images_dir": f"{S3_INFERENCE}/images.tar.gz",
"dataset.infer_dataset.csv_path": f"{S3_INFERENCE}/dataset.csv",
}
数据集转换
对于光学检测，数据集转换是可选的。如果数据集已经是TAO就绪的光学检测格式，则直接从images.tar.gz加dataset.csv分割开始，并在转换后的数据上运行train、evaluate、inference以及下游检查点/导出/部署操作。
PyT容器暴露了optical_inspection dataset_convert，但此模型技能未打包dataset_convert操作/模板。转换器期望原始的Factory PCB布局（root_dataset_dir、train/val/all PCB目录、golden_csv_dir、project_name和bot_top）。S3验证桶当前包含预转换的光学检测images.tar.gz加dataset.csv分割，而不是原始PCB/黄金CSV源。不要合成虚假的PCB数据集。在模型验证报告中，当只有转换后的数据可用时，将数据集转换标记为not run: preconverted dataset provided，而不是失败或阻塞。
在本地使用预转换的S3验证tarball时，在编写规范之前验证提取的目录。tarball可能解包出一个images/包装目录；将dataset.*.images_dir指向包含golden/以及dataset.csv引用的板/图像文件夹的内部目录，例如.../<split>/images/images，而不是外部包装器。
评估数据集
可选。评估数据集使用相同的格式（图像+CSV）。
重要参数
- model.model_type：Siamese变体。选项包括Siamese、Siamese_3。
- model.model_backbone：默认自定义。
- model.embedding_vectors：嵌入维度数。默认5。
- train.optim.lr：学习率。默认5e-4。
- dataset.batch_size：训练批量大小。必须大于1；对于最小冒烟测试使用
2或更高。 - dataset.num_input：每次比较的输入图像数。
- dataset.input_map：输入通道/图像对的映射。
多GPU/多节点
启动方式： Lightning管理（单个python进程，Lightning生成worker）。
| 规范键 | 描述 | 默认 |
|---|---|---|
train.num_gpus |
GPU数量 | 1 |
train.gpu_ids |
GPU设备索引 | [0] |
- 策略：
auto（Lightning自动选择最佳策略） - 无显式的
num_nodes或distributed_strategy配置——仅单节点 - 轻量级Siamese网络，单GPU通常足够
硬件
最少1个GPU，推荐1个GPU。每个GPU 8GB+ VRAM。用于检测的Siamese网络重量轻。单GPU足够。
错误模式
CSV格式错误：确保dataset.csv具有正确的图像对路径和标签列格式。
提取的图像根目录不匹配：如果train、evaluate或inference找不到来自dataset.csv的路径，请检查提取的images.tar.gz树。TAO就绪根目录必须包含golden/以及CSV中引用的板文件夹。对于验证S3 tarball，这可能在提取目标下一级，如images/images。
训练批量大小断言：光学检测数据加载器拒绝dataset.batch_size: 1用于训练。正常运行时保持模板默认值8，或为最小AutoML冒烟验证设置dataset.batch_size: 2。
下游操作的PyTorch检查点加载失败：对于由同一受信任的TAO训练/AutoML工作流生成的检查点，如果当前PyTorch默认阻止加载完整检查点，则在evaluate、inference、export和resume作业中设置TORCH_FORCE_NO_WEIGHTS_ONLY_LOAD=1。不要对不受信任的检查点使用此环境变量。
规范参数/父模型推断
模型特定的推断映射属于此MD文件，而不是config.json。生成的运行器应阅读本节，并在create_job()之前使用SDK辅助应用映射。这类似于旧的微服务infer_params.py流程。
来自TAO Core optical_inspection.config.json的推断映射：
| 操作 | 规范字段 | 推断函数 | 含义 |
|---|---|---|---|
| evaluate | encryption_key |
key |
加密密钥 |
| evaluate | evaluate.checkpoint |
parent_model |
从父作业结果文件夹推断的模型文件 |
| evaluate | results_dir |
output_dir |
当前作业结果目录 |
| export | encryption_key |
key |
加密密钥 |
| export | export.checkpoint |
parent_model |
从父作业结果文件夹推断的模型文件 |
| export | export.onnx_file |
create_onnx_file |
输出ONNX路径 |
| export | results_dir |
output_dir |
当前作业结果目录 |
| inference | encryption_key |
key |
加密密钥 |
| inference | inference.checkpoint |
parent_model |
从父作业结果文件夹推断的模型文件 |
| inference | inference.trt_engine |
parent_model |
从父作业结果文件夹推断的模型文件 |
| inference | results_dir |
output_dir |
当前作业结果目录 |
| train | encryption_key |
key |
加密密钥 |
| train | results_dir |
output_dir |
当前作业结果目录 |
| train | train.pretrained_model_path |
ptm_if_no_resume_model |
当没有恢复检查点时的PTM |
| train | train.resume_training_checkpoint_path |
resume_model |
从当前作业结果文件夹推断的模型文件 |
对于parent_model或parent_model_folder，将上游训练/导出/AutoML子作业id作为parent_job_id传递。SDK列出父结果文件夹，过滤检查点工件，并返回选定的模型文件或文件夹。不要将这些映射添加回config.json，也不要修补生成的运行器脚本以猜测检查点路径。