tao-train-sparse4d

Sparse4D

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

Sparse4D は、同期・キャリブレーション済みのマルチカメラ画像から 3D ボックスとトラッキング ID を予測します。選択したモデルの実験仕様とチェックポイントを起点にしてください。正式な TAO ドキュメントでは、モデルのワークフローについて説明しています。

手順

1. 要求されたアクション、データの教師情報、選択されたチェックポイント、およびプラットフォームを特定します。アクションの契約と、選択したプラットフォームのスキルを確認してください。ユーザーが選択したプラットフォーム、モデル、データ、およびトレーニング予算を維持してください。
2. バックボーン、クラスの順序、画像の前処理、アンカー、および時間方向の次元を、選択したチェックポイントに合わせます。仕様を準備する前に、以下のバックボーンとチェックポイントの選択に従ってください。
3. 互換性のある既存の info PKL が提供されている場合は、それを使用してください。生データについては、ローカルでの変換とアーティファクトの確認に従ってください。2D ターゲットがあるキャリブレーション済みの実シーンについては、幾何学的蒸留を確認してください。この方法では、3D アノテーションや変換で生成したアンカーは必要ありません。
4. references/spec_template_<action>.yaml と、選択したリリースの実験仕様を起点にします。パスは実際にステージングされたアーティファクトを基準に解決してください。results_dir およびアクション固有の results_dir は、現在のジョブ出力ディレクトリに設定してください。リリース済みの仕様には、古い出力パスが含まれている場合があります。フラットなドット区切りキーではなく、ネストされた YAML を記述してください。train/val/test ファイルやシーンの接尾辞を捏造しないでください。インストール済みのランタイムで、要求されたワークフローに使われるフィールドが利用できることを確認してください。
5. モデルアクションではモデルレベルのイメージを、dataset_convert ではアクションレベルの Data Services イメージを解決してください。特定の TAO リリースが要求された場合は、対応するスキルバンクのリリースブランチとそのイメージの固定指定を使用してください。デフォルトブランチのリリースで代用しないでください。tao-launch-workflowと、選択したプラットフォームのsubmit / status / logs / cancelの契約に従い、そのジョブ記録と明示的な出力ディレクトリを維持してください。既存のユーザー承認を適用してください。まだ承認されていない作業についてのみ、不足している起動承認を求めてください。
6. 生成されたアーティファクトとモデルのメトリクスを検証してください。処理の成功や短時間のトレーニング実行はスモークテストの結果であり、3D 精度が向上した証拠ではありません。未公開の実験的な修正や、別の実行の結果を、選択したイメージの検証結果として報告しないでください。

バックボーンとチェックポイントの選択

• ResNet-50 または ResNet-101 が明示的に指定されている場合は、その選択を尊重してください。既存の Sparse4D チェックポイントについては、付属の実験仕様とリリースのメタデータを使い、model.backbone.type（resnet_50 または resnet_101）を判断してください。これらが要求されたバックボーンと一致しない場合は、起動前に不一致を解消してください。チェックポイントの一部だけを読み込めるように、アーキテクチャを変更しないでください。
• チェックポイントまたはバックボーンが未選択の場合は、互換性のあるリリース済みモデルのうち、どれを使用するか尋ねてください。スキーマのデフォルトである resnet_101 は設定上のデフォルトであり、推奨やユーザーのチェックポイントに関する根拠ではありません。
• 選択したチェックポイントのクラス順、アンカー、入力次元、時間方向／クエリの次元を維持してください。由来が不明確な場合、ファイル名だけでは不十分です。
• LTT MLP は、独立したジオメトリアダプターです。ResNet-50 バンドルからダウンロードしても、Sparse4D のバックボーンが選択されたことにはなりません。順序付きのタクソノミーは、トレーニングデータおよびモデルと一致している必要があります。
• ファインチューニングには train.pretrained_model_path を使用します。実行を継続する場合は、train.resume_training_checkpoint_path と互換性のある保存済みのトレーニング状態を使用します。空の pretrained パスでのランダム初期化は、たとえば配線のスモークテストのように、明示的に要求された場合に限り適切です。

学習アクションのポリシー

学習リクエストの前に references/skill_info.yaml を読み込んでください。このモデルでは AutoML が有効です。明示的な automl_policy: on / off を維持してください。通常の学習、HPO なし、固定仕様での再現、範囲を限定した配線のスモークテスト、または厳密な続きからの再開のリクエストでは、その実行について off にします。それ以外の場合はデフォルトで on とし、schemas/train.schema.json と references/spec_template_train.yaml の両方が利用可能であれば、tao-skill-bank:tao-run-automl を通じて実行します。データセット、チェックポイント、仕様、GPU／プラットフォーム、予算のオーバーライドは維持してください。スキーマまたはテンプレートがない場合は、AutoML を利用できないことを報告し、ユーザーのリクエストの範囲内で直接学習を行ってください。

