hugging-face-model-trainer

Hugging Face Jobs での TRL トレーニング

概要

完全に管理された Hugging Face インフラストラクチャ上で、TRL（Transformer Reinforcement Learning）を使用して言語モデルをトレーニングします。ローカルで GPU をセットアップする必要はありません。モデルはクラウド GPU でトレーニングされ、結果は Hugging Face Hub に自動的に保存されます。

TRL には複数のトレーニング方法があります：

• SFT（教師ありファインチューニング）- 標準的な指示チューニング
• DPO（直接選好最適化）- 選好データによるアラインメント
• GRPO（グループ相対ポリシー最適化）- オンライン RL トレーニング
• 報酬モデリング - RLHF 用の報酬モデルをトレーニングします

TRL の各手法に関する詳しいドキュメント：

hf_doc_search("your query", product="trl")
hf_doc_fetch("https://huggingface.co/docs/trl/sft_trainer")  # SFT
hf_doc_fetch("https://huggingface.co/docs/trl/dpo_trainer")  # DPO
# etc.

関連項目： 手法の概要と選択のガイダンスについては、references/training_methods.md を参照してください

このスキルを使用する場面

ユーザーが次のことを希望する場合に、このスキルを使用します。

• ローカルのインフラストラクチャを使わずに、クラウド GPU で言語モデルをファインチューニングする
• TRL の手法（SFT、DPO、GRPO など）でトレーニングする
• Hugging Face Jobs のインフラストラクチャでトレーニングジョブを実行する
• トレーニング済みモデルを GGUF に変換し、ローカル環境（Ollama、LM Studio、llama.cpp）にデプロイする
• トレーニング済みモデルを Hub に永続的に保存する
• 最適化されたデフォルト設定を用いて最新のワークフローを利用する

Unsloth を使用する場面

次の場合は標準の TRL ではなく、Unsloth（references/unsloth.md）を使用してください。

• GPU メモリが限られている場合 - Unsloth は VRAM の使用量を約 60% 削減します
• 速度が重要な場合 - Unsloth は約 2 倍高速です
• 大規模モデル（>13B）をトレーニングする場合 - メモリ効率が重要です
• 視覚言語モデル（VLM）をトレーニングする場合 - Unsloth は FastVisionModel に対応しています

Unsloth の全ドキュメントについては references/unsloth.md を、実運用に対応したトレーニングスクリプトについては scripts/unsloth_sft_example.py を参照してください。

主な指示

トレーニングジョブを支援する際は、次の指示に従ってください。

1. 必ず hf_jobs() MCP ツールを使用する - trl-jobs の Bash コマンドではなく、hf_jobs("uv", {...}) を使ってジョブを送信してください。script パラメーターには Python コードを直接渡せます。ユーザーから明示的に求められない限り、ローカルファイルに保存しないでください。スクリプトの内容を文字列として hf_jobs() に渡してください。ユーザーが「モデルをトレーニングしたい」「ファインチューニングしたい」などと依頼した場合は、トレーニングスクリプトを作成し、直ちに hf_jobs() を使用してジョブを送信してください。

2. 必ず Trackio を含める - すべてのトレーニングスクリプトに、リアルタイムモニタリング用の Trackio を含めてください。テンプレートとして scripts/ 内のサンプルスクリプトを使用してください。

3. 送信後にジョブの詳細を提示する - 送信後、ジョブ ID、モニタリング URL、推定所要時間を提示し、後からステータスを確認するよう依頼できることを伝えてください。

4. サンプルスクリプトをテンプレートとして使用する - 出発点として、scripts/train_sft_example.py、scripts/train_dpo_example.py などを参照してください。

ローカルでのスクリプト実行

リポジトリのスクリプトでは、PEP 723 のインライン依存関係を使用しています。uv run で実行してください。

uv run scripts/estimate_cost.py --help
uv run scripts/dataset_inspector.py --help

前提条件のチェックリスト

トレーニングジョブを開始する前に、次の項目を確認してください。

✅ アカウントと認証

