总目录›Axolotl›第 7 章
Chapter 07

PEFT 集成与 4bit/8bit 量化

📌 commit ab1a0d8adapter 字段四档配置

Axolotl 的 PEFT / 量化是 YAML 几个字段的组合。本章按 4 种组合讲。

7.1四种典型组合

组合adapterload_in_*显存（7B）
全参 bf16未设未设~80 GB
LoRA bf16lora未设~22 GB
LoRA + 8bitloraload_in_8bit: true~16 GB
QLoRA (4bit)qloraload_in_4bit: true~14 GB

7.2LoRA 完整字段

adapter: lora
lora_r: 16
lora_alpha: 32
lora_dropout: 0.05
lora_target_modules:
  - q_proj
  - k_proj
  - v_proj
  - o_proj
  - gate_proj
  - up_proj
  - down_proj
lora_modules_to_save:                  # 扩词表时加这两个
  - embed_tokens
  - lm_head
lora_fan_in_fan_out: false             # GPT-2 类要 true
peft_use_dora: false                    # 开 DoRA
peft_use_rslora: false                  # 开 rsLoRA
peft_layers_to_transform: null          # 只对部分 layer 上 LoRA
peft_layers_pattern: model.layers

7.3QLoRA：bnb 量化集成

adapter: qlora                          # 必须 qlora（不是 lora）
load_in_4bit: true
bnb_4bit_quant_type: nf4
bnb_4bit_compute_dtype: bfloat16
bnb_4bit_use_double_quant: true

lora_r: 16
lora_alpha: 32
lora_target_modules: [q_proj,k_proj,v_proj,o_proj,gate_proj,up_proj,down_proj]
lora_dropout: 0.05

optimizer: paged_adamw_8bit             # 配合 QLoRA 用 paged optimizer

7.4LoftQ / PiSSA 初始化

QLoRA 长跑配 LoftQ 更稳，快收敛配 PiSSA。Axolotl 直接支持：

peft_init_lora_weights: loftq           # 或 pissa / pissa_niter_4 / olora
loftq_bits: 4
loftq_iter: 1

7.5其他 8bit 优化器

optimizer说明
adamw_torch标准
adamw_bnb_8bitbnb 8bit Adam
paged_adamw_8bit+ 分页（QLoRA 必备）
adamw_torch_fusedPyTorch fused AdamW（A100+）
schedule_free_adamwschedule-free AdamW
cameCAME (Confidence-guided Adaptive Memory Efficient)

7.6实战配方（7B QLoRA + DoRA）

base_model: Qwen/Qwen2.5-7B-Instruct
load_in_4bit: true
bnb_4bit_quant_type: nf4
bnb_4bit_compute_dtype: bfloat16
bnb_4bit_use_double_quant: true

adapter: qlora
lora_r: 16
lora_alpha: 32
lora_dropout: 0.05
peft_use_dora: true                     # ★ + DoRA
peft_init_lora_weights: pissa            # ★ + PiSSA

lora_target_modules:
  - q_proj
  - k_proj
  - v_proj
  - o_proj
  - gate_proj
  - up_proj
  - down_proj

datasets:
  - path: tatsu-lab/alpaca
    type: alpaca
sequence_len: 2048
sample_packing: true
micro_batch_size: 2
gradient_accumulation_steps: 8
num_epochs: 2
learning_rate: 2e-4
optimizer: paged_adamw_8bit
bf16: auto
flash_attention: true
gradient_checkpointing: true
output_dir: ./out

7.7合并 LoRA 推理

axolotl merge-lora my_qlora.yml \
    --lora_model_dir ./out \
    --output_dir ./merged

注意 QLoRA 不能直接 merge（4bit 不能加 LoRA）。Axolotl 自动 dequantize 再 merge。

7.8常见踩坑

现象处理
QLoRA NaN必须用 bf16 而非 fp16 作 compute_dtype
"adapter qlora not found"没装 bitsandbytes
训完 merge 后模型 OOM 加载正常，merged 是 bf16 全权重
DoRA + QLoRA 慢 50%正常，DoRA + 量化路径有额外开销

7.9Axolotl 量化 backend 全表

v2026 之后 Axolotl 支持多个量化路径，由 load_in_8bit / load_in_4bit / quantization_config 字段触发。来源 loaders/model.py 第 5 步 "configure quantization"：

量化路径YAML 触发能 merge?典型场景
BNB 8bit load_in_8bit: true ✅ 8bit LoRA
BNB 4bit (NF4) load_in_4bit: true + bnb_4bit_quant_type: nf4 ✅（自动 dequant）QLoRA 主线
GPTQ base_model 是 GPTQ checkpoint，自动检测 ❌ GPTQ 模型 + LoRA 微调
AWQ base_model 是 AWQ checkpoint ❌ AWQ 模型 + LoRA
AQLM checkpoint 自带 AQLM 标记 ❌ 2bit AQLM
torchao quantization_config: torchao ✅ FP8 / affine quant（2025-Q1 新增）
QAT NVFP4 qat: { type: nvfp4 } — 训练时量化感知（2025-Q3 新增）
QAT MXFP4 qat: { type: mxfp4 } — MX Format 4bit QAT
Expert quantexpert_quantization: ... — MoE expert 单独量化（2026-03，FSDP2 兼容）

7.10LoRA target 自动发现

loaders/adapter.py:52–69 的 find_all_linear_names() 决定 lora_target_modules: "all" 时实际选哪些层：

  1. 遍历所有 module，找 isinstance(m, bnb.nn.Linear*) or nn.Linear；
  2. 跳过 lm_head（除非显式加进 lora_modules_to_save）；
  3. Gemma4 特殊处理（line 72–89）：ClippableLinear 包装层要进 inner .linear；
  4. 返回所有匹配 module 的 short name set。

结果通常是 {q_proj, k_proj, v_proj, o_proj, gate_proj, up_proj, down_proj}，跟手写 7 个完全等价。

7.11QAT：训练时量化感知

2025-Q3 之后引入的 QAT（Quantization-Aware Training）是 axolotl 的进阶特性。配置示例：

qat:
  type: nvfp4        # nvfp4 / mxfp4 / fp8
  fake_quant: true
  granularity: per_token

# 配合 FSDP2 使用
fsdp_version: 2
fsdp_config:
  fsdp_offload_params: false

原理：训练 forward / backward 中插入"假量化"算子，模拟量化误差让模型适应。训完导出真正量化模型时精度损失极小。示例脚本 examples/llama-3/3b-qat-nvfp4.yaml。

7.12这章你需要带走的