Anthropic ClaudeLLM・AI開発⭐ リポ 0品質スコア 50/100

huggingface-llm-trainer

Name: huggingface-llm-trainer
Author: huggingface

TRL（Transformer Reinforcement Learning）またはUnslothを使用し、Hugging Face Jobsインフラ上で言語・ビジョンモデルのトレーニングやファインチューニングを行います。SFT・DPO・GRPO・報酬モデリングなどの学習手法やローカル展開向けのGGUF変換に対応し、データセット準備、ハードウェア選定、コスト見積もり、Trackioによるモニタリング、Hubの認証設定なども包括的にサポートします。ローカルGPU環境なしでHugging Face Jobs上でのクラウドGPUトレーニングやGGUF変換を行いたい場合に活用してください。

description の原文を見る

Train or fine-tune language and vision models using TRL (Transformer Reinforcement Learning) or Unsloth with Hugging Face Jobs infrastructure. Covers SFT, DPO, GRPO and reward modeling training methods, plus GGUF conversion for local deployment. Includes guidance on the TRL Jobs package, UV scripts with PEP 723 format, dataset preparation and validation, hardware selection, cost estimation, Trackio monitoring, Hub authentication, model selection/leaderboards and model persistence. Use for tasks involving cloud GPU training, GGUF conversion, or when users mention training on Hugging Face Jobs without local GPU setup.

SKILL.md 本文

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

概要

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

TRL は複数のトレーニング方法を提供します：

SFT (Supervised Fine-Tuning) - 標準的な命令チューニング
DPO (Direct Preference Optimization) - 選好データからのアライメント
GRPO (Group Relative Policy Optimization) - オンライン 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
# 等

参照： 方法の概要と選択ガイダンスについては 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 は約 60% 少ない VRAM を使用します
速度が重要 - Unsloth は約 2 倍高速です
大規模モデルをトレーニングしている (>13B) - メモリ効率が重要です
ビジョン言語モデル (VLM) をトレーニングしている - Unsloth は FastVisionModel をサポートしています

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

主要な指示

トレーニングジョブをサポートするときは：

常に hf_jobs() MCP ツールを使用してください - hf_jobs("uv", {...}) を使用してジョブを送信します。bash trl-jobs コマンドではなく。script パラメータは Python コードを直接受け入れます。ユーザーが明示的に要求しない限り、ローカルファイルに保存しないでください。スクリプトコンテンツを文字列として hf_jobs() に渡します。ユーザーが「モデルをトレーニングする」「ファインチューニング」などの同様のリクエストを求める場合、トレーニングスクリプトを作成し、hf_jobs() を使用してすぐにジョブを送信する 必要があります。
常に Trackio を含めてください - すべてのトレーニングスクリプトには、リアルタイムモニタリング用に Trackio を含める必要があります。scripts/ のサンプルスクリプトをテンプレートとして使用してください。
送信後にジョブの詳細を提供してください - 送信後、ジョブ ID、モニタリング URL、推定時間を提供し、ユーザーが後でステータスチェックをリクエストできることに注意してください。
サンプルスクリプトをテンプレートとして使用してください - 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

前提条件チェックリスト

トレーニングジョブを開始する前に、以下を確認してください：

✅ アカウント・認証

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

✅ データセット要件

データセットは Hub に存在するか、datasets.load_dataset() 経由でロード可能である必要があります
形式はトレーニング方法と一致する必要があります (SFT: "messages"/text/prompt-completion; DPO: chosen/rejected; GRPO: prompt のみ)
常に未知のデータセットを検証してください GPU トレーニングの前に形式の失敗を防ぐため (以下のデータセット検証セクションを参照)
ハードウェアに適したサイズ (デモ: t4-small で 50～100 例; 本番: a10g-large/a100-large で 1K～10K+)

⚠️ 重要な設定

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

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

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

必須アクション

ユーザーがトレーニングをリクエストする場合：

Trackio を含めてトレーニングスクリプトを作成します (scripts/train_sft_example.py をテンプレートとして使用)
直ちに hf_jobs() MCP ツールを使用して送信します - ユーザーがリクエストしない限りファイルに保存しないでください。スクリプトコンテンツをインラインで渡します
ジョブ ID、モニタリング URL、推定時間を報告します
ユーザーがステータスチェックをリクエストするのを待ちます - 自動的にポーリングしないでください

根本的なルール

ジョブはバックグラウンドで実行されます - 送信は直ちに返される; トレーニングは独立して続行します
初期ログは遅延します - ログが表示されるまで 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) でのクイックデモの場合、eval_dataset と eval_strategy を省略して約 40% のメモリを節約します。それでもトレーニング損失と学習の進行状況が表示されます。

