Gemma3 日本語 LoRA ファインチューニング徹底解説

!pip install -U "transformers>=4.41" "peft>=0.11" "accelerate>=0.30" "datasets>=3.0" "bitsandbytes>=0.43" sentencepiece pandas
!pip install -U huggingface_hub

• transformers：Hugging Faceが提供する、最先端の自然言語処理（NLP）モデルを扱うためのライブラリ。Gemma 3 を含む最新 LLM の推論・学習を支えます。
• peft / accelerate / bitsandbytes：LoRA / QLoRA によるパラメータ効率化学習を支援するライブラリ群です。4bit 量子化で学習する場合は bitsandbytes が必須になります。
• datasets / sentencepiece / pandas：データセットの取得・整形・確認に利用します。Gemma トークナイザーは SentencePiece を利用するため、事前にインストールしておくと安全です。
• huggingface_hub：Hugging Face Hub へのログインやモデル/データのダウンロードを行うためのライブラリです。

from transformers import AutoTokenizer, AutoModelForCausalLM
import torch

model_name = "google/gemma-3-1b-it"
tokenizer = AutoTokenizer.from_pretrained(model_name)
tokenizer.pad_token = tokenizer.eos_token
model = AutoModelForCausalLM.from_pretrained(
    model_name,
    device_map="auto",
    torch_dtype=torch.float16,
)

• from transformers import ...
  Hugging Faceのtransformersライブラリから、テキストをトークン（数値）に変換するための「トークナイザー」と、文章生成などに使う「因果言語モデル（Causal Language Model）」をインポートします。
• model_name = "google/gemma-3-1b-it"
  利用したいモデルの名前を指定します。Hugging Face Hubで公開されているモデルのリポジトリ名（例：google/gemma-3-1b-it）をそのまま使います。
• tokenizer = AutoTokenizer.from_pretrained(model_name)
  指定したモデルに対応したトークナイザー（テキスト→トークン変換器）をHugging Face Hubからダウンロードして使えるようにします。
• tokenizer.pad_token = tokenizer.eos_token
  Gemma のトークナイザーはデフォルトでパディングトークンが定義されていないため、EOS をパディングとして設定しておくと学習が安定します。
• model = AutoModelForCausalLM.from_pretrained(...)
  device_map="auto" と torch_dtype=torch.float16 を指定し、Colab 上の GPU メモリに収まる形でモデルをロードします。より厳しいメモリ制約では 4bit 量子化（QLoRA）を検討します。

1. LoRAの設定とモデルへの適用
   

   from peft import LoraConfig, get_peft_model, TaskType
   
   lora_config = LoraConfig(
       r=16,
       lora_alpha=32,
       target_modules=["q_proj", "k_proj", "v_proj", "o_proj"],
       lora_dropout=0.05,
       bias="none",
       task_type=TaskType.CAUSAL_LM
   )
   
   model = get_peft_model(model, lora_config)

   • r：LoRAのランク（表現力に影響）
   • lora_alpha：LoRAのスケーリング係数
   • target_modules：LoRAを適用する層（Gemma 3 の公開ノートブックでは Attention の q/k/v/o への適用が推奨されています）
   • lora_dropout：ドロップアウト率
   • bias：バイアス項の扱い
   • task_type：タスク種別（因果言語モデル）
   LoRAは大規模モデルの一部パラメータだけを効率的に微調整する手法です。
2. データセットのトークナイズ（前処理）
   

   def tokenize_function(example):
       tokens = tokenizer(
           example["text"],
           truncation=True,
           max_length=512,
           padding="max_length",
           return_tensors="pt",
       )
       tokens = {k: v.squeeze(0) for k, v in tokens.items()}
       tokens["labels"] = tokens["input_ids"].clone()
       return tokens
   
   tokenized_train = train_dataset.map(tokenize_function, batched=False)
   tokenized_test = test_dataset.map(tokenize_function, batched=False)

   • テキストをトークン（数値）に変換
   • 最大長512トークン、パディングあり
   • labelsにinput_idsのコピーを入れ、自己回帰型言語モデルの教師データに
