gemma-trainer

Gemma のトレーニングとファインチューニングのスキル

1. 基本原則：ローカルでのファインチューニング環境の設定

ローカルでトレーニングする場合は、メモリ効率と実行速度が非常に重要です。常に、以下のベストプラクティスに従うようユーザーに案内してください。

• Unsloth を優先する：ローカルで単一 GPU を使ってトレーニングする場合は、常に Unsloth を推奨してください。Gemma 4 をネイティブにサポートし、メモリ使用量を最大 70％削減し、標準的な Hugging Face PEFT によるトレーニングより最大 2 倍高速です。
• TRL に切り替える：マルチ GPU 環境（DDP/FSDP を使用）や Unsloth が利用できない場合は、Hugging Face TRL（SFTTrainer、DPOTrainer）を PEFT および bitsandbytes（QLoRA 用）と組み合わせて使用してください。
• 常に QLoRA（4 ビット量子化）を使用する：Gemma モデル（Gemma 4 12B/31B など）をコンシューマー向け VRAM に収めるうえで不可欠です。
• コンテキストウィンドウと最大長を管理する：Gemma 4 は最大 256K のコンテキストウィンドウをサポートしていますが、ローカルでは、メモリ不足（OOM）エラーを防ぐために、2048～8192 トークンのコンテキストウィンドウでのトレーニングを推奨してください。

2. 適切なトレーニング方法の選択

ユーザーの目的に応じて、適切なワークフローを選べるよう支援してください。

• 教師ありファインチューニング（SFT）：新しい分野、特化したタスク指示、またはカスタム出力構造を学習させます。
  • 前提条件：生テキスト、指示と応答のペア、またはチャットログ。
  • 出力：プロンプトと応答のペアでトレーニングしたアダプター。
• 直接選好最適化（DPO）：人間の選好に合わせて、モデルのスタイル、振る舞い、口調、安全性を調整します。
  • 前提条件：SFT でトレーニング済みの Gemma モデルと、選好を示すペアワイズデータセット。
  • 出力：独立した報酬ヘッドを使わず、モデルの重みを直接調整します。
• 報酬モデリング（RM）：応答の品質を評価するスコアリングシステムをトレーニングします。
  • 前提条件：二項選好ペアワイズデータセット。
  • 出力：Gemma の上に分類形式の報酬ヘッドを追加します。

3. データセットの準備と検証

フォーマットの問題は、トレーニングの実行結果が悪くなる最大の原因です。ユーティリティスクリプト [assets/dataset_prep.py] を使って、ファイルを必ず検証してください。

Gemma チャットプロンプト形式

データセットが Gemma の公式チャットテンプレートに一致していることを確認してください。

<|turn>system
Your instruction here<turn|>
<|turn>user
Your query here<turn|>
<|turn>model
Your response here<turn|>

フォーマットのずれを防ぐため、データセットのトークン化時にはトークナイザーの apply_chat_template を使用してください。

形式の仕様

• SFT（教師ありファインチューニング）： 会話ターンのリストとしてフォーマットします。

  {
    "messages": [
      {"role": "user", "content": "Tell me a joke."},
      {"role": "model", "content": "Why did the computer go to the doctor? It had a virus!"}
    ]
  }
  

• DPO（直接選好最適化）： プロンプト、選好された（より良い）応答、選好されなかった（より悪い）応答を含むペアワイズサンプルが必要です。

  {
    "prompt": "Write a python function to compute factorial.",
    "chosen": "def factorial(n):\n    return 1 if n <= 1 else n * factorial(n - 1)",
    "rejected": "factorial is computed using recursion or loops. Just import math."
  }
  

• 報酬モデリング： DPO データセットと同じ形式にします。RewardTrainer はペアを評価し、chosen のロジットスコアが rejected より高くなるよう学習します。

データセットの蒸留と合成（教師・生徒）

ローカルでの知識蒸留では、大規模で高性能な教師モデル（Gemma 4 31B や Gemma 4 26B A4B など）が生成した高品質なデータセットの出力を使って、小型で軽量な生徒モデル（Gemma 4 E2B など）をトレーニングできます。

ユーティリティスクリプト [assets/distill_dataset.py] を使って、ローカルマシン上でファインチューニング用データセットを生成してください。

