プロンプト活用

【LLM全般】LoRA/QLoRAで始めるファインチューニング入門：実践ガイドとよくあるエラー解決

· 17分で読めます · 1 閲覧

問題の概要：ファインチューニングのハードルとよくあるエラー

大規模言語モデル（LLM）を自社データや特定タスクに適応させる「ファインチューニング」は、AI活用の重要なステップです。しかし、フルファインチューニングは膨大な計算リソースと時間を要し、多くの開発者にとって現実的ではありません。また、以下のような具体的なエラーに直面することがよくあります。

  • RuntimeError: CUDA out of memory. – GPUメモリ不足エラー
  • ValueError: You can't train a model that has been loaded in 8-bit or 4-bit precision. – 量子化モデルの学習エラー
  • KeyError: 'q_proj' – モデルアーキテクチャの不一致エラー
  • 学習は進むが、生成結果が無意味（ナンセンス）になる
  • 学習損失（loss）が全く減少しない、または発散する

これらの課題を解決し、限られたリソースで効率的にファインチューニングを行うための技術が、LoRA（Low-Rank Adaptation）とその発展形であるQLoRAです。本記事では、これらの実践手法とトラブルシューティングを詳しく解説します。

原因の解説：なぜエラーが発生するのか？

上記のエラーは、主に以下の3つの原因から発生します。

1. リソース制約とモデルサイズのミスマッチ

数十億パラメータを持つ最新LLMをフル学習しようとすると、大量のGPUメモリが必要です。例えば、7BパラメータモデルのFP16学習には約14GB以上のGPUメモリが常時必要で、勾配やオプティマイザの状態を考慮するとさらに増加します。これがCUDA out of memoryエラーの主因です。

2. 量子化と学習プロセスの互換性問題

メモリ節約のためモデルを4bitや8bitに量子化（変換）してロードした後、そのまま学習を試みるとエラーが発生します。量子化は推論用の最適化であり、学習時には特定の処理（逆量子化など）が必要です。QLoRAはこの問題を巧妙に解決します。

3. モデルアーキテクチャの理解不足

LoRAを適用するターゲットモジュール（q_proj, v_projなど）はモデルによって異なります。誤ったモジュール名を指定するとKeyErrorが発生します。また、学習率やランクなどのハイパーパラメータ設定が不適切だと、学習が収束しません。

解決方法：LoRA/QLoRAによる効率的なファインチューニング

ここからは、Hugging Faceのtransformers、peft、bitsandbytesライブラリを使用した実践的な手順を説明します。

ステップ1: 環境構築とライブラリのインストール

まず、必要なパッケージをインストールします。バージョンの互換性に注意してください。

# 必要なライブラリのインストール（例）
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118
pip install transformers accelerate peft bitsandbytes datasets trl

ステップ2: モデルとトークナイザーの読み込み（QLoRAの場合）

QLoRAを使用すると、4bit量子化モデルをロードしながら学習可能にします。BitsAndBytesConfigの設定が鍵です。

from transformers import AutoModelForCausalLM, AutoTokenizer, BitsAndBytesConfig
import torch

# 4bit量子化の設定
bnb_config = BitsAndBytesConfig(
    load_in_4bit=True,
    bnb_4bit_quant_type="nf4", # 正規化浮動小数点4bit
    bnb_4bit_compute_dtype=torch.float16, # 計算はfloat16で
    bnb_4bit_use_double_quant=True # 二重量子化で精度向上
)

model_name = "elyza/ELYZA-japanese-Llama-2-7b"
tokenizer = AutoTokenizer.from_pretrained(model_name)
# トークナイザーのパディングトークン設定（ない場合）
if tokenizer.pad_token is None:
    tokenizer.pad_token = tokenizer.eos_token

# 量子化してモデルをロード
model = AutoModelForCausalLM.from_pretrained(
    model_name,
    quantization_config=bnb_config,
    device_map="auto", # GPUに自動配置
    trust_remote_code=True # 必要に応じて
)

ステップ3: LoRAの設定とモデル準備

peftライブラリを使ってLoRAを設定します。ターゲットモジュールはモデルアーキテクチャにより変更が必要です。

from peft import LoraConfig, get_peft_model, TaskType

# LoRA設定
lora_config = LoraConfig(
    task_type=TaskType.CAUSAL_LM, # 因果言語モデリング
    r=8, # LoRAのランク（低ランク行列の次元）。小さいほど軽量。
    lora_alpha=32, # スケーリングパラメータ
    target_modules=["q_proj", "v_proj"], # 対象モジュール。Llama系はこれ。
    lora_dropout=0.05, # ドロップアウト率
    bias="none" # バイアスは学習しない
)

# モデルにLoRA設定を適用
model = get_peft_model(model, lora_config)
model.print_trainable_parameters() # 学習可能パラメータのみ表示
# 例: trainable params: 4,194,304 || all params: 3,540,389,888 || trainable%: 0.1185%

【重要】target_modulesの特定方法
モデルによって適切なモジュール名が異なります。以下のコマンドで確認できます。

# モデルのモジュール名をリスト表示
for name, module in model.named_modules():
    if "proj" in name or "dense" in name: # 候補をフィルタリング
        print(name)
# 例: model.layers.0.self_attn.q_proj, model.layers.0.self_attn.v_proj ...