3. トレーニングパラメータの設定
   

   from transformers import TrainingArguments
   
   training_args = TrainingArguments(
       output_dir="./results",
       per_device_train_batch_size=2,
       per_device_eval_batch_size=2,
       gradient_accumulation_steps=2,
       num_train_epochs=1,
       evaluation_strategy="steps",
       save_steps=500,
       eval_steps=500,
       logging_steps=50,
       learning_rate=2e-4,
       fp16=True,
       report_to="none"
   )

   パラメータ	意味
   output_dir	結果の保存先ディレクトリ
   per_device_train_batch_size	1デバイスあたりの学習バッチサイズ（Colab無料枠を想定し小さめに設定）
   gradient_accumulation_steps	小さなバッチサイズでも実効バッチを大きくするための蓄積回数
   num_train_epochs	学習エポック数
   evaluation_strategy	検証タイミング（steps=一定ステップごと）
   save_steps, eval_steps, logging_steps	500/500/50ステップごとに保存・検証・ログ出力
   learning_rate	学習率 例: 5e-5（=0.00005）、1e-4（=0.0001） 学習率（learning_rate）は、モデルの重みをどれだけ一度に更新するかを決める重要な値です。 値が大きい（例: 1e-4や5e-4など）と、重みの更新幅が大きくなり、学習が速く進みますが、発散（損失が下がらず不安定になる）リスクも高まります。 値が小さい（例: 5e-5や1e-5など）と、学習はゆっくりですが、安定して収束しやすくなります。 LoRAや微調整では1e-4～5e-5あたりがよく使われます。 最適な値はデータ量やモデル、バッチサイズによって異なるため、最初は5e-5や1e-4で試し、損失の減り方や発散の有無を見て調整するのが一般的です。 例: learning_rate=5e-5（=0.00005） 例: learning_rate=1e-4（=0.0001）
   fp16	16bit精度で学習（GPUメモリ節約）
   load_best_model_at_end	最良モデルを最後に自動ロード
   metric_for_best_model	評価指標（eval_loss=損失）

   【パラメータ設定の具体例とカスタマイズ例】
   

   • バッチサイズ（per_device_train_batch_size, per_device_eval_batch_size）：
     例: 8（Google Colab A100の場合の推奨値。VRAMが少ない場合は4や2に下げる。
     大きくすると学習が速く安定するが、メモリ不足に注意。
   • エポック数（num_train_epochs）：
     例: 1（計算時間短縮のため1に設定。通常は1～5で調整。
     データ量が多い場合や精度を上げたい場合は増やす。
   • 学習率（learning_rate）：
     例: 5e-5（LoRA微調整では1e-4～5e-5がよく使われる。
     値が大きすぎると発散、小さすぎると収束が遅い。
   • fp16：
     True（16bit精度で学習し、GPUメモリを節約。A100やT4などのGPUで有効。
     古いGPUやCPUではFalseにする。
   • evaluation_strategy, save_steps, eval_steps, logging_steps：
     例: "steps", 500/500/50（一定ステップごとに検証・保存・ログ出力。
     頻度を上げると状況把握は容易になるが、オーバーヘッドも増えます。

   Tips:
   - Colabの無料枠やVRAM 16GB未満の環境ではバッチサイズを2～4に下げると安定します。
   - TRAIN_SAMPLE_SIZEやTEST_SAMPLE_SIZEを指定してデータ件数を減らすことで、試行錯誤が高速化できます。
   - EarlyStoppingCallbackを使うと、損失が改善しない場合に自動で学習を打ち切れます（例: callbacks=[EarlyStoppingCallback(early_stopping_patience=2)]）。

   【カスタマイズ例】
   

   training_args = TrainingArguments(
       output_dir="./results",
       per_device_train_batch_size=4,  # VRAMが少ない場合
       per_device_eval_batch_size=4,
       num_train_epochs=3,             # 精度重視でエポック数増
       evaluation_strategy="steps",
       save_steps=500,
       eval_steps=500,
       logging_steps=100,
       learning_rate=1e-4,             # 学習率を上げてみる
       fp16=True,
       report_to="none",
       load_best_model_at_end=True,
       metric_for_best_model="eval_loss"
   )
   
   # --- 超短時間で動作確認したい場合の例 ---
   training_args = TrainingArguments(
       output_dir="./results",
       per_device_train_batch_size=2,
       per_device_eval_batch_size=2,
       num_train_epochs=0.2,  # 0.2など小数もOK。全データの20%だけ学習してすぐ終了
       evaluation_strategy="steps",
       save_steps=50,
       eval_steps=50,
       logging_steps=10,
       learning_rate=5e-5,
       fp16=True,
       report_to="none",
       load_best_model_at_end=True,
       metric_for_best_model="eval_loss"
   )
   

   → 目的や環境に応じて柔軟に調整しましょう。
   特に「num_train_epochs=0.2」など小数を指定すると、全データの一部だけで素早く動作確認できます。