• Hugging Face の Pro、Team、または Enterprise プランのアカウント（Jobs の利用には有料プランが必要です）
• 認証済みのログイン：hf_whoami() で確認してください
• Hub へのプッシュ用の HF_TOKEN ⚠️ 重要 - トレーニング環境は一時的なため、Hub にプッシュする必要があります。プッシュしないと、トレーニング結果がすべて失われます
• トークンには書き込み権限が必要です
• トークンを利用可能にするには、ジョブ設定に secrets={"HF_TOKEN": "$HF_TOKEN"} を必ず渡してください（$HF_TOKEN 構文は、実際のトークン値を参照します）

✅ データセットの要件

• データセットが Hub に存在するか、datasets.load_dataset() で読み込み可能であること
• トレーニング方法に合った形式であること（SFT：「messages」／テキスト／プロンプトと補完、DPO：chosen/rejected、GRPO：プロンプトのみ）
• 形式エラーを防ぐため、GPU トレーニングの前に、形式が不明なデータセットを必ず検証してください（以下の「データセットの検証」セクションを参照）
• ハードウェアに適したサイズであること（デモ：t4-small で 50～100 件、本番：a10g-large／a100-large で 1,000～10,000 件以上）

⚠️ 重要な設定

• タイムアウトは想定されるトレーニング時間より長く設定してください - デフォルトの30分では、ほとんどのトレーニングに短すぎます。推奨される最小値は1～2時間です。タイムアウトを超えるとジョブは失敗し、進捗がすべて失われます。
• Hub へのプッシュを有効にしてください - 設定：push_to_hub=True、hub_model_id="username/model-name"；ジョブ：secrets={"HF_TOKEN": "$HF_TOKEN"}

非同期ジョブのガイドライン

⚠️ 重要：トレーニングジョブは非同期で実行され、数時間かかることがあります

必要な操作

ユーザーがトレーニングを依頼した場合：

1. Trackio を含めたトレーニングスクリプトを作成します（テンプレートとして scripts/train_sft_example.py を使用します）
2. hf_jobs() MCP ツールを使い、スクリプトの内容をインラインで指定してすぐに送信します。ユーザーから依頼がない限り、ファイルには保存しません
3. ジョブ ID、監視 URL、推定所要時間を添えて、送信完了を報告します
4. 状況確認の依頼があるまで待ちます。自動でポーリングしないでください

基本ルール

• ジョブはバックグラウンドで実行されます - 送信はすぐに完了し、トレーニングは独立して続行されます
• 初期ログの表示は遅れます - ログが表示されるまで30～60秒かかることがあります
• ユーザーが状況を確認します - 状況の更新を求められるまで待ちます
• ポーリングは避けてください - ユーザーから依頼があった場合のみログを確認し、代わりに監視リンクを提示します

送信後

ユーザーに提示する内容：

• ✅ ジョブ ID と監視 URL
• ✅ 完了予定時刻
• ✅ Trackio ダッシュボード URL
• ✅ 後から状況確認を依頼できることを伝えます

回答例：

✅ Job submitted successfully!

Job ID: abc123xyz
Monitor: https://huggingface.co/jobs/username/abc123xyz

Expected time: ~2 hours
Estimated cost: ~$10

The job is running in the background. Ask me to check status/logs when ready!

クイックスタート：3つの方法

💡 デモのヒント： 小型 GPU（t4-small）で手早くデモを行う場合は、メモリを約40％節約するために eval_dataset と eval_strategy を省略します。トレーニング損失と学習の進捗は引き続き確認できます。

シーケンス長の設定

TRL の設定クラスでは、トークン化されたシーケンス長を制御するために max_seq_length ではなく max_length を使います：

# ✅ CORRECT - If you need to set sequence length
SFTConfig(max_length=512)   # Truncate sequences to 512 tokens
DPOConfig(max_length=2048)  # Longer context (2048 tokens)

# ❌ WRONG - This parameter doesn't exist
SFTConfig(max_seq_length=512)  # TypeError!

デフォルトの動作： max_length=1024（右側から切り詰めます）。ほとんどのトレーニングで適切に機能します。

変更する場合：

