tao-train-fast-foundation-stereo

深度网络快速立体匹配

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

使用 FastFoundationStereo (FFS) 进行实时立体深度估计。FFS 是 FoundationStereo 的 bp2 商业蒸馏变体。它通过逐层剪枝宽度，从校正后的双目图像对预测视差图，实现实时推理。

单目／立体／快速立体技能共用统一的 TAO depth_net CLI；通过 model.model_type: FastFoundationStereo 选择 FFS。FFS 与 FoundationStereo 的区别仅在于逐层剪枝宽度和序列化的前向路径；其他所有内容（入口点、动作动词、数据集类、部署链）都与 depth-net-stereo 相同。

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

适用场景

使用此技能训练、评估、导出 TAO FastFoundationStereo 模型或运行其推理。支持以下两种用例：

FFS 原始部署和 bp2 微调流程需要预训练的 bp2 商业检查点（model_best_bp2_serialize.pth）。默认 PyT 映像不保证磁盘上存在此文件，因此应将检查点路径视为必需的用户／注册表制品。如果没有可用的 bp2 检查点，仍可通过从头训练验证工作流，但生成的指标不能代表 bp2 模型。

1. 原始部署——原样使用 bp2 检查点。跳过 train；直接使用 bp2 文件作为操作的检查点运行 inference / evaluate / export / gen_trt_engine。
2. 使用用户数据微调——将 train.pretrained_model_path 设为 bp2 文件，在用户数据上训练，然后验证并部署生成的检查点。支持完整的 7 步操作序列（train → evaluate pyt → inference pyt → export → gen_trt_engine → inference deploy → evaluate 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 前无法运行 AutoML。

FFS 共用 depth_net_stereo schema，但其 bp2 架构宽度是固定不变项。默认 AutoML 仅搜索 train.optim.lr 和 train.optim.lr_decay，除非用户明确要求扩大搜索范围。默认搜索空间中不要包含 FFS 架构字段，例如 model.volume_dim、model.hidden_dims 或其他 bp2 宽度设置。 非训练操作（如 evaluate、inference、export 和部署流程）仍由此模型技能处理。单次运行的 automl_policy 覆盖设置不会更改模型元数据。

工作流

前置条件 — 数据可访问性

你的数据集（训练 / 评估需要左图 + 右图 + GT 视差图；推理仅需要左图 + 右图）必须可从容器内部访问：

• SDK runner：将文件放在 runner 解析的 S3 路径下（spec overrides 中显示的 S3_TRAIN / S3_EVAL 占位符）。
• 直接使用 docker run（例如本地测试）：将主机上的数据集根目录以只读方式挂载到容器内的相同路径：

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

所有操作写入的 <output_dir> 以及 bp2 检查点路径也必须满足相同的可访问性要求。

步骤 1 — 标注文件

由 data_sources[*].data_file 引用的逐行标注文件。架构与 depth-net-stereo 相同：

列数	格式	用途
2	<left> <right>	立体推理（无 GT）
3	<left> <right> <disparity>	带 GT 的立体任务
4	<left> <right> <disparity> <occlusion_mask>	带 GT 和遮挡掩码的立体任务

如有需要，可通过 depth_net convert 生成；convert_spec.yaml 模板请参见 depth-net-stereo 技能。

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

FFS 使用 model_type: FastFoundationStereo。dataset_name 的选择与立体技能相同：数据布局符合已注册的数据集时，选择对应的数据集类；否则使用 GenericDataset。

数据类别	model_type	dataset_name
Middlebury	FastFoundationStereo	Middlebury
KITTI	FastFoundationStereo	Kitti
ETH3D	FastFoundationStereo	Eth3d
FSD 合成数据	FastFoundationStereo	FSD
IsaacReal 合成数据	FastFoundationStereo	IsaacRealDataset
Crestereo 合成数据	FastFoundationStereo	Crestereo
其他 / 非标准数据	FastFoundationStereo	GenericDataset

对于使用 2 列标注（左图 + 右图，无 GT）的推理，无论数据布局如何，都使用 dataset_name: GenericDataset。

步骤 3 — 设置 bp2 蒸馏宽度覆盖项

FFS 需要 15 个模型部分的宽度覆盖字段，其值必须与 bp2 商用检查点完全一致。省略任何字段都会回退到 TAO 默认值，这些值与 bp2 ckpt 不匹配，并会在前向计算时导致形状不匹配错误。完整的可直接复制 model: 配置块和说明请参见 references/setup-and-run.md。references/spec_template_*.yaml 中的 spec 模板包含此配置块，作为权威来源。

