lora-qlora-recipes

LoRA & QLoRA レシピ

このスキルは、ルーティングの判断がすでに済んでいることを前提としています — データの形が選好ペアや検証可能な報酬シグナルではなくデモンストレーション（SFT）であるため、finetuning-method-selection がすでにここを指し示しているはずです。以下に示すのは、アダプター自体を構成するための現在のベストプラクティスレシピです。どのモジュールを対象にするか、ランクとアルファをどう設定するか、どの学習率を使うか、そして QLoRA が本当に余地を生むのはいつで、単にリスクを増やすだけなのはいつか、です。データセットの準備と品質チェックは別の関心事です — dataset-curation を参照してください。

入力: ルーティングの判断（LoRA/QLoRA による SFT）と、対象のサイズクラス。 出力形式: 検証済みのアダプター設定 — 自由形式の助言ではなく、以下の kwarg の値 — であり、llm-finetuning-training-engineer が実行可能なスクリプトを生成する際に直接消費します。

リファレンスレシピ

リファレンスレシピは「LoRA Without Regret」（Thinking Machines/Schulman, 2025-09）であり、現在では LoRA/QLoRA SFT の定着した慣例となっています。

対象モジュール

アテンションだけでなく、すべての linear モジュールを対象にします:

target_modules = [
    "q_proj", "k_proj", "v_proj", "o_proj",   # attention
    "gate_proj", "up_proj", "down_proj",      # MLP — matters most
]

MLP 層（gate_proj、up_proj、down_proj）が最も重要です — アテンションのみを対象にするのは、より古く弱い慣例でした。メモリを節約するためにモジュールを削るのは、以下の失敗モードであり、有効な最適化ではありません。

アルファと学習率

• lora_alpha = 2 * r が定着した慣例です（NeurIPS 2025 の「intruder dimensions」の結果）。アルファをランクとは独立に手動調整しないでください — 毎回ランクから導出します。
• LoRA の学習率 ≈ 同等のフルファインチューニング学習率の 10 倍。 特に QLoRA では、2e-4 が標準的な出発点です。完全なハイパーパラメータ表と実例: references/hyperparameters.md。

タスク別のランク

ランクはタスクに応じて形が決まるものであり、単一のグローバルなデフォルトではありません:

タスク	ランク
RL（GRPO/RLVR アダプター）	1～32
一般的なデフォルト	16～32
大規模な SFT	最大 ~256

高いランクが自動的に優れているわけではありません — 汎化する能力を高めるのと同じ速さで、記憶する能力も高めます。タスクに合致する行から始め、下位のランクがホールドアウト評価で測定可能に過小適合した場合にのみ上の行へ移ってください。デフォルトのヘッジとして移すのではありません。

実効バッチサイズ

実効バッチサイズは 32 未満に保ってください。このレシピはそのスケールで検証されています — 実効バッチをこれより大きくするのは未検証の外挿であり、無償のスループット向上ではありません。

Unsloth のデフォルト

Unsloth は、このプラグインがデフォルトの高速パスとして想定するリファレンス実装です — ただし assistant_only_loss=True を用いた messages 形式の対話型 SFT は例外で、Unsloth 2026.7.x のコンパイル済みトレーナーには messages 形式のパスがまったく存在せず、その組み合わせではプレーン TRL への逃げ道（references/unsloth-trl-mapping.md）がデフォルトであり、まれなリグレッション時のフォールバックではありません。そのすぐに使えるデフォルトと、それぞれがそのように設定されている理由:

• lora_dropout=0 — 最適化されたカーネルパスは dropout がゼロであることを前提としています。非ゼロの値を設定すると、フューズドカーネルの高速化を放棄することになります。
• bias="none" — バイアス項は、このランク範囲では無視できるほどの品質向上のためにアダプターのパラメータを増やします。
• use_gradient_checkpointing="unsloth" — バニラの HF チェックポイントではなく、Unsloth のチェックポイント変種です。チェックポイントなしと比べておよそ 30% の VRAM を節約します。
• optim="adamw_8bit" — 8 ビット AdamW は、LoRA/QLoRA アダプターのスケールでは無視できるほどの品質への影響で、オプティマイザ状態のメモリを削減します。
• random_state を固定 — 実行間の再現性のために LoRA の初期化を固定します。他のシードと同様に扱い、調整可能な値とは見なしません。

