tao-port-huggingface-model

TAO-HF 統合スキル

HuggingFace（HF）のコンピュータービジョンモデルを NVIDIA TAO Toolkit エコシステムに統合します。各フェーズでは、純粋に直線的に進めるのではなく、構築 → テスト → デバッグ → 修正 → 再テストのループを繰り返してください。

この SKILL.md はワークフローの調整役です。各フェーズには、手順、コードブロック、Docker の実行コマンド、ゲートをすべて記載した専用のリファレンスファイルが references/ の下にあります。各フェーズの開始時に、該当するリファレンスを読んでください。以下の概要だけでは不十分です。

---

ローカルのみのルール

作業はすべてローカルで行います。リモートから許可されるのは読み取り／クローンのみです。ファイルの編集、Docker ビルド、テスト実行はすべてローカルマシン上で行ってください。git commit／git push／リモートブランチ（GitLab、GitHub、HuggingFace）の作成、マージリクエスト／プルリクエスト／Issue の作成、Docker イメージのレジストリやアーティファクトストアへのアップロード／公開／プッシュは絶対に行わないでください。これは references/execution-and-debugging.md のバインドマウントされたローカルクローンの構成に基づくルールです。

---

サブモジュールのオーバーライドと実行プラットフォーム

デフォルトのプラットフォームは local-docker です。ユーザーは TAO リポジトリ 4 つ（tao-core、tao-pytorch、tao-deploy、tao-dataservices）をそれぞれ独立して 1 つの作業ディレクトリにクローンします。各リポジトリには、元の未変更コミットに固定されているネストされた tao-core/（および tao-pytorch/）のサブモジュールも含まれており、古い状態のままです。変更はトップレベルの tao-core/ にのみ存在します。必ずトップレベルの tao-core/ からインストールしてください。<repo>/tao-core/ からインストールしてはいけません（ネストされたサブモジュールでは変更がすべて気付かないうちに失われます）。CI の pip install tao-core/ をオーバーライドするルールは 3 つです。作業ディレクトリ全体をマウントする（-v $(pwd):/workspace）。変更済みのスキーマが優先されるよう、最初に pip install /workspace/tao-core を実行する。トップレベルの tao-core を PYTHONPATH の先頭に置く（-e PYTHONPATH=/workspace/tao-core:/workspace/tao-pytorch）。

すべてのテスト、スモーク実行、エンドツーエンド検証は、ローカルで準備した TAO Toolkit コンテナ（Phase 0 で用意した tao-pytorch-base:latest、tao-deploy-base:latest、必要に応じて tao-dataservices-base:latest）内で実行します。ローカルクローンは /workspace にバインドマウントし、pip install /workspace/tao-core と setup.py develop でインストールします。Python の作業はすべてコンテナ内で実行してください。ホスト上の venv や pip install は使用しません。プラットフォームスキルでは、コンテナの実行方法を扱います。ホスト GPU ランタイムについては tao-setup-nvidia-gpu-host、docker run のフラグ／NGC 認証／マウント／環境変数の受け渡し／--ipc=host／--shm-size／検査／エラーモードについては tao-run-on-docker と tao-run-on-local-docker を参照してください。このワークフローで指定するのはコンテナ内で何を実行するかのみであり、これらの規約を別途定義しません。注釈付きの作業ディレクトリツリー、ワークフロー固有の -w／PYTHONPATH／インストール用シェルの追加設定を含む標準の docker run フラグ一式、3 つの分離コンテキスト、4 つの分離ルール、開発ループ、デバッグ手引きの表については、references/execution-and-debugging.md を参照してください。

フェーズマップ

7 つのフェーズ（目標とゲートの全容は以下を参照。フェーズごとのリファレンスも記載しています）：

• フェーズ 0 — 前提条件 + TAO Toolkit イメージ + ローカルイメージタグ：phase-0-prereqs.md
• フェーズ 1 — HF 検査環境、HF モデルとデータセットの検証：phase-1-inspection.md、hf-inspection.md
• フェーズ 2 — 最も近い既存の TAO リファレンスモデル：phase-2-codebase.md、task-type-guide.md
• フェーズ 3 — tao-core 設定 + tao-pytorch トレーナー / ネイティブ評価 / 推論：phase-3-implementation.md、tao-patterns.md、repo-structure.md
• フェーズ 4 — ONNX エクスポート + tao-deploy TRT エンジン、推論、評価：phase-4-deploy.md
• フェーズ 5 — パッケージ化（setup.py console_scripts）+ L0 テスト：phase-5-packaging.md
• フェーズ 6 — コンテナーベースのテスト + エンドツーエンドのパイプライン検証：phase-6-container-tests.md、docker-patterns.md
• フェーズ 7 — （条件付き）精度 / レイテンシ / サイズのチューニング：phase-7-optimization.md

