quantizing-models-bitsandbytes

bitsandbytes - LLM の量子化

クイックスタート

bitsandbytes は、精度の低下を 1% 未満に抑えながら、LLM のメモリ使用量を 50%（8-bit）または 75%（4-bit）削減します。

インストール：

pip install bitsandbytes transformers accelerate

8-bit 量子化（メモリ使用量を 50% 削減）：

from transformers import AutoModelForCausalLM, BitsAndBytesConfig

config = BitsAndBytesConfig(load_in_8bit=True)
model = AutoModelForCausalLM.from_pretrained(
    "meta-llama/Llama-2-7b-hf",
    quantization_config=config,
    device_map="auto"
)

# Memory: 14GB → 7GB

4-bit 量子化（メモリ使用量を 75% 削減）：

config = BitsAndBytesConfig(
    load_in_4bit=True,
    bnb_4bit_compute_dtype=torch.float16
)
model = AutoModelForCausalLM.from_pretrained(
    "meta-llama/Llama-2-7b-hf",
    quantization_config=config,
    device_map="auto"
)

# Memory: 14GB → 3.5GB

よくあるワークフロー

ワークフロー 1：GPU メモリが限られている環境で大規模モデルを読み込む

このチェックリストをコピーしてください：

Quantization Loading:
- [ ] Step 1: Calculate memory requirements
- [ ] Step 2: Choose quantization level (4-bit or 8-bit)
- [ ] Step 3: Configure quantization
- [ ] Step 4: Load and verify model

ステップ 1：メモリ要件を計算する

モデルのメモリ使用量を推定します：

FP16 memory (GB) = Parameters × 2 bytes / 1e9
INT8 memory (GB) = Parameters × 1 byte / 1e9
INT4 memory (GB) = Parameters × 0.5 bytes / 1e9

Example (Llama 2 7B):
FP16: 7B × 2 / 1e9 = 14 GB
INT8: 7B × 1 / 1e9 = 7 GB
INT4: 7B × 0.5 / 1e9 = 3.5 GB

ステップ 2：量子化レベルを選ぶ

GPU VRAM	モデルサイズ	推奨
8 GB	3B	4-bit
12 GB	7B	4-bit
16 GB	7B	8-bit または 4-bit
24 GB	13B	8-bit または 70B 4-bit
40+ GB	70B	8-bit

ステップ 3：量子化を設定する

8-bit の場合（精度重視）：

from transformers import BitsAndBytesConfig
import torch

config = BitsAndBytesConfig(
    load_in_8bit=True,
    llm_int8_threshold=6.0,  # Outlier threshold
    llm_int8_has_fp16_weight=False
)

4-bit の場合（メモリを最大限節約）：

config = BitsAndBytesConfig(
    load_in_4bit=True,
    bnb_4bit_compute_dtype=torch.float16,  # Compute in FP16
    bnb_4bit_quant_type="nf4",  # NormalFloat4 (recommended)
    bnb_4bit_use_double_quant=True  # Nested quantization
)

ステップ 4：モデルを読み込み、検証する

from transformers import AutoModelForCausalLM, AutoTokenizer

model = AutoModelForCausalLM.from_pretrained(
    "meta-llama/Llama-2-13b-hf",
    quantization_config=config,
    device_map="auto",  # Automatic device placement
    torch_dtype=torch.float16
)

tokenizer = AutoTokenizer.from_pretrained("meta-llama/Llama-2-13b-hf")

# Test inference
inputs = tokenizer("Hello, how are you?", return_tensors="pt").to("cuda")
outputs = model.generate(**inputs, max_length=50)
print(tokenizer.decode(outputs[0]))

# Check memory
import torch
print(f"Memory allocated: {torch.cuda.memory_allocated()/1e9:.2f}GB")

ワークフロー 2：QLoRA でファインチューニングする（4-bit トレーニング）

QLoRA を使うと、コンシューマー向け GPU で大規模モデルをファインチューニングできます。

このチェックリストをコピーしてください：

QLoRA Fine-tuning:
- [ ] Step 1: Install dependencies
- [ ] Step 2: Configure 4-bit base model
- [ ] Step 3: Add LoRA adapters
- [ ] Step 4: Train with standard Trainer

ステップ 1：依存関係をインストールする

pip install bitsandbytes transformers peft accelerate datasets

ステップ 2：4-bit のベースモデルを設定する

from transformers import AutoModelForCausalLM, BitsAndBytesConfig
import torch

bnb_config = BitsAndBytesConfig(
    load_in_4bit=True,
    bnb_4bit_compute_dtype=torch.float16,
    bnb_4bit_quant_type="nf4",
    bnb_4bit_use_double_quant=True
)

