tao-train-deformable-detrSkill tao-train-deformable-detr

名称	tao-train-deformable-detr
描述	用于2D目标检测的Deformable DETR。使用可变形注意力进行高效多尺度特征处理，比DINO更轻量且精度相当。适合训练、评估、导出、量化或对TAO Deformable-DETR模型进行推理。触发短语包括“train deformable-detr”、“Deformable DETR object detection”、“lightweight DETR detector”。
开源协议	Apache-2.0 compatibility: 需要Docker + nvidia-container-toolkit。 metadata:
版本	‘0.1.0’
作者	NVIDIA Corporation allowed-tools: Read Bash tags: - object - detection

Deformable DETR

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

Deformable DETR 用于2D目标检测。使用可变形注意力进行高效多尺度特征处理。比 DINO 更轻量，精度相当。

使用预训练权重。设置 model.pretrained_backbone_path 仅加载骨干网络，或设置 train.pretrained_model_path 进行完整模型初始化。

支持的父模型动作包括 train、evaluate、inference、export 和 quantize。PyT 模型容器不支持此网络的原生 gen_trt_engine 子任务。references/skill_info.yaml 中声明的 gen_trt_engine 动作必须在 TAO Deploy 容器中运行。部署规范模板位于本技能的 references/ 文件夹中，前缀为 spec_template_deploy_*.yaml。

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/<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 覆盖不会改变模型元数据。

训练要求

• 数据集类型： object_detection
• 格式： coco，coco_raw
• 监控指标： 用于 AP50 的 val_mAP50；用于 COCO/论文式基准比较的 val_mAP。

每个动作的数据集要求

动作	规范键	来源	文件	列表？
evaluate	dataset.test_data_sources.image_dir	eval_dataset	images.tar.gz	否
evaluate	dataset.test_data_sources.json_file	eval_dataset	annotations.json	否
export	dataset.train_data_sources	train_datasets	image_dir: images.tar.gz, json_file: annotations.json	是
export	dataset.val_data_sources	train_datasets	image_dir: images.tar.gz, json_file: annotations.json	是
inference	dataset.infer_data_sources.image_dir	inference_dataset	images.tar.gz	是
inference	dataset.infer_data_sources.classmap	inference_dataset	label_map.txt	否
quantize	dataset.train_data_sources	train_datasets	image_dir: images.tar.gz, json_file: annotations.json	是
quantize	dataset.val_data_sources	train_datasets	image_dir: images.tar.gz, json_file: annotations.json	是
quantize	dataset.quant_calibration_data_sources	train_datasets	image_dir: images.tar.gz, json_file: annotations.json	否
train	dataset.train_data_sources	train_datasets	image_dir: images.tar.gz, json_file: annotations.json	是
train	dataset.val_data_sources	train_datasets	image_dir: images.tar.gz, json_file: annotations.json	是

典型规范覆盖

数据源覆盖对每个动作都是强制性的——代理必须根据上面的每个动作数据集要求表构造数据源路径，并将它们包含在 spec_overrides 中。

S3_TRAIN = 's3://bucket/data/train'
S3_EVAL = 's3://bucket/data/eval'

训练（强制数据源）：

{
    'train.num_epochs': 10,
    'train.checkpoint_interval': 10,
    'train.validation_interval': 10,
    'train.num_gpus': 1,
    'train.gpu_ids': [0],
    'dataset.num_classes': '<object classes> + 1',
    'dataset.eval_class_ids': [1, 2, '...'],
    'dataset.train_data_sources': [{'image_dir': f'{S3_TRAIN}/images.tar.gz', 'json_file': f'{S3_TRAIN}/annotations.json'}],
    'dataset.val_data_sources': [{'image_dir': f'{S3_TRAIN}/images.tar.gz', 'json_file': f'{S3_TRAIN}/annotations.json'}],
}

评估（强制数据源）：