重要 — フェーズ 6 まで継続して実行すること： 実装（フェーズ 3～5）の後に停止して、ユーザーがテストを実行するのを待たないでください。直ちに必須のフェーズ 6 に進んでください。TAO Toolkit コンテナー内でテストに合格し、エンドツーエンドのパイプラインが検証されるまで、実装は完了していません。すべてのステップでビルド・テスト・デバッグのサイクルを適用してください。コードを記述したらすぐにテストし、失敗した場合は修正し、未テストのコードをため込まないでください。

---

フェーズ 0 — 前提条件の確認

目標： Python 3.10 以降と git を確認し、NVIDIA ドライバー / CUDA / Docker / NVIDIA Container Toolkit のホスト側確認を tao-setup-nvidia-gpu-host に委任します。また、NGC の docker login で nvcr.io にログインできることを確認します。次に、TAO Toolkit イメージの参照情報（tao-pytorch、tao-deploy、任意で tao-dataservices）をユーザーに尋ねて、イメージをプルし、フェーズ 3～6 用にローカルイメージタグ tao-pytorch-base:latest、tao-deploy-base:latest、tao-dataservices-base:latest を準備します。この準備では、イメージにすでに含まれているリリース済みの TAO パッケージを削除することで、ユーザーのローカルクローン（/workspace/... にマウント）がインストールされ、実行時に使用されるようにします。いずれかの確認に失敗した場合は、そこで処理を停止してください。すべてのコマンド、ユーザーへの質問文、各イメージの準備に使う Dockerfile のスニペット：phase-0-prereqs.md。

ゲート： すべての前提条件の確認に合格していること。ユーザーが必須のイメージ参照情報を提供済みであること。tao-pytorch-base:latest と tao-deploy-base:latest がローカルに存在すること。dataservices の作業を予定している場合は、tao-dataservices-base:latest も存在すること。

---

フェーズ 1 — 情報収集と検証

目標： 続行するかどうかを判断します。認証情報を収集し、4 つの TAO リポジトリの場所を特定（またはクローン）して、すべてに共通するローカル作業ブランチを作成します。長時間稼働する tao-hf-inspect コンテナーを起動し（分離コンテキスト A）、HF モデルがサポート対象の pipeline_tag を持つ CV モデルであることを検証し、config と state-dict のスキーマを抽出して、ONNX エクスポートが妥当かを確認し、後片付けを行います。手順の全容（1.1～1.7）：phase-1-inspection.md。一般的なパターン：hf-inspection.md。

次の場合は却下してください： pipeline_tag が NLP / 音声 / LLM（CV の対象範囲外）である場合、AutoConfig が例外を発生させる場合、または ONNX エクスポートが根本的に不可能で、書き換え方法もない場合。

ゲート： 4 つすべての TAO リポジトリの場所が特定されているかクローン済みで、共通の作業ブランチが設定されていること。pipeline_tag が CV であると確認されていること。model_type、image_size、hidden_size、num_labels が抽出されていること。state-dict のキーが記録され、HF から TAO へのリマッピング計画が作成されていること。ONNX の妥当性確認に合格していること（または失敗モードが把握されていること）。ユーザーが model_short_name とタスクタイプを確認済みであること。調査結果を提示し、続行前に確認を取ってください。

---

フェーズ 2 — コードベースの調査

目標： 検出された pipeline_tag に最も近い既存の TAO 参照モデル（classification → classification_pyt、detection → dino／rtdetr、segmentation → segformer、instance → mask2former、panoptic → oneformer、zero-shot → grounding_dino、depth → mono_depth）を見つけ、tao-core、tao-pytorch、tao-deploy にまたがる完全な実装を読み、バックボーンがすでに backbone_v2/ に存在するか判断します。選択した参照モデルが、その後のすべてを決定します。設定構造、アーキテクチャ、損失、ONNX エクスポートの出力形状、TRT ビルダー、デプロイ用インファレンサー／ローダー、メトリクス、データセット形式です。モデルごとの参照先一覧（12 ファイル）、backbone_v2/ の対応状況（すでに vit、swin、resnet、dino_v2 などに対応）、および tao-dataservices の対応状況の確認については、phase-2-codebase.md を参照してください。タスク別の詳細は task-type-guide.md を参照してください。

新しいバックボーンが必要な場合は、フェーズ 3 の前に方針（timm のラップ > スクラッチから再実装 > HF のブラックボックスラップ）を決めてください。重みの読み込み、ONNX エクスポート、デプロイのパイプラインに影響します。transformers.PreTrainedModel と BackboneBase を二重継承してはいけません（メタクラスの競合が発生します）。

