quantizing-models-bitsandbytes

bitsandbytes - 大模型量化

快速开始

bitsandbytes 可将大模型的内存占用降低 50%（8-bit）或 75%（4-bit），精度损失低于 1%。

安装：

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
)

问题：精度低于预期

尝试使用 8-bit 而非 4-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 训练指南：有关完整的微调工作流、超参数调优和多 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-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）

Agent 操作流程

1. 检查环境。 检查 GPU 类型、内存、驱动和 CUDA 版本（nvidia-smi）、框架版本，以及数据集的位置和大小。
2. 明确输入。 根据数据或用户确认格式、标识符和参数。任何会影响结果的值都应先询问，切勿猜测。
3. 先运行小规模版本。 进行冒烟测试：使用小型模型或子集，运行少量步骤，并确认损失下降且检查点已保存。
4. 按照上述说明和参考资料执行完整任务。
5. 验证结果。 在留出数据上跟踪指标，与基线进行比较，并记录随机种子、配置和硬件信息。
6. 报告结果。 说明运行了什么（版本、命令、参数）、检查了什么，以及哪些事项仍不确定。

如果出现以下情况	请执行以下操作
CUDA 显存不足	减小批量大小，启用梯度累积、梯度检查点或混合精度，或者对模型进行分片。
损失为 NaN 或不断发散	降低学习率，检查数据中是否有无效值，并启用梯度裁剪。
已安装版本中缺少这些说明里的函数、标志或端点	查阅已安装版本自己的文档（help()、--help、官方文档），调整操作，并告知用户。切勿编造 API。
必需的输入、标识符或参数不明确	询问用户，或在运行前明确说明所作假设。

诚信规则

• 切勿捏造结果、参数、标识符、引文或统计数据。如果无法运行或验证某项内容，请如实说明。
• 没有日志，切勿声称取得了训练结果；启动大型任务前，先估算计算成本。
• 请将此处与版本相关的细节视为可能已过时：对照已安装版本的官方文档进行确认。
• 对于会产生费用、占用共享 GPU 或云配额、涉及个人或患者数据，或无法撤销的操作，须先征得用户同意。

相关技能

• awq-quantization：采用激活感知权重量化，将大模型压缩至 4 位，提速 3 倍且精度损失极小。
• gptq：通过 AutoGPTQ 和 transformers，使用分组量化（默认组大小为 128）将大模型量化至 4 位（也支持 3 位），采用 GPTQ 方法。
• hqq-quantization：无需校准数据的大模型半二次量化。