tao-port-huggingface-model

スタンドアロンでインストールしますか？ このセッションが TAO skill bank プラグインによって初期化されていない場合は、まず tao-setup スキルを実行してください（ホストの事前確認、認証情報、スキル間の探索）。

TAO-HF Integration Skill

HuggingFace（HF）のコンピュータービジョンモデルを NVIDIA TAO Toolkit エコシステムに統合します。各フェーズは、ビルド → テスト → デバッグ → 修正 → 再テストのループをすべてのステップで繰り返し、単に直線的に進めるのではなく、反復的に取り組みます。何かが失敗した場合は、先に進む前に原因を診断して修正してください。合格した場合は、次のステップに進みます。

この SKILL.md はワークフローのコーディネーターです。各フェーズには、詳細な手順、コード、docker の呼び出し、合格基準を記載した専用の references/phase-N-*.md があります。各フェーズの開始時に該当するリファレンスを読んでください。以下の概要だけでは不十分です。

---

ローカル限定ルール

すべての作業は厳密にローカルで行います。リモート（GitLab、GitHub、HuggingFace）へのプッシュ、コミット、ブランチ作成、マージリクエストやプルリクエスト、イシューの作成、Docker イメージのレジストリやアーティファクトストアへのアップロードまたは公開は行わないでください。リモートから読み取りやクローンを行うことはできますが、編集、Docker ビルド、テスト実行はすべてローカルマシンで行ってください。

---

サブモジュールのオーバーライド戦略

ユーザーは TAO リポジトリ 4 つ（tao-core、tao-pytorch、tao-deploy、tao-dataservices）を、それぞれ独立して 1 つの作業ディレクトリにクローンします。各リポジトリ内にネストされた tao-core/ サブモジュールは、変更が加えられていない元のコミットを指しています。変更が存在するのはトップレベルの tao-core/ だけです。インストール元には必ずトップレベルの tao-core/ を使い、<repo>/tao-core/ は使わないでください。ネストされたサブモジュールでは、すべての変更が無視されます。オーバーライドルール：(1) 作業ディレクトリをマウントします（-v $(pwd):/workspace）。(2) tao-pytorch/tao-deploy より先に pip install /workspace/tao-core を実行します。(3) PYTHONPATH ではトップレベルの tao-core を先頭にします（例：-e PYTHONPATH=/workspace/tao-core:/workspace/tao-pytorch）。ディレクトリツリーについては references/cross-cutting.md を参照してください。

---

実行プラットフォーム

すべてのテスト、スモーク実行、エンドツーエンド検証は、ローカルで準備した TAO Toolkit コンテナ（tao-pytorch-base:latest、tao-deploy-base:latest、必要に応じて tao-dataservices-base:latest。いずれもフェーズ 0 で準備）内で実行します。プラットフォームスキルが実行方法を担い、このスキルでは実行内容を指定します。デフォルトのプラットフォーム： local-docker。フェーズ 0 では、ドライバー／CUDA／NCT の事前確認を tao-setup-nvidia-gpu-host に委任します。権威あるスキルの一覧、バインドマウントの理由、標準的な docker-run フラグのセットについては references/cross-cutting.md を参照してください。

---

フェーズマップ

フェーズ	目標	リファレンス
0	前提条件 + TAO Toolkit イメージ + ローカルイメージタグ	phase-0-prereqs.md
1	入力、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	パッケージ化（console_scripts）+ L0 テスト	phase-5-packaging.md
6	コンテナテスト + エンドツーエンド検証	phase-6-container-tests.md, docker-patterns.md
7	（条件付き）精度／レイテンシ／サイズの最適化	phase-7-optimization.md

横断的なリファレンス：workflow-consistency.md（CLI フロー、設定フィールドのパス、フェーズ間の依存関係）；cross-cutting.md（プラットフォーム、分離、モジュールに関する落とし穴、デバッグ）。

重要 — フェーズ 6 まで継続して実行すること： フェーズ 3～5 の後に、ユーザーがテストを実行するのを待つために停止してはいけません。フェーズ 6 は必須です。コンテナ内でテストに合格し、エンドツーエンドのパイプラインが検証されるまで完了ではありません。

---

開発ループ

