tao-train-fast-foundation-stereo

Depth Net Fast Stereo

FastFoundationStereo（FFS） を使用したリアルタイムステレオ深度推定です。FoundationStereo の bp2 商用蒸留版です。リアルタイム推論向けにレイヤーごとの幅をプルーニングし、整流済みステレオ画像ペアから視差マップを予測します。

mono／stereo／fast-stereo スキルは、統合された TAO depth_net CLI を共有します。FFS は model.model_type: FastFoundationStereo で選択します。FFS が FoundationStereo と異なるのは、レイヤーごとのプルーニング済み幅とシリアライズされた forward パスのみです。それ以外（エントリーポイント、アクション動詞、データセットクラス、デプロイチェーン）はすべて 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 にあります。

Train アクションのポリシー

このモデルはモデルレイヤーで AutoML が有効になっています。train ステージのリクエストに対応する前に、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 の両方がパッケージに含まれている場合、デフォルトでこのモデルの skill_dir を指定して、train アクションを tao-skill-bank:tao-run-automl 経由で実行します。データセット、仕様、出力ディレクトリ、GPU／プラットフォーム設定、親チェックポイント、automl_policy に対するワークフロー／アプリケーションのオーバーライドは保持してください。直接モデルをトレーニングするのは、automl_policy: off の場合、または train スキーマ／テンプレートがパッケージに含まれていない場合に限ります。スキーマがない場合は、AutoML は有効ですが、スキーマが生成されるまでこのモデルでは実行できないことを報告してください。

evaluate、inference、export、デプロイフローなどの train 以外のアクションは、このモデルのスキル内にとどまります。実行ごとの automl_policy オーバーライドによって、モデルのメタデータが変わることはありません。

2 つのユースケース

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）に対応しています。

ワークフロー

前提条件 — データへのアクセス

データセット（train／evaluate では左画像＋右画像＋GT 視差、inference では左画像＋右画像のみ）は、コンテナ内からアクセスできる必要があります。

• 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 で参照する、1 行ごとのアノテーションファイルです。スキーマは 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 では、bp2 商用チェックポイントと完全に一致する値を持つ、モデルセクションの幅上書きフィールドが 15 個必要です。フィールドを省略すると、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 — 仕様の上書きから仕様 YAML を作成する

references/spec-overrides.md のアクションブロック（アクションごとの Python 上書き dict と共通の FFS_MODEL_BLOCK）をコピーします。以下を置き換えます。

• model.model_type: FastFoundationStereo（設定済み）
• Step 2 に基づく dataset.<...>.data_sources[*].dataset_name
• Step 1 のパスを指定した dataset.<...>.data_sources[*].data_file
• raw deploy のユースケース（train なし）では、<action>.checkpoint に bp2 ファイルのパスを設定します
• finetune のユースケースでは、train.pretrained_model_path に bp2 ファイルのパスを設定します

連結した train → 次のアクションのチェックポイントパス：SDK ランナーを使わずに Docker 上でローカル連結する場合、学習済みチェックポイントは <train.results_dir>/<task>/dn_model_latest.pth にあります。Lightning ModelCheckpoint は task 名の下にネストされます。例：train.results_dir: /workspace/results/finetune/train の場合、/workspace/results/finetune/train/train/dn_model_latest.pth が生成されます。次のアクションの <action>.checkpoint には、このネストされたパスを使用します。SDK ランナーでの deploy では、parent_job_id によって自動的に解決されます。references/parent-model-inference.md を参照してください。

形状の整合性：エンドツーエンドで pyt と deploy の比較可能性を確保するため、dataset.test_dataset.augmentation.crop_size の crop_size は export.input_height／input_width と一致させる必要があります。形状の表については、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 を直接確認します（損失が 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

raw-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

アクションごとのデータセット要件

アクション	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	はい

すべてのアクションで、データソースのオーバーライドは必須です。各 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 / マルチノードの spec キー、ハードウェア要件については、references/parameters.md を参照してください。

エクスポート / TRT のデフォルト

export は、model.mixed_precision にかかわらず、常に fp32 ONNX を出力します。fp16 と fp32 の選択は、gen_trt_engine の gen_trt_engine.tensorrt.data_type で行います。FFS-bp2 で推奨される TRT 精度は、静的シェイプの ONNX パスでは fp16 です（ドリフトが最小になります）。動的シェイプのパスでは、fp32（デフォルト。静的 fp32 と同等）と fp16（レイテンシが重要なマルチ解像度向け。ドリフトが大きく、一部のチェックポイント状態では NaN が発生する可能性があります）の両方をサポートしています。NaN が確認された場合は、fp32 に切り替えてください。

TRT / ONNX のデフォルト設定と、4 通りのエクスポートのユースケースマトリックス（export.batch_size × export.dynamic_hw。動的 H/W は FFS 専用）については、references/export-trt-defaults.md を参照してください。デプロイメントマトリックスと、静的シェイプと動的シェイプの使い分けについては、references/tao-deploy-fast-foundation-stereo.md を参照してください。

トラブルシューティング

references/troubleshooting.md では、エラーのパターンと解決方法を説明しています。内容には、forward 時の shape mismatch（width override の指定漏れ）、gwc_feature_normalize がない（TAO Core が古い）、FS / mono エクスポート時の 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 Param / 親モデルの推論

モデル固有の推論マッピングは config.json ではなく、このスキルに記述します。生成されるランナーでは、create_job() の前に SDK ヘルパーを使ってマッピングを適用してください。アクションごとの spec フィールド → 推論関数のマッピング表全体については、references/parent-model-inference.md を参照してください。

parent_model または parent_model_folder では、上流の train / export / AutoML 子ジョブ ID を parent_job_id として渡します。SDK は親の結果フォルダーを一覧表示し、チェックポイントのアーティファクトをフィルタリングして、選択したモデルファイルまたはフォルダーを返します。親の train ジョブを使用しない raw-bp2 のユースケースでは、<action>.checkpoint フィールドに bp2 ファイルのパスを明示的に設定してください。チェックポイントのパスを推測するように、生成されたランナースクリプトを変更しないでください。