AutoML の監視名は val_mAP です。Sparse4D では img_bbox_NuScenes/mAP と mAP がエイリアスとして出力されます。昇格した再開ジョブでは、新たな評価が行われず、元のランクのメトリックが引き継がれることがあります。その出所を報告し、再開したチェックポイントを個別に検証してください。AutoML スキルのベースライン評価要件に従ってください。評価、推論、エクスポート、量子化は引き続きこのスキルで行います。

学習要件

学習には、変換済みの OVPKL データ、ホールドアウトされたラベル付き検証データ、一致するアンカー、選択した事前学習済みチェックポイントまたは再開状態が必要です。選択したバックボーンと順序付きタクソノミーを維持してください。幾何学的蒸留には、リリース済みの LTT チェックポイントと準備済みの教師信号キャッシュも必要です。GPU 数と学習予算は、ユーザーのリクエストと利用可能なリソースに基づいて選択してください。

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

このモデルでは OVPKL アノテーションを使用します。アクションコントラクトでは、段階的に受け渡す入力、コマンド、出力、任意のアーティファクトを宣言します。info PKL、分割リスト、遅延インデックスに埋め込まれたパスも、選択したランタイム内から参照できる必要があります。分割ファイルだけをステージングしても、そこから参照されるデータはステージングされません。

アクション	ランタイムコマンド	必要なデータ／モデルアーティファクト
dataset_convert	annotations convert -e SPEC（Data Services）	生シーンのルート、キャリブレーション、画像。ラベル付き変換の場合のみ 3D アノテーション
train	sparse4d train -e SPEC	学習用およびホールドアウト検証用の PKL／分割ファイル、画像ルート、一致するアンカー、選択した事前学習済みチェックポイントまたは再開チェックポイント。選択した教師信号ルートに応じて、任意の LTT／キャッシュアーティファクト
evaluate	sparse4d evaluate -e SPEC	evaluate.checkpoint、一致するアンカー、ラベル付きホールドアウト PKL（dataset.test_dataset.ann_file）、画像ルート
inference	sparse4d inference -e SPEC	inference.checkpoint、一致するアンカー、入力 PKL（dataset.test_dataset.ann_file）、画像ルート
export	sparse4d export -e SPEC	export.checkpoint、一致するアンカーとアーキテクチャ、明示的な export.onnx_file。学習データセットや外部 LTT チェックポイントは不要
quantize	sparse4d quantize -e SPEC	quantize.model_path と選択したバックエンドのキャリブレーション入力。ランタイムのバックエンドサポートを確認してください

評価 CLI はテストデータローダーを呼び出します。dataset.val_dataset.ann_file のみを設定しても、評価データは選択されません。このフィールドは学習中の検証に使用されます。完全な仕様に含まれる未使用のデータセットセクションは維持し、未使用のアノテーションファイルをでっち上げたり、ステージングしたりしないでください。

model.head.instance_bank.anchor は、選択したバンドルまたは互換性のあるラベル付き変換から、明示的なモデルアーティファクトとして解決してください。評価またはエクスポートに必須の学習データセットがあるものとして推測しないでください。

アーティファクトの受け渡し方法の詳細については、チェックポイントと出力の解決を参照してください。最初に見つかったチェックポイントを選んだり、削除された SDK ジョブリゾルバーに依存したりしないでください。

代表的な Spec のオーバーライド

AutoML では、上記の表にある具体的なステージング済みパスと skill_info.yaml の data_sources から spec_overrides を構成します。ドット区切りのキーは AutoML のオーバーライドマップであり、コンテナーの YAML 形式ではありません。選択したアクションに必要な入力のみを設定してください。

スコープ	解決するオーバーライド
学習データ	dataset.data_root、dataset.train_dataset.ann_file、dataset.val_dataset.ann_file
モデルの初期化	model.backbone.type、model.head.instance_bank.anchor、dataset.classes、および train.pretrained_model_path または train.resume_training_checkpoint_path
学習リソース	train.num_gpus、train.num_epochs、dataset.batch_size、dataset.num_workers。指定された予算を維持してください
幾何学的蒸留	学習用フラグメント の LTT／キャッシュパスとルートフィールド。HPO 中も、検証済みのクラス順序と教師信号のポリシーを維持してください
評価と推論	dataset.data_root、dataset.test_dataset.ann_file、対応するアンカー、アクションのチェックポイント
出力	results_dir と、現在のジョブに紐付けられたアクション固有の出力パス