これらは get_peft_model 呼び出しで一緒に現れます:

model = FastLanguageModel.get_peft_model(
    model,
    r=32,
    target_modules=target_modules,
    lora_alpha=64,               # 2 * r
    lora_dropout=0,
    bias="none",
    use_gradient_checkpointing="unsloth",
    random_state=3407,
)

正確な kwarg 名とそのプレーン TRL/PEFT 相当、および SFTConfig を含む完全な実例設定: references/unsloth-trl-mapping.md と references/hyperparameters.md。

LoRA vs QLoRA vs フル FT

状況	デフォルトの選択
デモンストレーションで振る舞いを適応させる	LoRA
ターゲットランクでベースモデルが bf16 に収まらない	QLoRA
密な新しいドメイン知識を注入する	フル FT (finetuning-method-selection を参照)
どれを選ぶか迷ったら	LoRA — メモリが逼迫した場合にのみ QLoRA にアップグレード

• QLoRA = NF4 で量子化された凍結ベース重み + BF16 アダプター。これにより 65B クラスの モデルが 48GB でトレーニング可能になります — メモリ削減の決め手は量子化されたベースであり、 アダプター自体ではありません。
• フルファインチューニングはデフォルトではありません。 これは、モデルが重みレベルで何を知っているかを 変えることが目的の密な知識注入のために取っておいてください。 振る舞いの適応ではありません。このスキルの範囲内の それ以外のすべてについては、LoRA または QLoRA が 出発点の前提です。
• DGX Spark では、同等の bf16 LoRA 実行が 先に OOM する前に QLoRA が OOM になることがあります — QLoRA の定常状態のフットプリントはより小さいにもかかわらず — bitsandbytes の逆量子化バッファは、ロード中に 急増する一時的な CUDA 側の割り当てです。 QLoRA の OOM は、モデルが収まらない証明にはなりません。 dgx-spark-ops プラグインの spark-memory-thermal-ops スキルが OOM 修復のはしご全体をカバーしています (次に試すのは bf16 LoRA であり、QLoRA をさらに 縮小することではありません)。

失敗モード

• 非 BF16 GPU での fp16 発散。 堅牢な BF16 サポートを持たないハードウェアで fp16 で トレーニングすることは、損失スパイクと サイレントな発散の既知の原因です。ハードウェアが サポートする場合は必ず bf16=True を強制してください。 fp16 が同等であるかのようにフォールバックしないでください。 dtype を選ぶ前にハードウェアサポートを確認してください:

  python -c "import torch; print(torch.cuda.is_bf16_supported())"
  

• 小さいデータセットでランクが高すぎると過学習します。 「大規模 SFT」向けに選ばれたランク（最大 ~256）を、 その背後にスケールがないデータセットで使うと、 汎化せずに記憶してしまいます。ランクは利用可能な 最大値ではなく、上記の「タスク別ランク」表に 合わせてください。

• メモリを節約するためにターゲットモジュールを削除すると、 ごくわずかな節約のために品質が犠牲になります。 gate_proj/up_proj/down_proj のアダプター パラメータは、モデル全体のサイズのごく一部です — これらを削ってもメモリはほとんど変わりませんが、 品質は測定可能なほど損なわれます。メモリが厳しい場合は、 ターゲットモジュールを削る前に QLoRA に移行するか、 ランク/バッチ/パック長を減らしてください。

これら 3 つの失敗モードは共通のパターンを 共有しています: それらはトレーニングループの バグ（損失スパイク、プラトー、記憶）のように 見えますが、実際には上記の参照レシピと矛盾する 設定の選択です。トレーニングループ自体を デバッグする前に、このスキルに対して設定を 確認してください。

参照

• references/hyperparameters.md — タスクタイプ別の 完全なランク/アルファ/LR 表、rsLoRA の注記、 バッチ/パッキングの相互作用、および完全に動作する Unsloth 設定ブロック。
• references/unsloth-trl-mapping.md — すべての Unsloth kwarg を対応する TRL/PEFT にマッピング、 現在の TRL API の注記、およびプレーンな TRL に 戻すタイミングに関するエスケープハッチのルール。

関連スキル: finetuning-method-selection は ここにルーティングします。dataset-curation は このスキルが扱わないデータ側をカバーします。 llm-finetuning-training-engineer は、このスキルが 生成する設定の下流のコンシューマーです。