4. Trainerオブジェクトの作成
   

   from transformers import Trainer, EarlyStoppingCallback
   
   trainer = Trainer(
       model=model,
       args=training_args,
       train_dataset=tokenized_train,
       eval_dataset=tokenized_test,
       callbacks=[EarlyStoppingCallback(early_stopping_patience=2)]
   )

   • model：LoRAを組み込んだモデル
   • train_dataset / eval_dataset：トークナイズ済みデータ
   • callbacks：EarlyStopping（評価損失が2回改善しなければ学習打ち切り）
   Trainerは学習・検証・保存・ロギングなどを一括管理します。
5. 学習の実行
   

   trainer.train()

   • 設定した内容に従い、実際に学習を開始
   • 進捗や損失値はログとして出力され、最良モデルが自動保存されます

• 各チェックポイントディレクトリ
  checkpoint-1000/ など
  → その時点のモデル重み（pytorch_model.bin等）、トークナイザー、学習状態ファイルが保存されます。

./results/
    checkpoint-1000/
        config.json
        pytorch_model.bin
        adapter_config.json
        trainer_state.json
        training_args.bin
        tokenizer.json
        ...
    checkpoint-2000/
        ...

• ① LoRAのみ保存
  ベースモデル（LLM）は保存せず、LoRAで追加・更新されたパラメータ（adapter）のみ保存
  用途：ストレージ節約・複数LoRA重みの切り替え・研究用途など
  推論時：必ず同じベースモデルを別途用意し、LoRA重みを適用して使う必要があります。
  保存例：
  

  trainer.save_model("lora_only_dir")
  tokenizer.save_pretrained("lora_only_dir")

  推論例：
  

  from transformers import AutoModelForCausalLM
  from peft import PeftModel
  base_model = AutoModelForCausalLM.from_pretrained("google/gemma-3-1b-it")
  model = PeftModel.from_pretrained(base_model, "lora_only_dir")

  メリット：ファイルサイズが小さい／配布しやすい
  デメリット：推論時に必ずベースモデルが必要／組み合わせミスに注意
• ② ベースモデルとLoRAをマージして保存
  ベースモデルとLoRA重みを合体させて、1つの完全なモデルとして保存
  用途：配布や再利用のしやすさ重視、Hugging Face Hub等での公開など
  保存例：
  

  from peft import PeftModel
  # LoRA適用済みモデルをロード
  model = PeftModel.from_pretrained(base_model, lora_dir)
  # LoRA重みをベースモデルにマージ
  model = model.merge_and_unload()
  # 1つのモデルとして保存
  model.save_pretrained("merged_model_dir")
  tokenizer.save_pretrained("merged_model_dir")

  推論例：
  

  from transformers import AutoModelForCausalLM
  model = AutoModelForCausalLM.from_pretrained("merged_model_dir")

  メリット：そのまま推論・配布ができる／LoRAの仕組みを意識しなくてよい
  デメリット：ファイルサイズが大きい／再度LoRA微調整したい場合は元の分離状態が必要

