tao-train-depth-anything-v2

Depth Net Mono

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

Metric Depth Anything v2 または Relative Depth Anything アーキテクチャを使用した単眼深度推定です。単一の RGB 画像からピクセルごとの深度を予測します。

事前学習済みチェックポイントの読み込み方法は、モデルのバリエーションとユースケースによって異なります。references/parameters.md の 事前学習済みチェックポイントの読み込み — ユースケースのマトリックスを参照してください。

mono と stereo の両スキルは、コンテナ内で統合された TAO depth_net CLI を呼び出します。mono/stereo のどちらを使用するかは model.model_type で選択します（references/parameters.md を参照）。

TAO Deploy の TensorRT アクション（gen_trt_engine、TensorRT の evaluate、TensorRT の inference）については、まず references/tao-deploy-depth-anything-v2.md を読んでください。Deploy 仕様テンプレートは、このスキルの references/spec_template_deploy.yaml にあります。

このモデルスキルにパッケージされている PyT アクションは、train、evaluate、inference、export、quantize です。PyT の depth_net エントリーポイントでは、現在の TAO イメージで PyT 側の gen_trt_engine アクションを受け付けません。gen_trt_engine アクションのメタデータは TAO Deploy コンテナで実行する必要があり、Deploy ワークフローは引き続き 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 がパッケージされている場合、デフォルトでこのモデルの skill_dir を指定して tao-skill-bank:tao-run-automl 経由で学習アクションを実行してください。データセット、仕様、出力ディレクトリ、GPU／プラットフォーム設定、親チェックポイント、automl_policy に対するワークフロー／アプリケーションのオーバーライドは維持してください。直接モデルを学習するのは、automl_policy: off の場合、またはパッケージされた学習スキーマ／テンプレートがない場合に限ります。スキーマがない場合は、AutoML は有効ですが、スキーマが生成されるまでこのモデルでは実行できないことを報告してください。

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

ワークフロー

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

データセット（RGB 画像と GT 深度ファイル）には、コンテナ内からアクセスできる必要があります。

• SDK ランナー：ランナーが解決する S3 パス（一般的な仕様のオーバーライドに示される S3_TRAIN / S3_EVAL プレースホルダー）にファイルを配置してください。ランナーは S3 からコンテナパスへのマウントを透過的に処理します。
• 直接 docker run（例：ローカルテスト）：ホストのデータセットルートを、コンテナ内の同じパスに読み取り専用でマウントしてください。

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

同じアクセス要件は、すべてのアクションが書き込む <output_dir> にも適用されます。

ステップ 1 — アノテーションファイル

data_sources[*].data_file で指定する、行単位のアノテーションファイル：

列	形式	用途
1	<image>	モノ推論（GT なし）
2	<image> <gt_depth>	GT ありのモノ

<left_image> <right_image> <gt_depth> のようなステレオのアノテーション行を、モノの学習／評価／推論にそのまま渡さないでください。ステレオ深度データセットしかない場合は、左画像と GT 深度の列を残してモノ用のアノテーションファイルを作成し、その派生アノテーションファイルで参照される同じコンテナパスに画像／深度アーカイブをマウントするか、配置してください。

すでにファイルがある場合は、そのパスを指定します。ない場合は、depth_net convert で生成します。

depth_net convert -e <convert_spec.yaml>

convert_spec.yaml のテンプレート：

results_dir: <directory where generated annotation files are written>
data_root: <directory whose immediate children are scene/sample folders that contain your image+depth files; convert walks data_root recursively but expects per-scene subdirectories at one level below>
image_dir_pattern: [<substring matching left/RGB image paths>]
depth_dir_pattern: [<substring matching GT depth paths>]
image_extension: ''     # optional .endswith filter, e.g. '.jpg'
depth_extension: ''     # optional, swapped during depth derivation, e.g. '.png'
split_ratio: 0.0        # 0.0/1.0 = test-only; 0.8 = 80/20 train+val