• より長いコンテキスト： 値を大きくします（例：max_length=2048）
• メモリの制約： 値を小さくします（例：max_length=512）
• ビジョンモデル： max_length=None に設定します（画像トークンが切り詰められるのを防ぎます）

通常、このパラメーターを設定する必要はありません。以下の例では適切なデフォルト値を使用しています。

方法1：UV スクリプト（推奨—デフォルトの選択肢）

UV スクリプトでは PEP 723 のインライン依存関係を使い、すっきりと自己完結したトレーニングを実現します。Claude Code での主な方法です。

hf_jobs("uv", {
    "script": """
# /// script
# dependencies = ["trl>=0.12.0", "peft>=0.7.0", "trackio"]
# ///

from datasets import load_dataset
from peft import LoraConfig
from trl import SFTTrainer, SFTConfig
import trackio

dataset = load_dataset("trl-lib/Capybara", split="train")

# Create train/eval split for monitoring
dataset_split = dataset.train_test_split(test_size=0.1, seed=42)

trainer = SFTTrainer(
    model="Qwen/Qwen2.5-0.5B",
    train_dataset=dataset_split["train"],
    eval_dataset=dataset_split["test"],
    peft_config=LoraConfig(r=16, lora_alpha=32),
    args=SFTConfig(
        output_dir="my-model",
        push_to_hub=True,
        hub_model_id="username/my-model",
        num_train_epochs=3,
        eval_strategy="steps",
        eval_steps=50,
        report_to="trackio",
        project="meaningful_prject_name", # project name for the training name (trackio)
        run_name="meaningful_run_name",   # descriptive name for the specific training run (trackio)
    )
)

trainer.train()
trainer.push_to_hub()
""",
    "flavor": "a10g-large",
    "timeout": "2h",
    "secrets": {"HF_TOKEN": "$HF_TOKEN"}
})

メリット： MCP ツールを直接使用できる、コードが簡潔、依存関係をインラインで宣言できる（PEP 723）、ファイルへの保存が不要、自由に制御できる
使用する場面： Claude Code でのすべてのトレーニングタスクにおけるデフォルトの選択肢、カスタムトレーニングロジック、hf_jobs() が必要なあらゆるケース

スクリプトの使用

⚠️ 重要： script パラメーターには、インラインコード（上記の例）または URL を指定できます。ローカルファイルパスは使用できません。

ローカルパスを使用できない理由： ジョブは、ローカルファイルシステムにアクセスできない分離された Docker コンテナ内で実行されます。スクリプトには次のいずれかを指定する必要があります。

• インラインコード（カスタムトレーニングに推奨）
• 誰でもアクセスできる URL
• 非公開リポジトリの URL（HF_TOKEN を使用）

よくある間違い：

# ❌ These will all fail
hf_jobs("uv", {"script": "train.py"})
hf_jobs("uv", {"script": "./scripts/train.py"})
hf_jobs("uv", {"script": "/path/to/train.py"})

正しい方法：

# ✅ Inline code (recommended)
hf_jobs("uv", {"script": "# /// script\n# dependencies = [...]\n# ///\n\n<your code>"})

# ✅ From Hugging Face Hub
hf_jobs("uv", {"script": "https://huggingface.co/user/repo/resolve/main/train.py"})

# ✅ From GitHub
hf_jobs("uv", {"script": "https://raw.githubusercontent.com/user/repo/main/train.py"})

# ✅ From Gist
hf_jobs("uv", {"script": "https://gist.githubusercontent.com/user/id/raw/train.py"})

ローカルスクリプトを使う場合： まず HF Hub にアップロードします。

hf repos create my-training-scripts --type model
hf upload my-training-scripts ./train.py train.py
# Use: https://huggingface.co/USERNAME/my-training-scripts/resolve/main/train.py

方法2：TRL メンテナンススクリプト（公式の例）

TRL では、すべての手法向けに十分な実績のあるスクリプトを提供しています。URL から実行できます。