{
    'dataset.num_classes': '<object classes> + 1',
    'dataset.eval_class_ids': [1, 2, '...'],
    'dataset.test_data_sources.image_dir': f'{S3_EVAL}/images.tar.gz',
    'dataset.test_data_sources.json_file': f'{S3_EVAL}/annotations.json',
}

如果训练或 AutoML 运行更改了架构相关字段，如 model.enc_layers、model.dec_layers、model.num_queries 或 model.num_select，则必须在评估、导出、推理和部署动作中使用所选检查点携带相同的值。除上述字段外，当 model.num_feature_levels、model.dim_feedforward、输入图像尺寸和数据集类别元数据被更改时，也要携带它们。将检查点加载到默认架构中可能会失败，尤其是当冒烟测试运行为了速度而缩小 transformer 时。

导出（强制数据源）：

{
    'dataset.num_classes': '<object classes> + 1',
    'dataset.eval_class_ids': [1, 2, '...'],
    'dataset.train_data_sources': [{'image_dir': f'{S3_TRAIN}/images.tar.gz', 'json_file': f'{S3_TRAIN}/annotations.json'}],
    'dataset.val_data_sources': [{'image_dir': f'{S3_TRAIN}/images.tar.gz', 'json_file': f'{S3_TRAIN}/annotations.json'}],
}

TensorRT 引擎生成：

使用 export 之后的部署规范模板。不要从父 PyT 模型容器中调用 deformable_detr gen_trt_engine；该 CLI 提供 convert、evaluate、export、inference、quantize、train 和 default_specs，但不提供 gen_trt_engine。模型动作元数据会为引擎生成选择 TAO Deploy 容器。

部署引擎生成需要导出的 ONNX 文件作为输入，并在 gen_trt_engine.trt_engine 创建引擎。

{
    'gen_trt_engine.tensorrt.data_type': 'FP16',
    'dataset.num_classes': '<object classes> + 1',
    'gen_trt_engine.tensorrt.calibration.cal_image_dir': [f'{S3_TRAIN}/images.tar.gz'],
}

推理（强制数据源）：

{
    'dataset.num_classes': '<object classes> + 1',
    'dataset.infer_data_sources.image_dir': [f'{S3_EVAL}/images.tar.gz'],
    'dataset.infer_data_sources.classmap': f'{S3_EVAL}/label_map.txt',
}

量化（强制数据源）：

{
    'dataset.train_data_sources': [{'image_dir': f'{S3_TRAIN}/images.tar.gz', 'json_file': f'{S3_TRAIN}/annotations.json'}],
    'dataset.val_data_sources': [{'image_dir': f'{S3_TRAIN}/images.tar.gz', 'json_file': f'{S3_TRAIN}/annotations.json'}],
    'dataset.quant_calibration_data_sources': {'image_dir': f'{S3_TRAIN}/images.tar.gz', 'json_file': f'{S3_TRAIN}/annotations.json'},
}

评估数据集

可选。如果提供，则在每个检查点间隔计算验证 mAP。

检查点处理

训练会输出 epoch 和 step 检查点，使用模式 model_epoch_<epoch>_step_<step>.pth，外加一个 dd_model_latest.pth 符号链接。对于依赖动作，使用模型特定或 SDK 提供的检查点解析器来选择预期工件。评估、推理、导出和量化应接收所选的精确检查点路径，而不是 dd_model_latest.pth 符号链接，除非用户明确要求最新。恢复/重新训练应将 train.resume_training_checkpoint_path 设置为要恢复的精确检查点。

重要参数