convert は data_root 以下を再帰的に走査し、パス文字列に image_dir_pattern のすべての部分文字列が含まれるパス（AND 条件でフィルタリング）を選択します。次に、image_dir_pattern[0] を depth_dir_pattern[0] に、image_extension を depth_extension に置き換えて深度パスを導出します。データセットのディレクトリ構成を確認し、RGB 画像と深度ファイルを区別する部分文字列（例：rgb_ と sync_depth_）を特定してください。

data_root は、シーンごとのサブディレクトリを含む親ディレクトリを指定する必要があります（例：NYU 評価では /data/nyu_v2/eval/test/bathroom ではなく /data/nyu_v2/eval/test を使用してください。前者では 1 つのシーンしか走査されません）。image_extension／depth_extension には必ず先頭のドットを含めてください（例：'jpg' ではなく '.jpg'）。部分文字列の置換は形式に依存するため、不一致があると導出されたパスが通知なく破損します。

ステップ 2 — データに基づいて model_type と dataset_name を組み合わせる

デフォルト — 各タスクの汎用クラス：

データカテゴリ	model_type	dataset_name
視差エンコードデータ（ピクセル）	RelativeDepthAnything	RelativeMonoDataset
メートル単位のメトリック深度	MetricDepthAnything	MetricMonoDataset
モノ推論（GT なし、任意の画像）	学習時の選択に一致	RelativeMonoDataset または MetricMonoDataset

データセット固有のクラス — 汎用クラスでは行われない前処理がデータに必要な場合に切り替えます：

特殊ケース	model_type	dataset_name	クラスが追加する処理
NYU sync_depth_*.png（生の uint16 ミリメートル値）— 相対	RelativeDepthAnything	NYUDV2Relative	mm→m の単位変換 + Eigen 評価クロップ
NYU sync_depth_*.png（生の uint16 ミリメートル値）— メトリック	MetricDepthAnything	NYUDV2	同上

単位変換が必要なデータ（例：NYU の生の uint16 PNG）に汎用クラスを使用すると、有効マスクが空になり、train_loss = NaN が通知なく発生します。データのエンコード形式に合ったクラスを選んでください。

相対モノデータ（RelativeMonoDataset または NYUDV2Relative）では、dataset.min_depth と dataset.max_depth は未設定のままにするか、両方を null に設定してください。null 以外のメトリック深度範囲を指定すると、相対データセットのコンストラクターに渡され、BaseRelativeMonoDataset.__init__() got an unexpected keyword argument 'min_depth' エラーが発生します。

ステップ 3 — Typical Spec Overrides から spec yaml を作成する

Typical Spec Overrides（references/spec-overrides.md）からアクションブロックをコピーします。以下を置き換えてください。

• model.model_type をステップ 2 の値に置き換えます
• dataset.<...>.data_sources[*].dataset_name をステップ 2 の値に置き換えます
• data_sources[*].data_file をステップ 1 のパスに置き換えます（SDK ランナーでは S3 パス、直接 docker を使用する場合はホストパス）
• メトリックのファインチューニングでは、さらに references/finetuning-recipes.md の Metric Variant Finetuning Recipe を適用します。

モノ学習では、train.precision: fp32（推奨）または bf16（Ampere SM80 以降で使用できる代替設定）を指定します。

ステップ 4 — 実行する

--user を使用する前に、マウントした出力パス内に書き込み可能なホーム／キャッシュディレクトリを作成してください。一部の TAO コンテナにはホスト UID に対応する /etc/passwd エントリーがなく、その UID で実行する場合、PyTorch／matplotlib には書き込み可能なキャッシュパスが必要です。

mkdir -p <output_dir>/home \
         <output_dir>/.cache/matplotlib \
         <output_dir>/.cache/torchinductor \
         <output_dir>/.cache/xdg

