tao-train-fast-foundation-stereo

Depth Net Fast Stereo

使用 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。部署规格模板位于 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 或缺少已打包的训练模式／模板时，才直接进行模型训练；若缺少模式，则报告 AutoML 已启用，但在生成模式之前无法对该模型运行。

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

两种用例

FFS 随附一个预训练的 bp2 商业检查点（model_best_bp2_serialize.pth）。

1. 直接部署——原样使用 bp2 ckpt。跳过 train；直接使用 bp2 文件作为操作的检查点运行 inference／evaluate／export／gen_trt_engine。
2. 使用用户数据微调——将 train.pretrained_model_path 设置为 bp2 文件，使用用户数据训练，然后在生成的 ckpt 上进行验证和部署。支持完整的 7 操作序列（train → evaluate pyt → inference pyt → export → gen_trt_engine → inference deploy → evaluate deploy）。

工作流

前提条件——数据可访问性

数据集（训练／评估需要左图、右图和 GT 视差；推理只需要左图和右图）必须能从容器内部访问：

• SDK runner：将文件放在 runner 会解析的 S3 路径中（规格覆盖设置中显示的 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 商用检查点完全一致。省略任何字段都会回退到与 bp2 ckpt 不匹配的 TAO 默认值，并在前向传播时产生形状不匹配错误。

model:
  model_type: FastFoundationStereo
  encoder: vitl
  hidden_dims: [128]                    # 1-layer GRU; NOT [128,128,128]
  n_gru_layers: 1                       # bp2 single-GRU
  corr_radius: 4
  corr_levels: 2
  n_downsample: 2
  valid_iters: 8
  max_disparity: 192                    # bp2 commercial; NOT 416 (full FS default)
  volume_dim: 28                       # bp2 ckpt invariant; NOT 32 (full FS default)
  mixed_precision: false                # see references/parameters.md
  gwc_feature_normalize: true           # see references/parameters.md

  # 15 bp2 distilled width overrides — copy as-is
  motion_encoder_widths: [56, 96, 16, 12]
  motion_encoder_final: 48
  gru_hidden: 60
  gru_gating_conv_widths: [100, 168]
  disp_head_input_dim: 60
  disp_head_intermediate: 36
  disp_head_pwconv1_widths: [212, 244]
  mask_widths: [32, 16]
  stem_2_widths: [12, 16]
  spx_2_gru_widths: [16, 12, 16, 24]
  spx_gru_out: 9
  classifier_mid: 14
  cnet_conv04_widths: [60, 48]
  cam_mid_channels: 8
  cost_agg_conv_patch_padding: [0, 0, 0]

references/spec_template_*.yaml 中的规格模板包含此代码块，可作为权威来源。

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

从 references/spec-overrides.md 复制 action 代码块（各 action 对应的 Python 覆盖字典，以及共享的 FFS_MODEL_BLOCK）。替换：

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

训练 → 下一 action 的串联检查点路径：对于本地 Docker 串联（无 SDK runner），训练得到的检查点位于 <train.results_dir>/<task>/dn_model_latest.pth — Lightning ModelCheckpoint 会在任务名称下创建子目录。例如：train.results_dir: /workspace/results/finetune/train 会生成 /workspace/results/finetune/train/train/dn_model_latest.pth。将此嵌套路径用于下一 action 的 <action>.checkpoint。SDK runner 部署会通过 parent_job_id 自动解析此路径 — 参见 references/parent-model-inference.md。

形状一致性：dataset.test_dataset.augmentation.crop_size 中的 crop_size 应与 export.input_height / input_width 匹配，以便端到端比较 pyt 与部署结果 — 参见 references/tao-deploy-fast-foundation-stereo.md 中的形状表。

步骤 5 — 运行

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> \
  -v <bp2_ckpt_dir>:<bp2_ckpt_dir>:ro \
  <container> \
  depth_net <action> -e <spec.yaml>

如果没有使用 --user $(id -u):$(id -g)，容器会以 nobody:nogroup 身份写入输出，从而阻碍主机端清理 / 重试。

关于本地绑定挂载的 __pycache__ 注意事项（仅限 QA / 开发 — 清除会遮蔽已修补源码的过期 .pyc 文件），参见 references/troubleshooting.md → “本地绑定挂载提示”。

步骤 6 — 验证

