tao-train-fast-foundation-stereo

Depth Net Fast Stereo

スタンドアロンでインストールしますか？ このセッションが TAO スキルバンクプラグインによって初期化されていない場合は、まず tao-setup スキルを実行してください（ホストの事前確認、認証情報、スキル間の検出）。

FastFoundationStereo（FFS）（FoundationStereo の bp2 商用蒸留版）を使用したリアルタイムステレオ深度推定です。整流化されたステレオ画像ペアから視差マップを予測し、レイヤーごとに幅を刈り込むことでリアルタイム推論を実現します。

mono／stereo／fast-stereo スキルは、統合された TAO depth_net CLI を共有します。FFS は model.model_type: FastFoundationStereo で選択します。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 モデルのトレーニング、評価、エクスポート、推論の実行には、このスキルを使用してください。サポートされている用途は次の 2 つです。

FFS の raw-deploy および bp2-finetune フローでは、事前トレーニング済みの bp2 商用チェックポイント（model_best_bp2_serialize.pth）が必要です。デフォルトの PyT イメージにはこのファイルがディスク上に存在する保証がないため、チェックポイントのパスは必須のユーザー／レジストリアーティファクトとして扱ってください。bp2 チェックポイントを利用できない場合でも、ワークフローの検証にはスクラッチトレーニングを使用できますが、得られるメトリクスは bp2 モデルの性能を反映しません。

1. Raw deploy — 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）がサポートされています。

Train アクションのポリシー

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

FFS は depth_net_stereo スキーマを共有しますが、bp2 アーキテクチャの幅は固定の不変条件です。デフォルトの AutoML では、ユーザーがより広い探索を明示的に要求しない限り、train.optim.lr と train.optim.lr_decay のみを探索してください。デフォルトの探索空間には、model.volume_dim、model.hidden_dims などの FFS アーキテクチャフィールドや、その他の bp2 幅設定を含めないでください。 evaluate、inference、export、デプロイフローなど、train 以外のアクションはこのモデルスキル内にとどめます。実行ごとの 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 では、bp2 商用チェックポイントと完全に一致する値を持つ、モデルセクションの幅オーバーライドフィールドが 15 個必要です。フィールドを 1 つでも省略すると、bp2 ckpt と一致しない TAO のデフォルト値が使われ、forward 時に形状不一致エラーが発生します。コピーしてそのまま使用できる model: ブロック全体と注記については、references/setup-and-run.md を参照してください。spec テンプレートの references/spec_template_*.yaml には、このブロックが標準の情報源として含まれています。

ステップ 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 のパスに置き換えます
• raw deploy のユースケース（学習なし）では、<action>.checkpoint に bp2 ファイルのパスを設定します
• finetune のユースケースでは、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 と deploy 間の KPI 名前空間の違いと、想定される deploy のドリフトについては、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 つのデプロイ専用 verb）で両方のユースケースをカバーできます。

トレーニング要件

• ステレオ 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 エントリは、2 つの必須フィールドを持つ dict です: data_file と dataset_name。model.* の width フィールドも必須です — ステップ 3 を参照してください。FFS_MODEL_BLOCK とアクション別（train / evaluate / inference / export）の Python オーバーライド dict については、references/spec-overrides.md を参照してください。

Eval データセット

任意です。Val データセットは 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 キー、export / TRT のデフォルト、export のユースケースマトリクス、ハードウェアのガイダンスについては、references/important-parameters.md を参照してください。

エラーパターン

shape mismatch、gwc_feature_normalize のスキーマエラー、max_disparity のドリフト、負の disparity、depth_net_stereo: not found、pyt-evaluate の crop_size 非対称性、Failed to import SAM3 警告、および dynamic-engine の stride 非互換によるサイレント障害については、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