docker run --gpus 'device=0' --shm-size 16G --shm-size=8g \
  --user "$(id -u):$(id -g)" \
  -e USER="$(id -un)" \
  -e LOGNAME="$(id -un)" \
  -e HOME=<output_dir>/home \
  -e MPLCONFIGDIR=<output_dir>/.cache/matplotlib \
  -e TORCHINDUCTOR_CACHE_DIR=<output_dir>/.cache/torchinductor \
  -e XDG_CACHE_HOME=<output_dir>/.cache/xdg \
  -v <data_root>:<data_root>:ro \
  -v <output_dir>:<output_dir> \
  <container> \
  depth_net <action> -e <spec.yaml>

--user "$(id -u):$(id -g)" を指定しないと、コンテナは nobody:nogroup として出力を書き込み、ホスト側でのクリーンアップや再試行ができなくなります。

Step 5 — 検証

• コンテナの終了コードが 0
• status.json の kpi ブロックが入力されている
• train の場合：各ステップの train_loss を直接確認してください。エントリーポイントは train_loss = NaN の場合でも Execution status: PASS を報告します（references/finetuning-recipes.md の「Metric Variant Finetuning Recipe」→「Sanity-run PASS criteria」を参照してください）。
• evaluate／inference の場合：results_dir 内にアーティファクトがある

TAO Deploy の TensorRT アクション（gen_trt_engine、TensorRT の evaluate、TensorRT の inference）については、最初に references/tao-deploy-depth-anything-v2.md を読んでください。Deploy 仕様テンプレートは、このスキルの references/ フォルダーにあり、spec_template_deploy_*.yaml というプレフィックスが付いています。

トレーニング要件

• mono の data_sources で有効な dataset_name 値（大文字と小文字を区別しません）：ThreeDVLM、FSD、NvCLIP、IssacStereo、Crestereo、Middlebury、NYUDV2、NYUDV2Relative、RelativeMonoDataset、MetricMonoDataset。NYUDV2 はメートル単位のメトリック深度 GT を含みます。MetricDepthAnything と組み合わせてください。NYUDV2Relative は相対深度の規約に従う同じデータです。RelativeDepthAnything と組み合わせてください。
• 監視メトリック： val/d1（最大化）、val/loss（最小化）。
• AutoML メトリックの要件： パッケージ化された相対深度のスモークデータで AutoML のサニティランを行う場合は、主監視メトリックとして val/d1 を使用し、最大化してください。mono の d1 は Delta-1 精度です。これは、max(pred/target, target/pred) < 1.25 を満たす有効なピクセルの割合です。この mono メトリックにステレオの d1 エラー率の方向性を適用しないでください。トレーナーが正常に終了し、使用可能なチェックポイントを書き出した場合でも、val/loss が NaN として出力されることがあります。そのため、実行のステータスメトリックに有限値が示されていない限り、信頼できる AutoML の目的関数ではありません。
• mono AutoML の検索許可リスト： デフォルトの相対深度トレーニングワークフローでは、train.optim.lr と train.optim.weight_decay を使用してください。dataset.val_dataset、dataset.test_dataset、dataset.infer_dataset の拡張フィールドは、トレーニングではなくスコアリングやその他の動作を変更するため、検索しないでください。model.corr_radius、model.cv_group、model.volume_dim はステレオアーキテクチャ用のフィールドであり、RelativeDepthAnything では機能しないため、mono では検索しないでください。

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

アクション	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	はい
quantize	dataset.train_dataset.data_sources	train_datasets	data_file: annotations.txt + dataset_name	はい
quantize	dataset.val_dataset.data_sources	eval_dataset	data_file: annotations.txt + dataset_name	はい
quantize	dataset.quant_calibration_dataset.images_dir	train_datasets	images.tar.gz	いいえ
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 のオーバーライド

