huggingface-llm-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 パッケージでは、最適化されたデフォルト設定と、ワンライナーでのトレーニングを利用できます。

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 params	t4-small	~$0.75	評価ステップなしのデモ、簡単なテストのみ
1-3B params	t4-medium、l4x1	~$1.50-2.50	開発
3-7B params	a10g-small、a10g-large	~$3.50-5.00	本番トレーニング
7-13B params	a10g-large、a100-large	~$5-10	大規模モデル（LoRA を使用）
13B+ params	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/hf_benchmarks.py を使用します。これにより、サイズとハードウェアの制約を考慮しながら、トレーニングのベースモデルを選択できます。

# Get help on the benchmarks command:
uv run scripts/hf_benchmarks.py --help

例 -- OCR のベースモデルを選択する

# Search for benchmarks containing whose name contains the text `ocr`
uv run scripts/hf_benchmarks.py search --query ocr

# Get the ranked leaderboard for the allenai/olmOCR-bench benchmark 
uv run scripts/hf_benchmarks.py leaderboard allenai/olmOCR-bench

コストの見積もり

パラメーターがわかっているジョブを計画する際は、コスト見積もりを提案してください。 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（デフォルトのスペース名として「trackio」を使用）
• 実行名：別途指定がない限り、ユーザーが認識しやすい名前を付けてください（例：タスク、モデル、目的がわかる名前）
• 設定：最小限に保ち、ハイパーパラメーターとモデル／データセットの情報のみを含めます
• プロジェクト名：特定のプロジェクトに実行を関連付けるため、プロジェクト名を使用します

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

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

実験の実行をグループ化する方法を含む詳細なドキュメントについては、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 ビット、5 ビット、8 ビット）に対応し、モデルサイズを削減できます
• 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/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変換スクリプト
• scripts/hf_benchmarks.py - タスク、別名、またはフリーテキストでベンチマーク結果とリーダーボードを検索します。

外部スクリプト

• データセットインスペクター - トレーニング前にデータセットの形式を検証します（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を使用します