tao-train-depth-anything-v2

Depth Net Mono

使用 Metric Depth Anything v2 或 Relative Depth Anything 架构进行单目深度估计。从单张 RGB 图像预测每个像素的深度。

预训练检查点的加载方式因模型变体和使用场景而异——请参阅 references/parameters.md 中的 预训练检查点加载——使用场景矩阵。

单目和立体技能都会在容器内调用统一的 TAO depth_net CLI；单目／立体系列通过 model.model_type 选择（完整参数术语表见 references/parameters.md）。

对于 TAO Deploy TensorRT 操作（gen_trt_engine、TensorRT evaluate 和 TensorRT inference），请先阅读 references/tao-deploy-depth-anything-v2.md。Deploy 规格模板位于此技能的 references/spec_template_deploy.yaml。

训练操作策略

此模型在模型层启用了 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 和 Deploy 流程等非训练操作仍在此模型技能中执行。每次运行的 automl_policy 覆盖不会改变模型元数据。

工作流

前提条件 — 数据可访问性

必须能从容器内部访问数据集（RGB 图像 + GT 深度文件）：

• SDK runner：将文件放在 runner 会解析的 S3 路径下（规格覆盖中显示的 S3_TRAIN／S3_EVAL 占位符）。runner 会透明地处理从 S3 到容器路径的挂载。
• 直接运行 docker run（例如本地测试）：将主机上的数据集根目录以只读方式挂载到容器内的相同路径：

docker run ... -v <host_data_root>:<host_data_root>:ro <container> ...

所有操作写入的 <output_dir> 也必须满足相同的可访问性要求。

步骤 1 — 标注文件

由 data_sources[*].data_file 引用的逐行标注文件：

列数	格式	用途
1	<image>	单目推理（无 GT）
2	<image> <gt_depth>	带 GT 的单目处理

如果已有标注文件，请直接指定它。否则，通过 depth_net convert 生成：

depth_net convert -e <convert_spec.yaml>

convert_spec.yaml 模板：

data_root: <directory whose immediate children are scene/sample folders that contain your image+depth files; convert walks data_root recursively but expects per-scene subdirectories at one level below>
image_dir_pattern: [<substring matching left/RGB image paths>]
depth_dir_pattern: [<substring matching GT depth paths>]
image_extension: ''     # optional .endswith filter, e.g. '.jpg'
depth_extension: ''     # optional, swapped during depth derivation, e.g. '.png'
split_ratio: 0.0        # 0.0/1.0 = test-only; 0.8 = 80/20 train+val

convert 会递归遍历 data_root，选择路径字符串中包含 image_dir_pattern 的所有子字符串（AND 筛选）的路径，然后通过将 image_dir_pattern[0] 替换为 depth_dir_pattern[0]，并将 image_extension 替换为 depth_extension，来推导深度文件路径。检查数据集的目录布局，找出用于区分 RGB 图像和深度文件的子字符串（例如 rgb_ 和 sync_depth_）。

data_root 必须指向包含各场景子目录的上级目录（例如，对于 NYU eval，应使用 /data/nyu_v2/eval/test，而不是 /data/nyu_v2/eval/test/bathroom——后者会将遍历范围限制在单个场景内）。image_extension／depth_extension 必须始终包含开头的点（例如 '.jpg'，而不是 'jpg'）；子字符串替换对格式敏感，不匹配会悄无声息地破坏推导出的路径。

步骤 2 — 根据数据配对 model_type 和 dataset_name

默认值 — 每种任务使用通用类：

数据类别	model_type	dataset_name
视差编码数据（像素）	RelativeDepthAnything	RelativeMonoDataset
度量深度（米）	MetricDepthAnything	MetricMonoDataset
单目推理（无 GT，任意图像）	与训练选择一致	RelativeMonoDataset 或 MetricMonoDataset

特定数据集类 — 当数据需要通用类不执行的预处理时，切换到此类：

特殊情况	model_type	dataset_name	类额外执行的操作
NYU sync_depth_*.png（原始 uint16 毫米值）— 相对深度	RelativeDepthAnything	NYUDV2Relative	毫米→米单位转换 + Eigen 评估裁剪
NYU sync_depth_*.png（原始 uint16 毫米值）— 度量深度	MetricDepthAnything	NYUDV2	相同

对需要单位转换的数据（例如原始 NYU uint16 PNG）使用通用类，会导致有效掩码为空，并静默产生 train_loss = NaN。请根据数据的编码方式匹配相应的类。

步骤 3 — 根据规范覆盖项编写规范 YAML

从 references/spec-overrides.md 复制操作区块。替换：

• model.model_type：使用步骤 2 中的值
• dataset.<...>.data_sources[*].dataset_name：使用步骤 2 中的值
• data_sources[*].data_file：使用步骤 1 中的路径（SDK runner 下使用 S3 路径，直接运行 docker 时使用主机路径）
• 对于度量微调：另外应用 references/finetuning.md 中的 度量变体微调方案。

对于单目训练，请设置 train.precision: fp32（推荐）或 bf16（Ampere SM80+，替代选项）。

步骤 4 — 运行

docker run --gpus 'device=0' --shm-size 16G --ipc=host \
  --user $(id -u):$(id -g) \
  -v <data_root>:<data_root>:ro \
  -v <output_dir>:<output_dir> \
  <container> \
  depth_net <action> -e <spec.yaml>

如果没有 --user $(id -u):$(id -g)，容器会以 nobody:nogroup 身份写入输出，从而妨碍主机端清理和重试。