ステップ4: データセットの準備と前処理

指示チューニング形式のデータセットを準備し、トークナイズします。

from datasets import Dataset

# サンプルデータ（例：指示と応答のペア）
sample_data = [
    {"instruction": "日本の首都は？", "output": "日本の首都は東京です。"},
    {"instruction": "PythonでHello Worldを出力するには？", "output": "print('Hello World') と書きます。"}
]
dataset = Dataset.from_list(sample_data)

def preprocess_function(examples):
    # 指示と応答を結合してプロンプトを作成
    prompts = [f"以下はタスクを説明する指示です。要求を適切に満たす応答を書いてください。nn### 指示:n{ins}nn### 応答:n{out}" for ins, out in zip(examples['instruction'], examples['output'])]
    # トークナイズ
    model_inputs = tokenizer(prompts, max_length=512, truncation=True, padding="max_length")
    # ラベルは応答部分のみ（教師付き学習のため）
    labels = model_inputs["input_ids"].copy()
    model_inputs["labels"] = labels
    return model_inputs

tokenized_dataset = dataset.map(preprocess_function, batched=True)

ステップ5: 学習の実行

Trainer APIを使用して学習を実行します。

from transformers import TrainingArguments, Trainer

training_args = TrainingArguments(
    output_dir="./lora-finetuned-model",
    per_device_train_batch_size=4, # GPUメモリに合わせて調整
    gradient_accumulation_steps=4,  # 実質的なバッチサイズ = 4 * 4 = 16
    num_train_epochs=3,
    learning_rate=2e-4, # LoRAでは少し高めの学習率が良い
    fp16=True, # 混合精度学習
    logging_steps=10,
    save_steps=100,
    evaluation_strategy="no",
    save_total_limit=2,
    push_to_hub=False, # Hugging Face Hubに上げる場合はTrue
)

trainer = Trainer(
    model=model,
    args=training_args,
    train_dataset=tokenized_dataset,
    data_collator=lambda data: {'input_ids': torch.stack([d['input_ids'] for d in data]),
                                'attention_mask': torch.stack([d['attention_mask'] for d in data]),
                                'labels': torch.stack([d['labels'] for d in data])}
)

trainer.train()

ステップ6: モデルの保存と読み込み

学習したLoRAアダプターのみを軽量ファイルとして保存します。

# LoRAアダプターの保存
model.save_pretrained("./my-lora-adapter")

# 推論時の読み込み例
from peft import PeftModel

# ベースモデルを再度読み込み（量子化推論用）
base_model = AutoModelForCausalLM.from_pretrained(
    model_name,
    quantization_config=bnb_config,
    device_map="auto"
)
# LoRAアダプターをマージ
model_for_inference = PeftModel.from_pretrained(base_model, "./my-lora-adapter")

コード例・コマンド例：主要エラーへの対処法

エラー1: CUDA out of memory.

対処法: バッチサイズを減らし、勾配累積で補う。

# TrainingArgumentsの設定変更例
training_args = TrainingArguments(
    per_device_train_batch_size=2, # 1 or 2まで下げる
    gradient_accumulation_steps=8, # 2 * 8 = 実バッチサイズ16
    gradient_checkpointing=True, # メモリ節約のため勾配チェックポイニングを有効化
    # ...
)

エラー2: KeyError: 'q_proj'

対処法: モデルに合ったターゲットモジュールを指定。

# モデルタイプ別のtarget_modules例（一例）
# Llama, Mistral系: ["q_proj", "v_proj"]
# GPT-2系: ["c_attn"]
# BLOOM系: ["query_key_value"]
lora_config = LoraConfig(
    target_modules=["q_proj", "v_proj"], # ここを変更
    # ...
)

学習が収束しない場合

対処法: 学習率、ランク(r)、データ品質を見直す。

# ハイパーパラメータ調整例
lora_config = LoraConfig(
    r=16, # 8から16に増やして表現力を向上
    lora_alpha=64, # alphaも比例して増やす（rの2〜4倍が目安）
    # ...
)
training_args = TrainingArguments(
    learning_rate=1e-4, # 2e-4から1e-4に下げて安定化
    # ...
)

まとめ・補足情報

LoRAとQLoRAは、限られた計算リソースでLLMをファインチューニングするための強力な技術です。本ガイドで紹介した手順とトラブルシューティングを参考に、以下のポイントを押さえて実践してください。

  1. リソースに応じた手法選択: GPUメモリが極めて少ない場合はQLoRA（4bit）、ある程度ある場合はLoRA（16bit）を検討します。
  2. データの質と量: 数百〜数千の高品質な例でも、適切なプロンプト形式で学習させれば効果が得られます。データセットの構築に時間をかけましょう。
  3. 段階的なアプローチ: まずは小さなデータセットと少ないエポック数で試行し、学習曲線（lossの減少）を確認してから本番学習に進みます。
  4. 最新ライブラリの確認: peft、bitsandbytes、transformersは活発に開発されています。互換性問題が起きた場合はバージョンを固定したり、ドキュメントを確認したりしましょう。

ファインチューニングは「試行錯誤」のプロセスです。本記事を出発点として、独自のデータでモデルをカスタマイズする実践的なAI開発の第一歩を踏み出してください。

この記事は役に立ちましたか？