hf_jobs("uv", {
    "script": "https://github.com/huggingface/trl/blob/main/trl/scripts/sft.py",
    "script_args": [
        "--model_name_or_path", "Qwen/Qwen2.5-0.5B",
        "--dataset_name", "trl-lib/Capybara",
        "--output_dir", "my-model",
        "--push_to_hub",
        "--hub_model_id", "username/my-model"
    ],
    "flavor": "a10g-large",
    "timeout": "2h",
    "secrets": {"HF_TOKEN": "$HF_TOKEN"}
})

メリット： コードを書く必要がない、TRL チームがメンテナンスしている、本番環境でのテスト済み
使用する場面： 標準的な TRL のトレーニング、手早い実験、カスタムコードが不要な場合
入手先： スクリプトは https://github.com/huggingface/trl/tree/main/examples/scripts から入手できます

Hub 上の UV スクリプトをさらに探す

uv-scripts 組織では、Hugging Face Hub 上のデータセットとして保存された、すぐに使える UV スクリプトを提供しています。

# Discover available UV script collections
dataset_search({"author": "uv-scripts", "sort": "downloads", "limit": 20})

# Explore a specific collection
hub_repo_details(["uv-scripts/classification"], repo_type="dataset", include_readme=True)

人気のコレクション： ocr、classification、synthetic-data、vllm、dataset-creation

アプローチ 3：HF Jobs CLI（ターミナルから直接実行するコマンド）

hf_jobs() MCP ツールを利用できない場合は、hf jobs CLI を直接使用します。

⚠️ 重要：CLI の構文規則

# ✅ CORRECT syntax - flags BEFORE script URL
hf jobs uv run --flavor a10g-large --timeout 2h --secrets HF_TOKEN "https://example.com/train.py"

# ❌ WRONG - "run uv" instead of "uv run"
hf jobs run uv "https://example.com/train.py" --flavor a10g-large

# ❌ WRONG - flags AFTER script URL (will be ignored!)
hf jobs uv run "https://example.com/train.py" --flavor a10g-large

# ❌ WRONG - "--secret" instead of "--secrets" (plural)
hf jobs uv run --secret HF_TOKEN "https://example.com/train.py"

主な構文規則：

1. コマンドの順序は hf jobs uv run です（hf jobs run uv ではありません）
2. すべてのフラグ（--flavor、--timeout、--secrets）はスクリプト URL より前に指定する必要があります
3. --secret ではなく --secrets（複数形）を使用します
4. スクリプト URL は位置引数の最後に指定する必要があります

CLI の完全な例：

hf jobs uv run \
  --flavor a10g-large \
  --timeout 2h \
  --secrets HF_TOKEN \
  "https://huggingface.co/user/repo/resolve/main/train.py"

CLI でジョブのステータスを確認する：

hf jobs ps                        # List all jobs
hf jobs logs <job-id>             # View logs
hf jobs inspect <job-id>          # Job details
hf jobs cancel <job-id>           # Cancel a job

アプローチ 4：TRL Jobs パッケージ（簡易トレーニング）

trl-jobs パッケージでは、最適化されたデフォルト設定と、1 行で実行できるトレーニングを利用できます。

uvx trl-jobs sft \
  --model_name Qwen/Qwen2.5-0.5B \
  --dataset_name trl-lib/Capybara

利点： 事前設定済みの設定、自動 Trackio 統合、自動 Hub プッシュ、1 行のコマンド 使用する場面： ユーザーがターミナルで直接作業している場合（Claude Code のコンテキストではない場合）、手早くローカルで試す場合 リポジトリ： https://github.com/huggingface/trl-jobs

⚠️ Claude Code のコンテキストでは、利用可能な場合、hf_jobs() MCP ツール（アプローチ 1）を優先してください。

ハードウェアの選択

モデルサイズ	推奨ハードウェア	コスト（概算／時間）	用途
<1B パラメーター	t4-small	~$0.75	評価ステップを伴わないデモや簡単なテストのみ
1-3B パラメーター	t4-medium、l4x1	~$1.50-2.50	開発
3-7B パラメーター	a10g-small、a10g-large	~$3.50-5.00	本番トレーニング
7-13B パラメーター	a10g-large、a100-large	~$5-10	大規模モデル（LoRA を使用）
13B+ パラメーター	a100-large、a10g-largex2	~$10-20	非常に大規模なモデル（LoRA を使用）