• dataset.num_classes：对象类别数加上背景类别。默认91（COCO）。必须与注释匹配。
• dataset.eval_class_ids：要包含在 COCO 指标中的前景类别 ID。在自定义数据集中设置为每个对象类别 ID；模板默认仅评估类别 ID 1。
• model.backbone：默认 resnet_50。支持：resnet_50，gcvit_tiny，gcvit_small，gcvit_base，gcvit_large，gcvit_large_384（比 DINO 更有限）。
• train.optim.lr：学习率。默认 2e-4（AdamW）。lr_backbone 为 2e-5。
• train.optim.lr_steps：MultiStep LR 调度。默认 [40]。对于短训练，设置为约总 epoch 的80%。
• model.num_queries：对象查询数。默认300。有效范围100-900。
• model.dropout_ratio：Transformer 层中的 dropout。默认0.3（高于 DINO 的0.0）。大数据集减少，小数据集增加。
• model.dim_feedforward：FFN 隐藏维度。默认1024（对比 DINO 的2048）。增加可提高容量但内存成本高。

多 GPU / 多节点

启动方法： Lightning 管理（单个 python 进程，Lightning 生成 worker）。

规范键	描述	默认
train.num_gpus	GPU 数量	1
train.gpu_ids	GPU 设备索引	[0]
train.num_nodes	节点数量	1
train.distributed_strategy	ddp 或 fsdp	ddp

与 DINO 相同的 DDP/FSDP 行为。多节点需要由编排者设置 WORLD_SIZE、NODE_RANK、MASTER_ADDR、MASTER_PORT 环境变量。

当增加 train.num_gpus 时，同时将 train.gpu_ids 设置为相同的可见设备范围。例如，8 GPU 单节点 Slurm 运行必须包括 'train.num_gpus': 8 和 'train.gpu_ids': [0, 1, 2, 3, 4, 5, 6, 7]。

导出 / TRT 默认值

• 导出输入：640x640，opset 17
• TRT 数据类型：FP32、FP16、INT8
• TRT 工作空间：1024 MB
• TRT 最大批量：1

硬件

最少 1 个 GPU，建议 4 个 GPU。每个 GPU 需要 16GB+（V100 或 A100）显存。由于 FFN 较小，比 DINO 略轻。batch_size=4 在大多数 16GB+ GPU 上可容纳。

错误模式

CUDA 内存不足：减小 batch_size（4 -> 2 -> 1）。

num_select 必须小于 num_queries * num_classes：与 DINO 相同的约束。

return_interm_indices 长度必须与 num_feature_levels 匹配：默认 [1,2,3,4] 与 num_feature_levels=4。

数据集大小小于总批量大小：减小 batch_size 或 num_gpus。

AutoML 指标提取：Deformable DETR 在结构化训练状态和日志中输出检测指标。对于 COCO/论文式基准比较，以 direction: maximize 优化 val_mAP；对于显式 AP50 工作流，优化 val_mAP50。优先使用 results_dir/train/status.json 或 AutoML 结果状态，而不是解析原始日志。默认检测模型调用不要优化 val_loss。

Spec 参数 / 父模型推断

模型特定的推断映射属于此 MD 文件，不属于 config.json。生成的运行器应读取此部分并在 create_job() 之前使用 SDK 助手应用映射。这类似于旧微服务 infer_params.py 流程。

来自 TAO Core deformable_detr.config.json 的推断映射：

动作	规范字段	推断函数	含义
evaluate	encryption_key	key	加密密钥
evaluate	evaluate.checkpoint	parent_model	根据父作业结果文件夹推断的模型文件
evaluate	evaluate.trt_engine	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	当前作业结果目录
quantize	encryption_key	key	加密密钥
quantize	quantize.model_path	parent_model	根据父作业结果文件夹推断的模型文件
quantize	results_dir	output_dir	当前作业结果目录
train	encryption_key	key	加密密钥
train	model.pretrained_backbone_path	ptm_if_no_resume_model	没有恢复检查点时的 PTM
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，将上游 train/export/AutoML 子作业 ID 作为 parent_job_id 传递。SDK 会列出父结果文件夹，筛选检查点工件，并返回所选的模型文件或文件夹。不要将这些映射添加回 config.json，也不要修改生成的运行器脚本来猜测检查点路径。

部署

• tao-deploy-deformable-detr