データソースのオーバーライドはすべてのアクションで必須です。アクションごとのデータセット要件の表に従ってデータソースのパスを構成し、spec_overrides に含めてください。各 data_sources エントリーは、data_file と dataset_name の2 つの必須フィールドを持つ辞書です。アクションごとの完全なオーバーライドブロック（train、evaluate、export、inference、quantize）、S3_TRAIN／S3_EVAL プレースホルダー、相対バリアントの精度に関する推奨事項、quantize の既知の問題に関する注記については、references/spec-overrides.md を参照してください。

評価データセット

任意です。検証データセットは dataset.val_dataset.data_sources で構成します（各エントリーには data_file と dataset_name が必要です）。

重要なパラメーター

パラメーターの用語集（model、train、dataset、export、inference のキーとオプション、デフォルト値、参照元）および事前学習済みチェックポイントの読み込み — ユースケースマトリックスの詳細については、references/parameters.mdを参照してください。

ファインチューニングのレシピ

以下については、references/finetuning-recipes.mdを参照してください。

• 相対バリアントのファインチューニングレシピ — TAO で学習済みのRelativeDepthAnythingチェックポイントからファインチューニングする方法（lr 5e-6、LambdaLR、サニティ実行と収束実行の指針、デプロイ時の LSQ アライメントに関する注意）。
• メトリックバリアントのファインチューニングレシピ — チェックポイントの互換性、必須の上書き設定、train AND export の仕様に必要なデータセット正規化ブロック（normalize_depth／min_depth／max_depth）、トレーナーが適用するデフォルト値、精度、1 エポックのサニティ実行用上書き設定、NaN 対策の適用順序を含むサニティ実行の PASS 基準。

マルチ GPU／マルチノード

起動方法： Lightning による管理（単一のpythonプロセスから Lightning がワーカーを起動します）。

Spec Key	説明	デフォルト
train.num_gpus	GPU の数	1
train.gpu_ids	GPU デバイスのインデックス	[0]
train.num_nodes	ノードの数	1
train.distributed_strategy	ddpまたはfsdp	ddp

• アクティベーションチェックポイントを使用するddp：find_unused_parameters=False
• アクティベーションチェックポイントを使用しないddp：find_unused_parameters=True
• fsdpでは精度が FP16 に固定されます

マルチノード環境変数（オーケストレーターによって設定）：WORLD_SIZE、NODE_RANK、MASTER_ADDR、MASTER_PORT、NUM_GPU_PER_NODE。

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

• TRT のデータ型：FP32、BF16（Ampere SM80 以降）。ViT-L モノバックボーンでは FP16 はサポートされていません。
• 新規インストール時の TRT の精度：fp32。BF16 は Ampere SM80 以降のハードウェアでサポートされていますが、ユーザーから明示的に BF16 を指定されない限り、スモークテストは FP32 で実行してください。

ハードウェア

GPU は最低 1 基、推奨 2 基です。各 GPU に 24GB 以上の VRAM が必要です。ViT-Large エンコーダーはメモリーを大量に使用します。トレーニングにはfp32（推奨）またはbf16（Ampere SM80 以降、代替）を使用してください。より大きな入力にはアクティベーションチェックポイントを使用できます。

エラーパターン

エラーパターンの全カタログ（深度範囲の不一致、相対データセットでのmin_depth拒否、事前学習済み重みの欠落、encoderキーの場所、struct にないdataset_name、depth_net_monoが見つからない、メトリックバリアントのハイパーパラメーターの参照元、エクスポート時の ONNX 上書き）については、references/troubleshooting.mdを参照してください。

Spec パラメーター／親モデルの推論

モデル固有の推論マッピング（TAO Core のdepth_net_mono.config.jsonアクションテーブル）、<results_dir>/train/内のチェックポイントファイルの命名規則、dn_model_latest.pthのポリシー、親のgen_trt_engineの根拠、parent_model／parent_job_idの解決ルールについては、references/spec-param-inference.mdを参照してください。

デプロイ

• tao-deploy-depth-anything-v2