tao-train-depth-anything-v2

单目深度网络

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

使用 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。部署规格模板位于此技能的 references/spec_template_deploy.yaml 中。

此模型技能打包的 PyT 操作为：train、evaluate、inference、export 和 quantize。当前 TAO 镜像中的 PyT depth_net 入口点不接受 PyT 侧的 gen_trt_engine 操作。gen_trt_engine 操作元数据必须使用 TAO Deploy 容器运行，部署工作流仍是特定于部署的入口点。

训练操作策略

此模型在模型层启用了 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 或缺少已打包的训练 schema／模板时，才直接训练模型；如果缺少 schema，请说明 AutoML 已启用，但在生成 schema 之前无法用于此模型。

evaluate、inference、export 等非训练操作及部署流程仍由此模型技能处理。每次运行的 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

不要将立体标注行（例如 <left_image> <right_image> <gt_depth>）直接用于单目训练／评估／推理。如果只能使用立体深度数据集，请通过保留左图和 GT 深度列来生成单目标注文件，然后在相同的容器路径挂载或暂存图像／深度存档；这些路径必须与派生标注文件中引用的路径一致。

如果已有标注文件，请指定其路径。否则，使用 depth_net convert 生成：

depth_net convert -e <convert_spec.yaml>

convert_spec.yaml 模板：

results_dir: <directory where generated annotation files are written>
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 评估，应使用 /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 不会报错。请根据数据的编码方式匹配类别。

对于相对单目数据（RelativeMonoDataset 或 NYUDV2Relative），请将 dataset.min_depth 和 dataset.max_depth 留空或都设为 null。非空的度量深度范围会传入相对数据集构造函数，并导致错误：BaseRelativeMonoDataset.__init__() got an unexpected keyword argument 'min_depth'。

步骤 3 — 根据 Typical Spec Overrides 编写 spec yaml

从 Typical Spec Overrides（references/spec-overrides.md）复制 action 块。替换：

• model.model_type：使用步骤 2 中的设置
• dataset.<...>.data_sources[*].dataset_name：使用步骤 2 中的设置
• data_sources[*].data_file：使用步骤 1 中的路径（SDK runner 下使用 S3 路径，直接使用 docker 时使用主机路径）
• 对于度量深度微调：还需应用 references/finetuning-recipes.md 中的 Metric Variant Finetuning Recipe。

单目训练时，将 train.precision 设为 fp32（推荐）或 bf16（Ampere SM80+，备选）。

步骤 4 — 运行

使用 --user 前，请在已挂载的输出路径内创建可写的 home/cache 目录。部分 TAO 容器没有对应主机 UID 的 /etc/passwd 条目，并且以该 UID 运行时，PyTorch／matplotlib 需要可写的缓存路径。

mkdir -p <output_dir>/home \
         <output_dir>/.cache/matplotlib \
         <output_dir>/.cache/torchinductor \
         <output_dir>/.cache/xdg

docker run --gpus 'device=0' --shm-size 16G --shm-size=8g \
  --user "$(id -u):$(id -g)" \
  -e USER="$(id -un)" \
  -e LOGNAME="$(id -un)" \
  -e HOME=<output_dir>/home \
  -e MPLCONFIGDIR=<output_dir>/.cache/matplotlib \
  -e TORCHINDUCTOR_CACHE_DIR=<output_dir>/.cache/torchinductor \
  -e XDG_CACHE_HOME=<output_dir>/.cache/xdg \
  -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-recipes.md 中的 Metric Variant Finetuning Recipe → 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 规范模板位于此 skill 的 references/ 文件夹中，前缀为 spec_template_deploy_*.yaml。

训练要求

• mono data_sources 的有效 dataset_name 值（不区分大小写）：ThreeDVLM、FSD、NvCLIP、IssacStereo、Crestereo、Middlebury、NYUDV2、NYUDV2Relative、RelativeMonoDataset、MetricMonoDataset。NYUDV2 包含以米为单位的 metric depth GT — 与 MetricDepthAnything 配对；NYUDV2Relative 是采用 relative-depth 约定的相同数据 — 与 RelativeDepthAnything 配对。
• 监控指标： val/d1（最大化）、val/loss（最小化）。
• AutoML 指标约定： 对打包的 relative-depth 冒烟测试数据运行 AutoML 冒烟测试时，将 val/d1 作为主要监控指标并将其最大化。Mono d1 是 Delta-1 准确率：有效像素中满足 max(pred/target, target/pred) < 1.25 的比例。不要将 stereo d1 错误率的方向应用于此 mono 指标。即使训练器成功退出并写入可用检查点，也可能会输出 NaN 作为 val/loss，因此除非运行状态指标显示有限值，否则它不是可靠的 AutoML 目标。
• Mono AutoML 搜索允许列表： 对默认的 relative-depth train 工作流，使用 train.optim.lr 和 train.optim.weight_decay。不要搜索 dataset.val_dataset、dataset.test_dataset 或 dataset.infer_dataset 的增强字段，因为它们会改变评分/非训练行为，而不是训练行为。不要为 mono 搜索 model.corr_radius、model.cv_group 或 model.volume_dim；这些字段属于 stereo 架构，对 RelativeDepthAnything 不起作用。

各操作的数据集要求

操作	Spec Key	来源	文件	列表？
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）、S3_TRAIN / S3_EVAL 占位符、relative-variant 精度建议以及 quantize 已知问题说明，请参阅 references/spec-overrides.md。

Eval 数据集

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

重要参数

完整的参数词汇表（包含 model、train、dataset、export 和 inference 键及其选项、默认值和来源）以及预训练检查点加载 — 用例矩阵，请参阅 references/parameters.md。

微调方案

以下内容请参阅 references/finetuning-recipes.md：

• 相对变体微调方案——从 TAO 训练的 RelativeDepthAnything 检查点进行微调（lr 5e-6、LambdaLR、sanity 与收敛指导、部署 LSQ 对齐说明）。
• 度量变体微调方案——检查点兼容性、必需的覆盖项、train 和 export 规格中都必须包含的数据集归一化块（normalize_depth/min_depth/max_depth）、训练器强制执行的默认值、精度、1 个 epoch 的 sanity-run 覆盖项，以及包含 NaN 缓解顺序的 sanity-run PASS 标准。

多 GPU / 多节点

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

规格键	说明	默认值
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 精度：fp32。Ampere SM80+ 硬件支持 BF16，但除非用户明确要求使用 BF16，否则 smoke test 应使用 FP32。

硬件

至少需要 1 块 GPU，建议使用 2 块 GPU。每块 GPU 需要 24GB 以上显存。ViT-Large 编码器的显存占用较高。训练时使用 fp32（推荐）或 bf16（Ampere SM80+，替代选项）。较大输入可使用激活检查点。

错误模式

完整的错误模式目录（深度范围不匹配、相对数据集拒绝 min_depth、缺少预训练权重、encoder 键的位置、dataset_name 不在 struct 中、未找到 depth_net_mono、度量变体超参数来源，以及导出时覆盖 ONNX），请参阅 references/troubleshooting.md。

规格参数 / 父模型推断

模型专属的推断映射（TAO Core depth_net_mono.config.json 操作表）、<results_dir>/train/ 下的检查点文件命名、dn_model_latest.pth 策略、父级 gen_trt_engine 的原因，以及 parent_model / parent_job_id 解析规则，请参阅 references/spec-param-inference.md。

部署

• tao-deploy-depth-anything-v2