tao-train-ocdnet

OCDNet

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

シーンテキスト検出用の OCDNet です。微分可能な二値化アプローチを使用して、自然画像内の任意の向きのテキスト領域を検出します。

事前学習済みの重みには model.pretrained_model_path を設定してください。

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

PyT OCDNet CLI は train、evaluate、export、inference、prune、quantize、default_specs をサポートしています。PyT 側の retrain および gen_trt_engine サブコマンドは公開していません。このモデルスキルでは、model.load_pruned_graph: true と model.pruned_graph_path を指定して ocdnet train を実行することで retrain を提供します。エポックチェックポイントから再開するには、ocdnet train と train.resume_training_checkpoint_path を使用します。TensorRT エンジンの生成は、Deploy ワークフローが担当します。

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 があるとは想定しないでください。メンテナーはスキルバンクをパッケージ化する前にスキーマ／テンプレートを再生成してください。

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 は有効ですが、スキーマが生成されるまではこのモデルで実行できないことを報告してください。

AutoML train では、最適化メトリックとして train_loss_epoch または train_loss を使用し、direction=minimize を指定してください。Lightning の進捗ログは train_loss_epoch を出力し、TAO の status.json は同じ最終値を train_loss の下に記録します。1 エポックのローカル AutoML スモーク実行では、train.lr_scheduler.args.warmup_epoch: 0 を設定してください。ウォームアップをエポック数と同じにすると、推奨結果がメトリックを報告する前にトレーナーが失敗します。evaluate、inference、export、Deploy フローなど、train 以外のアクションはこのモデルスキルの対象です。実行ごとの automl_policy の上書きによって、モデルのメタデータが変わることはありません。

トレーニング要件

• データセットの種類： ocdnet
• フォーマット： default
• AutoML トレーニング指標： train_loss（ステータスロガーの最終的な train_loss_epoch 値）、direction=minimize
• AutoML 指標の契約： トレーニング中に出力される train_loss を使用して 最小化します。train_loss_epoch はログのフォールバックエイリアスとしてのみ扱い、 選択したチェックポイントの検証には単独の hmean のみを使用します。
• 単独評価指標： hmean、direction=maximize

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

アクション	Spec Key	ソース	実行時の値	リスト？
evaluate	dataset.validate_dataset.data_path	eval_dataset	img/ と gt/ を含む抽出済みの検証分割フォルダー	はい
inference	inference.input_folder	inference_dataset or eval_dataset	抽出済みの画像フォルダー	いいえ
prune	dataset.validate_dataset.data_path	eval_dataset	img/ と gt/ を含む抽出済みの検証分割フォルダー	はい
quantize	dataset.train_dataset.data_path	train_datasets	img/ と gt/ を含む抽出済みのトレーニング分割フォルダー	はい
quantize	dataset.validate_dataset.data_path	eval_dataset	img/ と gt/ を含む抽出済みの検証分割フォルダー	はい
quantize	dataset.quant_calibration_dataset.images_dir	train_datasets or calibration_dataset	抽出済みのキャリブレーション用画像フォルダー	いいえ
train	dataset.train_dataset.data_path	train_datasets	img/ と gt/ を含む抽出済みのトレーニング分割フォルダー	はい
train	dataset.validate_dataset.data_path	eval_dataset	img/ と gt/ を含む抽出済みの検証分割フォルダー	はい
retrain	dataset.train_dataset.data_path	train_datasets	img/ と gt/ を含む抽出済みのトレーニング分割フォルダー	はい
retrain	dataset.validate_dataset.data_path	eval_dataset	img/ と gt/ を含む抽出済みの検証分割フォルダー	はい

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

データソースのオーバーライドはすべてのアクションで必須です。エージェントは、上記の「アクションごとのデータセット要件」テーブルに基づいてデータソースパスを構成し、spec_overrides に含める必要があります。OCDNet は実行時にデータセットアーカイブを展開しません。ソースが train.tar.gz、test.tar.gz、または img.tar.gz の場合は、先に展開してから、分割フォルダーまたは画像フォルダーを spec に渡してください。分割フォルダーには img/ と gt/ が含まれている必要があります。あるいは、画像パスとラベルパスを対応付けた行を含む UTF-8 のデータリストテキストファイルを渡してください。

