tao-train-centerpose

CenterPose

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

キーポイント／ポーズ推定用の CenterPose です。オブジェクトの中心を検出し、キーポイントの位置を回帰します。6-DoF オブジェクトポーズ推定に使用します。

model.backbone.pretrained_backbone_path を設定します。

TAO Deploy TensorRT アクション（gen_trt_engine、TensorRT evaluate、TensorRT inference）では、このスキルの references/ フォルダーに格納されている、spec_template_deploy_*.yaml をプレフィックスとするデプロイ仕様テンプレートを使用してください。

データクラススキーマ

生成された TAO Core スキーマは schemas/<action>.schema.json に格納され、利用可能なアクションは schemas/manifest.json に記載されています。生成された各スキーマから、スキーマ最上位の default フィールドを基に references/spec_template_<action>.yaml も生成されます。AutoML の有効化は、references/skill_info.yaml のモデルレイヤーで automl_enabled を介して宣言されます。あるアクションで AutoML を実行するには、schemas/<action>.schema.json と references/spec_template_<action>.yaml が存在し、解析できる必要があります。automl_default_parameters、automl_disabled_parameters、デフォルト値、最小値／最大値の範囲、列挙値、オプションの重み、数式条件、依存関係、よく使われるパラメーターには、パッケージに含まれる選択済みアクションのスキーマを使用してください。実行時に ~/tao-core が利用できることを前提にしないでください。メンテナーは、スキルバンクをパッケージ化する前にスキーマ／テンプレートを再生成してください。

Train アクションのポリシー

このモデルではモデルレイヤーで AutoML が有効になっています。train ステージのリクエストを処理する前に、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 は有効ですが、スキーマが生成されるまでこのモデルでは実行できないことを報告してください。

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

トレーニング要件

• データセットの種類： centerpose
• 形式： デフォルト
• トレーニング監視メトリクス： val_3DIoU、val_2DMPE
• 評価タスクのメトリクス： test_3DIoU、test_2DMPE
• AutoML メトリクスの契約： 推奨評価に基づくベースライン、eval_fn を通じた各推奨、最良モデルの選択、最終評価には、最大化方向で test_3DIoU を使用してください。val_3DIoU はトレーニングで出力されますが、evaluate アクションでは出力されないため、影響ベースラインを使用しないことが明示的に承認された、トレーニングプロキシ実行でのみ使用できます。

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

アクション	仕様キー	ソース	ファイル	リスト？
evaluate	dataset.test_data	eval_dataset	test.tar.gz	いいえ
gen_trt_engine	gen_trt_engine.tensorrt.calibration.cal_image_dir	calibration_dataset	train.tar.gz	はい
inference	dataset.inference_data	inference_dataset	val.tar.gz	いいえ
train	dataset.train_data	train_datasets	train.tar.gz	いいえ
train	dataset.val_data	eval_dataset	val.tar.gz	いいえ

一般的な Spec のオーバーライド

データソースのオーバーライドはすべてのアクションで必須です。エージェントは、上記の Per-Action Dataset Requirements テーブルに基づいてデータソースのパスを構築し、spec_overrides に含める必要があります。

TRAIN_DIR = "/path/to/extracted/train"
VAL_DIR = "/path/to/extracted/val"
TEST_DIR = "/path/to/extracted/test"
INFER_DIR = VAL_DIR
CAL_IMAGE_DIRS = ["/path/to/extracted/train/<sequence_or_image_dir>"]

train（必須データソース）：

{
    "train.num_epochs": 30,
    "train.checkpoint_interval": 10,
    "train.validation_interval": 10,
    "train.num_gpus": 1,
    "dataset.category": "bike",
    "dataset.batch_size": 4,
    "dataset.train_data": TRAIN_DIR,
    "dataset.val_data": VAL_DIR,
}

evaluate（必須データソース）：

{
    "dataset.category": "bike",
    "dataset.test_data": TEST_DIR,
}

inference（必須データソース）：

{
    "dataset.category": "bike",
    "dataset.inference_data": INFER_DIR,
}

gen_trt_engine（必須データソース）：

{
    "gen_trt_engine.tensorrt.calibration.cal_image_dir": CAL_IMAGE_DIRS,
}

評価データセット

任意です。Val データセットと test データセットは、個別の tarball として提供されます。トレーニングでは val_3DIoU／val_2DMPE KPI が書き込まれ、evaluate では test_3DIoU／test_2DMPE が書き込まれます。トレーニング用のプレフィックスが付いた名前を抽出する evaluate ベースの AutoML コールバックは設定しないでください。

重要なパラメーター

• dataset.num_classes：オブジェクトカテゴリの数です。デフォルトは 1 です。
• dataset.num_joints：オブジェクトあたりのキーポイント数です。8（bbox キーポイント）に固定されています。有効な値は 8 のみです。
• dataset.input_res：入力解像度です。512 に固定されています。出力解像度は 128 に固定されています。
• dataset.category：オブジェクトカテゴリ名です。デフォルトは "cereal_box" です。
• model.backbone.model_type：デフォルトは fan_small です。バックボーンのオプションはスキーマで制限されています。
• train.optim.lr：学習率です。デフォルトは 6e-5 です。MultiStep スケジューラーでは、lr_steps=[90, 120]、lr_decay=0.1 を使用します。
• train.loss_config：切り替え可能な詳細な損失設定です。mse_loss、obj_scale、obj_scale_uncertainty、hps_uncertainty、reg_bbox、hm_hp を指定できます。重みは wh_weight=0.1、off_weight=1、hp_weight=1 です。
• inference.use_pnp：6-DoF 姿勢推定に PnP を使用します。デフォルトは True です。カメラ内部パラメーター（focal_length_x/y、principle_point_x/y）が必要です。
• export.input_width：エクスポート時の入力サイズです。512x512 に固定されています。opset_version=16 です。