シーケンス長設定

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

# ✅ 正しい - シーケンス長を設定する必要がある場合
SFTConfig(max_length=512)   # シーケンスを 512 トークンに切り詰める
DPOConfig(max_length=2048)  # 長いコンテキスト (2048 トークン)

# ❌ 間違い - このパラメータは存在しません
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")

# トレーニング/評価分割をモニタリング用に作成
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_project_name", # トレーニング名用のプロジェクト名 (trackio)
        run_name="meaningful_run_name",   # 特定のトレーニング実行の説明名 (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 付き)

一般的な間違い：

# ❌ これらはすべて失敗します
hf_jobs("uv", {"script": "train.py"})
hf_jobs("uv", {"script": "./scripts/train.py"})
hf_jobs("uv", {"script": "/path/to/train.py"})

正しいアプローチ：

# ✅ インラインコード (推奨)
hf_jobs("uv", {"script": "# /// script\n# dependencies = [...]\n# ///\n\n<your code>"})

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

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

# ✅ 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
# 使用: 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 スクリプトを提供します：

# 利用可能な UV スクリプト コレクションを検出
dataset_search({"author": "uv-scripts", "sort": "downloads", "limit": 20})

# 特定のコレクションを探索
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 構文ルール

# ✅ 正しい構文 - スクリプト URL の前のフラグ
hf jobs uv run --flavor a10g-large --timeout 2h --secrets HF_TOKEN "https://example.com/train.py"

# ❌ 間違い - "uv run" の代わりに "run uv"
hf jobs run uv "https://example.com/train.py" --flavor a10g-large

# ❌ 間違い - スクリプト URL の後のフラグ (無視されます!)
hf jobs uv run "https://example.com/train.py" --flavor a10g-large

# ❌ 間違い - "--secret" の代わりに "--secrets" (複数形)
hf jobs uv run --secret HF_TOKEN "https://example.com/train.py"

主要な構文ルール：

コマンド順は hf jobs uv run です (「hf jobs run uv」ではない)
すべてのフラグ (--flavor、--timeout、--secrets) はスクリプト URL より前に来る必要があります
--secret ではなく --secrets (複数形) を使用してください
スクリプト 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                        # すべてのジョブをリスト
hf jobs logs <job-id>             # ログを表示
hf jobs inspect <job-id>          # ジョブの詳細
hf jobs cancel <job-id>           # ジョブをキャンセル

アプローチ 4: TRL Jobs パッケージ (簡略トレーニング)

trl-jobs パッケージは最適化されたデフォルトとワンライナートレーニングを提供します。

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

利点: 事前設定された設定、自動 Trackio 統合、自動 Hub プッシュ、ワンラインコマンド 使用時期: ユーザーが直接ターミナルで作業している場合 (Claude Code コンテキストではない)、クイックローカル実験 リポジトリ: https://github.com/huggingface/trl-jobs

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

ハードウェア選択

モデルサイズ	推奨ハードウェア	コスト (約/時間)	ユースケース
<1B パラメータ	`t4-small`	~$0.75	デモ、eval ステップなしのクイックテストのみ
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",  # 指定が必須
    hub_strategy="every_save",  # オプション: チェックポイントをプッシュ
)

ジョブ送信内：

{
    "secrets": {"HF_TOKEN": "$HF_TOKEN"}  # 認証を有効にする
}

検証チェックリスト

送信前：

設定で push_to_hub=True が設定されている
hub_model_id に username/repo-name が含まれている
secrets パラメータに HF_TOKEN が含まれている
ユーザーはターゲットリポジトリへの書き込みアクセス権を持っている

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

タイムアウト管理

⚠️ デフォルト: 30 分—トレーニングには短すぎる

タイムアウトの設定

{
    "timeout": "2h"   # 2 時間 (形式: "90m"、"2h"、"1.5h"、または整数として秒)
}

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

シナリオ	推奨	注釈
クイックデモ (50-100 例)	10-30 分	セットアップを検証
開発トレーニング	1-2 時間	小さいデータセット
本番 (3-7B モデル)	4-6 時間	完全なデータセット
LoRA を使用した大規模モデル	3-6 時間	データセットによる

常に 20-30% のバッファを追加してください - モデル/データセット読み込み、チェックポイント保存、Hub プッシュ操作、ネットワーク遅延用。

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

ベースモデルを選択 (モデル選択)

タスクタイプまたはベンチマーク結果に基づいてトレーニングするモデルを特定してください。

scripts/hf_benchmarks.py を使用して、特定のタスク用に高性能なモデルを特定します。これにより、ユーザーはトレーニングの基盤として使用するモデルを選択しながら、サイズとハードウェアの制約を考慮できます。

