QLoRA 与量化微调

QLoRA（Quantized LoRA，量化低秩适配）在 4bit 量化基座上挂 LoRA，把 7B–70B 微调压进单张消费级 GPU。本篇是 02-01 LoRA 的显存进阶；BF16 全基座 + LoRA 仍 OOM 时再启用 QLoRA。

段末注释：NF4（4-bit NormalFloat）为 QLoRA 论文采用的 4bit 量化数据类型，针对神经网络权重分布优化；双重量化（double quantization）进一步压缩量化常数占用的显存。

系列索引：微调技术路线导读

一、QLoRA vs LoRA

	LoRA（BF16 基座）	QLoRA
基座权重	16bit 全量加载	4bit 量化加载，冻结
可训练参数	LoRA (A,B)	同左
显存	中	低
速度	较快	略慢（量化反量化开销）
精度	通常最好	略降，多数任务可接受

公式层与 LoRA 相同：(y = W_0 x + \frac{\alpha}{r}BAx)，区别在 (W_0) 以 4bit 存储并在前向时反量化。

二、最小配置示例

import torch
from transformers import AutoModelForCausalLM, AutoTokenizer, BitsAndBytesConfig
from peft import LoraConfig, prepare_model_for_kbit_training
from trl import SFTConfig, SFTTrainer

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

model = AutoModelForCausalLM.from_pretrained(
    MODEL_ID,
    quantization_config=bnb_config,
    device_map="auto",
)
model = prepare_model_for_kbit_training(model)

lora_config = LoraConfig(
    r=16, lora_alpha=32, lora_dropout=0.05,
    task_type="CAUSAL_LM",
    target_modules=["q_proj", "k_proj", "v_proj", "o_proj",
                    "gate_proj", "up_proj", "down_proj"],
)

trainer = SFTTrainer(
    model=model,
    train_dataset=train_ds,
    peft_config=lora_config,
    args=SFTConfig(
        output_dir="./qlora-out",
        learning_rate=2e-4,
        per_device_train_batch_size=2,
        gradient_accumulation_steps=8,
        gradient_checkpointing=True,
        bf16=True,
        optim="paged_adamw_8bit",  # 量化训练常用
        max_length=512,
        completion_only_loss=True,
    ),
)
trainer.train()

三、关键参数

参数	说明
`load_in_4bit=True`	启用 4bit 权重
`bnb_4bit_quant_type="nf4"`	NF4 量化类型
`bnb_4bit_compute_dtype=bfloat16`	matmul 计算精度
`bnb_4bit_use_double_quant=True`	双重量化，省显存
`prepare_model_for_kbit_training`	开启 gradient checkpointing 兼容、冻结 norm 等
`optim="paged_adamw_8bit"`	分页 8bit 优化器，降 optimizer state 显存

LoRA 的 r、alpha、target_modules 见 02-01。

四、显存粗算

QLoRA 7B 单卡常见 12–24 GB（视 batch、max_length、rank 而定）。仍不够时叠加 07-01 显存优化：gradient_accumulation、降 max_length、收窄 target_modules。

五、平台兼容

平台	建议
NVIDIA CUDA + A100/4090	QLoRA 首选场景；`bitsandbytes` 成熟
NVIDIA 旧卡	可用；优先 BF16 compute
AMD ROCm	常不稳定；AMD 实战采用 BF16 基座 + LoRA，不用 4bit
Apple MPS	量化支持有限；多数仍 BF16 LoRA

决策：ROCm 或 bnb 报错 → 退回 BF16 LoRA + gradient checkpointing。

六、与部署的衔接

训练产物仍是 LoRA adapter（与 BF16 LoRA 相同）。
推理时可 PeftModel 挂载；合并后导出 GGUF 见 02-04 Adapter 合并。
4bit 基座仅训练省显存；部署不必保持 4bit，可按框架选 AWQ/GPTQ/FP16。

七、常见踩坑

现象	原因	对策
`bitsandbytes` 导入失败	未装或 CUDA 版本不匹配	按官方 wheel 重装
loss NaN	compute_dtype 与数据不匹配	改 `bfloat16`；降 lr
效果弱于 BF16 LoRA	量化误差	提 rank；关键任务对比 BF16
ROCm 崩溃	4bit 路径未充分支持	BF16 LoRA

八、小结

QLoRA = 4bit 冻结基座 + LoRA + paged optimizer，单卡训大模型的默认省钱方案；ROCm 等生态不成熟环境优先 BF16 LoRA。

下一步：02-03 PEFT 方法对比或 07-01 显存优化栈。