マルチ GPU／マルチノード

**起動方法：**Lightning によって管理されます（単一の python プロセスで、Lightning がワーカーを起動します）。

Spec Key	説明	デフォルト
train.num_gpus	GPU の数	1
train.gpu_ids	GPU デバイスのインデックス	[0]

• 戦略：auto（Lightning が最適な戦略を自動的に選択します）
• num_nodes または distributed_strategy の明示的な設定はありません。単一ノードのみです
• sync_batchnorm はありません

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

• エクスポート入力：512x512（固定）、opset 16
• TRT データ型：FP32、FP16、INT8
• TRT opt_batch_size：4、max_batch_size：8

ハードウェア

最低 1 GPU、推奨 2 GPU です。GPU あたり 16GB 以上の VRAM が必要です。CenterPose のメモリー使用量は、入力解像度とキーポイント数に応じて中程度に増加します。

エラーパターン

num_joints の不一致：dataset.num_joints が、アノテーション内のキーポイント数と一致していることを確認してください。

ローカル Docker 用の S3 tarball の展開：スターターキットの S3 データは train.tar.gz、val.tar.gz、test.tar.gz としてパッケージ化されていますが、CenterPose の TAO アクションでは展開済みフォルダーが必要です。各アーカイブを展開し、dataset.train_data、dataset.val_data、dataset.test_data、dataset.inference_data に、展開した各分割データのディレクトリを設定してください。

チェックポイントの引き継ぎ：CenterPose のトレーニングでは、model_epoch_000_step_00008.pth のような具体的なチェックポイントと、centerpose_model_latest.pth シンボリックリンクが書き込まれます。evaluate、inference、export、resume では、SDK／モデルのチェックポイントリゾルバー、またはエポック／ステップを指定した正確なチェックポイントを使用してください。シンボリックリンクは、ユーザーが明示的に最新のものを要求した場合に限り使用してください。

TAO Deploy の後処理との互換性：スキルに固定された deploy イメージ、または選択したプラットフォームから解決された deploy イメージを使用してください。gen_trt_engine が正常に完了しても、deploy の evaluate や inference が動作するとは限りません。これらのアクションの終了コードとログを個別に確認してください。特に、TypeError: only 0-dimensional arrays can be converted to Python scalars のような CenterPose の後処理エラーに注意してください。

Spec Param／親モデルの推論

モデル固有の推論マッピングは、config.json ではなくこの MD ファイルに記述します。生成されたランナーはこのセクションを読み込み、create_job() の前に SDK ヘルパーを使ってマッピングを適用します。これは、以前のマイクロサービスにおける infer_params.py のフローを踏襲しています。

TAO Core の centerpose.config.json からの推論マッピング：

アクション	Spec フィールド	推論関数	意味
evaluate	encryption_key	key	暗号化キー
evaluate	evaluate.checkpoint	parent_model	親ジョブの結果フォルダーから推論されるモデルファイル
evaluate	evaluate.trt_engine	parent_model	親ジョブの結果フォルダーから推論されるモデルファイル
evaluate	results_dir	output_dir	現在のジョブの結果ディレクトリ
export	encryption_key	key	暗号化キー
export	export.checkpoint	parent_model	親ジョブの結果フォルダーから推論されるモデルファイル
export	export.onnx_file	create_onnx_file	ONNX の出力パス
export	results_dir	output_dir	現在のジョブの結果ディレクトリ
gen_trt_engine	encryption_key	key	暗号化キー
gen_trt_engine	gen_trt_engine.onnx_file	parent_model	親ジョブの結果フォルダーから推論されるモデルファイル
gen_trt_engine	gen_trt_engine.tensorrt.calibration.cal_cache_file	create_cal_cache	キャリブレーションキャッシュのパス
gen_trt_engine	gen_trt_engine.trt_engine	create_engine_file	TensorRT エンジンの出力パス
gen_trt_engine	results_dir	output_dir	現在のジョブの結果ディレクトリ
inference	encryption_key	key	暗号化キー
inference	inference.checkpoint	parent_model	親ジョブの結果フォルダーから推論されるモデルファイル
inference	inference.trt_engine	parent_model	親ジョブの結果フォルダーから推論されるモデルファイル
inference	results_dir	output_dir	現在のジョブの結果ディレクトリ
train	encryption_key	key	暗号化キー
train	model.backbone.pretrained_backbone_path	ptm_if_no_resume_model	再開用チェックポイントがない場合の PTM
train	results_dir	output_dir	現在のジョブの結果ディレクトリ
train	train.resume_training_checkpoint_path	resume_model	現在のジョブの結果フォルダーから推論されるモデルファイル

parent_model または parent_model_folder には、上流の train／export／AutoML 子ジョブの ID を parent_job_id として渡します。SDK は親の結果フォルダーを一覧表示し、チェックポイントアーティファクトを絞り込み、選択されたモデルファイルまたはフォルダーを返します。これらのマッピングを config.json に戻したり、チェックポイントパスを推測するよう生成済みランナースクリプトを修正したりしないでください。

デプロイ

• tao-deploy-centerpose