tao-train-dino

DINO

用于 2D 目标检测的 DINO（DETR with Improved DeNoising Anchor Boxes）。基于 Transformer 的检测器，具备去噪训练、多尺度特征和可选的蒸馏支持。

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

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

生成的 TAO Core schema 打包在 schemas/<action>.schema.json 中（由 schemas/manifest.json 列出各项操作）；每个 schema 都会生成一个对应的 references/spec_template_<action>.yaml。有关 SDK 编排使用的数据类 schema、规范模板、数据源和父模型推断的完整详情，请参阅 references/sdk_orchestration.md。

训练操作策略

此模型在模型层面启用了 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。保留工作流／应用对数据集、规范、输出目录、GPU／平台设置、父检查点以及 automl_policy 的覆盖设置。仅当 automl_policy: off 或缺少已打包的训练 schema／模板时，才直接训练模型；若缺少 schema，请说明 AutoML 已启用，但在为此模型生成 schema 之前无法运行。

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

训练要求

在为 DINO 生成任何训练或 AutoML 脚本之前，Agent MUST 阅读本节。

• 数据集类型： object_detection
• 格式： coco，coco_raw
• 接受的数据集用途： training，evaluation，testing，calibration
• 监控指标： val_mAP50

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

数据集	必需	原因
训练数据集 URI	是	训练数据（COCO 格式）
验证数据集 URI	是 — 始终需要	DINO 无条件构建验证数据加载器。省略 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 的 config.json 中 data_sources 为空，因为运行器无法自动解析对象数组形式的规范键。Agent MUST 构建数据源路径并将其包含在 spec_overrides 中。

请参阅 references/spec_overrides.md，了解：各操作的数据集要求表；train、evaluate、export、gen_trt_engine、inference、quantize 和 distill 必需的 spec_overrides 块；通过 parent_model 推断解析检查点，以及 results_dir/train/dino_model_latest.pth 回退路径；COCO 数据集格式和 images.tar.gz 存档文件名主体规则；各操作的数据源布局；完整的重要参数列表（num_classes、backbone 及其支持的值、lr/lr_backbone、num_epochs、lr_steps、num_queries、batch_size）；默认值（num_epochs 10、batch_size 4、learning_rate 2e-4、lr_backbone 2e-5、num_classes 91、backbone resnet_50）；评估默认值；导出默认值（输入 640x640、opset 17、trt_data_types [FP32, FP16, INT8]、trt_workspace_size_mb 1024）；以及硬件建议（至少 1 个 GPU，建议 4 个，A100 需 24GB+）。完整的 TAO Deploy 参考：tao-deploy-dino。

生成 evaluate 规范时，沿用 AutoML 获胜记录中的结构模型设置（model.backbone、model.num_queries、model.dropout_ratio、dataset.num_classes），使检查点形状与评估模型匹配。

错误模式

常见故障包括 CUDA OOM、num_select < num_queries * num_classes、spec/schema 合并错误、数据集大小小于批次大小、return_interm_indices 与 num_feature_levels 不匹配、图像缺失或验证数据缺失导致的 FileNotFoundError、num_classes 过低导致的 CUDA device-side assert、S3 输入未下载，以及在结果根目录中找不到评估检查点。每种错误模式及其修复方法请参阅 references/troubleshooting.md。

AutoML / HPO 说明

AutoML 会运行训练——上述所有 训练要求 均适用；无输入的情况使用 DINO_AUTOML_PROFILE。请勿检查之前的 AutoML 运行来推断数据集 URI、num_classes、推荐数量或间隔设置。请使用显式的 metric="mAP50" 和 direction="maximize"，并使用读取 Validation mAP50 的自定义 metric_extractor，而不是 metric="kpi"。建议的指标提取器、超参数列表、custom_param_ranges、train.optim.weight_decay 说明和骨干网络约束指南请参阅 references/automl.md。

可选：通过 TAO SDK 运行

SDK script_runner 编排、S3 I/O 封装、AutoML 内部机制、规格模板生成、数据源缺口、config.json 中的 inputs 声明，以及完整的各操作 spec 参数 / 父模型推断映射表均记录在 references/sdk_orchestration.md 中。使用 docker run 在本地运行时，请跳过此部分。