UnslothでLLMファインチューニング完全ガイド2025：QLoRA、4bit量子化、2倍高速学習

Full Fine-tuning（全パラメータ更新）
+------------------------+
|   W (d x d)            |  <- 全体の重み更新
|   例: 4096 x 4096      |     = 16Mパラメータ
|   = 64MB (FP16)        |
+------------------------+

LoRA (Low-Rank Adaptation)
+------------------------+
|   W0（固定）+ B * A     |
|   W0: 4096 x 4096     |  <- 固定（更新なし）
|   B: 4096 x 16         |  <- 学習 (65Kパラメータ)
|   A: 16 x 4096         |  <- 学習 (65Kパラメータ)
|   = 0.25MB (FP16)      |     合計130Kパラメータ
+------------------------+

QLoRA (Quantized LoRA)
+------------------------+
|   W0 (4bit) + B * A   |
|   W0: 4096 x 4096     |  <- 4bit量子化 (8MB)
|   B: 4096 x 16         |  <- FP16学習
|   A: 16 x 4096         |  <- FP16学習
|   = 8.25MB 合計         |
+------------------------+

W_new = W_old + delta_W

delta_W = B * A
ここで:
  Bは d x r 行列 (d=モデル次元, r=LoRAランク)
  Aは r x d 行列
  r << d (例: r=16, d=4096)

# Full Fine-tuningパラメータ数
d = 4096
full_params = d * d  # = 16,777,216 (16.7M)

# LoRAパラメータ数
r = 16
lora_params = d * r + r * d  # = 131,072 (131K)

# 節約率
savings = 1 - (lora_params / full_params)
print(f"パラメータ節約: {savings:.2%}")  # 99.22%

# ColabでのUnslothインストール（T4 GPU基準）
# ランタイム -> ランタイムのタイプを変更 -> T4 GPU選択

# 1. Unslothインストール
!pip install "unsloth[colab-new] @ git+https://github.com/unslothai/unsloth.git"
!pip install --no-deps "xformers<0.0.27" "trl<0.9.0" peft accelerate bitsandbytes

# 2. GPU確認
import torch
print(f"GPU: {torch.cuda.get_device_name(0)}")
print(f"VRAM: {torch.cuda.get_device_properties(0).total_mem / 1024**3:.1f} GB")

# Conda環境作成
conda create -n unsloth python=3.11
conda activate unsloth

# PyTorchインストール (CUDA 12.1)
conda install pytorch torchvision torchaudio pytorch-cuda=12.1 -c pytorch -c nvidia

# Unslothインストール
pip install "unsloth[cu121] @ git+https://github.com/unslothai/unsloth.git"
pip install --no-deps trl peft accelerate bitsandbytes

# インストール確認
python -c "from unsloth import FastLanguageModel; print('Unsloth OK')"

from unsloth import FastLanguageModel
import torch

# モデルとトークナイザのロード
model, tokenizer = FastLanguageModel.from_pretrained(
    model_name="unsloth/Meta-Llama-3.1-8B-bnb-4bit",  # 4bit事前量子化モデル
    max_seq_length=2048,    # 最大シーケンス長
    dtype=None,             # 自動検出 (A100: bfloat16, その他: float16)
    load_in_4bit=True,      # 4bit量子化ロード
)

# GPUメモリ確認
gpu_stats = torch.cuda.get_device_properties(0)
start_gpu_memory = round(torch.cuda.max_memory_reserved() / 1024 / 1024 / 1024, 3)
max_memory = round(gpu_stats.total_mem / 1024 / 1024 / 1024, 3)
print(f"GPU = {gpu_stats.name}. Max memory = {max_memory} GB.")
print(f"{start_gpu_memory} GB of memory reserved.")

# LoRAアダプタ追加
model = FastLanguageModel.get_peft_model(
    model,
    r=16,                          # LoRAランク (8, 16, 32, 64)
    target_modules=[               # LoRAを適用するモジュール
        "q_proj", "k_proj", "v_proj", "o_proj",  # Attention
        "gate_proj", "up_proj", "down_proj",       # MLP
    ],
    lora_alpha=16,                 # LoRA alpha（通常rと同じ）
    lora_dropout=0,                # Unslothでは0が最適
    bias="none",                   # bias学習なし
    use_gradient_checkpointing="unsloth",  # Unsloth最適化チェックポインティング
    random_state=3407,
    use_rslora=False,
    loftq_config=None,
)