步骤 4 — 根据 spec overrides 编写 spec yaml

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

• model.model_type: FastFoundationStereo（已设置）
• 将 dataset.<...>.data_sources[*].dataset_name 设置为步骤 2 中的值
• 将 dataset.<...>.data_sources[*].data_file 设置为步骤 1 中的路径
• 对于原始部署用例（无训练）：将 <action>.checkpoint 设置为 bp2 文件路径
• 对于微调用例：将 train.pretrained_model_path 设置为 bp2 文件路径

关于串联训练 → 后续操作时的检查点路径解析和形状一致性说明，请参见 references/setup-and-run.md。SDK-runner 部署会通过 parent_job_id 自动解析交接；请参见 references/parent-model-inference.md。

步骤 5 — 运行

使用 --user 前，先在挂载的输出路径内创建可写的 home/cache 目录，然后运行 docker run ... depth_net <action> -e <spec.yaml>。完整的 mkdir + docker run 命令、--user 的原因以及本地绑定挂载 __pycache__ 的提示，请参见 references/setup-and-run.md。

步骤 6 — 验证

检查容器退出代码是否为 0，以及 status.json 中的 kpi 块是否已填充。对于 train，直接检查每一步的 train_loss（即使 loss 为 NaN，入口程序仍会报告 Execution status: PASS）；对于 evaluate，检查 epe / bp1 / bp2 / bp3 / d1 / rmse；对于 inference，检查 results_dir 下的产物。pyt 与部署端 KPI 命名空间的差异以及预期的部署偏差，详见 references/setup-and-run.md。

7 个操作的部署流程

train (optional)            → finetuned ckpt
evaluate (pyt)              → PyT eager EPE / bp on val GT
inference (pyt)             → PyT eager disparity samples (visual sanity)
export                      → static fp32 ONNX (recommended at 480×736 or 320×736)
gen_trt_engine             → fp16 TRT engine on static ONNX path
inference (deploy)         → TRT disparity samples
evaluate (deploy)          → TRT EPE / bp drift vs PyT eager fp32

部署 raw-bp2 时跳过 train。其余 6 个操作（或从 export 开始的 4 个仅用于部署的动词）可覆盖这两种用例。

训练要求

• 立体视觉 data_sources 的有效 dataset_name 值（不区分大小写）：FSD、IsaacRealDataset、Crestereo、Middlebury、Eth3d、Kitti、GenericDataset
• 监控指标： val/loss

各操作的数据集要求

操作	Spec 键	来源	文件	是否为列表？
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	是
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 覆盖项

每个操作都必须覆盖数据源。每个 data_sources 条目都是一个包含两个必填字段的字典：data_file 和 dataset_name。model.* 宽度字段同样是必填项，参见步骤 3。有关 FFS_MODEL_BLOCK 和各操作（train / evaluate / inference / export）的 Python 覆盖字典，请参见 references/spec-overrides.md。

评估数据集

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

重要参数

关键参数包括 model.model_type（FastFoundationStereo）、model.encoder（vitl）、model.max_disparity（显式设为 192——架构默认值 416 会导致严重偏差）、model.mixed_precision（false）、model.gwc_feature_normalize（true）、model.volume_dim（28）、model.valid_iters（8），以及各数据集划分的 batch_size / workers / crop_size / data_sources。完整的参数参考、评估指标、多 GPU / 多节点 Spec 键、导出 / TRT 默认值、导出用例矩阵和硬件指南，请参见 references/important-parameters.md。

错误模式

有关 shape mismatch、gwc_feature_normalize 架构错误、max_disparity 偏差、负视差、depth_net_stereo: not found、pyt-evaluate 的 crop_size 不对称、Failed to import SAM3 警告，以及动态引擎步幅不兼容的静默失败，请参见 references/error-patterns.md。

Spec 参数 / 父模型推断

有关模型专属推断映射（train / evaluate / inference / export / gen_trt_engine 的操作 Spec 字段 → 推断函数）、parent_job_id / parent_model 解析以及 raw-bp2 显式检查点处理，请参见 references/parent-model-inference.md。生成的运行器应读取该章节，并在调用 create_job() 前使用 SDK 辅助函数应用这些映射。

部署

• tao-deploy-fast-foundation-stereo