model = AutoModelForCausalLM.from_pretrained(
    "meta-llama/Llama-2-7b-hf",
    quantization_config=bnb_config,
    device_map="auto"
)

ステップ 3：LoRA アダプターを追加する

from peft import LoraConfig, get_peft_model, prepare_model_for_kbit_training

# Prepare model for training
model = prepare_model_for_kbit_training(model)

# Configure LoRA
lora_config = LoraConfig(
    r=16,  # LoRA rank
    lora_alpha=32,  # LoRA alpha
    target_modules=["q_proj", "k_proj", "v_proj", "o_proj"],
    lora_dropout=0.05,
    bias="none",
    task_type="CAUSAL_LM"
)

# Add LoRA adapters
model = get_peft_model(model, lora_config)
model.print_trainable_parameters()
# Output: trainable params: 4.2M || all params: 6.7B || trainable%: 0.06%

ステップ 4：標準の Trainer でトレーニングする

from transformers import Trainer, TrainingArguments

training_args = TrainingArguments(
    output_dir="./qlora-output",
    per_device_train_batch_size=4,
    gradient_accumulation_steps=4,
    num_train_epochs=3,
    learning_rate=2e-4,
    fp16=True,
    logging_steps=10,
    save_strategy="epoch"
)

trainer = Trainer(
    model=model,
    args=training_args,
    train_dataset=train_dataset,
    tokenizer=tokenizer
)

trainer.train()

# Save LoRA adapters (only ~20MB)
model.save_pretrained("./qlora-adapters")

ワークフロー 3：メモリ効率の高いトレーニング向け 8-bit オプティマイザー

8-bit Adam/AdamW を使うと、オプティマイザーのメモリ使用量を 75% 削減できます。

8-bit Optimizer Setup:
- [ ] Step 1: Replace standard optimizer
- [ ] Step 2: Configure training
- [ ] Step 3: Monitor memory savings

ステップ 1：標準のオプティマイザーを置き換える

import bitsandbytes as bnb
from transformers import Trainer, TrainingArguments

# Instead of torch.optim.AdamW
model = AutoModelForCausalLM.from_pretrained("model-name")

training_args = TrainingArguments(
    output_dir="./output",
    per_device_train_batch_size=8,
    optim="paged_adamw_8bit",  # 8-bit optimizer
    learning_rate=5e-5
)

trainer = Trainer(
    model=model,
    args=training_args,
    train_dataset=train_dataset
)

trainer.train()

オプティマイザーを手動で使用する場合：

import bitsandbytes as bnb

optimizer = bnb.optim.AdamW8bit(
    model.parameters(),
    lr=1e-4,
    betas=(0.9, 0.999),
    eps=1e-8
)

# Training loop
for batch in dataloader:
    loss = model(**batch).loss
    loss.backward()
    optimizer.step()
    optimizer.zero_grad()

ステップ 2：トレーニングを設定する

メモリ使用量を比較します：

Standard AdamW optimizer memory = model_params × 8 bytes (states)
8-bit AdamW memory = model_params × 2 bytes
Savings = 75% optimizer memory

Example (Llama 2 7B):
Standard: 7B × 8 = 56 GB
8-bit: 7B × 2 = 14 GB
Savings: 42 GB

ステップ 3：メモリ節約効果を確認する

import torch

before = torch.cuda.memory_allocated()

# Training step
optimizer.step()

after = torch.cuda.memory_allocated()
print(f"Memory used: {(after-before)/1e9:.2f}GB")

代替手段との使い分け

bitsandbytes を使う場合：

• GPU メモリが限られている（より大きなモデルを収める必要がある）
• QLoRA でトレーニングする（単一 GPU で 70B モデルをファインチューニングする）
• 推論のみを行う（メモリ使用量を 50～75% 削減）
• HuggingFace Transformers を使用する
• 精度が 0～2% 低下しても許容できる

代替手段を使う場合：

• GPTQ/AWQ：本番環境でのサービング（bitsandbytes より推論が高速）
• GGUF：CPU 推論（llama.cpp）
• FP8：H100 GPU（ハードウェア FP8 の方が高速）
• フル精度：精度が重要で、メモリに制約がない

よくある問題

問題：読み込み中に CUDA エラーが発生する

対応する CUDA バージョンをインストールしてください：

# Check CUDA version
nvcc --version

# Install matching bitsandbytes
pip install bitsandbytes --no-cache-dir

問題：モデルの読み込みが遅い

大規模モデルでは CPU オフロードを使用してください：

model = AutoModelForCausalLM.from_pretrained(
    "model-name",
    quantization_config=config,
    device_map="auto",
    max_memory={0: "20GB", "cpu": "30GB"}  # Offload to CPU
)

問題：予想より精度が低い

4-bit の代わりに 8-bit を試してください：

