tao-train-dino

DINO

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

DINO（带改进去噪锚框的 DETR）用于 2D 目标检测。这是一种基于 Transformer 的检测器，采用去噪训练、多尺度特征，并支持可选的蒸馏。

使用预训练的骨干网络权重（例如 ResNet-50 ImageNet）。对于仅骨干网络的权重，设置 model.pretrained_backbone_path；对于完整模型，设置 train.pretrained_model_path。

适用场景

训练、评估、导出、蒸馏、量化或运行 TAO DINO 2D 目标检测器的推理。

对于 TAO Deploy TensorRT 操作（gen_trt_engine、TensorRT evaluate 和 TensorRT inference），请先阅读 references/tao-deploy-dino.md。部署规范模板位于此技能的 references/ 文件夹中，前缀为 spec_template_deploy_*.yaml。

参考资料索引

• references/dino-data-specs.md — 数据集约定、各操作的数据集要求、各操作的规范覆盖示例（train、evaluate、export、deploy/gen_trt_engine、inference、quantize、distill）、数据源数组、检查点推断和数据集布局。
• references/dino-actions-errors.md — 重要参数、默认值、evaluate/export 默认设置、硬件和完整的错误模式目录。
• references/dino-tuning-multigpu.md — 完整的 AutoML/HPO 说明（指标、超参数、提取器）和多 GPU 规范一致性。
• references/tao-deploy-dino.md — TensorRT 部署工作流。
• references/detailed-guide.md — 详细模型指南索引。

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。请使用打包的 train 架构获取 automl_default_parameters、automl_disabled_parameters、默认值、最小/最大界限、枚举、选项权重、数学条件、依赖项和常用参数。不要假设运行时存在 ~/tao-core；维护者会在打包 skill bank 前重新生成架构和模板。

Train 操作策略

此模型在模型层启用了 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 执行 train 操作，并传入此模型的 skill_dir。保留工作流/应用覆盖项，包括数据集、规范、输出目录、GPU/平台设置、父检查点和 automl_policy。仅当 automl_policy: off 或缺少已打包的 train 架构/模板时，才直接训练模型；若缺少架构，请说明此模型虽已启用 AutoML，但在生成架构之前无法运行 AutoML。

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

训练要求

Agent 在生成任何用于 DINO 的训练或 AutoML 脚本前，必须先阅读本节。

• 数据集类型： object_detection
• 格式： coco、coco_raw
• 接受的数据集用途： training、evaluation、testing、calibration
• AutoML 指标约定： 对于默认的、基于评估的工作流，使用 test_mAP50，并设为最大化方向。只有在用户明确要求 COCO/论文风格的 mAP 时，才使用 test_mAP。
• 训练监控指标： 使用 val_mAP50（记录为 Validation mAP50）进行快速运行检查；使用 val_mAP 进行 COCO/论文风格的基准比较。
• Evaluate 操作指标： 使用 test_mAP50 表示 AP50，使用 test_mAP 表示 COCO mAP。使用独立 evaluate 操作对建议进行评分的 AutoML 工作流，必须使用对应的 test_* KPI。

必需数据集 — 必须解析两者：

数据集	必需	原因
训练数据集 URI	是	训练数据（COCO 格式）
验证数据集 URI	是 — 始终必需	DINO 无条件构建 val dataloader。无论指标或工作流如何，省略 val_data_sources 都会在启动时导致 FileNotFoundError。如果用户没有单独的评估数据划分，则重复使用训练 URI。

生成任何训练配置前的必需输入：

1. 训练数据集 URI — COCO 格式训练数据的 S3 路径
2. 验证数据集 URI — COCO 格式验证数据的 S3 路径（可与训练数据相同）
3. num_classes — 有多少个对象类别？默认值为 91（COCO）。必须 >= max(category_id) + 1。值过低会导致 CUDA error: device-side assert triggered。

从用户请求或下方的默认配置中解析这些值。应用配置规则后，仅询问仍缺失的值。

DINO AutoML 冒烟运行的可复用本地默认配置：

仅当用户要求运行 DINO AutoML，且未提供数据集或类别数输入时，才使用此配置。此配置规模较小，专用于此技能库；它适用于冒烟测试和迭代运行，不适用于生产基准测试。不要搜索以往的运行记录、日志、会话状态、Shell 历史记录或主目录来查找这些值。