# 学習可能なパラメータ確認
def print_trainable_parameters(model):
    trainable = sum(p.numel() for p in model.parameters() if p.requires_grad)
    total = sum(p.numel() for p in model.parameters())
    print(f"学習可能: {trainable:,} / 全体: {total:,} = {trainable/total:.2%}")

print_trainable_parameters(model)
# 学習可能: 41,943,040 / 全体: 8,030,261,248 = 0.52%

# Alpacaプロンプトテンプレート
alpaca_prompt = """Below is an instruction that describes a task, paired with an input that provides further context. Write a response that appropriately completes the request.

### Instruction:
{}

### Input:
{}

### Response:
{}"""

# データセットフォーマッティング関数
EOS_TOKEN = tokenizer.eos_token

def formatting_prompts_func(examples):
    instructions = examples["instruction"]
    inputs = examples["input"]
    outputs = examples["output"]
    texts = []
    for instruction, input_text, output in zip(instructions, inputs, outputs):
        text = alpaca_prompt.format(instruction, input_text, output) + EOS_TOKEN
        texts.append(text)
    return {"text": texts}

from datasets import load_dataset

# KoAlpacaデータセットのロード
dataset = load_dataset("beomi/KoAlpaca-v1.1a", split="train")

# フォーマット変換
def format_koalpaca(examples):
    texts = []
    for instruction, output in zip(examples["instruction"], examples["output"]):
        text = alpaca_prompt.format(instruction, "", output) + EOS_TOKEN
        texts.append(text)
    return {"text": texts}

dataset = dataset.map(format_koalpaca, batched=True)

# OpenAI Messagesフォーマット（Llama 3 chat template使用）
def format_openai_messages(examples):
    texts = []
    for messages in examples["messages"]:
        text = tokenizer.apply_chat_template(
            messages,
            tokenize=False,
            add_generation_prompt=False,
        )
        texts.append(text)
    return {"text": texts}

from trl import SFTTrainer
from transformers import TrainingArguments
from unsloth import is_bfloat16_supported

trainer = SFTTrainer(
    model=model,
    tokenizer=tokenizer,
    train_dataset=dataset,
    dataset_text_field="text",
    max_seq_length=2048,
    dataset_num_proc=2,
    packing=False,
    args=TrainingArguments(
        # === 基本設定 ===
        output_dir="./outputs",
        num_train_epochs=3,

        # === バッチ & メモリ ===
        per_device_train_batch_size=2,
        gradient_accumulation_steps=4,  # 有効バッチ = 2 * 4 = 8

        # === 学習率 ===
        learning_rate=2e-4,             # QLoRA推奨学習率
        lr_scheduler_type="cosine",
        warmup_steps=5,

        # === 精度 ===
        fp16=not is_bfloat16_supported(),
        bf16=is_bfloat16_supported(),

        # === ロギング ===
        logging_steps=1,
        logging_dir="./logs",
        report_to="wandb",

        # === 保存 ===
        save_strategy="steps",
        save_steps=100,
        save_total_limit=3,

        # === 最適化 ===
        optim="adamw_8bit",
        weight_decay=0.01,
        max_grad_norm=0.3,
        seed=3407,
    ),
)

# 学習開始
trainer_stats = trainer.train()

# 学習結果出力
print(f"学習時間: {trainer_stats.metrics['train_runtime']:.2f}秒")
print(f"最終Loss: {trainer_stats.metrics['train_loss']:.4f}")

# GPUメモリ使用量確認
used_memory = round(torch.cuda.max_memory_reserved() / 1024 / 1024 / 1024, 3)
print(f"最大VRAM使用量: {used_memory} GB")

# Unsloth最適化Gradient Checkpointing
model = FastLanguageModel.get_peft_model(
    model,
    r=16,
    target_modules=["q_proj", "k_proj", "v_proj", "o_proj",
                     "gate_proj", "up_proj", "down_proj"],
    use_gradient_checkpointing="unsloth",  # 重要！30% VRAM節約
)