步骤 5 — 验证

• 容器退出代码为 0
• status.json 的 kpi 区块已填充
• 对于 train：直接检查每步的 train_loss — 即使 train_loss = NaN，入口点仍会报告 Execution status: PASS（参见 references/finetuning.md 中的 Sanity-run PASS 标准）
• 对于 evaluate / inference：查看 results_dir 下的产物

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

训练要求

• 单目 data_sources 的有效 dataset_name 值（不区分大小写）：ThreeDVLM、FSD、NvCLIP、IssacStereo、Crestereo、Middlebury、NYUDV2、NYUDV2Relative、RelativeMonoDataset、MetricMonoDataset。NYUDV2 携带度量深度 GT（米）— 与 MetricDepthAnything 配对；NYUDV2Relative 是采用相对深度约定的相同数据 — 与 RelativeDepthAnything 配对。
• 监控指标： val/loss

各操作的数据集要求

操作	规范键	来源	文件	列表？
evaluate	dataset.test_dataset.data_sources	eval_dataset	data_file: annotations.txt + dataset_name	是
inference	dataset.infer_dataset.data_sources	inference_dataset	data_file: annotations.txt + dataset_name	是
quantize	dataset.train_dataset.data_sources	train_datasets	data_file: annotations.txt + dataset_name	是
quantize	dataset.val_dataset.data_sources	eval_dataset	data_file: annotations.txt + dataset_name	是
quantize	dataset.quant_calibration_dataset.images_dir	train_datasets	images.tar.gz	否
train	dataset.train_dataset.data_sources	train_datasets	data_file: annotations.txt + dataset_name	是
train	dataset.val_dataset.data_sources	eval_dataset	data_file: annotations.txt + dataset_name	是

Spec 覆盖项

每个操作都必须覆盖数据源——根据上方的“每个操作的数据集要求”表构建数据源路径，并将其包含在 spec_overrides 中；每个 data_sources 条目都是一个包含两个必填字段 data_file 和 dataset_name 的字典。完整的各操作 train / evaluate / export / inference / quantize 覆盖块及精度建议，请参阅 references/spec-overrides.md。

评估数据集

可选。通过 dataset.val_dataset.data_sources 配置验证数据集（每个条目都需要 data_file 和 dataset_name）。

重要参数

完整的参数词汇表（model.*、train.*、dataset.*、export.*、inference.* 字段的选项、默认值和来源），以及预训练检查点加载——用例矩阵，请参阅 references/parameters.md。关键起始参数：model.model_type（默认值 MetricDepthAnything）、model.encoder（默认值 vitl）、train.optim.lr（默认值 1e-4，AdamW）、train.precision（推荐 fp32）、dataset.{train,val,test,infer}_dataset.augmentation.crop_size（默认值 [518, 518]）。

微调配方

相对深度和度量深度变体的微调配方——包括必需的 spec 键、度量深度训练和导出 spec 中都必需的 dataset.{normalize_depth, min_depth, max_depth} 块、训练器强制默认值（clip_grad_norm: 0.1、warmup_steps: 20、weight_decay: 1e-4）、健全性运行覆盖项，以及用于捕获静默 train_loss = NaN 的健全性运行通过标准——请参阅 references/finetuning.md。两种配方都使用 train.optim.lr: 5e-6 和 LambdaLR（从已收敛或预训练的骨干网络进行微调时，AdamW 默认值 1e-4 过于激进）。

多 GPU / 多节点

**启动方式：**由 Lightning 管理（单个 python 进程，Lightning 会启动工作进程）。

Spec 键	说明	默认值
train.num_gpus	GPU 数量	1
train.gpu_ids	GPU 设备索引	[0]
train.num_nodes	节点数量	1
train.distributed_strategy	ddp 或 fsdp	ddp

• 使用激活检查点时的 ddp：find_unused_parameters=False
• 不使用激活检查点时的 ddp：find_unused_parameters=True
• fsdp 会强制使用 FP16 精度

多节点环境变量（由编排器设置）：WORLD_SIZE、NODE_RANK、MASTER_ADDR、MASTER_PORT、NUM_GPU_PER_NODE。

导出 / TRT 默认值

• TRT 数据类型：FP32、BF16（Ampere SM80+）。ViT-L 单目骨干网络不支持 FP16。
• 推荐的 TRT 精度：bf16。如果硬件不支持 BF16，请使用 fp32。

完整的 TAO Deploy 参考文档：tao-deploy-depth-anything-v2。

硬件

最低要求为 1 块 GPU，推荐 2 块 GPU。每块 GPU 需有 24GB 以上显存。ViT-Large 编码器对内存要求较高。训练时使用 fp32（推荐）或 bf16（Ampere SM80+，替代方案）。较大的输入可使用激活检查点。

错误模式

常见故障特征及修复方法——深度范围不匹配、缺少预训练权重、Key 'encoder' not in 'MonoBackBone'、缺少 dataset_name、找不到 depth_net_mono、度量深度变体超参数来源问题，以及导出时拒绝覆盖 ONNX 的错误——请参阅 references/troubleshooting.md。

Spec 参数 / 父模型推理

针对模型的推理映射（完整的 depth_net_mono.config.json 中按操作列出的 spec 字段到推理函数的映射表，以及 parent_model / parent_job_id 解析指南）请参阅 references/spec-param-inference.md。这些映射应放在 MD 中，而不是 config.json 中；生成的运行器应读取该参考文档，并在调用 create_job() 前使用 SDK 助手应用这些映射。