tao-train-foundation-stereo

Depth Net Stereo

使用 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）。

对于 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”“禁用 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 覆盖不会更改模型元数据。

工作流

前置条件 — 数据可访问性

你的数据集（左图 + 右图 + 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 模板（立体）：

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

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

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

从 references/foundation-stereo-spec-overrides.md 复制操作区块（每项操作对应的 spec_overrides、必需数据源）。替换：

• 将 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 评估器才能使用相同的形状运行——请参阅 references/foundation-stereo-troubleshooting.md。

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

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

训练要求

• 立体视觉 data_sources 的有效 dataset_name 值（不区分大小写）：FSD、IsaacRealDataset、Crestereo、Middlebury、Eth3d、Kitti、GenericDataset
• **监控指标：**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	是

典型规范覆盖项

每项操作都必须覆盖数据源——Agent 必须根据上方的「各操作的数据集要求」表构造数据源路径，并将其包含在 spec_overrides 中。每个 data_sources 条目都是一个字典，包含两个必填字段：data_file 和 dataset_name。

完整的、按操作划分的 spec_overrides 块（train、evaluate、export、gen_trt_engine、inference、quantize），包含 S3_TRAIN / S3_EVAL 占位符，请参阅 references/foundation-stereo-spec-overrides.md。

评估数据集

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

重要参数

主要默认值：model.model_type = FoundationStereo（唯一可选类型）；model.encoder（顶层字段，不在 stereo_backbone 下），架构默认值为 vitl，但 FS small NGC ckpt 需要 vits，请显式覆盖；model.max_disparity 默认值为 416；train.optim.lr 默认值为 1e-4；train.precision 为 fp32（推荐）或 fp16（不支持 bf16）；export.batch_size 默认值为 -1。字段名是 workers，不是 num_workers。

完整的参数术语表（包含所有 model.*、dataset.*、train.*、export.* 字段及其默认值和范围），以及评估指标参考（说明应信任哪些 epe / bp* / d1 / rmse，以及为什么 abs_rel / sq_rel / rmse_log 对立体视觉没有意义），请参阅 references/foundation-stereo-parameters.md。

多 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/FSDP 行为与 depth-net-mono 相同。多节点需要 WORLD_SIZE、NODE_RANK、MASTER_ADDR、MASTER_PORT 环境变量。

导出 / TRT 默认值

TRT 数据类型为 FP32 / FP16。静态形状 ONNX（export.batch_size: 1）和仅批次动态 ONNX（export.batch_size: -1）都支持 fp16；高度和宽度始终固定为追踪时的形状（不支持 H/W 动态引擎——请为每个 (H, W) 单独构建引擎）。对于 NGC 版本（576×960），设置 export.batch_size: 1、export.opset_version: 17、export.on_cpu: True。

完整的导出 / TRT 默认值（opset 与 on_cpu 的配对规则、确定性说明、on_cpu 的 GPU 内存阈值）以及硬件要求，请参阅 references/foundation-stereo-export-trt-hardware.md。三个受支持的部署路径及验证表，请参阅 references/tao-deploy-foundation-stereo.md。

完整的 TAO Deploy 参考：tao-deploy-foundation-stereo。

错误模式

常见问题：视差溢出（减小 model.max_disparity）；缺少预训练路径（设置 model.stereo_backbone.depth_anything_v2_pretrained_path 和 model.stereo_backbone.edgenext_pretrained_path）；Key 'encoder' not in 'StereoBackBone'（encoder 位于顶层 model.encoder）；Key 'dataset_name' is not in struct（每个 data_sources 条目都需要同时包含 data_file 和 dataset_name）；bash: exec: depth_net_stereo: not found（入口是 depth_net，没有后缀）。

请参阅 references/foundation-stereo-troubleshooting.md，了解完整的错误模式，以及 pyt 与 deploy 的 crop_size 讨论（pyt evaluate 路径以图像原始分辨率运行，并忽略 crop_size，其中包含 Middlebury 分辨率指南）和 Shape consistency 规则。

Spec 参数／父模型推断

特定于模型的推断映射应放在 MD 中，而不是 config.json 中。生成的运行器会读取这些映射，并在调用 create_job() 之前使用 SDK 辅助函数应用它们（与旧版微服务的 infer_params.py 流程相同）。对于 parent_model / parent_model_folder，将上游 train/export/AutoML 子作业 ID 作为 parent_job_id 传入；SDK 会列出父级结果文件夹，筛选检查点制品，并返回选定的模型文件或文件夹。不要将这些映射加回 config.json，也不要修改生成的运行器脚本来猜测检查点路径。

请参阅 references/foundation-stereo-spec-param-inference.md，了解完整的按操作划分的推断映射表（train / evaluate / inference / export / gen_trt_engine / quantize，其中包括 train 的预训练路径链接／目标位置映射和恢复检查点映射）。