tao-train-action-recognition

アクション認識

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

動画シーケンスからアクションを認識します。動画クリップ内の時間的なアクションを分類するため、RGB、オプティカルフロー、結合（マルチストリーム）入力タイプをサポートしています。

事前学習済みのバックボーンの重みには、model.pretrained_model_path を設定してください。

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

Docker ネイティブの起動方式です。ホストに TAO SDK も Python も必要ありません。環境固有のコマンドのほうが厳格な要件（root 以外の UID マッピング、キャッシュのリダイレクト、リモートデーモン）を満たす場合は、代わりにローカルの Docker／プラットフォームスキルを使用してください。

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" \
  action_recognition train -e /specs/train.yaml

評価：

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

推論：

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

エクスポート：

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

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

Dataclass スキーマ

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

トレーニングアクションのポリシー

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

evaluate、inference、export などのトレーニング以外のアクションやデプロイのフローは、このモデルスキル内で実行します。実行ごとの automl_policy の上書きによって、モデルのメタデータが変更されることはありません。

トレーニング要件

• データセットの種類： action_recognition
• 形式： default
• トレーニングのモニタリング指標： val_loss、val_acc
• 評価タスクの指標： accuracy、m_accuracy
• AutoML 指標の要件： 評価に基づく必須のベースラインと最終比較には、最大化方向の accuracy を使用し、すべての推奨設定で eval_fn を通じて evaluate を実行してください。evaluate では val_loss が出力されないため、val_loss は明示的に承認されたトレーニングプロキシ実行に限り使用できます。開始チェックポイントのないスクラッチ実行では、まず最小限のデフォルトトレーニングジョブを実行し、その後、ベースラインとしてそのジョブの正確なエポック／ステップのチェックポイントを評価する必要があります。

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

アクション	Spec キー	ソース	ファイル	リスト？
evaluate	evaluate.test_dataset_dir	train_datasets	test.tar.gz から展開した test/	いいえ
inference	inference.inference_dataset_dir	train_datasets	test/smile.tar.gz から展開した test/smile/	いいえ
train	dataset.train_dataset_dir	train_datasets	train.tar.gz から展開した train/	いいえ
train	dataset.val_dataset_dir	train_datasets	test.tar.gz から展開した test/	いいえ

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

データソースのオーバーライドは、すべてのアクションで必須です。エージェントは、上記の「アクションごとのデータセット要件」テーブルに基づいてデータソースのパスを作成し、spec_overrides に含める必要があります。

LOCAL_DATA = "/workspace/data/extracted"

ソースデータセットが TAO のサンプルアーカイブ train.tar.gz、test.tar.gz、または test/smile.tar.gz として提供されている場合は、TAO コンテナを起動する前にダウンロードして展開してください。アクション認識のエントリーポイントではディレクトリパスが必要なため、これらの Spec キーに .tar.gz ファイルを指定すると NotADirectoryError が発生します。

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

{
    "train.num_epochs": 30,
    "train.checkpoint_interval": 10,
    "train.validation_interval": 10,
    "train.num_gpus": 1,
    "dataset.label_map": {
        "catch": 0,
        "smile": 1
    },
    "dataset.batch_size": 2,
    "dataset.train_dataset_dir": f"{LOCAL_DATA}/train",
    "dataset.val_dataset_dir": f"{LOCAL_DATA}/test",
}

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

{
    "dataset.label_map": {
        "catch": 0,
        "smile": 1
    },
    "evaluate.test_dataset_dir": f"{LOCAL_DATA}/test",
}

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

{
    "dataset.label_map": {
        "catch": 0,
        "smile": 1
    },
    "inference.inference_dataset_dir": f"{LOCAL_DATA}/smile_infer/smile",
}

export（必須チェックポイント＋出力パス）：

{
    "export.checkpoint": "<selected train checkpoint>",
    "export.onnx_file": "<results_dir>/action_recognition.onnx",
}

SDK のリゾルバーを使わずにローカル Docker で直接チェーンする場合は、学習で生成された具体的なチェックポイント（例：model_epoch_000_step_00005.pth）を選択し、そのファイルを evaluate、inference、export に渡してください。ユーザーが最新チェックポイントを使用するよう明示的に求めていない限り、ar_model_latest.pth のシンボリックリンクは使用しないでください。学習を再開する場合は、再開対象の正確なエポック／ステップのチェックポイントを train.resume_training_checkpoint_path に設定してください。

評価データセット

任意です。テストデータセットは学習用とは別に test.tar.gz として配布される場合があります。展開し、展開後の test/ ディレクトリを Spec に指定してください。TAO の学習では、パッケージに含まれるサンプルデータに対して val_loss と val_acc が出力されます。一方、evaluate アクションでは accuracy と m_accuracy が出力されます。通常の評価に基づく AutoML ワークフローでは、最大化する指標として accuracy を使用してください。必要な影響ベースラインなしの学習のみの代替指標をユーザーが明示的に認める場合に限り、最小化する指標として val_loss を使用してください。

重要なパラメーター

• model.model_type：入力タイプ。rgb、of（オプティカルフロー）、または joint（マルチストリーム）です。
• model.backbone：デフォルトは resnet_18 です。空間特徴抽出器として使用されます。
• dataset.label_map：クラス名をインデックスに対応付ける辞書です。
• model.rgb_seq_length：RGB 入力におけるクリップあたりのフレーム数です。
• model.of_seq_length：オプティカルフロー入力におけるフレーム数です。
• train.optim.lr：学習率です。デフォルトは 5e-4 です。

マルチ GPU／マルチノード

起動方法： Lightning 管理（単一の python プロセスから Lightning がワーカーを起動します）。

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

• ストラテジー：auto（Lightning が最適なストラテジーを自動的に選択します）
• 明示的な num_nodes または distributed_strategy の設定はありません（単一ノード向け）

ハードウェア

最低 1 GPU、推奨 2 GPU です。GPU あたり 16GB 以上の VRAM が必要です。メモリ使用量はシーケンス長と入力解像度によって異なります。動画データでは batch_size=2 が控えめな設定です。

エラーパターン

シーケンス長の不一致：動画クリップに、設定した rgb_seq_length または of_seq_length に必要なフレーム数があることを確認してください。

evaluate／inference でラベルマップがない：後続のアクションでは、チェックポイントを読み込む前に ActionRecognitionModel を再構築するため、学習時と同じ dataset.label_map が必要です。各 evaluate または inference の Spec に含めてください。含めないと、チェックポイントを検証する前にモデルの構築が失敗します。

仕様パラメーター／親モデルの推論

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

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

アクション	仕様フィールド	推論関数	意味
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	results_dir	output_dir	現在のジョブの結果ディレクトリ
train	encryption_key	key	暗号化キー
train	model.of_pretrained_model_path	ptm_if_no_resume_model	レジューム用チェックポイントが存在しない場合の PTM
train	model.rgb_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 に戻したり、チェックポイントパスを推測するよう生成されたランナースクリプトにパッチを適用したりしないでください。