GPU フレーバー： cpu-basic/upgrade/performance/xl、t4-small/medium、l4x1/x4、a10g-small/large/largex2/largex4、a100-large、h100/h100x8

ガイドライン：

• メモリ使用量を抑えるため、7B を超えるモデルには LoRA/PEFT を使用します
• マルチ GPU は TRL/Accelerate によって自動的に処理されます
• テストには小規模なハードウェアから始めます

参照： 詳細な仕様については references/hardware_guide.md を参照してください

重要：結果を Hub に保存する

⚠️ 一時的な環境です。必ず Hub にプッシュしてください

Jobs 環境は一時的です。ジョブが終了すると、すべてのファイルが削除されます。モデルが Hub にプッシュされていない場合、トレーニング結果はすべて失われます。

必須の設定

トレーニングスクリプト／設定内：

SFTConfig(
    push_to_hub=True,
    hub_model_id="username/model-name",  # MUST specify
    hub_strategy="every_save",  # Optional: push checkpoints
)

ジョブの送信時：

{
    "secrets": {"HF_TOKEN": "$HF_TOKEN"}  # Enables authentication
}

確認チェックリスト

送信前に確認してください：

• 設定で push_to_hub=True が指定されている
• hub_model_id にユーザー名／リポジトリ名が含まれている
• secrets パラメーターに HF_TOKEN が含まれている
• ユーザーが対象リポジトリへの書き込み権限を持っている

参照： 詳細なトラブルシューティングについては references/hub_saving.md を参照してください

タイムアウトの管理

⚠️ デフォルトは 30 分です。トレーニングには短すぎます

タイムアウトの設定

{
    "timeout": "2h"   # 2 hours (formats: "90m", "2h", "1.5h", or seconds as integer)
}

タイムアウトのガイドライン

シナリオ	推奨時間	備考
簡単なデモ（50～100 件の例）	10～30 分	セットアップを確認
開発時のトレーニング	1～2 時間	小規模なデータセット
本番環境（3～7B モデル）	4～6 時間	完全なデータセット
LoRA を使った大規模モデル	3～6 時間	データセットによって異なります

モデル／データセットの読み込み、チェックポイントの保存、Hub へのプッシュ処理、ネットワーク遅延に備えて、常に 20～30% の余裕を加えてください。

タイムアウトした場合： ジョブはただちに強制終了され、保存されていない進捗はすべて失われます。最初から再開する必要があります

コストの見積もり

既知のパラメーターでジョブを計画する際は、コストの見積もりを提案してください。 scripts/estimate_cost.py を使用します：

uv run scripts/estimate_cost.py \
  --model meta-llama/Llama-2-7b-hf \
  --dataset trl-lib/Capybara \
  --hardware a10g-large \
  --dataset-size 16000 \
  --epochs 3

出力には、推定時間、コスト、推奨タイムアウト（余裕時間込み）、最適化の提案が含まれます。

提案する場面： ユーザーがジョブを計画している場合、コストや所要時間について質問した場合、ハードウェアを選択している場合、またはジョブの実行時間が 1 時間を超えるか、コストが $5 を超える場合

トレーニングスクリプトの例

本番環境ですぐに使えるベストプラクティスを網羅したテンプレート：

正しく読み込むには、次のスクリプトを使用してください。

• scripts/train_sft_example.py - Trackio、LoRA、チェックポイントを使った完全なSFTトレーニング
• scripts/train_dpo_example.py - 嗜好学習のためのDPOトレーニング
• scripts/train_grpo_example.py - オンラインRLのためのGRPOトレーニング

これらのスクリプトでは、適切なHubへの保存、Trackioとの統合、チェックポイント管理、最適化されたパラメーターを紹介しています。内容をインラインでhf_jobs()に渡すか、カスタムスクリプトのテンプレートとして使用してください。

モニタリングとトラッキング

Trackioは、メトリクスをリアルタイムで可視化します。完全なセットアップガイドについては、references/trackio_guide.mdを参照してください。

主なポイント：

