quantizing-models-bitsandbytes

bitsandbytes - LLM 量子化

クイックスタート

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

インストール:

pip install bitsandbytes transformers accelerate

8ビット量子化（メモリを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ビット量子化（メモリを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ビット（より高い精度）の場合:

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ビット（最大のメモリ削減）の場合:

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ビット学習）

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ビットのベースモデルを設定する

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ビットオプティマイザー

8ビットの 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ビットの代わりに 8ビットを試してください:

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ビットでも OOM（メモリ不足）になる

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

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

応用トピック

QLoRA 学習ガイド: 完全なファインチューニングのワークフロー、ハイパーパラメータのチューニング、マルチ GPU 学習については references/qlora-training.md を参照してください。

量子化フォーマット: INT8、NF4、FP4 の比較、二重量子化、カスタム量子化設定については references/quantization-formats.md を参照してください。

メモリ最適化: CPU オフロード戦略、勾配チェックポイント、メモリプロファイリングについては references/memory-optimization.md を参照してください。

ハードウェア要件

• GPU: コンピュート能力 7.0 以上の NVIDIA GPU（Turing、Ampere、Hopper）
• VRAM: モデルと量子化方式によって異なります
  • 4ビットの Llama 2 7B: 4GB
  • 4ビットの Llama 2 13B: 8GB
  • 4ビットの 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）