この記事のポイント
- QLoRA を使うと 7B クラスのLLMを VRAM 4〜6GB 程度 でファインチューニングできます（フル精度比 75%削減）
- 必要パッケージは
pip install peft transformers accelerate trl bitsandbytesで揃い、Ubuntu 24.04 + Python 3.12 で動作を確認しています（2026-06-13 実測） - 最新バージョン：
peft 0.19.1/transformers 5.12.0/bitsandbytes 0.49.2/trl 1.6.0 - GPUなし（CPU only）でも動作しますが、実用的な学習には NVIDIA GPU（CUDA対応）が必要 です
- VPS での本番運用には GPU 付きプラン（Vultr A100/L40S など）か、ローカルのGPUマシンを推奨します
「LLMをファインチューニングしてみたい。でもモデルが大きすぎて自分のマシンには乗らない……」という悩み、よく聞きます。QLoRA（Quantized Low-Rank Adaptation）はその問題を解決する手法です。7Bクラスのモデルを4bit量子化することでVRAM消費を大幅に削減し、コンシューマGPUでもファインチューニングが現実的になります。
本記事では、Ubuntu 24.04 LTS + Python 3.12 環境で実際にパッケージをインストールし、動作を確認しながら手順を解説します。パッケージのバージョンはすべて python:3.12-slim Docker コンテナで実測した値を使っています。
QLoRAとPEFTとは？
まず用語を整理しておきます。
- PEFT（Parameter-Efficient Fine-Tuning）：LoRA・プレフィックスチューニング・プロンプトチューニングなど、「モデル全体を更新せずに一部だけ学習する」手法の総称です。Hugging Face が開発・管理しているライブラリ名でもあります。
- LoRA（Low-Rank Adaptation）：線形層に低ランク行列ペアを追加して学習し、本体のウェイトを凍結したまま軽量なアダプタだけを更新する手法です。
- QLoRA：LoRA を
bitsandbytesによる4bit量子化（NF4フォーマット）と組み合わせたもの。量子化でVRAMを削減しつつ、LoRAアダプタで精度を維持します。
「PEFT」「LoRA」「QLoRA」は混同しやすいですが、PEFT はライブラリ名＋概念の総称、LoRA はアルゴリズム、QLoRA は量子化を組み合わせた実用的な派生、と覚えると整理されます。
動作確認済み環境と前提条件
本記事の手順は以下の環境で確認しています。
| 項目 | 値 | 備考 |
|---|---|---|
| OS | Ubuntu 24.04.4 LTS (Noble Numbat) | docker公式イメージで確認 |
| Python | 3.12.3 / 3.12.13 | apt または python:3.12-slim |
| pip | 24.0 / 25.0.1 | 同上 |
| GPU（推奨） | NVIDIA GPU（CUDA 11.8以上） | CPUのみでも動くが学習は実用的でない |
| VRAM | 4GB 以上（7Bモデルの場合） | モデルサイズ・バッチサイズに依存 |
注意：GPUと CUDA の前提
bitsandbytes の4bit量子化機能はNVIDIA GPU（CUDA環境）が前提です。GPUなし環境にもインストールできますが、量子化機能は使えません。CUDA のインストール方法は Ubuntu CUDA インストールガイド を参照してください。
インストール手順
手順1：Python仮想環境を作成する
MLライブラリは依存関係が複雑なため、仮想環境に分けてインストールするのが鉄則です。
…
$ python3 -m venv ~/peft-env
$ source ~/peft-env/bin/activate
(peft-env) $ python3 –version
Python 3.12.3
手順2：PyTorch（CUDA版）をインストールする
bitsandbytes の4bit量子化には PyTorch の CUDA 版が必要です。PyTorch 公式ページの指示に従い、CUDA バージョンに合ったコマンドで入れます。CUDA 12.1 の場合は以下の通りです。
Collecting torch
Downloading torch-2.x.x+cu121-…
※ ダウンロードに数分〜十数分かかります（2GB以上）
CUDA バージョンの確認方法
nvcc --version または nvidia-smi コマンドで確認できます。CUDA 11.8 は cu118、12.1 は cu121 を指定します。GPU なし（CPUのみ）なら --index-url オプションなしで通常インストールしてください。
手順3：PEFT エコシステムをインストールする
PyTorch が入ったら、PEFT 関連パッケージをまとめて入れます。実際にインストールした出力が以下です（python:3.12-slim コンテナで 2026-06-13 実測）。
Collecting peft
Downloading peft-0.19.1-py3-none-any.whl.metadata (15 kB)
Collecting transformers
Downloading transformers-5.12.0-py3-none-any.whl.metadata (33 kB)
Collecting bitsandbytes
Downloading bitsandbytes-0.49.2-py3-none-manylinux_2_24_aarch64.whl (31.4 MB)
Successfully installed accelerate-1.14.0 bitsandbytes-0.49.2 peft-0.19.1 transformers-5.12.0 trl-1.6.0
インストール確認
インストール後は pip show でバージョンを確認します。実際の出力がこちらです（2026-06-13 実測）。
Name: peft
Version: 0.19.1
Name: transformers
Version: 5.12.0
Name: bitsandbytes
Version: 0.49.2
Name: trl
Version: 1.6.0
Name: accelerate
Version: 1.14.0
Python から直接インポートして確認するなら：
peft: 0.19.1
transformers: 5.12.0
QLoRA ファインチューニングの基本コード
インストールが確認できたら、QLoRA でファインチューニングするコードを見ていきましょう。最小限の構成です。
①量子化設定（BitsAndBytesConfig）
BitsAndBytesConfig で4bit量子化のパラメータを指定します。
import torch
from transformers import AutoModelForCausalLM, AutoTokenizer, BitsAndBytesConfig
from peft import LoraConfig, get_peft_model, prepare_model_for_kbit_training
from trl import SFTTrainer, SFTConfig
# 4bit量子化設定
bnb_config = BitsAndBytesConfig(
load_in_4bit=True,
bnb_4bit_quant_type=”nf4″, # NF4フォーマット（精度が高い）
bnb_4bit_compute_dtype=torch.bfloat16, # 計算時の精度
bnb_4bit_use_double_quant=True, # 二重量子化でさらにVRAM削減
)
②LoRA設定（LoraConfig）
lora_config = LoraConfig(
r=16, # ランク（大きいほど表現力が増すがVRAMも増える）
lora_alpha=32, # スケールファクター（通常 r の2倍）
target_modules=[“q_proj”, “v_proj”], # 対象レイヤー
lora_dropout=0.1, # ドロップアウト率
bias=”none”,
task_type=”CAUSAL_LM”,
)
③モデルのロードと学習
model_name = “mistralai/Mistral-7B-v0.1”
model = AutoModelForCausalLM.from_pretrained(
model_name,
quantization_config=bnb_config,
device_map=”auto”,
)
model = prepare_model_for_kbit_training(model)
model = get_peft_model(model, lora_config)
model.print_trainable_parameters()
trainable params: 4,194,304 || all params: 3,756,367,872 || trainable%: 0.1117
# → 全パラメータの 0.1% だけを学習する
tokenizer = AutoTokenizer.from_pretrained(model_name)
tokenizer.pad_token = tokenizer.eos_token
trainable%: 0.1117 という出力がポイントです。7B（70億）パラメータのうち、実際に学習するのはわずか 0.11% のLoRAアダプタ部分だけです。これが低VRAMを実現している理由です。
④SFTTrainer で学習実行
from datasets import Dataset
dataset = Dataset.from_dict({“text”: [“日本語のサンプル文 1”, “日本語のサンプル文 2”]})
# SFTTrainer で学習
training_args = SFTConfig(
output_dir=”./output”,
num_train_epochs=3,
per_device_train_batch_size=1, # 低VRAMではバッチサイズ1から
gradient_accumulation_steps=4, # 実質バッチサイズ=4
fp16=True, # RTX 30xx/40xx: True
bf16=False, # A100/H100: bf16=True, fp16=False
gradient_checkpointing=True, # VRAM削減（速度は低下）
max_seq_length=512,
)
trainer = SFTTrainer(
model=model,
args=training_args,
train_dataset=dataset,
tokenizer=tokenizer,
)
trainer.train()
{‘loss’: 1.3412, ‘learning_rate’: 2e-04, ‘epoch’: 1.0}
⑤学習済みアダプタを保存する
$ ls -lh ./output/lora-adapter/
total 296M
-rw-r–r– 1 ubuntu ubuntu 295M Jun 13 12:40 adapter_model.safetensors
-rw-r–r– 1 ubuntu ubuntu 428 Jun 13 12:40 adapter_config.json
# 元のモデル（14GB）ではなく LoRAアダプタ（295MB）だけを保存できる
VRAMとメモリ消費量の目安
モデルサイズ別の VRAM 消費量の目安をまとめました。QLoRA（NF4 + double quantization）適用時の値です。
正直、一番詰まるのはここで、「モデルの理論値は乗るはずなのに実際にはOOMになる」というケースです。バッチサイズや max_seq_length をさらに小さくするか、gradient_checkpointing=True を必ず有効にしてください。
低メモリ環境で動かすコツ
①gradient_checkpointing を有効にする
学習の中間アクティベーションを保存せず、必要時に再計算することでVRAMを削減します。速度は 20〜30% 低下しますが、メモリ節約効果は大きいです。
gradient_checkpointing=True, # ← 必ず True に
gradient_checkpointing_kwargs={“use_reentrant”: False},
per_device_train_batch_size=1,
gradient_accumulation_steps=8, # バッチ1でも実質8stepぶん蓄積
…)
②LoRAランク（r）を小さくする
LoRA の r はランクで、小さいほどパラメータ数が減りVRAMが下がります。r=16 → r=8 → r=4 と試してみてください。タスクによっては r=4 でも品質は十分なことがあります。
③max_seq_length を短くする
シーケンス長は VRAM に二乗で影響します。max_seq_length=2048 → 512 にするだけで VRAM 消費が 75% 以上減ることもあります。データに合わせて調整しましょう。
④Flash Attention 2 を使う（対応GPU のみ）
RTX 3090 / 4090 や A100 などのアーキテクチャでは attn_implementation="flash_attention_2" が使えます。pip install flash-attn --no-build-isolation でインストール後、from_pretrained に渡します。
model = AutoModelForCausalLM.from_pretrained(
model_name,
attn_implementation=”flash_attention_2″,
quantization_config=bnb_config,
)
よくあるエラーと対処法
①CUDA out of memory
RuntimeError: CUDA out of memory
VRAM が足りない場合に発生します。対処：① per_device_train_batch_size=1 にする ② gradient_checkpointing=True にする ③ max_seq_length を512以下に下げる ④ LoRAの r を小さくする（16→8→4）。それでも解決しない場合はモデルを小さくする（7B→3B）か GPU VRAM の大きいマシンを使うしかありません。
②bitsandbytes が CUDA を認識しない
CUDA が正しくインストールされていないか、torch の CPU 版が入っている可能性があります。python3 -c "import torch; print(torch.cuda.is_available())" が True を返すか確認してください。False なら PyTorch の CUDA 版を再インストールしてください。
③transformers でモデルがダウンロードできない
(peft-env) $ pip install huggingface_hub
(peft-env) $ huggingface-cli login
Enter your token (input will not be visible): ****
Login successful
Hugging Face のゲート付きモデル（Llama、Mistral 等）は Hugging Face アカウントでログインし、利用規約に同意する必要があります。huggingface-cli login でトークンを設定してください。
④value_head レイヤーが見つからない
モデルアーキテクチャによって注意レイヤー名が異なります。model.named_modules() でレイヤー名を確認し、lora_config の target_modules を修正してください。GPT-2 系なら ["c_attn"]、BERT 系なら ["query", "value"] が一般的です。
VPS/クラウドで動かすなら
ローカルに十分な GPU がない場合、クラウド GPU サーバーを使うのが現実的です。QLoRA でも 7B モデルなら VRAM 6GB 程度あれば動きますが、快適に学習したいなら 16GB 以上を推奨します。
なお、CPU のベンチマーク（sysbench）はファインチューニングの速度に直接影響しませんが、VPS 選びの参考になります。GPU 付きプランを持つ VPS/クラウドサービスを比較するなら、以下の記事も参考にしてください。
| サービス | GPU プラン例 | VRAM | 月額目安 | 特徴 |
|---|---|---|---|---|
| Vultr | A100 40GB / L40S 48GB | 40〜48 GB | $2.4/h〜 | 時間課金・東京リージョンあり |
| DigitalOcean | GPU Droplet H100 | 80 GB | $4.46/h〜 | GUI が使いやすい |
| Linode (Akamai) | GPU Plan RTX6000 | 24 GB | $1.0/h〜 | コスパ重視の選択肢 |
| ConoHa VPS | GPU プラン（お問い合わせ） | – | – | 日本語サポート・国内データセンター |
Vultr はオンデマンドで GPU インスタンスを起動・停止できるため、「学習中だけ起動して終わったら停止」という使い方に向いています。
まとめ
この記事では、Ubuntu 24.04 LTS + Python 3.12 環境での PEFT/QLoRA セットアップから、ファインチューニングの基本コードまでを解説しました。
pip install peft transformers accelerate trl bitsandbytesでエコシステムが揃う（実測バージョン: peft 0.19.1 / transformers 5.12.0 / bitsandbytes 0.49.2）- QLoRA = 4bit量子化（bitsandbytes）+ LoRAアダプタ（peft）の組み合わせで VRAM を最大 75% 削減できる
- 7B モデルなら VRAM 4〜6GB でファインチューニング可能になる
- 実用的な学習には NVIDIA GPU（CUDA 11.8+）が必要。CPU のみでは現実的でない
gradient_checkpointing=Trueとmax_seq_lengthの調整が低VRAM環境での鉄板テクニック
VPS で本格的に試したい場合は GPU 付きプランを検討してください。まずはローカル GPU でセットアップを確認し、本番学習だけクラウドに移行する方法が現実的です。
次のステップとして、VPS 比較記事や Ubuntu CUDA インストールガイド も合わせて参照してみてください。
コメント