# Gradient Checkpointingオプション:
# "unsloth": Unsloth最適化版（より高速でメモリ効率的）
# True: 標準PyTorch gradient checkpointing
# False: 無効（最速だがメモリ最大使用）

# 短いシーケンスを1つにまとめてGPU活用率向上
trainer = SFTTrainer(
    model=model,
    train_dataset=dataset,
    packing=True,           # シーケンスパッキング有効化
    max_seq_length=2048,    # パッキング後の全体長
)

# パッキング効果:
# パッキングOFF: [トークンPAD PAD PAD] [トークンPAD PAD PAD]
# パッキングON:  [トークンSEPトークントークン] -> GPU活用率向上

# LoRAアダプタのみ保存（小さいサイズ）
model.save_pretrained("lora_adapter")
tokenizer.save_pretrained("lora_adapter")

# 保存ファイル確認
import os
for f in os.listdir("lora_adapter"):
    size = os.path.getsize(f"lora_adapter/{f}") / 1024 / 1024
    print(f"  {f}: {size:.1f} MB")

# LoRAアダプタをベースモデルとマージ
merged_model = model.merge_and_unload()

# マージされたモデルを保存
merged_model.save_pretrained("merged_model")
tokenizer.save_pretrained("merged_model")

# Unslothの内蔵GGUF変換機能
# 様々な量子化レベルに対応

# Q4_K_M: 最も一般的（品質/サイズのバランス）
model.save_pretrained_gguf(
    "model_gguf",
    tokenizer,
    quantization_method="q4_k_m",
)

# Q5_K_M: より高品質
model.save_pretrained_gguf(
    "model_q5",
    tokenizer,
    quantization_method="q5_k_m",
)

# Q8_0: 最高品質（サイズ大）
model.save_pretrained_gguf(
    "model_q8",
    tokenizer,
    quantization_method="q8_0",
)

# モデルをHugging Face Hubにアップロード

# LoRAアダプタのみアップロード
model.push_to_hub(
    "my-org/llama3-8b-korean-lora",
    token="hf_xxxxx",
    private=True,
)
tokenizer.push_to_hub(
    "my-org/llama3-8b-korean-lora",
    token="hf_xxxxx",
    private=True,
)

# GGUFファイルアップロード
model.push_to_hub_gguf(
    "my-org/llama3-8b-korean-gguf",
    tokenizer,
    quantization_method="q4_k_m",
    token="hf_xxxxx",
)

# 推論モードに切り替え
FastLanguageModel.for_inference(model)

# 単一プロンプト推論
def generate_response(instruction, input_text=""):
    prompt = alpaca_prompt.format(instruction, input_text, "")
    inputs = tokenizer([prompt], return_tensors="pt").to("cuda")

    outputs = model.generate(
        **inputs,
        max_new_tokens=512,
        temperature=0.7,
        top_p=0.9,
        repetition_penalty=1.15,
        do_sample=True,
    )

    response = tokenizer.batch_decode(outputs)[0]
    response = response.split("### Response:\n")[-1]
    response = response.replace(tokenizer.eos_token, "").strip()
    return response

# テスト
test_questions = [
    "韓国の伝統的な祝日について説明してください。",
    "Pythonでデコレータの動作原理を説明してください。",
    "健康的な食習慣のためのアドバイスを教えてください。",
]

for q in test_questions:
    print(f"Q: {q}")
    print(f"A: {generate_response(q)}")
    print("-" * 80)

# 生成パラメータ別の効果
generation_configs = {
    "正確な回答 (factual)": {
        "temperature": 0.1,
        "top_p": 0.9,
        "repetition_penalty": 1.0,
    },
    "創造的な回答 (creative)": {
        "temperature": 0.8,
        "top_p": 0.95,
        "repetition_penalty": 1.15,
    },
    "バランスの取れた回答 (balanced)": {
        "temperature": 0.5,
        "top_p": 0.9,
        "repetition_penalty": 1.1,
    },
}

# lm-eval-harnessでベンチマーク評価
pip install lm-eval

