tao-finetune-huggingface-model

tao-finetune-huggingface-model

HuggingFace モデルをローカルの NVIDIA GPU でファインチューニングします。常に取得するドキュメントに基づき、フォールバック用の安全策として厳選したリファレンスも利用します。NGC コンテナ 1 つ、目的を絞った少数のスクリプト、HF Hub へのプッシュ 1 回で完了します。動作はこのファイルのルールに従います。必ず守り、独自の判断で変更しないでください。

優先順位（高い順）： （1）ユーザー入力 → （2）最新の調査（モデルカード、HF リポジトリのサンプル、作者のスクリプト、タスクのドキュメント、論文 — Step 3 で必ず取得）→ （3）厳選した references/*.md（最新の調査に記載がない場合のフォールバック）→ （4）トレーニングデータの記憶（最後の手段。誤りを含む可能性があります）。矛盾がある場合は、特定のモデルと現在の API について、最新の調査を優先します。優先順位と矛盾の解決ルールの全容については、references/core-rules.md を参照してください。

---

入力

必須：

• model_id — HuggingFace モデル ID。例：google/vit-base-patch16-224

条件付きの認証情報（SessionStart フックが ~/.config/tao/.env から読み込みます）：

• HF_TOKEN — モデルまたはデータセットがゲート付きの場合（読み取り）、または push_to_hub が有効な場合（書き込み）のみ必要です。公開モデルかつ push_to_hub: false の実行では不要です。エージェントは値を読み取りません。[ -n "$HF_TOKEN" ] で設定の有無だけを確認します。
• WANDB_API_KEY、WANDB_PROJECT — WandB が有効な場合のみ必要です。オプトアウトするには WANDB_MODE=disabled を設定します。

データセット — 次のいずれか 1 つ：

• dataset_id — HuggingFace データセット ID（ソース：hf）
• local_dataset_path — ローカルのフォルダーまたはファイル（ソース：local）。任意の local_dataset_format ∈ {auto, imagefolder, coco, voc, jsonl, arrow, parquet, csv} を指定できます（デフォルトは自動検出）。
• （省略）— エージェントが一般的なデータセットを推奨します（ソース：recommend）

任意（デフォルト値あり）： task_type（自動検出）、n_train=10000、 n_eval=1000、n_epochs=3、lora_r=16、output_dir=./output/<model_short_name>； hf_model_repo（プッシュ先。未設定で HF_TOKEN に書き込み権限がある場合、 <whoami>/<model_short_name>-finetuned として自動導出）；push_to_hub=True （スキップするには False を設定）；skip_baseline=False（ゼロショットのベースライン評価をスキップ）。

任意の成果物（デフォルトでは無効）： emit_progress_log → output_dir/PROGRESS.md（ステップごとの ✅/⚠️/❌ 作業記録）；emit_report → reports/report.{pdf,html}（学習曲線とサンプルを含む）；emit_unit_tests → tests/（異種バッチを使ったフェイクデータテスト）。

すべての値は output_dir/config.yaml に保存します。Python コードに値をハードコードしないでください。

---

実行プラットフォーム

このスキルは何を実行するかを調整し、プラットフォームスキルはどのように実行するかを担います（まずそれらを読み、ここで規約を書き直さないでください）。 tao-setup-nvidia-gpu-host （GPU ホストのランタイム — ドライバー 580、CUDA Toolkit 13.0、NVIDIA Container Toolkit 1.19.0）、tao-run-on-docker （docker run のフラグ、NGC 認証、--gpus、マウント、環境変数の引き渡し、 --ipc=host/--shm-size、エラー発生時の動作）、および tao-run-on-local-docker （ローカル Docker ジョブの実行前チェック — デーモンへの接続、GPU スモークテスト）。

デフォルトのプラットフォーム： local-docker — 専用イメージ （run-<short>:latest）をビルドし、ローカル Docker デーモン上で実行します。別のバックエンド（Brev、Lepton/SLURM/Kubernetes）が必要な場合にのみ、ユーザーに確認してください。その手順、代替バックエンドへの振り分け、GPU ランタイムの実行前チェック、認証情報のポリシー、および docker run の規約については、references/execution-platform.md を参照してください。

---

References — フォールバック用の安全策

厳選された references/*.md は、ライブ調査で情報が見つからない場合、曖昧な場合、または利用できない場合にのみ参照します。特定のモデルと現在の API については、常にライブドキュメントを優先します。以下のワークフローの各ステップには、そのステップで必要なファイルへのリンクが直接記載されています。フォールバックする前に、試したライブソースと不十分だった理由を記録してください（config.yaml の notes: と、有効な場合は PROGRESS.md に記録します）。cv-scripts.md／vlm-scripts.md の [FETCH LIVE] マーカーは調査チェックリストであり、コードにそのまま記述するものではありません。ブロックに Step 3 の調査結果がない場合は、記載された URL を再取得してください。

完全なインデックスについては references/reference-index.md を参照してください。常時参照するすべてのリファレンスと、フラグで有効化する3つのオプションリファレンス（emit_progress_log による progress-tracking.md、emit_unit_tests による testing.md、emit_report による reporting.md）が、それぞれのステップごとの役割とともに記載されています。

---

基本ルール

譲れない動作です。全文は references/core-rules.md を参照してください。 要約：

• HF ライブラリに関する知識は古くなっています。 ML コードを書く前にライブドキュメントを取得してください。トレーナーの引数、コレーター、変換を記憶に頼って生成してはいけません（Step 3）。
• 本番実行の前に、実データで --max_steps 1 を指定してスモークテストを行ってください。
• model_id、dataset_id、training_method を黙って置き換えてはいけません。停止して確認してください。
• エラーからの復旧は最小限の変更で行います。 OOM → バッチサイズを半分にし、grad_accum を2倍にして、勾配チェックポイントを有効にします（承認なしに LoRA に切り替えてはいけません）。NaN → LR を10分の1にします。損失が横ばい → コレーターを調査します。同じエラーが3回発生 → 停止して確認します。
• コレーターを使用する前に、データセットの列を検証します。 列名の変更 → prepare_data.py を使用します。構造の変更 → 停止して確認します。
• ハードウェア要件（bf16）： ≤3B → 24 GB、7–13B → 80 GB、30B+ → マルチ GPU または 1× 80 GB で LoRA、70B+ → 8× 80 GB または LoRA。収まらず、LoRA のリクエストもない場合は確認してください。

references/core-rules.md には、全項目の詳細（幻覚したインポート、承認なしでは決して行わない操作の一覧、エラー復旧とハードウェア要件の全表）が記載されています。

---

ワークフロー — 6ステップ

順番に1回ずつ実行します。各ステップには、次に進む前の明確なゲートがあります。

Step 1 — 調査と適格性の確認

進めてよいかどうかを判断します。1a. モデルを調査し、1b. データセットを調査します。ホスト側に Python の前提条件を必要としない、CPU のみの python:3.12-slim コンテナ化プローブを2つ実行します。モデルプローブでは model_type、architectures、tags、ヘッド数を報告し、データセットプローブでは読み込み可能かどうかと列スキーマを検証します。architectures、tags、カード本文から task を検出します（カードに AutoModelFor... の記載がない場合は references/model-discovery.md を参照し、notes: に記録します）。source = recommend の場合は、references/dataset-recommendations.md から3～5件の候補を提示します。source = local の場合は、references/dataset-sources.md のローダーを使用します。1c. 採用／却下を行い、1d. references/compat-workarounds.md を順に確認して該当項目を config.yaml の applicable_workarounds: に記録し、その後、1e. config.yaml のひな型を作成します。

プローブスクリプトの全文と docker run の呼び出し方法、Docker デーモンの事前確認、前提条件（MODEL_ID、任意の DATASET_ID／HF_TOKEN、既定値が ./output/<model_short_name> で Steps 4～5 によってバインドマウントされる OUTPUT_DIR）、データセット列の検証と列名変更のルール、却下基準の全文、互換性確認の詳細、ひな型の正確な内容、.probe のクリーンアップについては references/step1-probes.md を参照してください。

ゲート： config.yaml に model、dataset、task、applicable_workarounds が存在していること。いずれかのフィールドが欠けている場合は先に進まないでください。

---

ステップ 2 — ハードウェア監査とNGCイメージ

Docker、GPU、ディスクを確認し、NGC PyTorchイメージをその場で選択して、 ハードウェアに依存する互換性ルールを確定します。**2a. 監査（必須ゲート）**は tao-setup-nvidia-gpu-host --check-only で実行します（ドライバーブランチ 580、CUDA Toolkit 13.0、 NVIDIA Container Toolkit 1.19.0）。失敗した場合はインストールの許可を求めてから 再実行します。空きディスク容量が < 100 GB の場合はソフト警告を出します。この実行で 必要な認証情報のみを確認します。ハード失敗の場合はステップ 4 に進まないでください。 gpu_count、 gpu_name、driver_major、vram_gb_per_gpu を記録します。2b. NGCイメージの選択（ライブ） — Min driver ≤ driver_major かつ コンテナの CUDA がホストの CUDA Toolkit 以下である、バージョンが最も高い PyTorch NGCイメージを選びます （aN／bN／rcN サフィックスを理由に除外しないでください）。WebFetch に失敗した場合は references/hardware-container.md を代替資料として使用します。2c. 再評価 — hw に依存する互換性ルールを再評価します。2d. モデル適合性チェック — bf16 の場合、param_bytes ≈ 2×param_count です。これが vram_gb_per_gpu × 1e9 の 60% を超える場合は、LoRAを推奨します。

完全な監査スクリプト、ソフト警告と MIN_DISK_GB による上書き、 ライブ選択ルール、サポートマトリックスの WebFetch URL、 24.09-py3／SDPA+GQA の attn_implementation: "eager" フォールバック、および could not select device driver の失敗時の注意については、 references/hardware-audit-ngc.md を参照してください。

ゲート： config.yaml に ngc_image、gpu_count、gpu_name、driver_major、 vram_gb_per_gpu が記載されています。ハードウェア依存の互換性修正が記録されています。

---

ステップ 3 — レシピを調査する

ライブのレシピを取得します。エージェントの transformers／trl／peft に関する記憶は 信頼できないため、ステップ 3 は必須です。優先度順（優先度 1 → 6）に references/research-priorities.md を確認します。 検出されたタスクについて、AutoModel／プロセッサークラス、学習と評価の変換、 コレーター、compute_metrics、およびハイパーパラメーターのヒント （LR、バッチサイズ、エポック数、スケジューラー）がそろった時点で終了します。 調査結果を meta/recipe.md に記録し、出典 URL を config.yaml: research_sources: に 追記します。項目についてライブの調査結果がない場合は、該当するスキャフォールド （cv-scripts.md／ vlm-scripts.md）を使い、notes: の下に「fallback to scaffold — no live source for 」と記録します。 競合の解決ルールについては references/research-priorities.md を参照してください。

ゲート： 上記の必須項目がすべて埋まっており、出典 URL または明示的な スキャフォールドへのフォールバックに関する注記があります。

---

ステップ 4 — プロジェクトの生成とスモークテスト

すべてのスクリプトを作成し、イメージをビルドし、データを準備して、実データで1ステップのスモークテストを実行します（docker build を1回、docker run を2回）。

4a. プロジェクトファイルを生成する — output_dir/ に config.yaml、Dockerfile、 requirements.txt、prepare_data.py、train.py、run_eval.py（評価スクリプトは 必ず run_eval.py にしてください。HF の evaluate と競合するため、evaluate.py は使用しないでください）、 infer.py、VLM-LoRA 用の merge_lora.py、.gitignore を作成します。優先順位：ステップ 3 での最新調査 → スキャフォールドの参考資料（cv-scripts.md / vlm-scripts.md）は 構造のみ参照し、[FETCH LIVE] ブロックは決して参照しないでください。各 applicable_workarounds エントリーを、Dockerfile のブロック、requirements のピン留め、 設定のオーバーライド、またはランタイム環境変数として適用します。生成するすべての .py ファイルは、NVIDIA Apache-2.0 の # コメント著作権ヘッダーで始めてください（そうでない場合、エミッターは失敗しなければなりません）。emit_unit_tests: true の場合は、references/testing.md に従って tests/ も生成します。ファイル一覧、正確な著作権ヘッダー、Dockerfile のテンプレート（依存関係 → 互換性 → コードのレイヤー順）については、references/project-scaffold.md を参照してください。

4b. ビルド、準備、スモークテスト — docker build -t run-<short>:latest . を実行し、続いて references/docker-runs.md の §1（ビルド）、§2（prepare_data）、§3（スモークテスト、 --smoke --max_steps 1）を実行します。§3 にはスモークテストの合格基準（例外がない、損失が有限、ステップ 1 で grad_norm > 0）が記載されています。emit_unit_tests: true の場合は、コンテナ内で pytest tests/ も実行します。失敗した場合 → STOP。

4c. 事前確認サマリー — 枠で囲んだ ─ PREFLIGHT ─ サマリー（参考 URL、データセットの列、push_to_hub リポジトリ、wandb モニタリング、ngc_image、ハードウェア、スモークテスト結果）を出力し、フル学習を開始する前にすべての項目が入力済みであることを確認します。正確な形式：references/project-scaffold.md。

ゲート： プロジェクトファイルが作成済み、イメージがビルド済み、スモークテストが合格、事前確認に空欄がないこと。

---

ステップ 5 — 学習、評価、推論

references/docker-runs.md に記載されているすべてのコマンドを、次の順に実行します。5a ベースライン評価（§4、skip_baseline: true の場合は省略）、5b フル学習をデタッチモードで実行（§5）、5c LoRA のマージ（§6、VLM と LoRA の組み合わせの場合のみ）、5d 学習後の評価（§7）、5e 5 サンプルの推論（§8）。マルチ GPU の場合：python train.py の前に torchrun --nproc_per_node=$gpu_count を付けます。docker logs -f hft_train を監視します。損失は 10～20 ステップ以内に低下するはずです（横ばい → 停止、NaN → LR を下げる、OOM → バッチを半分にする。完全な復旧手順は references/core-rules.md と references/error-playbook.md を参照）。emit_report: true の場合は、ステップ 5e の後に references/reporting.md に従って report.py を実行します。

ゲート： 以下のすべてを満たすこと — checkpoints/final/（LoRA の場合は checkpoints/merged/）が存在する、reports/eval_results.json に数値の主要メトリクスがある、reports/baseline_results.json が存在する（省略された場合を除く）、reports/inference_samples/ に 5 サンプルがある、wandb の URL で損失の低下を確認できる。

---

ステップ 6 — プッシュして再実行スキルを出力する

実行結果を公開し、再調査せずに再現できるようにします。

6a. HF Hub にプッシュする — references/hub-push.md を使用します（マージ済みまたは最終版の重み、生成したモデルカード README.md、results/{eval,baseline}_results.json、config.yaml、Dockerfile、requirements.txt、inference_samples/*.jpg、および emit_report: true の場合は report.{pdf,html} をプッシュします）。config.yaml で push_to_hub: false が明示されている場合に限り、スキップします。

6b. 再実行スキルを出力する — references/pipeline-skill-template.md に従って、<output_dir>/skills/run-<short>/SKILL.md に出力します。すべての <placeholder> は実際の値に置き換える必要があります（プレースホルダーがそのまま残っているのは不具合です）。完全な YAML（license、compatibility、metadata、allowed-tools）と、閉じる --- の直後に HTML コメントで NVIDIA の著作権表示を含めます。テンプレートの記載例に従ってください。出力された SKILL.md にこれらのフィールドと著作権コメントが含まれていない場合、エミッターは失敗する必要があります。

ゲート（完了条件）： 次のすべてを満たすこと — ステップ 5 のゲートを満たしていること。push_to_hub: false の場合を除き、HF Hub リポジトリが解決済み URL に存在し、重み、カード、results/ が揃っていること。<output_dir>/skills/run-<short>/SKILL.md が存在し、<placeholder> が残っておらず、pipeline-skill-template.md に従ったメタデータと著作権の HTML コメントが含まれていること。

ユーザーへの最終メッセージ — 簡潔に、直接 URL を記載します。wandb URL、HF Hub URL、主指標のベースライン → ファインチューニング後（Δ）、reports/inference_samples/ のパス、<output_dir>/skills/run-<short>/SKILL.md のパスを含めます。

---

エラープレイブック

既知の実行時エラーが発生した場合は、設計を変更する前に references/error-playbook.md を参照してください。症状 → 最小限の修正をまとめた表には、NGC ENTRYPOINT、SDPA+GQA、transformers>=4.51 のリグレッション、numpy 2.x ABI、Albumentations の bbox、PEFT + gradient_checkpointing、SmolVLM SDPA、LoRA のターゲット正規表現、CV 拡張の不足、ステップ 0 での OOM などが記載されています。複数の実行で同じ行が 2 回該当した場合は、detect ルールとともに references/compat-workarounds.md に追加し、エラーが発生する前にステップ 1d で自動適用されるようにします。

---

コミュニケーションスタイル

簡潔にします。無駄な文言や依頼の言い換えは不要です。Hub と wandb の直接 URL を必ず含めます。エラー時には、何が起きたか、なぜ起きたか、何を変更したかを伝えます（選択肢を並べたり、答えが明確な場合に「オプション A/B/C」を提示したりせず、実行します）。全文は references/core-rules.md を参照してください。

パイプラインの例

• tao-rerun-convnext-cifar10 — cifar10 上の facebook/convnext-tiny-224（画像分類、10 クラス、サブセット 5000/1000）。
• tao-rerun-detr-cppe5 — cppe-5 上の facebook/detr-resnet-50（物体検出、5 クラス、サブセット 800/200）。
• tao-rerun-segformer-foodseg103 — EduardoPacheco/FoodSeg103 上の nvidia/mit-b0（セマンティックセグメンテーション、103 クラス + 背景、サブセット 1000/200）。
• tao-rerun-smolvlm-vqav2 — merve/vqav2-small 上の HuggingFaceTB/SmolVLM-256M-Instruct（画像テキストからテキストへの VLM LoRA、サブセット 500/100、5 エポック）。