• 依存関係にtrackioを追加する
• report_to="trackio" and run_name="meaningful_name"を指定してトレーナーを設定する

Trackioのデフォルト設定

ユーザーから別の指定がない限り、適切なデフォルト値を使用してください。 Trackioを使ったトレーニングスクリプトを生成する場合：

デフォルト設定：

• Space ID：{username}/trackio（デフォルトのSpace名として「trackio」を使用）
• 実行名：別途指定がない限り、ユーザーが認識しやすい名前を付けます（例：タスク、モデル、目的がわかる説明的な名前）
• 設定：最小限に保ちます。ハイパーパラメーターとモデル／データセットの情報のみを含めます
• プロジェクト名：特定のプロジェクトに実行を関連付けるために、プロジェクト名を使用します

**ユーザーによる上書き：**ユーザーが特定のTrackio設定（カスタムSpace、実行名、グループ化、追加設定など）を指定した場合は、デフォルトではなく、その希望に従ってください。

同じ設定で複数のジョブを管理したり、トレーニングスクリプトの移植性を保ったりする場合に便利です。

実験の実行をグループ化する方法など、完全なドキュメントについてはreferences/trackio_guide.mdを参照してください。

ジョブのステータスを確認する

# List all jobs
hf_jobs("ps")

# Inspect specific job
hf_jobs("inspect", {"job_id": "your-job-id"})

# View logs
hf_jobs("logs", {"job_id": "your-job-id"})

**注意：**ユーザーからステータス確認の依頼があった場合にのみ確認してください。繰り返しポーリングするのは避けてください。

データセットの検証

トレーニング失敗の最大の原因であるフォーマットの不一致を防ぐため、GPUトレーニングを開始する前にデータセットのフォーマットを必ず検証してください。

検証する理由

• トレーニング失敗の50％以上は、データセットのフォーマットの問題が原因です
• DPOは特に厳格で、列名（prompt、chosen、rejected）が完全に一致している必要があります
• GPUジョブが失敗すると、1～10ドルと30～60分が無駄になります
• CPUでの検証は約0.01ドルで、1分未満で完了します

検証するタイミング

次の場合は必ず検証してください：

• 未知のデータセットまたはカスタムデータセット
• DPOトレーニング（重要：90％のデータセットでマッピングが必要です）
• TRLとの互換性が明示されていないデータセット

TRL互換とわかっているデータセットでは、検証を省略できます：

• trl-lib/ultrachat_200k、trl-lib/Capybara、HuggingFaceH4/ultrachat_200kなど

使用方法

hf_jobs("uv", {
    "script": "https://huggingface.co/datasets/mcp-tools/skills/raw/main/dataset_inspector.py",
    "script_args": ["--dataset", "username/dataset-name", "--split", "train"]
})

スクリプトは高速で、通常は同期的に完了します。

結果の読み方

出力には、各トレーニング方法との互換性が表示されます。

• ✓ READY - データセットは互換性があり、そのまま使用できます
• ✗ NEEDS MAPPING - 互換性はありますが、前処理が必要です（マッピングコードが提供されます）
• ✗ INCOMPATIBLE - この方法では使用できません

マッピングが必要な場合、出力にはコピーしてすぐ使えるPythonコードを含む**「MAPPING CODE」**セクションが表示されます。

ワークフローの例

# 1. Inspect dataset (costs ~$0.01, <1 min on CPU)
hf_jobs("uv", {
    "script": "https://huggingface.co/datasets/mcp-tools/skills/raw/main/dataset_inspector.py",
    "script_args": ["--dataset", "argilla/distilabel-math-preference-dpo", "--split", "train"]
})

# 2. Check output markers:
#    ✓ READY → proceed with training
#    ✗ NEEDS MAPPING → apply mapping code below
#    ✗ INCOMPATIBLE → choose different method/dataset

# 3. If mapping needed, apply before training:
def format_for_dpo(example):
    return {
        'prompt': example['instruction'],
        'chosen': example['chosen_response'],
        'rejected': example['rejected_response'],
    }
dataset = dataset.map(format_for_dpo, remove_columns=dataset.column_names)

# 4. Launch training job with confidence