dataset.lazy_load: true の場合は、分割データの親ディレクトリをフォルダーとしてステージングし、分割データと同じ場所にある <split>_lazy_index.pkl と、使用する場合は _pkl_cam_counts.pkl も含めてください。ステージング済みディレクトリ内を指すように ann_file を設定し、ファイル単位のステージングによってインデックスから離れた場所に移動しないようにしてください。参照される PKL と画像を参照可能な状態に保ち、移動後はインデックスを再構築してください。dataset.pkl_cam_counts_path は任意のカメラ数オーバーライドであり、lazy index ではありません。

構成とリソースの確認

生成されたスキーマとテンプレートはパッケージ化された契約を示します。schemas/manifest.json にはアクションが一覧表示されています。ユーザーのマシンに TAO Core のチェックアウトを要求しないでください。起動には、ランタイムに対応するリリース仕様を使用してください。スキーマが新しいフィールドを認識していても、古いイメージがそのフィールドをサポートするとは限りません。

• model.backbone.type：選択したチェックポイントに合わせてください。
• train.optim.lr、train.optim.lr_scheduler、train.optim.grad_clip：オプティマイザーの設定は optim の下にネストされています。
• dataset.batch_size：GPU あたりのバッチサイズです。サポートされている場合、dataset.max_cameras によってサンプリングされる学習カメラ数を減らせます。結果として得られる教師信号の網羅性を検証してください。
• train.precision：ハードウェア／ランタイムのサポートに応じて、bf16、fp16、fp32 を指定します。BF16 は必須ではありません。
• train.num_gpus、train.gpu_ids、train.num_nodes：選択したプラットフォームの割り当てを使用してください。1 GPU でのスモーク学習はサポートされています。必要なメモリは、バックボーン、解像度、カメラ数、バッチサイズ、時間設定によって異なります。
• dataset.num_frames と dataset.num_bev_groups はスケジューリング／データサイズの設定であり、アクティベーションメモリにおけるシーケンス長の調整値ではありません。データセットや GPU 数をまたいで学習予算を比較する前に、実際のデータローダーの長さと反復回数を確認してください。
• dataset.eval_dist_fcn と dataset.eval_hota：サポートされている検出／追跡評価を選択します。比較では、しきい値、クラス順序、データセット、raw チェックポイントと EMA チェックポイントの選択を同一にしてください。

Lightning がローカルワーカーを管理します。2 つ目の分散起動ツールを追加しないでください。プラットフォームのマルチノード環境契約を使用してください。TAO の WORLD_SIZE 起動変数はノード数を表し、GPU の総数を表すものではありません。3D／2D の混合分散学習では、幾何学的蒸留のリファレンスにある同期ルート設定も必要です。

エラーのパターン

• アノテーションまたは画像が見つからない場合： コンバーターの出力と埋め込みパスを確認してください。出力された BEV グループのサフィックス、カメラ ID、フレーム ID、マウントルートを保持してください。train を変換しても、val と test の出力は作成されません。
• アンカーが見つからない場合： 選択した事前学習済みバンドルに対応するアンカーを再利用するか、互換性がある場合はラベル付き変換で生成されたアンカーを使用してください。アノテーションなしの変換では、意図的にアンカーの初期化がスキップされます。
• レガシー HDF5 の深度タプル： 該当するラベル付き PKL を確認し、記載されたレイアウトが一致する場合に限り、変換リファレンスのオプションの正規化ヘルパーを使用してください。ラベルなしのシーンには、正規化する深度パスがありません。
• 時間方向の OOM： まず GPU あたりのバッチサイズ、またはサポートされているカメラサンプリングを減らしてください。チェックポイントのアーキテクチャは保持してください。アンカーや時間方向の次元をむやみに縮小したり、num_frames をメモリー対策として扱ったりしないでください。
• LTT または教師キャッシュの不一致： クラスの順序、シーン／カメラ／フレームの結合、コンテナパスを確認してください。公開されている LTT のルートがサポートするのは、元の 7 クラスです。クラス名を変更しても、重みは適応されません。
• エクスポート時の形状変更： 縮小したスモークモデルをトレーニングする前に、変換リファレンスでエクスポーターの仕様を確認してください。現在のエクスポートでは、20 個のダミーカメラと 600 個のキャッシュ済み時間インスタンスを使用します。推論に成功しただけでは、エクスポートとの互換性は確認できません。
• サポート対象外の量子化バックエンド／イメージ： 選択したイメージ、バックエンド、正確なチェックポイント、エラーを報告してください。過去の検証イメージでの結果を根拠に、現在のランタイムが動作すると主張したり、エラーを隠すためにアクションを削除したりしないでください。