tao-finetune-huggingface-model

tao-finetune-huggingface-model

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

HuggingFace モデルをローカルの NVIDIA GPU でファインチューニングします。取得した最新のドキュメントに基づき、厳選されたリファレンスを安全策として用意しています。NGC コンテナを 1 つ、目的を絞ったスクリプトをいくつか使用し、HF Hub に 1 回プッシュします。このファイルのルールに従ってください。独自の判断で手順を変えないでください。

専用モデルへのルーティング判定

ステップ 1 の実行や、プローブ、イメージの選択、パッケージのインストール、venv の作成、トレーニングコードの生成を行う前に、パッケージ化されたモデル所有者レジストリを使って model_id の所有先を解決してください。このファイルの読み込み元となったスキルバンクの絶対パスを使用します。

python <bank-root>/scripts/resolve_tao_model.py \
  --skill-bank <bank-root> \
  --model "$MODEL_ID" \
  --format json

リゾルバーは、huggingface_model_ids、network_arch、スキル名、レガシーエイリアスなどのモデルメタデータを照合します。ルーティングは内部で行われます。モデル ID とタスクだけで十分です。スキル、コンテナ、チェックポイント形式について、プロンプトに定型文を含めるよう求めてはいけません。

• 終了コード 0：このワークフローを中止し、所有するモデルスキルの環境、アクションメタデータ、事前確認、チェックポイント準備に従ってください。
• 終了コード 3：パッケージ化されたモデルスキルに ID の所有者がありません。汎用ワークフローのステップ 1 に進めるのは、この結果の場合のみです。
• その他のゼロ以外の終了コード：所有者の検出に問題があるか、結果が曖昧です。中止して問題を解決してください。汎用 Hugging Face トレーニングに黙ってフォールバックしてはいけません。

Hugging Face でホストされていることによって、所有者が変更されることはありません。一致したスキルを迂回する目的でこのワークフローを使ったり、内部で必要な準備をユーザーに指定させたりしてはいけません。たとえば、nvidia/Cosmos3-Nano は tao-finetune-cosmos-reason にルーティングされます。

このワークフローでは、ホスト上にトレーニング用 venv を作成しないでください。デフォルトの実行経路は、以下で説明する NGC コンテナです。venv を使ったトレーニング経路には、ユーザーからの明示的な依頼が必要です。

優先順位（高い順）：

1. ユーザーの入力 — 明示的な model_id、dataset_id、training_method、config.yaml の上書き。
2. 最新情報の調査 — モデルカード、HF リポジトリの使用例、作成者のファインチューニングスクリプト、HF タスクのドキュメント、論文。必ず取得してください（ステップ 3 と references/research-priorities.md）。
3. 厳選されたリファレンス（references/*.md）— 最新情報の調査で情報が得られない場合や、内容が曖昧な場合のフォールバック。
4. トレーニングデータに関する知識 — 最終手段として使用してください。信頼性が低いため、(2)/(3) と照合してください。

(2) と (3) の間の矛盾の解決方法、およびソース行の不一致に関する注記は、references/research-priorities.md にあります。

---

入力

必須：

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

条件付きの認証情報（セッション環境から読み込みます。起動前にエクスポートするか、ユーザーが承認した環境ファイルをソースしてください）：

• 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 — config とモデルカードから自動検出
• 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: false   # output_dir/PROGRESS.md (per-step journal)
emit_report:       false   # reports/report.{pdf,html} with curves & samples
emit_unit_tests:   false   # tests/ with fake-data heterogeneous-batch tests

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

---

実行プラットフォーム

このスキルは何を実行するかを調整し、プラットフォームスキルはGPUホスト上での実行方法を担います。まずそちらを読んでください。

確認事項	正式なスキル
GPUホストのランタイム（ドライバー 580、CUDA Toolkit 13.0、NVIDIA Container Toolkit 1.19.0）	tao-skill-bank:tao-setup-nvidia-gpu-host
docker run のフラグ、NGC 認証、マウント、環境変数の受け渡し、ローカル／リモート Docker ジョブの事前確認（デーモン、GPU のスモークテスト）	tao-skill-bank:tao-run-on-docker

デフォルトのプラットフォーム： local-docker — 単発のイメージ（run-<short>:latest）をビルドし、ローカルの Docker デーモンで実行します。ユーザーが別のバックエンド（Brev のリモート GPU、SLURM／Kubernetes）を明示的に必要としている場合に限り、確認してください。その場合は、まずそのプラットフォームの事前確認を実行し、ステップ 4～5 の docker run コマンドをそのプラットフォーム経由で実行します。GPU ランタイムと、値を読み取らない認証情報の有無のみの事前確認、標準の docker run フラグ一式、インストール済みのプラットフォームスキル（tao-run-on-docker / -slurm / -kubernetes / -brev、および外部スキル）からの実行プラットフォームの検出（ランタイムで基本のルータースキルのみが表示される場合は、skills/platform/tao-run-on-*/SKILL.md のフロントマターを読み取ってください）、およびワークフロー固有のフラグ（--entrypoint /bin/bash -lc、PYTORCH_CUDA_ALLOC_CONF、--name hft_train）については、references/workflow-intake-preflight.md を参照してください。