4. ファインチューニングのワークフロー

教師ありファインチューニング（SFT）

ローカルで QLoRA ファインチューニングセッションを開始するには、[assets/sft_train.py] アセットを使用します。

• LoRA ハイパーパラメーター：
  • ランク（r）：16 または 32（ランクを高くすると複雑な動作を捉えられますが、より多くのメモリを消費します）。
  • アルファ（lora_alpha）：32 または 64（目安：lora_alpha = 2 * r）。
  • ドロップアウト（lora_dropout）：0.05 または 0.1（特定の経路に頼るのではなく、より堅牢な特徴を学習するようモデルを促します）。
  • 対象モジュール：PEFT の Gemma 4 のデフォルトのスコープであるLM レイヤーを使用します。
  • 学習率：QLoRA の場合は 2e-4、フルファインチューニングの場合は 2e-5。

直接選好最適化（DPO）

アラインメントを実行するには、[assets/dpo_train.py] テンプレートを使用します。

• DPO のルール：
  • DPO を実行する前に、使用する指示形式で必ずベースモデルに SFT を実施してください。ドメイン外のベースモデルに DPO を直接実施すると、通常は失敗するか、出力形式が劣化します。
  • beta（DPO の温度パラメーター）は 0.1 に設定します。0.1 から 0.5 の値で、モデルが参照ポリシーにどれだけ厳密に従うかを調整します。

報酬モデリング（RM）

評価モデルを学習するには、[assets/reward_train.py] テンプレートを使用します。

• シーケンス分類ヘッド（num_labels=1 を指定した AutoModelForSequenceClassification）を使用してモデルを初期化します。
• 優先される応答を区別するため、単一のスカラー報酬値を学習します。

5. マルチモーダルファインチューニング（ビジョンとオーディオ）

Gemma 4 モデルはネイティブでマルチモーダルに対応しています。画像またはオーディオでファインチューニングするには、以下の手順に従います。

ビジョン SFT

• Gemma 4 E2B/E4B/12B/26B/31B モデルを使用します。
• カスタムのビジュアルデータコレーターと、標準の Hugging Face SFTTrainer を使用します。
• ローカルの画像パスまたは PIL 画像と、それに対応する会話形式の指示を含むデータセットを用意します。

  {
    "messages": [
      {"role": "user", "content": [
          {"type": "image", "url": "path/to/image.png"},
          {"type": "text", "text": "Describe this image."}
      ]},
      {"role": "assistant", "content": [
          {"type": "text", "text": "An abstract oil painting with vibrant warm gradients."}
      ]}
    ]
  }
  
  

オーディオ SFT

• Gemma 4 E2B/E4B/12B モデルを使用します。
• 生のオーディオ配列（16kHz でサンプリング）をモデルプロセッサーに渡し、input_features を生成します。
• 会話形式を維持し、メッセージ形式で image タイプを audio タイプに置き換えます。

  {
    "messages": [
      {"role": "user", "content": [
          {"type": "text", "text": "Describe this audio."},
          {"type": "audio", "url": "path/to/audio.wav"}
      ]},
      {"role": "assistant", "content": [
          {"type": "text", "text": "This is an audio file of a bird chirping."}
      ]}
    ]
  }
  

6. ポストトレーニングとデプロイ用ユーティリティ

GGUF への変換

LoRA の学習が完了したら、モデルを GGUF 形式に変換できます。

オプション 1：Unsloth によるネイティブエクスポート（推奨）

Unsloth を使用してモデルを学習した場合は、GGUF 形式にネイティブに直接エクスポートできます。これにより、マージと量子化が自動的に処理されます。

ベストプラクティスについては、GGUF への保存をご覧ください。

オプション 2：llama.cpp による手動変換

Unsloth を使用していない場合は、llama.cpp を使用して、マージ済みの Hugging Face モデルディレクトリを手動で変換できます。

LiteRT-LM（.litertlm）によるオンデバイスデプロイ

LiteRT-LM は、ハードウェアアクセラレーション（CPU、GPU、NPU）を利用して、モバイル、ウェブ、IoT ハードウェア上で Gemma 4 E2B や Gemma 4 E4B などのモデルを実行するよう最適化されています。ベストプラクティスについては、LiteRT-LM ガイドをご覧ください。