tao-train-depth-anything-v2

Depth Net Mono

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

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

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 にあります。

Train Action Policy

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

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

Workflow

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

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

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

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

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

Step 1 — アノテーションファイル

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

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

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

depth_net convert -e <convert_spec.yaml>

convert_spec.yaml テンプレート：

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 を使用し、/data/nyu_v2/eval/test/bathroom は使用しないでください。後者では 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 が警告なしで発生します。データのエンコード方式に合ったクラスを選択してください。

ステップ 3 — spec overrides から spec yaml を作成する

references/spec-overrides.md からアクションブロックをコピーします。以下を置き換えます：

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

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

ステップ 4 — 実行する

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

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

ステップ 5 — 検証する

• コンテナの終了コードが 0
• status.json の kpi ブロックが入力済み
• train の場合：ステップごとの train_loss を直接確認します。train_loss = NaN でもエントリーポイントは Execution status: PASS を報告します（references/finetuning.md の 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 spec テンプレートは、このスキルの references/ フォルダーにあり、spec_template_deploy_*.yaml というプレフィックスが付いています。

学習要件

• モノ data_sources で有効な dataset_name 値（大文字と小文字を区別しません）：ThreeDVLM、FSD、NvCLIP、IssacStereo、Crestereo、Middlebury、NYUDV2、NYUDV2Relative、RelativeMonoDataset、MetricMonoDataset。NYUDV2 はメトリック深度 GT（メートル単位）を含むため、MetricDepthAnything と組み合わせます。NYUDV2Relative は相対深度の規約に従った同じデータであるため、RelativeDepthAnything と組み合わせます。
• モニタリング指標： 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	はい
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 Overrides

データソースのオーバーライドはすべてのアクションで必須です。上記のPer-Action Dataset Requirementsテーブルに基づいてデータソースのパスを構築し、spec_overridesに含めてください。各data_sourcesエントリーは、必須フィールドdata_fileとdataset_nameを持つ辞書です。アクションごとのtrain／evaluate／export／inference／quantize用オーバーライドブロックと推奨精度の詳細については、references/spec-overrides.mdを参照してください。

Eval Dataset

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

Important Parameters

オプション、デフォルト値、参照元を含む全パラメーターの用語集（model.*、train.*、dataset.*、export.*、inference.*フィールド）と、事前学習済みチェックポイントの読み込み — ユースケースのマトリックスは、references/parameters.mdにあります。主な設定項目は、model.model_type（デフォルトはMetricDepthAnything）、model.encoder（デフォルトはvitl）、train.optim.lr（デフォルトは1e-4、AdamW）、train.precision（fp32を推奨）、dataset.{train,val,test,infer}_dataset.augmentation.crop_size（デフォルトは[518, 518]）です。

Finetuning Recipes

RelativeおよびMetricバリアントのファインチューニングレシピ（必須のspecキー、trainとexportの両方のspecで必要なmetric用dataset.{normalize_depth, min_depth, max_depth}ブロック、トレーナーが強制するデフォルト値（clip_grad_norm: 0.1、warmup_steps: 20、weight_decay: 1e-4）、サニティラン用のオーバーライド、およびtrain_loss = NaNが検出されずに発生するのを防ぐためのサニティランのPASS条件）については、references/finetuning.mdを参照してください。どちらのレシピもLambdaLRを使用し、train.optim.lr: 5e-6を設定します（収束済み／事前学習済みバックボーンからファインチューニングする場合、AdamWのデフォルト値1e-4では学習率が高すぎます）。

Multi-GPU / Multi-Node

起動方法： 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。

Export / TRT Defaults

• TRTのデータ型：FP32、BF16（Ampere SM80以降）。FP16はViT-L monoバックボーンではサポートされていません。
• 推奨するTRTの精度：bf16。BF16に対応するハードウェアがない場合は、fp32を使用してください。

TAO Deployの完全なリファレンス：tao-deploy-depth-anything-v2。

Hardware

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

Error Patterns

よくある失敗の兆候と対処法（深度範囲の不一致、事前学習済み重みの欠落、Key 'encoder' not in 'MonoBackBone'、dataset_nameの欠落、depth_net_mono: not found、metricバリアントのハイパーパラメーターの参照元、export時にONNXファイルの上書きを拒否するエラー）については、references/troubleshooting.mdに記載されています。

Spec Param / Parent Model Inference

モデル固有の推論マッピング（アクションごとのspecフィールドから推論関数への対応表を含むdepth_net_mono.config.jsonの全内容、およびparent_model／parent_job_idの解決方法）については、references/spec-param-inference.mdを参照してください。これらのマッピングはconfig.jsonではなくMDに記載されています。生成されたランナーはこのリファレンスを読み、create_job()の前にSDKヘルパーを使ってマッピングを適用してください。