---

参考資料 — フォールバック用のセーフティネット

実際の調査結果が得られない、曖昧、または利用できない場合に限り参照します。特定のモデルと現在の API については、常に最新のドキュメントを優先してください。各ステップには必要な参考資料へのリンクがあります。全カタログは references/detailed-workflow.md にあります。

常時参照：core-rules.md、error-playbook.md、compat-workarounds.md、model-discovery.md、dataset-recommendations.md、dataset-sources.md、dataset-patterns.md、hardware-container.md、research-priorities.md、cv-scripts.md、vlm-scripts.md、docker-runs.md、hub-push.md、pipeline-skill-template.md、deliverables.md。必要に応じて参照（該当するフラグ／要件がある場合）：progress-tracking.md、testing.md、reporting.md、workflow-intake-preflight.md、workflow-generate-train.md、workflow-push-rerun.md。

**ルール：**フォールバックする前に、試した最新の情報源と、それだけでは不十分だった理由を記録してください（config.yaml の notes: および、有効な場合は PROGRESS.md）。cv-scripts.md／vlm-scripts.md の [FETCH LIVE] マーカーは調査用チェックリストであり、コードにそのまま埋め込むものではありません。ステップ 3 での調査結果がないブロックについては、記載された URL から再取得してください。

---

基本ルール

譲れない動作です。要約版（幻覚によるインポートの一覧、承認なしでは行わない事項の一覧、エラー復旧とハードウェアサイジングの完全な表は references/core-rules.md にあります。トレーニング時の判断を行う前に参照してください）：

• **HF ライブラリに関する知識は古くなっています。**ML コードを書く前に最新のドキュメント（モデルカード、HF リポジトリの例、タスクのドキュメント）を取得してください。トレーナーの引数、コレーター、変換処理を記憶から生成してはいけません（ステップ 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 または 80 GB × 1 で LoRA、70B 以上 → 80 GB × 8 または LoRA。フルファインチューニングでは収まらず、LoRA も指定されていない場合は、切り替える前に確認してください。

---

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

1 回の実行で順番に進めます。各ステップには、次のステップを始める前に通過すべき明確なゲートがあります。

ステップ 1 — 検査と適格性の確認

目標： 続行するかどうかを判断します。モデルとデータセットを調査し、受け入れ／拒否を判断し、該当する互換性修正を登録して、初期の config.yaml を作成します。

前提条件：MODEL_ID、任意の DATASET_ID / local_dataset_path、任意の HF_TOKEN、OUTPUT_DIR（デフォルトは ./output/<model_short_name>）。調査は CPU のみの python:3.12-slim Docker コンテナ（.probe/ スクラッチをバインドマウント）内で実行するため、ホストに仮想環境は不要です。ただし、事前に Docker がインストールされている必要があります。Docker の存在確認ガード、コンテナ環境、調査の完全な実行方法、モデル／データセットの調査スクリプトについては、references/workflow-intake-preflight.md、references/model-discovery.md、references/dataset-sources.md を参照してください。

調査要件：

• モデル：AutoConfig を読み込み、モデルカードのタグを取得し、architectures、タグ、カードの例からタスクを検出します（フォールバック時のログ記録については model-discovery.md を参照）。
• データセット：推奨データセットの場合は、最初に dataset-recommendations.md から 3～5 個の候補を提示します。ローカルデータの場合は、読み取り専用でバインドマウントし、dataset-sources.md の形式検出を使用します。
• モデル設定の読み込みに失敗した場合、タスクが対象範囲外の場合、レシピのソースが存在しない場合、またはデータセットを読み込めない／タスクスキーマに適合しない場合は、早い段階で拒否します。
• モデル／タスクに対して compat-workarounds.md を評価します。ハードウェアに依存するルールはステップ 2 まで保留します。