• 容器退出代码为 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，但这些指标对立体视觉没有意义）
• 对于 inference：检查 results_dir 下的产物
• pyt 和 deploy 之间的 KPI 命名空间差异：pyt evaluate 会将指标集写入 kpi.val/epe、kpi.val/bp1 等位置（由 Lightning 的 val/ 前缀命名空间限定）。Deploy evaluate（TRT 引擎路径）会将相同的指标集写入 kpi.epe、kpi.bp1 等位置（没有 val/ 前缀）。读取 status.json 的下游验证脚本需要兼容这两种结构。
• 在自己的数据集上验证漂移：如果在相同输入上比较 TAO FFS deploy（gen_trt_engine + TRT evaluate）与上游 FFS deploy 路径，预期会出现少量残余 mean_abs 差异漂移（TAO 导出图与 TRT 10.13 的交互所致；无法在源代码层面改进）。确切幅度取决于数据集和硬件，请在自己的数据上测量，并判断该漂移对下游任务是否可接受。

7 个操作的 deploy 流程

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

原始 bp2 deploy 可跳过 train。其余 6 个操作（或从 export 开始的仅 deploy 的 4 个动词）覆盖这两种用例。

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

训练要求

• 立体视觉 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	是
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	是

每个操作都必须覆盖数据源。每个 data_sources 条目都需要包含 data_file 和 dataset_name。步骤 3 中的 model.* 宽度字段也为必填项。完整的各操作覆盖字典（train 微调、raw-bp2 evaluate / inference / export）以及共享的 FFS_MODEL_BLOCK，请参阅 references/spec-overrides.md。

评估数据集

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

参数、指标、硬件

完整的参数术语表（包括 max_disparity: 192、gwc_feature_normalize: true、mixed_precision: false、volume_dim: 28、valid_iters、save_raw_pfm 等 model.* / dataset.* / train.* 参数）、评估指标表（epe / bp1 / bp2 / bp3 / d1 / rmse 有意义；abs_rel / sq_rel / rmse_log 没有意义）、多 GPU / 多节点规格键及硬件要求，请参阅 references/parameters.md。

导出 / TRT 默认值

export 始终会导出 fp32 ONNX，无论 model.mixed_precision 的值是什么；fp16 与 fp32 的选择由 gen_trt_engine 中的 gen_trt_engine.tensorrt.data_type 决定。对于 FFS-bp2，在静态形状 ONNX 路径上推荐使用 fp16 精度，以将偏差降至最低。动态形状路径同时支持 fp32（默认值；与静态 fp32 路径结果一致）和 fp16（适用于延迟敏感的多分辨率场景；偏差较大，某些检查点状态下可能出现 NaN——如果观察到此情况，请回退到 fp32）。

有关完整的 TRT/ONNX 默认值以及四种导出用例矩阵（export.batch_size × export.dynamic_hw），请参阅 references/export-trt-defaults.md（动态 H/W 仅适用于 FFS）。有关部署矩阵以及静态与动态形状的使用指南，请参阅 references/tao-deploy-fast-foundation-stereo.md。

故障排除

有关错误模式及其修复方法，请参阅 references/troubleshooting.md，其中包括 forward 阶段的 shape mismatch（缺少宽度覆盖值）、缺少 gwc_feature_normalize（TAO Core 版本过旧）、FS / 单目导出时的 dynamic_hw: true 警告、Key 'encoder' not in 'StereoBackBone'、data_sources 中缺少 dataset_name、视差为负值、视差偏差大于预期（缺少 max_disparity: 192）、depth_net_stereo: not found、仅用于装饰的 pyt-eval crop_size、无实际影响的 Failed to import SAM3 警告，以及动态部署时静默出现的步幅不兼容问题。

Spec 参数 / 父模型推断

特定于模型的推断映射应放在此技能中，而非 config.json 中。生成的运行器应在调用 create_job() 前，使用 SDK 辅助函数应用这些映射。有关按操作列出的 spec 字段 → 推断函数完整映射表，请参阅 references/parent-model-inference.md。

对于 parent_model 或 parent_model_folder，请将上游训练 / 导出 / AutoML 子作业 ID 作为 parent_job_id 传入。SDK 会列出父级结果文件夹、筛选检查点制品，并返回选定的模型文件或文件夹。对于没有父级训练作业的 raw-bp2 用例，请将 <action>.checkpoint 字段明确设为 bp2 文件路径。不要修改生成的运行器脚本来猜测检查点路径。