import os
from datetime import datetime

# 保存先のベースディレクトリ名（あとで変更しやすいように定数化）
BASE_DIR = "/content/drive/MyDrive/colab/lora_finetuned_model"

# 今日の日時（例: 2024-06-09_15-30-45）
today = datetime.now().strftime('%Y-%m-%d_%H-%M-%S')

# 1. LoRAのみ（マージしない）保存
save_dir_non_merged = f"{BASE_DIR}_non_merged_{today}"
os.makedirs(save_dir_non_merged, exist_ok=True)
trainer.save_model(save_dir_non_merged)
tokenizer.save_pretrained(save_dir_non_merged)

# 2. LoRAをベースモデルにマージして保存
save_dir_merged = f"{BASE_DIR}_merged_{today}"
os.makedirs(save_dir_merged, exist_ok=True)

from peft import PeftModel
# すでにLoRA適用済みのmodelがある前提
tmp_model = model.merge_and_unload()
tmp_model.save_pretrained(save_dir_merged)
tokenizer.save_pretrained(save_dir_merged)

• ① LoRAのみ（マージしない）保存形式
  - 保存内容：LoRAで追加・更新されたパラメータ（adapter）のみ。
  - 形式：adapter_model.binやadapter_config.jsonなどが含まれるディレクトリ。
  - 推論時の使い方：
  

  from transformers import AutoModelForCausalLM, AutoTokenizer
  from peft import PeftModel
  import torch
  
  base_model_name = "google/gemma-3-1b-it"  # 保存時と同じベースモデル名
  lora_dir = "保存したLoRAディレクトリ"
  
  # ベースモデルとトークナイザーをロード
  base_model = AutoModelForCausalLM.from_pretrained(
      base_model_name,
      device_map="auto",
      torch_dtype=torch.float16,
  )
  tokenizer = AutoTokenizer.from_pretrained(base_model_name)
  tokenizer.pad_token = tokenizer.eos_token
  
  # LoRA重みを適用
  model = PeftModel.from_pretrained(base_model, lora_dir)
  model.eval()
  
  # 推論（例）
  inputs = tokenizer("質問文", return_tensors="pt").to(model.device)
  with torch.no_grad():
      outputs = model.generate(**inputs, max_new_tokens=100)
  print(tokenizer.decode(outputs[0], skip_special_tokens=True))
  

  ポイント：必ず同じベースモデルを用意し、LoRA重みを適用してから推論します。
• ② マージ保存形式
  - 保存内容：ベースモデルとLoRA重みが合体した「1つの完全なモデル」。
  - 形式：通常のHugging Face Transformersモデル（pytorch_model.binやconfig.jsonなど）。
  - 推論時の使い方：
  

  from transformers import AutoModelForCausalLM, AutoTokenizer
  import torch
  
  model_dir = "保存したマージ済みモデルのディレクトリ"
  
  model = AutoModelForCausalLM.from_pretrained(model_dir, device_map="auto", torch_dtype=torch.float16)
  tokenizer = AutoTokenizer.from_pretrained(model_dir)
  tokenizer.pad_token = tokenizer.eos_token
  
  # 推論（例）
  inputs = tokenizer("質問文", return_tensors="pt").to(model.device)
  with torch.no_grad():
      outputs = model.generate(**inputs, max_new_tokens=100)
  print(tokenizer.decode(outputs[0], skip_special_tokens=True))
  

  ポイント：マージ済みモデルは、そのまま通常のTransformersモデルとして推論できます。