TRAIN_ROOT = "/path/to/extracted/train"
EVAL_ROOT = "/path/to/extracted/test"
INFER_IMG_DIR = "/path/to/extracted/test/img"
CALIB_IMG_DIR = "/path/to/extracted/train/img"

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

{
    "train.num_epochs": 30,
    "train.checkpoint_interval": 10,
    "train.validation_interval": 10,
    "train.num_gpus": 1,
    "dataset.train_dataset.loader.batch_size": 16,
    "dataset.train_dataset.data_path": [TRAIN_ROOT],
    "dataset.validate_dataset.data_path": [EVAL_ROOT],
}

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

{
    "evaluate.checkpoint": "<selected train/AutoML checkpoint>",
    "dataset.validate_dataset.data_path": [EVAL_ROOT],
}

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

{
    "inference.checkpoint": "<selected train/AutoML checkpoint>",
    "inference.input_folder": INFER_IMG_DIR,
}

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

{
    "prune.checkpoint": "<selected train/AutoML checkpoint>",
    "dataset.validate_dataset.data_path": [EVAL_ROOT],
}

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

{
    "quantize.model_path": "<selected train checkpoint or exported ONNX>",
    "dataset.train_dataset.data_path": [TRAIN_ROOT],
    "dataset.validate_dataset.data_path": [EVAL_ROOT],
    "dataset.quant_calibration_dataset.images_dir": CALIB_IMG_DIR,
}

トレーニングの再開（必須データソース）：

{
    "train.resume_training_checkpoint_path": "<exact model_epoch checkpoint>",
    "dataset.train_dataset.data_path": [TRAIN_ROOT],
    "dataset.validate_dataset.data_path": [EVAL_ROOT],
}

prune の出力から再トレーニング（必須データソース）：

{
    "model.load_pruned_graph": True,
    "model.pruned_graph_path": "<selected prune output>",
    "dataset.train_dataset.data_path": [TRAIN_ROOT],
    "dataset.validate_dataset.data_path": [EVAL_ROOT],
}

default_specs：

{
    "results_dir": "<writable output directory>",
}

評価データセット

任意です。別の tarball として提供されるテストデータセットです。

重要なパラメーター

• model.backbone：デフォルトは deformable_resnet18 です。変形可能な畳み込みにより、不規則なテキストのテキスト領域検出が向上します。
• train.optimizer.args.lr：学習率です。デフォルトは 0.001（Adam）です。
• postprocess.thresh：テキスト領域を抽出するための二値化しきい値です。
• postprocess.box_thresh：検出結果をフィルタリングするためのボックス信頼度しきい値です。

マルチ GPU／マルチノード

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

Spec Key	説明	デフォルト
train.num_gpus	GPU の数	1
train.gpu_ids	GPU デバイスのインデックス	[0]
train.distributed_strategy	ddp、fsdp、または deepspeed_stage_3_offload	ddp

• アクティベーションチェックポイントを使用する ddp：find_unused_parameters=False
• アクティベーションチェックポイントを使用しない ddp：find_unused_parameters=True
• fsdp は FP16 を強制します
• deepspeed_stage_3_offload は OCDNet でのみサポートされます（FP16 を強制します）
• FAN バックボーンでは sync_batchnorm が自動的に有効になります

ハードウェア

GPU は最低 1 基、推奨 1 基です。GPU 1 基あたり 8GB 以上の VRAM が必要です。OCDNet は軽量です。ほとんどのデータセットでは、GPU 1 基で十分です。

エラーパターン

検出率が低い場合：postprocess.thresh と box_thresh を調整してください。デフォルトのしきい値では、データセットによっては厳しすぎる場合があります。

デフォルトのスケジューラーで 1 エポックのスモークトレーニングを行う場合：train.num_epochs と train.lr_scheduler.args.warmup_epoch を同じ値にしないでください。1 エポックの検証では warmup_epoch: 0 を設定し、通常の初回実行では num_epochs > warmup_epoch を維持してください。