よくあるケース：DPOフォーマットの不一致

ほとんどのDPOデータセットでは、標準とは異なる列名が使われています。例：

Dataset has: instruction, chosen_response, rejected_response
DPO expects: prompt, chosen, rejected

バリデーターはこの問題を検出し、修正に必要な正確なマッピングコードを提示します。

モデルをGGUFに変換する

トレーニング後、llama.cpp、Ollama、LM Studio、その他のローカル推論ツールで使用できるよう、モデルをGGUF形式に変換します。

GGUFとは：

• llama.cppを使用したCPU/GPU推論に最適化されています
• 量子化（4-bit、5-bit、8-bit）に対応し、モデルサイズを削減できます
• Ollama、LM Studio、Jan、GPT4All、llama.cppと互換性があります
• 7Bモデルの場合、通常は2～8GBです（量子化なしでは14GB）

変換するタイミング：

• OllamaまたはLM Studioを使用してモデルをローカルで実行する場合
• 量子化によってモデルサイズを削減する場合
• エッジデバイスにデプロイする場合
• ローカル優先の用途向けにモデルを共有する場合

参照： 本番環境で使用できる変換スクリプト、量子化オプション、ハードウェア要件、使用例、トラブルシューティングを含む、変換手順の完全版については、references/gguf_conversion.mdを参照してください。

簡易変換：

hf_jobs("uv", {
    "script": "<see references/gguf_conversion.md for complete script>",
    "flavor": "a10g-large",
    "timeout": "45m",
    "secrets": {"HF_TOKEN": "$HF_TOKEN"},
    "env": {
        "ADAPTER_MODEL": "username/my-finetuned-model",
        "BASE_MODEL": "Qwen/Qwen2.5-0.5B",
        "OUTPUT_REPO": "username/my-model-gguf"
    }
})

一般的なトレーニングパターン

以下を含む詳細な例については、references/training_patterns.mdを参照してください。

• クイックデモ（5～10分）
• チェックポイントを使用した本番環境向けトレーニング
• マルチGPUトレーニング
• DPOトレーニング（選好学習）
• GRPOトレーニング（オンラインRL）

よくある失敗パターン

メモリ不足（OOM）

対処法（上から順に試してください）：

1. バッチサイズを減らします：per_device_train_batch_size=1とし、gradient_accumulation_steps=8に増やします。有効バッチサイズはper_device_train_batch_size x gradient_accumulation_stepsです。最良のパフォーマンスを得るには、有効バッチサイズを128に近づけてください。
2. 次を有効にします：gradient_checkpointing=True
3. ハードウェアをアップグレードします：t4-small → l4x1、a10g-small → a10g-largeなど。

データセットの形式が正しくない

対処法：

1. まず、データセットインスペクターで検証します。

   uv run https://huggingface.co/datasets/mcp-tools/skills/raw/main/dataset_inspector.py \
     --dataset name --split train
   

2. 互換性マーカー（✓ READY、✗ NEEDS MAPPING、✗ INCOMPATIBLE）が出力されているか確認します
3. 必要に応じて、インスペクターの出力にあるマッピングコードを適用します

ジョブのタイムアウト

対処法：

1. ログで実際の実行時間を確認します：hf_jobs("logs", {"job_id": "..."})
2. 余裕を持たせてタイムアウトを延長します："timeout": "3h"（推定時間に30%を加算します）
3. または、トレーニング量を減らします：num_train_epochsを減らす、小さいデータセットを使う、max_stepsを有効にする
4. チェックポイントを保存します：save_strategy="steps"、save_steps=500、hub_strategy="every_save"

注： デフォルトの30分では、実際のトレーニングには不十分です。最低でも1～2時間必要です。

Hubへのプッシュ失敗

対処法：

1. ジョブに追加します：secrets={"HF_TOKEN": "$HF_TOKEN"}
2. 設定に追加します：push_to_hub=True、hub_model_id="username/model-name"
3. 認証を確認します：mcp__huggingface__hf_whoami()
4. トークンに書き込み権限があり、リポジトリが存在することを確認します（またはhub_private_repo=Trueを設定します）

依存関係の不足