初期の config.yaml を作成します（model_id、task、dataset_id または local_dataset_path、ステップ 3 で記入する research_sources: []、ステップ 1 の applicable_workarounds:、参照フォールバック用の notes: []、デフォルト値が true の push_to_hub。注釈付きテンプレートについては references/workflow-intake-preflight.md を参照）。条件を満たした後、必要に応じて rm -rf "$OUTPUT_DIR/.probe" を実行できます。

ゲート： config.yaml にモデル、データセット、タスク、applicable_workarounds が記載されていること。いずれかのフィールドが欠けている場合は続行しないでください。

---

Step 2 — ハードウェアの監査と NGC イメージ

目標： Docker、GPU、ディスクを確認し、最新の NGC PyTorch イメージを選択して、ハードウェア依存の互換性ルールを確定します。

2a. 監査（必須ゲート） — 3 つの確認項目（コマンドは references/workflow-intake-preflight.md を参照）：

1. GPU ホストのランタイム — tao-setup-nvidia-gpu-host の setup-nvidia-gpu-host.sh --backend docker --check-only を実行します。失敗した場合は、承認を得てから --install --yes を付けて再実行します。
2. 空きディスク容量のソフト警告 — MIN_DISK_GB で上書きできます（デフォルトは 100 GB）。NGC ベース（約 20 GB）と HF キャッシュ、チェックポイント、データのため、≥ 100 GB を推奨します。
3. 条件付きの認証情報の有無（値は読み取りません） — HF_TOKEN はゲート条件がある場合、または push_to_hub が有効な場合のみ確認します。WANDB_* は WandB が有効な場合のみ確認します。

ハードフェイルの場合は Step 4 に進まないでください — Step 4 の docker build は 20+ GB の NGC ベースをプルします。また、nvidia-container-toolkit がない場合、後になって could not select device driver "" with capabilities: [[gpu]] が表示されます。gpu_count、 gpu_name、driver_major、vram_gb_per_gpu を config.yaml に記録します。

2b. NGC イメージの選択（最新情報に基づく）： NVIDIA Deep Learning Frameworks のサポート マトリックス（https://docs.nvidia.com/deeplearning/frameworks/support-matrix/index.html）の PyTorch NGC コンテナーセクションから、Min driver ≤ 検出した driver_major かつコンテナーの CUDA がホストの CUDA Toolkit 以下の、最もバージョンの高いイメージを選びます（cuDNN / TensorRT のバージョンが揃うよう、できるだけ近いものを選びます）。NGC はイメージ全体を検証するため、PyTorch タグが aN／bN／rcN であることを理由にイメージを除外しないでください。CUDA のバージョンが合う最新のイメージを選び、バージョンごとの問題は compat-workarounds.md で対処します。マトリックスにアクセスできない場合は、references/hardware-container.md の代替案を使用します。デフォルトは nvcr.io/nvidia/pytorch:24.09-py3 です（ドライバー ≥ 545。SDPA+GQA のバグがあるため、 num_key_value_heads < num_attention_heads の場合は attn_implementation: "eager" を設定します）。 ngc_image を config.yaml に記録します。

2c. ハードウェア依存の互換性ルールを再評価： detect に hw が必要な項目について、 compat-workarounds.md の手順を再実行し、applicable_workarounds: をその場で更新します。

2d. モデル適合性の確認： param_bytes ≈ 2×param_count（bf16）で推定します。値が vram_gb_per_gpu × 1e9 の 60% を超える場合は、ユーザー向けの要約で LoRA を推奨します。

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

---

Step 3 — レシピの調査

目標： 最新のレシピを取得します。transformers／trl／peft のトレーニングデータに関する知識は信頼できないため、Step 3 は必須です。references/research-priorities.md を優先順位順（Priority 1 → 6）に確認し、検出されたタスクについて以下が揃ったら終了します。

• 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 またはスキャフォールドへのフォールバックの注記があること。

---

Step 4 — プロジェクトを生成してスモークテストを実施する

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

