tao-train-foundation-stereo

Depth Net Stereo

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

使用 FoundationStereo 架构进行立体深度估计。根据立体图像对预测视差图，用于 3D 重建。

使用预训练的 Depth Anything v2 和 EdgeNeXt 编码器。设置 model.stereo_backbone.depth_anything_v2_pretrained_path 和 model.stereo_backbone.edgenext_pretrained_path。

单目和立体技能都会在容器内调用统一的 TAO depth_net CLI；单目或立体系列由 model.model_type 选择（例如 FoundationStereo）。

此模型技能打包的 PyT 操作为：train、evaluate、inference、export 和 quantize。当前 TAO 镜像中的 PyT depth_net 入口点不接受 gen_trt_engine 操作；只能通过部署工作流构建 TensorRT 引擎。

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

训练操作策略

此模型在模型层面启用了 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 之前，此模型无法运行 AutoML。

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

工作流

前提条件 — 数据可访问性

必须能够从容器内访问数据集（左图 + 右图 + GT 视差）：

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

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

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

步骤 1 — 标注文件

由 data_sources[*].data_file 指定的逐行标注文件：

列数	格式	用途
2	<left> <right>	立体推理（无 GT）
3	<left> <right> <disparity>	带 GT 的立体任务
4	<left> <right> <disparity> <occlusion_mask>	带 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 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 image paths>]
right_dir_pattern: [<substring matching right image paths>]
depth_dir_pattern: [<substring matching GT disparity paths>]
nocc_dir_pattern: []                 # optional, occlusion mask paths
image_extension: '.png'  # always include the leading dot
depth_extension: '.png'  # form must match image_extension (the swap is a substring replace)
nocc_extension: ''
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] 替换为相应模式的第一个元素并切换扩展名，推导出右图／深度／掩码路径。检查数据集的目录结构，找出区分左图、右图和 GT 的子字符串（例如 Middlebury 中的 im0、im1 和 disp0GT）。

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

如果数据布局符合受支持的类型，优先使用特定数据集类——它会应用该类专属的路径约定、评估裁剪方式，以及（如适用）遮挡掩码处理。只有在数据布局与任何已注册类都不匹配时，才回退到 GenericDataset。

数据类别	model_type	dataset_name
Middlebury 数据	FoundationStereo	Middlebury
KITTI 数据	FoundationStereo	Kitti
ETH3D 数据	FoundationStereo	Eth3d
FSD 合成数据	FoundationStereo	FSD
IsaacReal 合成数据	FoundationStereo	IsaacRealDataset
Crestereo 合成数据	FoundationStereo	Crestereo
其他／非规范布局	FoundationStereo	GenericDataset

立体 data_sources 的有效 dataset_name 值（不区分大小写）：FSD、IsaacRealDataset、Crestereo、Middlebury、Eth3d、Kitti、GenericDataset。

训练和评估操作使用相同的 dataset_name 值（这些操作的标注均为 3 列或 4 列，且包含 GT 视差）。部署侧的 evaluate 操作遵循相同规则——请参阅 references/tao-deploy-foundation-stereo.md。对于使用 2 列标注（左图 + 右图，不含 GT）的推理，无论数据布局如何，都使用 dataset_name: GenericDataset——特定数据集类（Middlebury / Kitti / Eth3d / FSD / IsaacRealDataset / Crestereo）要求输入为 3 列，并会在数据加载器层拒绝 2 列标注。对于使用 3 列标注（左图 + 右图 + GT）的推理，可以使用特定数据集类。

步骤 3 — 根据规格覆盖项编写规格 yaml

从 references/spec-overrides-foundation-stereo.md 复制对应的操作块。替换：

• 将 model.model_type 替换为步骤 2 中的值（通常为 FoundationStereo）
• 将 dataset.<...>.data_sources[*].dataset_name 替换为步骤 2 中的值
• 将 dataset.<...>.data_sources[*].data_file 替换为步骤 1 中的路径
• 对于部署侧的 evaluate：强制设置 dataset.test_dataset.batch_size: 1（请参阅 references/tao-deploy-foundation-stereo.md）。

