tao-train-centerpose

CenterPose

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

model.backbone.pretrained_backbone_path を設定してください。

TAO Deploy の TensorRT アクション（gen_trt_engine、TensorRT の evaluate、TensorRT の inference）については、最初に references/tao-deploy-centerpose.md をお読みください。デプロイ仕様テンプレートは、このスキルの references/ フォルダーに spec_template_deploy_*.yaml というプレフィックスで格納されています。

Dataclass スキーマ

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

Train アクションのポリシー

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

evaluate、inference、export、デプロイフローなどの train 以外のアクションは、このモデルのスキル内で処理します。実行ごとの automl_policy オーバーライドは、モデルのメタデータを変更しません。

トレーニング要件

• データセットタイプ： centerpose
• 形式： デフォルト
• モニタリング指標： val_3DIoU

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

アクション	仕様キー	ソース	ファイル	リスト？
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_overrides に含める必要があります。

S3_TRAIN = "s3://bucket/data/train"
S3_EVAL = "s3://bucket/data/eval"

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": f"{S3_TRAIN}/train.tar.gz",
    "dataset.val_data": f"{S3_EVAL}/val.tar.gz",
}

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

{
    "dataset.category": "bike",
    "dataset.test_data": f"{S3_EVAL}/test.tar.gz",
}

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

{
    "dataset.category": "bike",
    "dataset.inference_data": f"{S3_EVAL}/val.tar.gz",
}

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

{
    "gen_trt_engine.tensorrt.calibration.cal_image_dir": [f"{S3_TRAIN}/train.tar.gz"],
}

Eval データセット

任意です。Val データセットと test データセットは、別々の tarball として提供されます。

重要なパラメーター

• 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 がワーカーを起動します）。

仕様キー	説明	デフォルト
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

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

ハードウェア

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

エラーパターン

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

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 に戻したり、チェックポイントのパスを推測するように生成済みランナースクリプトを修正したりしないでください。