ゲート： 参照する TAO モデルを特定し、12 か所すべてを読み終えていること。タスク種別による影響（アーキテクチャ、損失、ONNX 出力、デプロイクラス、メトリクス、データセット）を理解していること。バックボーンの対応方針（再利用／timm のラップ／新規）を決定していること。dataservices の対応状況を確認していること。

---

フェーズ 3 — TAO Core の設定とネイティブ実装

目標： tao-core の設定スキーマ、tao-pytorch のトレーナー、ネイティブ推論、ネイティブ評価を記述し、各段階の間でスモークテストを行います。<model_name>（フェーズ 1 で決めた snake_case）と <ModelName>（PascalCase）を使用します。手順は 7 つです。（1）config/<model_name>/ に tao-core の設定を作成します。ExperimentConfig(CommonExperimentConfig) には、model、dataset、train、evaluate、inference、export、gen_trt_engine、quantize を必ず含めます。（2）cv/<model_name>/ に tao-pytorch のトレーナーを作成します（build_model()、<ModelName>PlModel(TAOLightningModule)、train.py、エントリーポイント、experiment_spec.yaml。新しいバックボーンの場合は cv/backbone_v2/<backbone_name>.py を追加して登録します）。（3）エントリーポイントの launch() を使ってマルチ GPU／マルチノードに対応します。（4）ネイティブ推論で result.csv を出力します。（5）ネイティブ評価で results.json を出力します。（6–7）MLOps を接続します（@monitor_status → status.json）。export.onnx_file と gen_trt_engine.onnx_file の整合性、および ??? が必須の MISSING を表すことなど、一貫性のルールは以下のクロスフェーズチェックリストで確認します。

各手順のコードと標準の experiment_spec.yaml 全文については、phase-3-implementation.md を参照してください（スニペットは tao-patterns.md、構成は repo-structure.md、タスク別の詳細は task-type-guide.md を参照してください）。

ゲート： 手順 1 — コンテナ内で ExperimentConfig を問題なくインポートできること。手順 2 — build_model(cfg) が動作し、PLModel をインスタンス化できること。全体 — 7 つの手順がすべて完了し、スモークテストに合格し、__init__.py の不足がないこと。

フェーズ 4 — エクスポート、デプロイ、TensorRT 統合

目標： tao-pytorch からの ONNX エクスポートを実装し、さらに tao-core の ExperimentConfig を再利用する TRT エンジンビルダー、TRT 推論、tao-deploy での TRT 評価を実装します。4 つのステップ（8～11）：ONNX エクスポート（scripts/export.py、タスクごとの入力名／出力名、batch_size=-1 ⇒ 動的バッチ）；TRT エンジンビルダー（gen_trt_engine.py、EngineBuilder のサブクラスを作成するか、ClassificationEngineBuilder を再利用し、specs/{gen_trt_engine,inference,evaluate}.yaml を書き込みます）；TRT 推論（NumPy のみを使用する ClassificationLoader → result.csv）；TRT 評価（sklearn／pycocotools → results.json）。コード全体とフェーズ 3・4 のゲートについては、phase-4-deploy.md を参照してください。

モジュールに関する注意点：tao-pytorch と tao-deploy には、それぞれ別個の hydra_runner と monitor_status の実装があります。デプロイスクリプトでは deploy 版を使用してください。どちらのリポジトリでも ExperimentConfig は nvidia_tao_core からインポートします（スキーマとフィールドパスは同じです）。

フェーズ 3・4 のゲート： コンテナ内の 3 つのチェックすべてに合格すること — tao-pytorch のインポート、モデル、ONNX エクスポート、および tao-deploy のインポート。

---

フェーズ 5 — パッケージングと L0 テスト

目標： tao-pytorch/setup.py と tao-deploy/setup.py の両方で、モデルを '<model_name>=...entrypoint.<model_name>:main' という console_script として登録します（deploy のエントリーポイントでは nvidia_tao_deploy.cv.common.entrypoint.entrypoint_hydra を使用します）。さらに、L0 テストを追加します — deploy のテスト（tao-deploy/tests/<model_name>/、subprocess と --buildOnly trtexec）およびトレーナーのテスト（tao-pytorch/tests/cv_unit_test/<model_name>/、Trainer(..., fast_dev_run=True)、マーカー @pytest.mark.cv_unit @pytest.mark.<model_name>）。コード全体とテストの構成については、phase-5-packaging.md を参照してください。

ゲート： エントリーポイントが登録されていること。pytest のファイルが存在し、マーカーの規約に従っていること。ここで止まらず、フェーズ 6 に直接進んでください。