lm_eval --model hf \
    --model_args pretrained=./merged_model \
    --tasks kobest_boolq,kobest_copa,kobest_hellaswag,kobest_sentineg,kobest_wic \
    --batch_size 4 \
    --output_path ./eval_results

# deepspeed_config.json
"""
{
    "zero_optimization": {
        "stage": 2,
        "offload_optimizer": {
            "device": "cpu",
            "pin_memory": true
        },
        "allgather_partitions": true,
        "reduce_scatter": true
    },
    "bf16": {
        "enabled": true
    },
    "train_batch_size": "auto",
    "train_micro_batch_size_per_gpu": "auto"
}
"""

# 実行
# deepspeed --num_gpus 4 train.py --deepspeed deepspeed_config.json

from trl import DPOTrainer, DPOConfig
from unsloth import FastLanguageModel, PatchDPOTrainer

# DPOパッチ適用
PatchDPOTrainer()

# DPOデータセット準備
dpo_dataset = load_dataset("argilla/ultrafeedback-binarized-preferences", split="train")

# DPO Trainer設定
dpo_trainer = DPOTrainer(
    model=model,
    ref_model=None,           # Unslothでは None（自動処理）
    args=DPOConfig(
        output_dir="./dpo_output",
        per_device_train_batch_size=2,
        gradient_accumulation_steps=4,
        learning_rate=5e-7,       # DPOは低い学習率
        num_train_epochs=1,
        beta=0.1,                 # DPO beta（KL divergence重み）
        fp16=not is_bfloat16_supported(),
        bf16=is_bfloat16_supported(),
        logging_steps=1,
    ),
    train_dataset=dpo_dataset,
    tokenizer=tokenizer,
)

dpo_trainer.train()

# ドメイン特化テキストでのContinued Pre-training
from trl import SFTTrainer

domain_dataset = load_dataset("my-org/medical-korean-corpus", split="train")

trainer = SFTTrainer(
    model=model,
    tokenizer=tokenizer,
    train_dataset=domain_dataset,
    dataset_text_field="text",
    max_seq_length=4096,     # 長いドキュメント
    packing=True,            # 効率性のためパッキング使用
    args=TrainingArguments(
        output_dir="./cpt_output",
        learning_rate=2e-5,  # 非常に低い学習率
        num_train_epochs=1,  # 1 epochで十分
        per_device_train_batch_size=1,
        gradient_accumulation_steps=8,
        optim="adamw_8bit",
        warmup_ratio=0.1,
    ),
)

trainer.train()

# 症状: CUDA out of memory
# 解決法の順序:
# 1. batch_sizeを減らす
per_device_train_batch_size = 1  # 最小値

# 2. gradient_accumulation_stepsを増やす
gradient_accumulation_steps = 8

# 3. max_seq_lengthを減らす
max_seq_length = 1024  # 2048 -> 1024

# 4. LoRA rankを減らす
r = 8  # 16 -> 8

# 5. gradient checkpointingを確認
use_gradient_checkpointing = "unsloth"

# 6. キャッシュクリア
torch.cuda.empty_cache()
import gc
gc.collect()

# 症状: lossがNaNに発散
# 原因: 学習率が高すぎるかデータの問題

# 解決法:
# 1. 学習率を下げる
learning_rate = 1e-5  # 2e-4 -> 1e-5

# 2. max_grad_normを設定
max_grad_norm = 0.3  # gradient clipping

# 3. データ検証
def check_data_issues(dataset, tokenizer):
    """データの問題を検査"""
    issues = []
    for i, item in enumerate(dataset):
        text = item["text"]
        if not text.strip():
            issues.append(f"[{i}] 空テキスト")
        tokens = tokenizer.encode(text)
        if len(tokens) > 4096:
            issues.append(f"[{i}] テキストが長すぎる: {len(tokens)} tokens")
    return issues

# 症状: ファインチューニング後に既存知識が消える
# 解決法:

# 1. 低い学習率を使用
learning_rate = 5e-5

# 2. 少ないepoch (1-3)
num_train_epochs = 1

# 3. データに一般知識を混合
# オリジナルデータ 80% + 一般知識データ 20%

# 4. LoRA rankを下げる（変更幅を制限）
r = 8

# 5. 正則化を強化
weight_decay = 0.1