tao-train-pose-classification

ポーズ分類

ST-GCN（Spatial Temporal Graph Convolutional Network）を使用したポーズ分類です。ポーズのキーポイントデータから、骨格シーケンスをアクションカテゴリに分類します。

通常、骨格データを使用してスクラッチからトレーニングします。

パッケージ化された PyTorch Pose Classification CLI は、dataset_convert、train、evaluate、export、inference をサポートしています。dataset_convert は条件付きです。入力が生の DeepStream BodyPose JSON の場合にのみ実行してください。データセットがすでに TAO 対応の .npy / .pkl ファイルに変換されている場合は、それらのファイルを使って直接 train を開始し、検証レポートではデータセット変換を not run: preconverted dataset provided と記載してください。このモデルでは、deploy、prune、quantize、スタンドアロンの retrain アクションは公開されていません。再開／再トレーニングでは、train.resume_training_checkpoint_path を設定した pose_classification train -e ... を使用します。

データクラスのスキーマ

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

evaluate、inference、export などの train 以外のアクションと deploy フローは、このモデルのスキル内で実行します。実行ごとの automl_policy 上書き設定によって、モデルのメタデータが変わることはありません。

トレーニング要件

• データセットの種類： pose_classification
• 形式： default
• 監視メトリクス： val_loss

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

アクション	Spec キー	ソース	ファイル	リストか
dataset_convert（オプション）	dataset_convert.data	id	DeepStream BodyPose JSON	いいえ
evaluate	evaluate.test_dataset.data_path	train_datasets	val_data.npy	いいえ
evaluate	evaluate.test_dataset.label_path	train_datasets	val_label.pkl	いいえ
inference	inference.test_dataset.data_path	train_datasets	test_data.npy	いいえ
train	dataset.train_dataset.data_path	train_datasets	train_data.npy	いいえ
train	dataset.train_dataset.label_path	train_datasets	train_label.pkl	いいえ
train	dataset.val_dataset.data_path	train_datasets	val_data.npy	いいえ
train	dataset.val_dataset.label_path	train_datasets	val_label.pkl	いいえ

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

データソースのオーバーライドは、実行するすべてのアクションで必須です。エージェントは、上記の「アクションごとのデータセット要件」表に基づいてデータソースのパスを構成し、spec_overrides に含める必要があります。提供されたデータセットがすでに .npy / .pkl ファイルに変換されている場合は、dataset_convert を実行しないでください。

S3_TRAIN = "s3://bucket/data/purpose_built_models_pose_classification_train/nvidia"
CHECKPOINT = "/results/{train_job_id}/results_dir/model_epoch_000_step_00007.pth"

dataset_convert（任意。未加工の DeepStream BodyPose JSON のみ）：

{
    "dataset_convert.data": "s3://bucket/data/<deepstream-bodypose-output>.json",
}

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

{
    "train.num_epochs": 30,
    "train.checkpoint_interval": 10,
    "train.validation_interval": 10,
    "train.num_gpus": 1,
    "wandb.enable": False,
    "dataset.num_classes": 6,
    "dataset.label_map": {
        "class_0": 0,
        "class_1": 1,
        "class_2": 2,
        "class_3": 3,
        "class_4": 4,
        "class_5": 5,
    },
    "model.graph_layout": "nvidia",
    "dataset.train_dataset.data_path": f"{S3_TRAIN}/train_data.npy",
    "dataset.train_dataset.label_path": f"{S3_TRAIN}/train_label.pkl",
    "dataset.val_dataset.data_path": f"{S3_TRAIN}/val_data.npy",
    "dataset.val_dataset.label_path": f"{S3_TRAIN}/val_label.pkl",
}

train の再開（必須のチェックポイント）：

{
    "train.num_epochs": 31,
    "train.resume_training_checkpoint_path": CHECKPOINT,
    "dataset.train_dataset.data_path": f"{S3_TRAIN}/train_data.npy",
    "dataset.train_dataset.label_path": f"{S3_TRAIN}/train_label.pkl",
    "dataset.val_dataset.data_path": f"{S3_TRAIN}/val_data.npy",
    "dataset.val_dataset.label_path": f"{S3_TRAIN}/val_label.pkl",
}

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

{
    "evaluate.test_dataset.data_path": f"{S3_TRAIN}/val_data.npy",
    "evaluate.test_dataset.label_path": f"{S3_TRAIN}/val_label.pkl",
    "evaluate.checkpoint": CHECKPOINT,
}

export（必須のチェックポイントと出力）：

{
    "export.checkpoint": CHECKPOINT,
    "export.onnx_file": "/results/{export_job_id}/results_dir/pose_classification.onnx",
}

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

{
    "inference.test_dataset.data_path": f"{S3_TRAIN}/test_data.npy",
    "inference.test_dataset.label_path": f"{S3_TRAIN}/test_label.pkl",
    "inference.checkpoint": CHECKPOINT,
    "inference.output_file": "/results/pose_classification_inference.txt",
}

データセットの変換