# ベンチマーク コマンドのヘルプを取得:
uv run scripts/hf_benchmarks.py --help

例 – OCR ベースモデルの選択

# 名前に `ocr` テキストを含むベンチマークを検索
uv run scripts/hf_benchmarks.py search --query ocr

# allenai/olmOCR-bench ベンチマークのランク付きリーダーボードを取得
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" と run_name="meaningful_name" でトレーナーを設定

Trackio 設定デフォルト

ユーザーが別の方法で指定しない限り、賢明なデフォルトを使用してください。 Trackio でトレーニングスクリプトを生成する場合：

デフォルト設定：

Space ID: {username}/trackio (デフォルトスペース名として "trackio" を使用)
実行命名: 別途指定がない場合、ユーザーが認識できるような方法で実行に名前を付けてください (例: タスク、モデル、または目的の説明)
設定: 最小限に保つ - ハイパーパラメータとモデル/データセット情報のみを含める
プロジェクト名: 実行を特定のプロジェクトに関連付けるためにプロジェクト名を使用してください

ユーザーのオーバーライド： ユーザーが特定の trackio 設定 (カスタムスペース、実行命名、グループ化、または追加設定) をリクエストする場合、デフォルトの代わりにユーザーの設定を適用してください。

これは、同じ設定で複数のジョブを管理したり、トレーニングスクリプトをポータブルに保つのに便利です。

詳細については references/trackio_guide.md を参照してください (実験用の実行のグループ化を含む)。

ジョブステータスをチェック

# すべてのジョブをリスト
hf_jobs("ps")

# 特定のジョブを検査
hf_jobs("inspect", {"job_id": "your-job-id"})

# ログを表示
hf_jobs("logs", {"job_id": "your-job-id"})

記憶： ユーザーがステータスチェックをリクエストするのを待ってください。繰り返しポーリングを避けてください。

データセット検証

GPU トレーニングを起動する前にデータセット形式を検証して、トレーニング失敗の第 1 位の原因である形式の不一致を防いでください。

なぜ検証するのか

トレーニング失敗の 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 - この方法では使用できません

マッピングが必要な場合、出力には 「MAPPING CODE」 セクションが含まれ、コピー&ペースト対応の Python コードがあります。

ワークフローの例

# 1. データセットを検査 (約 $0.01 のコスト、CPU で <1 分)
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. 出力マーカーをチェック:
#    ✓ READY → トレーニングに進む
#    ✗ NEEDS MAPPING → 下記のマッピング コードを適用
#    ✗ INCOMPATIBLE → 別の方法/データセットを選択

# 3. マッピングが必要な場合、トレーニングの前に適用:
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. 自信を持ってトレーニング ジョブを起動

一般的なシナリオ: DPO 形式の不一致

ほとんどの DPO データセットは非標準の列名を使用します。例：

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

バリデータはこれを検出し、修正するための正確なマッピングコードを提供します。

モデルを GGUF に変換

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

GGUF とは：

llama.cpp によるローカル CPU/GPU 推論に最適化
量子化 (4 ビット、5 ビット、8 ビット) をサポートして、モデルサイズを削減
Ollama、LM Studio、Jan、GPT4All、llama.cpp と互換性あり
通常 2～8GB (非量子化 14GB に対して) 7B モデル

変換時期：

Ollama または LM Studio を使用してローカルでモデルを実行している
量子化によるモデルサイズの削減
エッジデバイスへのデプロイ
ローカルファーストの使用でモデルを共有

参照： 本番対応の変換スクリプト、量子化オプション、ハードウェア要件、使用例、トラブルシューティングについては references/gguf_conversion.md を参照してください。

クイック変換：