---

フェーズをまたぐデータフローと一貫性の検証

Docker テストの前に、アーティファクトの連鎖を検証してください — train が <results_dir>/train/<model_name>_model_latest.pth を生成 → export.checkpoint → <results_dir>/export/<model_name>.onnx → gen_trt_engine → <results_dir>/trt/<model_name>.engine → inference.trt_engine ／ evaluate.trt_engine。続いて、一貫性チェックリストを確認してください：*_latest.pth という名前、トレーニング spec、inference.yaml、evaluate.yaml 間、およびビルダーの preprocess_mode で augmentation.mean／std が一致していること、ONNX の input_names／output_names、export.input_width／input_height と dataset.img_size の整合性、model.head.in_channels と model_params_mapping.py の整合性、共有の classes.txt、そしてすべてのパッケージディレクトリに __init__.py があること（get_subtasks() の pkgutil による検出用の scripts/__init__.py を含む）。補間パスの全一覧、項目別チェックリスト、設定フィールドのパスについては、workflow-consistency.md を参照してください。

---

フェーズ 6 — コンテナテストとエンドツーエンド検証

必須 — フェーズ 5 の直後にすぐ開始してください。 TAO のすべてのモデルは Docker イメージとして提供されます。コンテナの外でしか動作しないコードは未完成です。テストはTAO Toolkit コンテナ内で直接実行します（テストループ内で Docker イメージをビルドしません）。ローカルのソースをフェーズ 0 のイメージタグにマウントし、setup.py develop でインストールして、pytest／pylint／pydocstyle／flake8 を直接実行します。通常の pytest と lint バイナリを使用し、ci/run_functional_tests.py／ci/run_static_tests.py のラッパーは使用しないでください（これらは NVIDIA の内部ミラーにのみ存在し、公開されている github.com/NVIDIA-TAO/ ミラーには ci/ ディレクトリがありません）。

手順 16～25 を順番に実施します。ローカルのイメージタグを確認（16）、tao-core のコンテナ内で pytest を実行（17）、tao-pytorch のコンテナ内で pytest を実行（18、-m cv_unit、--shm-size=16G）、tao-deploy のコンテナ内で pytest を実行（19）、静的解析／lint テストを実行（20、pylint --errors-only と、任意の pydocstyle／flake8）、wheel をビルド（21）、エンドツーエンドのパイプラインを実行（22 — tao-pytorch の 1 つのセッション内でトレーニングのドライランとエクスポートを実行し、その後、tao-deploy の 1 つのセッション内で gen_trt_engine、推論、評価を実行します。--rm によってインストール済みパッケージが破棄されるためです）、ネイティブと TRT のクロスチェックを実行（23 — FP32 はほぼ完全に一致、FP16 はわずかな差、乖離がある場合は ONNX／TRT の問題）、対話型のデバッグシェルを使用（24）、任意でリリース用 Docker イメージをビルド（25、配布のみ）。各手順の詳しいコマンドと修正・再テストのループについては、フェーズ 6 コンテナテストを参照してください。ビルドスクリプト、ランナーのパターン、要件、CI の規約については、Docker のパターンを参照してください。

フェーズ 6 の合格条件（完了基準）： tao-core／tao-pytorch／tao-deploy のユニットテストが、それぞれの TAO Toolkit コンテナ内で合格すること。静的テストが合格すること（または従来からある lint 警告のみであること）。wheel がビルドできること。エンドツーエンドで <model_name>_model_latest.pth → model.onnx → model.engine → 空でない result.csv と results.json が生成されること。ネイティブと TRT の予測結果が許容範囲内で一致すること。

---

フェーズ 7 — 最適化とチューニング（条件付き）

フェーズ 6 に合格したものの、精度／レイテンシ／モデルサイズの改善が必要な場合にのみ開始します。まずユーザーに目標指標を確認してください。 4 つのカテゴリ（精度が低すぎる、TRT とネイティブの差、トレーニングが遅すぎる、推論が遅すぎる）を対象に診断（手順 26）し、その後、該当する手法を適用します。ハイパーパラメーターのチューニング（27）、INT8 量子化（28）、チャネルプルーニングと再トレーニング（29）、知識蒸留（30）、または解像度のチューニング（31）です。診断の詳細、設定ブロック、YAML オーバーライド、判断ツリーについては、フェーズ 7 の最適化を参照してください。

---

引数

$ARGUMENTS

指定されている場合、$ARGUMENTS をフェーズ 1 の開始点として使用する HuggingFace モデル ID または URL として解釈します。認証情報またはモデルの短縮名が含まれていない場合は、先にユーザーに確認してください。