各ステップで、コードを書く → すぐにテストする（インポートチェック、ユニットテスト、またはドライラン）→ 失敗した場合はトレースバックを読み、原因を診断して修正し、再テストする。成功した場合は次に進みます。テストしていないコードをため込んではいけません。最後にまとめてテストすると、バグが累積します。

---

デバッグ手順

問題が発生した場合は、手当たり次第に修正を試す前に、references/cross-cutting.md の症状 → 考えられる原因 → 修正方法の表を参照してください。この表では、ModuleNotFoundError、BACKBONE_REGISTRY の KeyError、形状の不一致、NaN 損失、ONNX/TRT のビルド失敗、TRT と PyTorch の精度差、OOM、DDP のハング、チェックポイントの読み込み失敗、古いサブモジュールの設定に関する問題を取り上げています。

---

環境の分離戦略

すべての Python 作業は Docker コンテナ内で 行います。ホストの venv は使用せず、ホストの Python には pip install しません（ホストに必要なのは、tao-setup-nvidia-gpu-host からの Docker のみです）。実行環境は 3 つあります。A（tao-hf-inspect 内でのフェーズ 1 の HF 検査。フォールバックは python:3.12-slim）、B（準備済みコンテナ内でのフェーズ 3／4／6 のスモークテスト／L0／E2E。ソースは pip install /workspace/tao-core && python setup.py develop でインストール）、C（ホストにバインドマウントするスクラッチ領域）。各環境の詳細と、番号付きの 4 つのルールの原文（ホストパッケージでの --check-only、フェーズ 1 での --user $(id -u):$(id -g) と root の使い分け、HOME=/workspace／PIP_USER=1 のフォールバック、ディストリビューションのパッケージマネージャー一覧、root:root のトレードオフ、tao-hf-inspect のクリーンアップ）については、references/cross-cutting.md を参照してください。

---

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

目標： Python 3.10 以降と git を確認し、ドライバー／CUDA／Docker／NVIDIA Container Toolkit のホスト側チェックを tao-setup-nvidia-gpu-host に委任し、nvcr.io への NGC docker login を確認します。その後、TAO Toolkit のイメージ参照（tao-pytorch、tao-deploy、任意で tao-dataservices）をユーザーに尋ね、イメージを取得して、後続フェーズ向けにローカルタグ tao-pytorch-base:latest、tao-deploy-base:latest、tao-dataservices-base:latest を準備します。この準備では、プリインストールされているリリース済み TAO パッケージを削除し、ユーザーの /workspace/... クローンを pip install /workspace/tao-core && python setup.py develop でインストール／読み込みできるようにします。チェックに失敗した場合は、必ず停止してください。必須のユーザー入力：イメージ参照と認証情報（NGC ログイン、HF_TOKEN）。完全なコマンド、プロンプトの文言、イメージごとの Dockerfile スニペットについては、フェーズ 0 のリファレンスを参照してください。

ゲート： すべての前提条件チェックに合格していること。ユーザーから必須のイメージ参照が提供されていること。ローカルに tao-pytorch-base:latest と tao-deploy-base:latest が存在すること。dataservices の作業を予定している場合は、tao-dataservices-base:latest も存在すること。

---

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

目標： そもそも作業を進めるべきか判断します。認証情報を収集し、4 つの TAO リポジトリを見つけるかクローンし、一貫性のある作業ブランチを作成し、tao-hf-inspect コンテナ（コンテキスト A）を起動して、HF モデルがサポート対象の pipeline_tag を持つ CV であることを検証し、設定と state-dict のスキーマを抽出し、ONNX エクスポートが妥当か確認して、後片付けを行います。完全な手順については、フェーズ 1 のリファレンスを参照してください。

次の場合は却下： 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 とタスク種別を確認していること。（完全なチェックリスト：phase-1-inspection.md。）まず調査結果を提示し、ユーザーの確認を得てください。

---

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

目標： 検出した pipeline_tag に最も近い既存の TAO 参照モデルを見つけ、tao-core／tao-pytorch／tao-deploy にまたがる実装を読み、バックボーンが backbone_v2/ に存在するか、新規作成が必要かを判断します。