対処法： PEP 723ヘッダーに追加します。

# /// script
# dependencies = ["trl>=0.12.0", "peft>=0.7.0", "trackio", "missing-package"]
# ///

トラブルシューティング

よくある問題：

• ジョブがタイムアウトする → タイムアウトを延長する、エポック数やデータセットを減らす、小さいモデルまたはLoRAを使用する
• モデルがHubに保存されない → push_to_hub=True、hub_model_id、secrets=HF_TOKENを確認する
• メモリ不足（OOM） → バッチサイズを減らす、勾配累積を増やす、LoRAを有効にする、より大きなGPUを使用する
• データセット形式エラー → データセットインスペクターで検証する（「データセットの検証」セクションを参照）
• インポート／モジュールエラー → 依存関係を記載したPEP 723ヘッダーを追加し、形式を確認する
• 認証エラー → mcp__huggingface__hf_whoami()、トークンの権限、secretsパラメーターを確認する

参照： トラブルシューティングガイドの完全版については、references/troubleshooting.mdを参照してください。

リソース

参考資料（このスキル内）

• references/training_methods.md - SFT、DPO、GRPO、KTO、PPO、報酬モデルの概要
• references/training_patterns.md - 一般的なトレーニングパターンと例
• references/unsloth.md - 高速なVLMトレーニング向けのUnsloth（速度約2倍、VRAMを60%削減）
• references/gguf_conversion.md - GGUF変換ガイドの完全版
• references/trackio_guide.md - Trackioのモニタリング設定
• references/hardware_guide.md - ハードウェアの仕様と選定
• references/hub_saving.md - Hub認証のトラブルシューティング
• references/troubleshooting.md - よくある問題と解決方法
• references/local_training_macos.md - macOSでのローカルトレーニング

Scripts（このスキル内）

• scripts/train_sft_example.py - 本番用SFTテンプレート
• scripts/train_dpo_example.py - 本番用DPOテンプレート
• scripts/train_grpo_example.py - 本番用GRPOテンプレート
• scripts/unsloth_sft_example.py - Unsloth用テキストLLMトレーニングテンプレート（高速、VRAM使用量が少ない）
• scripts/estimate_cost.py - 所要時間とコストを見積もります（適切な場合に提案してください）
• scripts/convert_to_gguf.py - 完全なGGUF変換スクリプト

外部スクリプト

• データセットインスペクター - トレーニング前にデータセットの形式を検証します（uv runまたはhf_jobs経由で使用）

外部リンク

• TRLドキュメント
• TRL Jobsトレーニングガイド
• TRL Jobsパッケージ
• HF Jobsドキュメント
• TRLサンプルスクリプト
• UVスクリプトガイド
• UVスクリプトの構成

主なポイント

1. スクリプトをインラインで送信する - scriptパラメーターにはPythonコードを直接指定できます。ユーザーから要望がない限り、ファイルに保存する必要はありません
2. ジョブは非同期です - 待機したり、ポーリングしたりせず、準備ができたらユーザー自身で確認できるようにします
3. 必ずタイムアウトを設定する - デフォルトの30分では不十分です。最低1～2時間を推奨します
4. 必ずHubへのプッシュを有効にする - 環境は一時的なため、プッシュしないと結果がすべて失われます
5. Trackioを含める - リアルタイム監視には、サンプルスクリプトをテンプレートとして使用します
6. コスト見積もりを提案する - パラメーターが分かっている場合は、scripts/estimate_cost.pyを使用します
7. UVスクリプトを使用する（アプローチ1） - インラインスクリプトを指定してhf_jobs("uv", {...})をデフォルトで使用します。標準的なトレーニングにはTRLのメンテナンス対象スクリプトを使用し、Claude Codeではbashのtrl-jobsコマンドを避けてください
8. 最新のTRLドキュメントにはhf_doc_fetch／hf_doc_searchを使用する
9. トレーニング前にデータセットの形式を検証する - データセットインスペクターを使用します（データセットの検証セクションを参照）
10. モデルのサイズに適したハードウェアを選ぶ - 7Bを超えるモデルにはLoRAを使用します