⚡

tao-train-fast-foundation-stereoSkill tao-train-fast-foundation-stereo

该技能提供 NVIDIA TAO 中 FastFoundationStereo（FFS）模型的实时立体深度估计工作流，支持训练（含 AutoML 调参）、评估、导出和 TensorRT 部署。FFS 是 FoundationStereo 的蒸馏商业版本，能以约 10 倍低延迟预测视差图。关键词：FastFoundationStereo、立体匹配、视差估计、深度模型训练、TAO、TensorRT、实时推理。

视觉模型训练 0 次安装 0 次浏览 更新于 9/6/2026
名称 tao-train-fast-foundation-stereo
描述 使用 FastFoundationStereo (FFS) 的实时立体深度估计，FFS 是 FoundationStereo 的蒸馏 bp2 商业变体。与全量 FoundationStereo 相比，从立体图像对预测视差图的延迟降低约 10 倍。在训练、评估、导出或运行 TAO FastFoundationStereo (FFS) 模型的推理时使用。触发短语包括 “train fast stereo”、“real-time stereo disparity”、“FastFoundationStereo”、“distilled stereo depth”。
开源协议 Apache-2.0 compatibility: 需要 docker + nvidia-container-toolkit。 metadata:
版本 “0.1.0”
作者 NVIDIA Corporation allowed-tools: Read Bash tags: - 立体 - 深度 - 估计 - 实时 - 蒸馏

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

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

mono / stereo / fast-stereo 技能共享统一的 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。部署 spec 模板位于 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。保留对数据集、specs、输出目录、GPU/平台设置、父检查点和 automl_policy 的工作流/应用程序覆盖。仅当 automl_policy: off 或打包的训练 schema/模板缺失时才使用直接模型训练；在缺失 schema 的情况下，报告 AutoML 已启用但在生成 schema 前无法为这个模型运行。

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 运行器：将文件放在运行器解析的 S3 路径上（spec 覆盖中显示的 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 引用的逐行标注文件。Schema 与 depth-net-stereo 相同：

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

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

步骤 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 个 model-section 宽度覆盖字段，这些字段的值必须与 bp2 商业检查点完全匹配。省略任何字段都会回退到与 bp2 ckpt 不匹配的 TAO 默认值，并在前向时产生形状不匹配错误。请参阅 references/setup-and-run.md 获取完整的原样复制 model: 块和说明。位于 references/spec_template_*.yaml 的 spec 模板将此块作为规范来源。

步骤 4 — 根据 spec 覆盖编写 spec yaml

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

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

关于链式训练 → 下一步检查点路径解析和形状一致性说明，请参阅 references/setup-and-run.md。SDK 运行器部署通过 parent_job_id 自动解析交接 — 请参阅 references/parent-model-inference.md。

步骤 5 — 运行

在使用 --user 之前，在挂载的输出路径内创建可写的主目录/缓存目录，然后启动 docker run ... depth_net <action> -e <spec.yaml>。请参阅 references/setup-and-run.md 获取完整的 mkdir + docker run 命令、--user 原理以及本地绑定挂载 __pycache__ 的提示。

步骤 6 — 验证

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

7 操作部署流程

train (可选)                → 微调后的 ckpt
evaluate (pyt)              → PyT eager EPE / bp on val GT
inference (pyt)             → PyT eager 视差样本（视觉检查）
export                      → 静态 fp32 ONNX（推荐 480×736 或 320×736）
gen_trt_engine              → 基于静态 ONNX 路径的 fp16 TRT 引擎
inference (deploy)          → TRT 视差样本
evaluate (deploy)           → TRT EPE / bp 漂移 vs PyT eager fp32

原始 bp2 部署跳过 train。其余 6 个操作（或从 export 开始仅部署的 4 个动词）涵盖了两个用例。

训练要求

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

按操作的数据集要求

操作 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 是
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 条目是一个 dict，包含两个必填字段：data_file 和 dataset_name。model.* 宽度字段也是强制的——请参阅步骤 3。有关 FFS_MODEL_BLOCK 和按操作（train / evaluate / inference / export）的 Python 覆盖 dict，请参阅 references/spec-overrides.md。

Eval Dataset（评估数据集）

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

重要参数

关键旋钮包括 model.model_type (FastFoundationStereo)、model.encoder (vitl)、model.max_disparity(显式设置为 192 — schema 默认值 416 会导致严重漂移)、model.mixed_precision (false)、model.gwc_feature_normalize (true)、model.volume_dim (28)、model.valid_iters (8) 以及每个 split 的 batch_size / workers / crop_size / data_sources。完整参数参考、评估指标、多 GPU / 多节点 spec 键、导出 / TRT 默认值、导出的用例矩阵以及硬件指南请参阅 references/important-parameters.md。

错误模式

有关 shape mismatch、gwc_feature_normalize schema 错误、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 解析和原始 bp2 显式检查点处理，见 references/parent-model-inference.md。生成的运行器应阅读该部分，并在 create_job() 之前使用 SDK 辅助工具应用映射。

部署