Pose Classification では、データセットの変換は任意です。ユーザーが未加工の DeepStream BodyPose JSON を提供した場合にのみ、pose_classification dataset_convert を実行してください。一般的な S3 検証データセットは、すでに train_data.npy、train_label.pkl、val_data.npy、val_label.pkl、test_data.npy、test_label.pkl に変換されています。train／evaluate／inference／export の各フローでは、これらのファイルを直接使用し、偽の BodyPose JSON を生成しないでください。

評価データセット

任意です。検証データは、トレーニングデータとともに val_data.npy / val_label.pkl として提供されます。TAO トレーニングでは、このモデルの TensorBoard 検証スカラーとして val_loss が出力されます。カスタム評価フックで別のメトリックが指定されていない限り、AutoML の選択には最小化方向の val_loss を使用してください。

重要なパラメーター

• dataset.num_classes：ポーズアクションクラスの数です。デフォルトは 6 です。
• model.graph_layout：スケルトングラフのレイアウトです。選択肢は nvidia、openpose です。関節の接続方法を決定します。
• model.graph_strategy：GCN のグラフ分割戦略です。
• train.optim.lr：学習率です。デフォルトは 0.1（SGD）です。グラフ畳み込みの特性により、ビジョンモデルより高くなっています。
• model.dropout：正則化のためのドロップアウト率です。

マルチ GPU／マルチノード

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

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

• 戦略：auto（Lightning が最適な戦略を自動的に選択します）
• num_nodes や distributed_strategy の明示的な設定はありません。単一ノードのみです。
• 軽量なモデルのため、通常は単一 GPU で十分です。

ハードウェア

最低 1 GPU、推奨 1 GPU です。GPU あたり 8GB 以上の VRAM が必要です。Pose Classification は非常に軽量で、スケルトンデータも小さいため、単一 GPU で十分です。

エラーパターン

グラフレイアウトの不一致：model.graph_layout が、.npy データファイル内のスケルトン形式と一致していることを確認してください。

ラベル形状の不一致：train_label.pkl のクラスインデックスは、[0, num_classes) の範囲内である必要があります。

ラベルマップの欠落：トレーニング用データローダーは、dataset.label_map が辞書であることを前提としています。データセットが数値のクラス ID のみを提供する場合は、6 クラスの NVIDIA サンプルデータに対して、class_0: 0 から class_5: 5 のような連続した合成マップを設定してください。

チェックポイントの引き継ぎ：AutoML／トレーニングの後、チェックポイントリゾルバーを使って親結果フォルダー内の目的の保存済み .pth チェックポイント（model_epoch_000_step_00007.pth など）を選択し、そのファイルを evaluate.checkpoint、export.checkpoint、inference.checkpoint、または train.resume_training_checkpoint_path に指定してください。pc_model_latest.pth は最新のチェックポイントへのシンボリックリンクです。ユーザーが特定の／最良のチェックポイントではなく最新のものを明示的に要求した場合にのみ使用してください。後続のアクションでも、同じ dataset.num_classes、dataset.label_map、model.graph_layout のオーバーライドを維持してください。

データセット変換の入力元：dataset_convert は、DeepStream BodyPose アプリから出力された未加工の JSON を想定しています。一般的な NVIDIA サンプルの S3 フォルダーには、すでに train_data.npy、train_label.pkl、val_data.npy、val_label.pkl、test_data.npy、test_label.pkl への変換済みファイルが含まれています。これらがある場合は変換をスキップし、変換済みファイルから開始してください。

アクションごとのデータセットパス：evaluate と inference のテンプレートには、トレーニング用の dataset.train_dataset および dataset.val_dataset ブロックも含まれています。evaluate の場合は、evaluate.test_dataset.data_path と evaluate.test_dataset.label_path を設定してください。inference の場合は、inference.test_dataset.data_path を設定し、inference.output_file も指定してください。ファイル内で最初に見つかった data_path または label_path を置き換えただけで終わらせないでください。

出力ファイル：エクスポートには、export.onnx_file の明示的なパスが必要です。inference では、inference.output_file に書き込み可能なファイルパスを設定する必要があります。パッケージに含まれるテンプレートのデフォルト値は空文字列で、現在の PyTorch 推論コードはその値を直接開きます。

Spec Param / 親モデル推論

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

TAO Core の pose_classification.config.json からの推論マッピング:

Action	Spec フィールド	推論関数	意味
dataset_convert	dataset_convert.results_dir	output_dir	現在のジョブの結果ディレクトリ
evaluate	encryption_key	key	暗号化キー
evaluate	evaluate.checkpoint	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	現在のジョブの結果ディレクトリ
inference	encryption_key	key	暗号化キー
inference	inference.checkpoint	parent_model	親ジョブの結果フォルダーから推論されたモデルファイル
inference	inference.output_file	create_inference_result_file_pose	ポーズ推論の結果ファイル
inference	results_dir	output_dir	現在のジョブの結果ディレクトリ
train	encryption_key	key	暗号化キー
train	model.pretrained_model_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 に戻さないでください。また、チェックポイントパスを推測するために生成されたランナースクリプトにパッチを当てないでください。