hf_jobs("uv", {
    "script": "<references/gguf_conversion.md の完全なスクリプトを参照>",
    "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)

修正 (順に試してください)：

バッチサイズを削減: per_device_train_batch_size=1、gradient_accumulation_steps=8 を増加。有効バッチサイズは per_device_train_batch_size × gradient_accumulation_steps です。最高のパフォーマンスのために有効バッチサイズを 128 に近く保ちます。
有効にする: gradient_checkpointing=True
ハードウェアをアップグレード: t4-small → l4x1、a10g-small → a10g-large など。

データセットの形式が誤っている

修正：

データセットインスペクタで最初に検証:

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

互換性マーカーの出力をチェック (✓ READY、✗ NEEDS MAPPING、✗ INCOMPATIBLE)
必要に応じて、インスペクタ出力のマッピングコードを適用してください

ジョブのタイムアウト

修正：

ログで実際のランタイムをチェック: hf_jobs("logs", {"job_id": "..."})
バッファを使用してタイムアウトを増加: "timeout": "3h" (推定時間に 30% を追加)
またはトレーニングを削減: num_train_epochs を低くし、より小さいデータセットを使用し、max_steps を有効にします
チェックポイントを保存: save_strategy="steps"、save_steps=500、hub_strategy="every_save"

注：デフォルトの 30 分は本番トレーニングには不十分です。最小 1～2 時間。

Hub プッシュの失敗

修正：

ジョブに追加: secrets={"HF_TOKEN": "$HF_TOKEN"}
設定に追加: push_to_hub=True、hub_model_id="username/model-name"
認証を検証: mcp__huggingface__hf_whoami()
トークンに書き込み権限があり、リポジトリが存在することを確認してください (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() をチェック、トークンの権限、秘密パラメータ

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

リソース

参照 (このスキル内)

references/training_methods.md - SFT、DPO、GRPO、KTO、PPO、報酬モデリングの概要
references/training_patterns.md - 一般的なトレーニングパターンと例
references/unsloth.md - 高速 VLM トレーニング用の Unsloth (~2 倍速度、60% 少ない VRAM)
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 で使用)

外部リンク

主要な要点

スクリプトをインラインで送信 - script パラメータは Python コードを直接受け入れます。ユーザーがリクエストしない限りファイル保存は不要です
ジョブは非同期 - 待機/ポーリングしないでください。ユーザーが準備完了時にチェックできるようにしてください
常にタイムアウトを設定 - デフォルトの 30 分は不十分です。最小 1～2 時間を推奨
常に Hub プッシュを有効にする - 環境は一時的です。プッシュなしでは、すべての結果が失われます
Trackio を含める - サンプルスクリプトをリアルタイムモニタリングのテンプレートとして使用してください
コスト推定を提供する - パラメータが既知の場合、scripts/estimate_cost.py を使用してください
UV スクリプト (アプローチ 1) を使用 - インラインスクリプトで hf_jobs("uv", {...}) をデフォルトにしてください。標準トレーニング用の TRL メンテナンススクリプト。Claude Code で bash trl-jobs コマンドを避けてください
最新の TRL ドキュメントについて hf_doc_fetch/hf_doc_search を使用
トレーニング前にデータセット形式を検証 - データセットインスペクタで (データセット検証セクションを参照)
モデルサイズに適したハードウェアを選択。モデル >7B には LoRA を使用してください

ライセンス: Apache-2.0(寛容ライセンスのため全文を引用しています) · 原本リポジトリ

詳細情報

作者: huggingface
リポジトリ: huggingface/skills
ライセンス: Apache-2.0
最終更新: 不明

GitHubで原本を見る →フィードバックを送る

Source: https://github.com/huggingface/skills / ライセンス: Apache-2.0

SKILL.md 本文

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

概要

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

Unsloth を使用する場合

主要な指示

ローカル スクリプト実行

前提条件チェックリスト

✅ アカウント・認証

✅ データセット要件

⚠️ 重要な設定

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

必須アクション

根本的なルール

送信後

クイック スタート: 3 つのアプローチ

シーケンス長設定

アプローチ 1: UV スクリプト (推奨—デフォルト選択)

スクリプトの操作

アプローチ 2: TRL メンテナンス スクリプト (公式例)

Hub でさらに多くの UV スクリプトを検索

アプローチ 3: HF Jobs CLI (直接ターミナル コマンド)

アプローチ 4: TRL Jobs パッケージ (簡略トレーニング)

ハードウェア選択

重要: 結果を Hub に保存

必要な設定

検証チェックリスト

タイムアウト管理

タイムアウトの設定

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

ベース モデルを選択 (モデル選択)

例 – OCR ベース モデルの選択

コスト推定

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

モニタリングと追跡

Trackio 設定デフォルト

ジョブ ステータスをチェック

データセット検証

なぜ検証するのか

検証時期

使用方法

結果の読み取り

ワークフローの例

一般的なシナリオ: DPO 形式の不一致

モデルを GGUF に変換

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

一般的な失敗モード

メモリ不足 (OOM)

データセットの形式が誤っている

ジョブのタイムアウト

Hub プッシュの失敗

依存関係がない

トラブルシューティング

リソース

参照 (このスキル内)

スクリプト (このスキル内)

外部スクリプト

外部リンク

主要な要点

詳細情報

関連スキル

agent-browser

anyskill

engram

skyvern

pinchbench

openui

ローカルスクリプト実行

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

クイックスタート: 3 つのアプローチ

アプローチ 2: TRL メンテナンススクリプト (公式例)

アプローチ 3: HF Jobs CLI (直接ターミナルコマンド)

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

ベースモデルを選択 (モデル選択)

例 – OCR ベースモデルの選択

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

ジョブステータスをチェック

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