tao-train-pose-classification

ポーズ分類

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

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 ... を使用します。

クイックスタート（docker run）

Docker ネイティブで起動でき、ホストに TAO SDK や Python は不要です。ローカルの Docker／プラットフォームスキルで、より厳格な環境固有のコマンド（非 root UID マッピング、キャッシュのリダイレクト、リモートデーモンなど）が指定されている場合は、そちらを使用してください。

TAO_PYT_IMAGE_DEFAULT=nvcr.io/nvidia/tao/tao-toolkit:7.3.0-pyt  # versions-key: images.tao_toolkit.pyt
TAO_PYT_IMAGE="${TAO_PYT_IMAGE:-$TAO_PYT_IMAGE_DEFAULT}"
RUN_ROOT="${RUN_ROOT:-$PWD}"
DOCKER_COMMON=(
  --rm --gpus all --shm-size=8g
  --shm-size=8g
  --ulimit memlock=-1
  --ulimit stack=67108864
  -v "$RUN_ROOT/data:/data:ro"
  -v "$RUN_ROOT/specs:/specs:ro"
  -v "$RUN_ROOT/results:/results"
)

データセット変換：

docker run "${DOCKER_COMMON[@]}" "$TAO_PYT_IMAGE" \
  pose_classification dataset_convert -e /specs/dataset_convert.yaml

トレーニング：

docker run "${DOCKER_COMMON[@]}" "$TAO_PYT_IMAGE" \
  pose_classification train -e /specs/train.yaml

評価：

docker run "${DOCKER_COMMON[@]}" "$TAO_PYT_IMAGE" \
  pose_classification evaluate -e /specs/evaluate.yaml

推論：

docker run "${DOCKER_COMMON[@]}" "$TAO_PYT_IMAGE" \
  pose_classification inference -e /specs/inference.yaml

エクスポート：

docker run "${DOCKER_COMMON[@]}" "$TAO_PYT_IMAGE" \
  pose_classification export -e /specs/export.yaml

各アクションでは -e で spec を指定します。results_dir は spec で設定するか、コマンドラインで上書きします。spec が参照する事前トレーニング済み重みのディレクトリをマウントし、すべてのアクションでコンテナ内のパスに一貫性を持たせてください。

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/<action>.schema.json と references/spec_template_<action>.yaml が存在し、解析可能である必要があります。automl_default_parameters、automl_disabled_parameters、デフォルト値、最小／最大境界値、列挙値、オプションの重み、数式条件、依存関係、よく使われるパラメーターには、同梱された選択アクションのスキーマを使用してください。実行時に ~/tao-core が存在するとは限りません。メンテナーはスキルバンクをパッケージ化する前にスキーマ／テンプレートを再生成してください。

Train アクションのポリシー

このモデルはモデルレイヤーで AutoML が有効になっています。トレーニング段階のリクエストに対応する前に、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、deploy フローなどの train 以外のアクションは、このモデルのスキル内で実行します。実行ごとの automl_policy 上書きによって、モデルのメタデータが変わることはありません。

トレーニング要件

• データセットの種類: pose_classification
• 形式: default
• AutoML トレーニング指標: val_loss、direction=minimize
• 単独評価指標: accuracy、direction=maximize。トレーニング段階の AutoML 推奨候補の順位付けには val_loss を使用し、選択したチェックポイントの読み込みと評価が正常に行われることの確認にのみ accuracy を使用してください。

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

アクション	Spec Key	ソース	ファイル	リストか？
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 を使用してください。単独の evaluate アクションでは accuracy が出力されます。この値を選択したチェックポイントの評価結果と比較してください。ただし、トレーニング段階の val_loss によるランキング KPI の代わりに使用しないでください。

重要なパラメーター

• 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 に戻さないでください。また、チェックポイントパスを推測するために生成されたランナースクリプトにパッチを当てないでください。