データセットのパスにアーカイブを指定した場合：OCDNet では、dataset.*.data_path にアーカイブのパスを指定しません。train.tar.gz または test.tar.gz を直接指定すると、データローダーが gzip ファイルを UTF-8 のデータリストとして開こうとします。アーカイブを展開して img/ と gt/ を含む分割フォルダーを指定するか、実際の UTF-8 データリストファイルを指定してください。

量子化するチェックポイントの種類：PyTorch の量子化パスに model_best.pth を指定しないでください。一部の古い PyT ランタイムでは、Lightning のチェックポイントメタデータがすべて含まれていない model_best.pth が書き出されていました。デフォルトの torchao 量子化パスでは、適切な完全版の model_epoch_<epoch>_step_<step>.pth チェックポイントを使用し、quantized_model_torchao.pth を書き出してください。

デフォルトの specs 出力ディレクトリ：ocdnet default_specs には、書き込み可能な results_dir の上書き指定が必要です。たとえば、results_dir=/workspace/run/results/default_specs のように指定します。

チェックポイントの受け渡し

OCDNet のトレーニングでは、model_best.pth と、model_epoch_001_step_00046.pth などの Lightning エポックチェックポイント全体が書き込まれます。また、最新のシンボリックリンクとして ocd_model_latest.pth が書き込まれる場合もあります。ユーザーがベストチェックポイントを求めている場合は、evaluate.checkpoint、inference.checkpoint、export.checkpoint、および prune.checkpoint に model_best.pth を使用してください。train.resume_training_checkpoint_path や、Lightning のチェックポイント全体を明示的に必要とするアクションには、特定の model_epoch_<epoch>_step_<step>.pth を使用してください。Prune では pruned_<ch_sparsity>.pth などのアーティファクトが書き込まれます。プルーニング済みグラフから再トレーニングする場合は、model.pruned_graph_path に該当するプルーニング済みの .pth アーティファクトを正確に指定してください。最新のチェックポイントを使用するのは、ユーザーが明示的に最新のものを求めている場合に限ります。

PyTorch バックエンドで量子化を再試行する場合は、意図するベストエポックまたは指定されたエポックに対応する、Lightning のチェックポイント全体 model_epoch_<epoch>_step_<step>.pth を特定してください。PyTorch の量子化パスに model_best.pth を指定しないでください。modelopt.onnx で量子化を再試行する場合は、エクスポート済み ONNX を quantize.model_path に指定し、実行時のイメージに modelopt.onnx.quantization が実際に含まれていることを確認してください。

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

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

モデルの引き継ぎマッピング：

アクション	Spec フィールド	推論関数	意味
評価	evaluate.checkpoint	parent_model	親ジョブの結果フォルダーから推論したモデルファイル
評価	results_dir	output_dir	現在のジョブの結果ディレクトリ
エクスポート	export.checkpoint	parent_model	親ジョブの結果フォルダーから推論したモデルファイル
エクスポート	export.onnx_file	create_onnx_file	出力 ONNX パス
エクスポート	results_dir	output_dir	現在のジョブの結果ディレクトリ
推論	inference.checkpoint	parent_model	親ジョブの結果フォルダーから推論したモデルファイル
推論	results_dir	output_dir	現在のジョブの結果ディレクトリ
プルーニング	prune.checkpoint	parent_model	親ジョブの結果フォルダーから推論したモデルファイル
プルーニング	results_dir	output_dir	現在のジョブの結果ディレクトリ
量子化	quantize.model_path	parent_model	親ジョブの結果フォルダーから推論したモデルファイル
量子化	results_dir	output_dir	現在のジョブの結果ディレクトリ
プルーニングからの再トレーニング	model.pruned_graph_path	parent_model	親のプルーニング結果フォルダーから推論した、正確なプルーニング済みモデルファイル
プルーニングからの再トレーニング	results_dir	output_dir	現在のジョブの結果ディレクトリ
トレーニング	model.pretrained_model_path	ptm_if_no_resume_model	再開用チェックポイントが存在しない場合の PTM
トレーニング	results_dir	output_dir	現在のジョブの結果ディレクトリ
トレーニング	train.resume_training_checkpoint_path	resume_model	現在のジョブの結果フォルダーから推論したモデルファイル

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

デプロイ

• tao-deploy-ocdnet