HF の pipeline_tag から TAO 参照モデルへの対応（分類 → classification_pyt、物体検出 → dino／rtdetr、セグメンテーション → segformer、インスタンス → mask2former、パノプティック → oneformer、ゼロショット → grounding_dino、深度 → mono_depth）が、以降のすべて（設定、アーキテクチャ、損失、ONNX の形状、TRT ビルダー、デプロイクラス、メトリクス、データセット形式）を左右します。モデルごとの参照ファイル一覧（12 ファイル）、backbone_v2/ と tao-dataservices の対応状況の確認、タスクごとのアーキテクチャについては、フェーズ 2 のリファレンスを参照してください。

新しいバックボーンが必要な場合は、フェーズ 3 の前に戦略（timm ラッパー ＞ 再実装 ＞ HF ブラックボックスラッパー）を決定してください。これは重みの読み込み、ONNX エクスポート、デプロイに影響します。transformers.PreTrainedModel と BackboneBase を多重継承してはいけません（メタクラスの競合が発生するため、代わりにコンポジションを使用します）。

ゲート： TAO 参照モデルが特定され、12 か所すべての参照先を読んでいること。タスク種別がもたらす影響（アーキテクチャ、損失、ONNX 出力、デプロイクラス、メトリクス、データセット）を理解していること。バックボーンの対応方針（再利用／timm ラッパー／新規作成）が決まっていること。dataservices の対応状況が確認されていること。（完全なチェックリスト：phase-2-codebase.md。）

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

目標： tao-core の設定スキーマ、tao-pytorch のトレーナー／ネイティブ推論／評価を作成し、各ステップの間にスモークテストを実施します。 （<model_name> ＝ snake_case の短縮名、<ModelName> ＝ PascalCase。）

ステップ 1～7（各ステップは前のステップを土台とし、その間にスモークテストを実施）：tao-core の設定（1）、tao-pytorch のトレーナー（2）、マルチ GPU／マルチノード（3）、ネイティブ推論 → result.csv（4）、ネイティブ評価 → results.json（5）、トレーニングと評価／推論の MLOps → status.json（6～7）。ExperimentConfig(CommonExperimentConfig) には、model、dataset、train、evaluate、inference、export、gen_trt_engine、quantize を含める必要があります。すべての ??? フィールドは MISSING（ユーザーが YAML／CLI で指定）。augmentation.mean／std、model.head.in_channels、チェックポイント名、onnx_file の一致要件は、以下のチェックリストに記載されています。

各ステップの詳細な内容、コード、標準の experiment_spec.yaml、スモークテストコマンドについては、フェーズ 3 のリファレンスを参照してください。

ゲート： ステップ 1 — コンテナ内で ExperimentConfig を問題なくインポートできること。ステップ 2 — コンテナ内で build_model(cfg) が実行され、PLModel をインスタンス化できること。フェーズ 3 — 7 ステップすべてが完了し、スモークテストが成功し、__init__.py の不足がないこと。

---

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

目標： tao-pytorch から ONNX をエクスポートし、その後 tao-core の ExperimentConfig を再利用して、tao-deploy で TRT エンジンのビルダー、推論、評価を実装します。

ステップ 8～11：ONNX エクスポーター（8 — タスク固有の入出力名、batch_size=-1 ⇒ バッチサイズを動的に設定）。TRT エンジンビルダー（9 — EngineBuilder をサブクラス化するか、ClassificationEngineBuilder を再利用し、specs/{gen_trt_engine,inference,evaluate}.yaml を作成。同じ ExperimentConfig スキーマを使用し、augmentation.mean／std はトレーニング時の値と必ず一致させる）。TRT 推論 → result.csv（10）。TRT 評価 → results.json（11）。コードの全容とフェーズ 3+4 のゲート（コンテナ内での 3 つのチェック：インポート、モデルのビルドとフォワード、ONNX のラウンドトリップ）については、フェーズ 4 のリファレンスを参照してください。

モジュールに関する注意点： tao-pytorch と tao-deploy は、それぞれ別の hydra_runner と monitor_status を使用します。デプロイスクリプトでは deploy 用のものを使用してください。両方で ExperimentConfig は nvidia_tao_core から取得します（スキーマ／フィールドパスは同じです）。

フェーズ 3+4 のゲート： コンテナ内の 3 つのチェックがすべて成功すること（tao-pytorch のインポート、モデル、ONNX エクスポート、および tao-deploy のインポート）。