config = BitsAndBytesConfig(load_in_8bit=True)
# 8-bit has <0.5% accuracy loss vs 1-2% for 4-bit

または、二重量子化を使った NF4 を使用してください：

config = BitsAndBytesConfig(
    load_in_4bit=True,
    bnb_4bit_quant_type="nf4",  # Better than fp4
    bnb_4bit_use_double_quant=True  # Extra accuracy
)

問題：4-bit でも OOM が発生する

CPU オフロードを有効にしてください：

model = AutoModelForCausalLM.from_pretrained(
    "model-name",
    quantization_config=config,
    device_map="auto",
    offload_folder="offload",  # Disk offload
    offload_state_dict=True
)

高度なトピック

QLoRA トレーニングガイド：references/qlora-training.md では、ファインチューニングのワークフロー、ハイパーパラメーターの調整、マルチ GPU トレーニングについて詳しく説明しています。

量子化形式：references/quantization-formats.md では、INT8、NF4、FP4 の比較、二重量子化、カスタム量子化設定について説明しています。

メモリの最適化：references/memory-optimization.md では、CPU オフロードの方法、勾配チェックポイント、メモリプロファイリングについて説明しています。

ハードウェア要件

• GPU：コンピュート能力 7.0 以上の NVIDIA（Turing、Ampere、Hopper）
• VRAM：モデルと量子化によって異なります
  • 4-bit Llama 2 7B：4GB
  • 4-bit Llama 2 13B：8GB
  • 4-bit Llama 2 70B：24GB
• CUDA：11.1 以上（12.0 以上を推奨）
• PyTorch：2.0 以上

対応プラットフォーム：NVIDIA GPU（主要）、AMD ROCm、Intel GPU（実験的）

リソース

• GitHub：https://github.com/bitsandbytes-foundation/bitsandbytes
• HuggingFace ドキュメント：https://huggingface.co/docs/transformers/quantization/bitsandbytes
• QLoRA 論文：「QLoRA: Efficient Finetuning of Quantized LLMs」（2023）
• LLM.int8() 論文：「LLM.int8(): 8-bit Matrix Multiplication for Transformers at Scale」（2022）

エージェントの実行手順

1. 環境を確認します。 GPU の種類、メモリ、ドライバー／CUDA のバージョン（nvidia-smi）、フレームワークのバージョン、データセットの場所とサイズを確認します。
2. 入力を明確にします。 データまたはユーザーに確認し、形式、識別子、パラメーターを確定します。結果に影響する値は推測せず、質問してください。
3. まず小規模に実行します。 スモークテストとして、小さなモデルまたはサブセットを使い、少ないステップ数で実行して、損失が減少し、チェックポイントが保存されることを確認します。
4. 上記の手順と参考資料に従って、タスク全体を実行します。
5. 結果を検証します。 保留データで指標を追跡し、ベースラインと比較して、シード、設定、ハードウェアを記録します。
6. 報告します。 実行した内容（バージョン、コマンド、パラメーター）、確認した内容、未確定の事項を伝えます。

この状況が発生した場合	対応
CUDA のメモリ不足	バッチサイズを小さくする、勾配蓄積／チェックポイント化または混合精度を有効にする、あるいはモデルをシャーディングします。
損失が NaN になる、または発散する	学習率を下げ、データに無効な値がないか確認し、勾配クリッピングを有効にします。
これらの手順に記載された関数、フラグ、またはエンドポイントが、インストール済みのバージョンに存在しない	インストール済みバージョンのドキュメント（help()、--help、公式ドキュメント）を確認し、適宜対応して、ユーザーに伝えます。API を捏造してはいけません。
必須の入力、識別子、またはパラメーターが曖昧	ユーザーに質問するか、実行前に仮定を明示します。

誠実性に関するルール

• 結果、パラメーター、識別子、引用、統計情報を捏造してはいけません。実行または検証できないことは、率直に伝えます。
• ログなしに学習結果を主張してはいけません。大規模なジョブを開始する前に、計算コストを見積もります。
• ここに記載されたバージョン固有の情報は古くなっている可能性があるものとして扱い、インストール済みバージョンの公式ドキュメントで確認します。
• 費用が発生する、共有 GPU やクラウドのクォータを消費する、個人データや患者データに触れる、または元に戻せない操作を行う前に、確認を求めます。

関連スキル

• awq-quantization：精度の損失を最小限に抑えつつ 3 倍の高速化を実現する、4 ビット LLM 圧縮向けのアクティベーション対応重み量子化です。
• gptq：AutoGPTQ と transformers を使用し、グループ単位の量子化（デフォルトのグループサイズは 128）により、GPTQ で LLM を 4 ビット（3 ビットにも）量子化します。
• hqq-quantization：キャリブレーションデータを使わずに LLM を量子化する、半二次量子化です。