4a. プロジェクトファイルを生成する：output_dir/ に config.yaml、Dockerfile、 requirements.txt、prepare_data.py、train.py、run_eval.py、infer.py、 任意の merge_lora.py、任意の tests/、.gitignore を作成します。Step 3 のライブ調査を正とし、 cv-scripts.md／vlm-scripts.md はスキャフォールドの形状を把握する目的でのみ使用します。すべての applicable_workarounds エントリーを、Dockerfile のブロック、依存関係のバージョン固定、設定の上書き、または実行時環境変数として適用します。厳守事項：run_eval.py は正確にそのファイル名を維持します（HF の evaluate パッケージとの衝突を避けるため）。生成するすべての .py は NVIDIA Apache-2.0 の著作権ヘッダーで始め、そのヘッダーがない場合はどのエミッターも失敗するようにします。emit_unit_tests: true の場合は、references/testing.md に従ってテストを生成して実行します。スクリプト本体、Dockerfile の形状、エミッターの契約については references/workflow-generate-train.md を参照してください。

4b. ビルド、準備、スモークテスト — docker build -t run-<short>:latest . を実行し、続いて prepare_data と --smoke --max_steps 1 の実行を行います（references/docker-runs.md §1-3）。スモークテストの合格基準（logs/smoke.log 内）：

• 例外が発生しない
• 損失が有限値（0.0 でも NaN でもない）
• ステップ1で grad_norm > 0

emit_unit_tests: true の場合は、コンテナ内で pytest tests/ も実行します。失敗があれば → STOP。

4c. 事前確認の概要 — 本トレーニングの前に、参照 URL、 データセットの列、Hub のターゲット、モニタリングのターゲット、NGC イメージ、ハードウェア、スモークテストの損失／勾配ノルムを表示して確認します。

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

---

Step 5 — トレーニング、評価、推論

目標： ベースライン評価、本トレーニング、トレーニング後評価、任意の LoRA マージ、推論サンプル5件を実施します（すべてのコマンドは references/docker-runs.md §4-8 を参照）。

サブステップ	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 を参照してください。emit_report: true の場合は、Step 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 で損失の低下を確認できる

---

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

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

push_to_hub: false が明示されていない限り、references/hub-push.md に従ってプッシュします（重み、モデルカード、評価／ベースライン JSON、config.yaml、Dockerfile、requirements.txt、推論サンプル、レポート（出力されている場合））。 references/pipeline-skill-template.md から <output_dir>/skills/run-<short>/SKILL.md を出力します。すべてのプレースホルダーを置き換え、YAML メタデータ全体と NVIDIA 著作権 HTML コメントを含め、それらが欠けている場合はどのエミッターも失敗するようにします。

ゲート（完了基準）： 以下をすべて満たすこと：

• Step 5 のゲートを満たしている
• HF Hub リポジトリが解決済み URL に存在し、重み＋カード＋results/ がある（push_to_hub: false の場合を除く）
• <output_dir>/skills/run-<short>/SKILL.md が存在し、<placeholder> が残っておらず、pipeline-skill-template.md に従ったメタデータと著作権 HTML コメントが含まれている

最終メッセージ：wandb URL、HF Hub URL、ベースラインからファインチューニング後への主要指標の変化、reports/inference_samples/、再実行用スキルのパス。

---

エラープレイブック

既知のランタイムエラーが発生した場合は、何かを再設計する前に、references/error-playbook.md の症状 → 最小修正の表（NGC エントリーポイント、PyTorch/Transformers のリグレッション、numpy ABI、Albumentations の bbox、PEFT/チェックポイント作成、LoRA のターゲット範囲、CV オーグメンテーションの不足、ステップ 0 での OOM）を確認してください。表の項目が複数回の実行で 2 回発生したら、detect ルールを付けて compat-workarounds.md に追加し、エラーが発生する前のステップ 1 で自動適用してください。

---

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

• 簡潔に。余計な言葉や依頼内容の言い換えは避け、適切な場合は一語で回答してください。
• 成果物に言及する場合は、Hub と wandb の直接 URL を必ず記載してください。
• エラーが発生した場合は、何が起きたか、なぜ起きたか、何を変更したかを述べてください。選択肢は提示しないでください。
• 回答が明確な依頼に対して、「選択肢 A/B/C」は提示しないでください。実行してください。