DINO_AUTOML_PROFILE = {
    "train_dataset_uri": "s3://nvcf-storage-handling/data/tao_od_synthetic_subset_train_no_convert",
    "validation_dataset_uri": "s3://nvcf-storage-handling/data/tao_od_synthetic_subset_val_no_convert",
    "object_classes": 4,
    "dataset_num_classes": 5,
    "image_archive": "images.tar.gz",
    "annotation_file": "annotations.json",
    "max_recommendations": 10,
    "train_num_epochs": 10,
    "train_checkpoint_interval": 10,
    "train_validation_interval": 1,
    "train_num_gpus": 1,
}

如果用户提供了任何数据集 URI 或类别数值，优先使用用户提供的值，并询问其余缺失的 DINO 必需值。除非用户确认，否则不要将用户自定义数据集与此配置中的类别数部分混用。

标准 DINO 数据集无需询问图像布局。 标准 TAO DINO 数据集制品为 images.tar.gz 和 annotations.json。在远程 image_dir 规范覆盖中使用 images.tar.gz。SDK 会下载该存档，并将运行时规范重写为以存档主文件名命名的解压文件夹（images.tar.gz -> images）。仅当用户明确提供了不同的图像制品名称时，才采用其他设置。

核心工作流

DINO 支持训练、评估、导出、蒸馏、量化和推理。每项操作都必须覆盖数据源——DINO 的 config.json 中 data_sources 为空，因为运行器无法自动解析对象数组类型的规范键。Agent 必须构建数据源路径，并将其纳入 spec_overrides。

请参阅 references/dino-data-specs.md，了解各操作的数据集要求表、标准数据集制品（images.tar.gz + annotations.json）和运行时文件夹重写规则，以及 train、evaluate、export、deploy/gen_trt_engine、inference、quantize 和 distill 的完整 spec_overrides 示例——其中包括通过 parent_model 进行检查点推理、results_dir/train/ 检查点位置，以及蒸馏中的 FAN 教师模型和学生模型规则。

重要参数和默认值

默认值：num_epochs=10、batch_size=4、learning_rate=2e-4、 lr_backbone=2e-5、num_classes=91、backbone=resnet_50。

• dataset.num_classes：默认值为 91（COCO）。必须 >= max(category_id) + 1。值过低会导致 CUDA error: device-side assert triggered。在规格覆盖项中设置为 <num_classes> + 1。
• num_epochs：默认值为 10（用于快速迭代）；实际数据集通常需要 30–50+ 个训练轮次才能获得良好的 mAP。

完整参数列表（骨干网络选项、train.optim.lr/lr_steps、model.num_queries、batch_size）、默认值、评估默认值、导出默认值（输入 960x544、opset 17、TRT 数据类型、工作区 1024 MB）和硬件要求，请参阅 references/dino-actions-errors.md。

多 GPU 和 AutoML / HPO

增加 train.num_gpus 时，还要将 train.gpu_ids 设为相同的可见设备范围，否则分布式启动可能不一致。

AutoML 会运行训练——以上所有 训练要求 均适用。对于无需输入的本地冒烟测试，请使用 DINO_AUTOML_PROFILE。对于仅根据训练日志评分的情况，请使用 val_mAP50（从 Validation mAP50 提取）或 val_mAP。通过独立评估操作为每个推荐方案评分时，请使用 test_mAP50 或 test_mAP，并设置 direction="maximize"。

完整的多 GPU 规格一致性规则（8 GPU 示例、NCCL 超时说明）和 AutoML/HPO 说明（指标选择、metric_extractor、推荐超参数、weight_decay 行为、密集数据集恢复指南和父模型推理映射），请参阅 references/dino-tuning-multigpu.md。

错误模式

常见故障包括 CUDA OOM（减小 batch_size）、缺少 val_data_sources（启动时出现 FileNotFoundError——务必提供 val）、num_classes 过低（出现 CUDA device-side assert），以及父级 dino gen_trt_engine / dino convert PyT-CLI 限制。

包含诊断和修复方法的完整错误模式目录，请参阅 references/dino-actions-errors.md。

规格参数 / 父模型推理

特定于模型的推理映射应放在此 MD 文件中。对于 parent_model/parent_model_folder，请将上游 train/export/AutoML 子任务 ID 作为父任务 ID 传入；列出父结果文件夹、筛选检查点产物，并选择解析出的模型。

完整推理映射表（按操作列出：parent_model、key、output_dir、ptm_if_no_resume_model、resume_model、create_onnx_file）和 TensorRT 映射说明，请参阅 references/dino-tuning-multigpu.md。TensorRT 映射位于部署工作流中，而非 PyT 模型技能中。

部署

• tao-deploy-dino