---

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

目標： 両方のリポジトリでモデルを console_script として登録し、ユニットテストを追加します。

ステップ 12～15：tao-pytorch/setup.py（12）と tao-deploy/setup.py（13）の console_scripts に '<model_name>=...:main' を登録します（13 では entrypoint_hydra を介して deploy の entrypoint/<model_name>.py を作成）。deploy の L0 テスト（14）。トレーナーの L0 テスト — Trainer(..., fast_dev_run=True) と @pytest.mark.cv_unit @pytest.mark.<model_name>（15）。正確なエントリーポイント文字列、コード、L0 テストファイルの一覧については、フェーズ 5 のリファレンスを参照してください。

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

フェーズ間のデータフローと整合性の検証

Docker テストの前に、train → export → gen_trt_engine → inference / evaluate の流れ（*_model_latest.pth → .onnx → .engine のアーティファクトフローと、各段階で読み書きする設定フィールド。全体図は references/cross-cutting.md を参照）を検証します。

整合性チェックリスト（次に進む前に検証）：self.checkpoint_filename と、evaluate.checkpoint / export.checkpoint が参照する *_latest.pth の名前が一致すること；augmentation.mean / std が、トレーニング仕様、inference.yaml、evaluate.yaml、エンジンビルダーの preprocess_mode で同一であること；ONNX の input_names=['input'] / output_names=['output']（検出／インスタンスセグメンテーションではタスク固有の名前を使用）；export.input_width / input_height が dataset.img_size と一致すること；model.head.in_channels が model_params_mapping.py と一致すること；dataset.root_dir にある classes.txt を両方のリポジトリから読み取れること；すべての __init__.py（pkgutil 経由の get_subtasks() に必要な scripts/__init__.py を含む）が存在すること。フルパスについては、workflow-consistency.md を参照してください。

---

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

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

ステップ 16～25：ローカルのイメージタグが存在することを確認（16）；tao-core / tao-pytorch（-m cv_unit、--shm-size=16G）/ tao-deploy の単体テスト（17～19）；リンター（20）；wheel（21）；エンドツーエンド — 1 つの tao-pytorch セッションで train のドライランと export を実行し、続いて 1 つの tao-deploy セッションで gen_trt_engine + inference + evaluate を実行（同一セッションが重要です。--rm によりインストール内容が破棄されます）（22）；ネイティブと TRT の照合（23）；デバッグシェル（24）；任意のリリースイメージ（25）。

完全なコマンド（すべての docker run、コンテナーごとの環境変数、正確な pytest / lint の呼び出しと全テストスイート版、すべての CLI オーバーライドを含む train/export/gen_trt_engine/inference/evaluate のワンライナー、ci/ に関する注記、修正と再テストのループ）、およびビルドスクリプト／ランナーパターンについては、フェーズ 6 のリファレンスを参照してください。

フェーズ 6 の合格条件（完了基準）： tao-core / tao-pytorch / tao-deploy の単体テストが各コンテナーで合格すること；静的テストに合格すること（または従来のリンター警告のみであること）；wheel をビルドできること；エンドツーエンドで <model_name>_model_latest.pth → model.onnx → model.engine → 空ではない result.csv + results.json が得られること；ネイティブと TRT が許容範囲内で一致すること。

---

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

フェーズ 6 に合格したものの、精度／レイテンシー／サイズの改善が必要な場合のみ開始します。最初にユーザーに目標メトリクスを確認してください。

診断カテゴリ：精度が低すぎる；TRT とネイティブの差；トレーニングが遅すぎる；推論が遅すぎる。手法：ステップ 27 — ハイパーパラメーターのチューニング；ステップ 28 — INT8 量子化（torchao / modelopt による PTQ、TRT INT8 + キャリブレーション）；ステップ 29 — チャネルプルーニング + 再トレーニング；ステップ 30 — 知識蒸留；ステップ 31 — 解像度のチューニング（TAO は ViT の位置埋め込みを自動的に補間します）。各カテゴリのチェック項目、設定ブロック、YAML オーバーライド、判断ツリー、根拠については、フェーズ 7 のリファレンスを参照してください。

---

引数

$ARGUMENTS

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