形状一致性：dataset.test_dataset.augmentation.crop_size 中的 crop_size 应与 export.input_height / input_width 相匹配，以确保训练模型评估器和部署侧 TensorRT 评估器使用相同形状。请注意，在 pyt evaluate 流程中，crop_size 仅作参考；而在部署侧的 evaluate 中，它是权威设置——请参阅 references/troubleshooting-foundation-stereo.md 和 references/tao-deploy-foundation-stereo.md。

全新安装的冒烟测试已在 crop_size: [128, 128]、dataset.max_disparity: 128 和 model.max_disparity: 128 的配置下通过验证。冒烟测试时，避免使用 112×112 的裁剪，也不要将 max_disparity 设得小于正方形裁剪的边长：这些组合可能会在生成检查点之前，因特征图或损失掩码形状不匹配而导致 FoundationStereo 内部出错。

每个操作都必须覆盖数据源。每个 data_sources 条目都是包含两个必填字段的字典：data_file 和 dataset_name。有关各操作的数据集要求表、每个操作的覆盖块以及 quantize 已知问题说明，请参阅 references/spec-overrides-foundation-stereo.md。

步骤 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（即使 loss 为 NaN，入口点仍会报告 Execution status: PASS）
• 对于 evaluate：依据 epe / bp1 / bp2 / bp3 / d1 / rmse（评估器还会输出 abs_rel / sq_rel / rmse_log，这些指标对立体视觉没有意义——参见 references/parameters-foundation-stereo.md）
• 对于 inference：检查 results_dir 下的产物

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

训练要求

• **AutoML 指标约定：**使用打包的 evaluate 操作对建议进行评分时，使用 val/epe，并设置为最小化方向。
• 训练监控指标：val/loss 仅将此指标用于实时训练损失监控。
• AutoML/评估 KPI：val/epe，最小化。打包的 evaluate 操作会将此键写入 status.json；将 val/loss 用作 AutoML 目标会导致试验指标提取失败。其 Lightning 控制台表格 将相同的评估器输出标记为 test/epe，因此验证运行时，请将 AutoML 记录的 val/epe 值与控制台中的 test/epe 值进行比较。
• 推荐的 AutoML 训练参数：train.optim.lr 和 train.optim.weight_decay。不要搜索验证/测试/推理数据增强字段，也不要搜索 model.volume_dim，因为当前实现不会使用此参数。
• **评估数据集：**可选。通过 dataset.val_dataset.data_sources 配置验证数据集（每个条目都需要 data_file 和 dataset_name）。

参见 references/spec-overrides-foundation-stereo.md，了解各操作的数据集要求表以及每个操作必需的数据源覆盖块。

参数、指标、多 GPU、导出/TRT、硬件

参见 references/parameters-foundation-stereo.md，了解完整的重要参数列表（包括 model.encoder 的 vits 覆盖、model.max_disparity 默认值 416、model.volume_dim 无操作说明、dataset.baseline、dataset.focal_x、train.precision、export.batch_size）、评估指标表、多 GPU / 多节点启动键、导出 / TRT 默认值（opset_version/on_cpu 配对、NGC 576×960 设置）以及硬件要求。

错误模式与故障排除

参见 references/troubleshooting-foundation-stereo.md，了解视差溢出、冒烟测试形状不匹配、缺少预训练路径、encoder / dataset_name 结构体错误、depth_net_stereo: not found 入口点说明、pyt 与 deploy 的 crop_size 讨论，以及 deploy evaluate 标量转换失败。

规格参数 / 父模型推理

参见 references/checkpoint-inference-mappings-foundation-stereo.md，了解检查点解析规则（model_epoch_<epoch>_step_<step>.pth、dn_model_latest.pth 策略）、父级 PyT 不支持 gen_trt_engine 的情况，以及 depth_net_stereo.config.json 中完整的各操作推理映射表（包括 parent_model / parent_job_id 解析）。

部署

• tao-deploy-foundation-stereo