SFT：全参 / LoRA / QLoRA / 长上下文

6.1 SFT 在 LLaMA-Factory 里的四种模式

SFT (Supervised Fine-Tuning) 在框架里通过 finetuning_type 与 quantization_bit 两个字段的组合，可以走出四条路：

6.2 全参 SFT

仓库自带 examples/train_full/qwen3_full_sft.yaml。其中关键不同于 LoRA 的是：

### method
stage: sft
do_train: true
finetuning_type: full
deepspeed: examples/deepspeed/ds_z3_config.json  # 必须！

全参微调几乎都要 DeepSpeed ZeRO-3 把参数 / 梯度 / 优化器全切，单机 8 卡 Qwen3-4B 才能塞得下。它的 per_device_train_batch_size = 1, gradient_accumulation_steps = 2, learning_rate = 1e-5 —— 比 LoRA 学习率小 10 倍，因为整个模型都在动，太大就会忘掉 pretrain 习得。

6.3 LoRA SFT

第 3 章已经跑过 examples/train_lora/qwen3_lora_sft.yaml。这里讲关键超参的选择直觉：

lora_rank（秩 $r$）

LoRA 增量参数量：

$$\#\Delta W = 2 d r,\qquad \text{其中}\ d=\text{hidden size},\ r=\text{lora\_rank}$$

lora_alpha 与 lora_dropout

LoRA 实际作用到原权重的形式是：

$$y = W x + \tfrac{\alpha}{r}\, B A\, x$$

• lora_alpha 是 $\alpha$，默认 2*lora_rank；调大会放大 LoRA 影响；
• lora_dropout 仅在 LoRA 旁支内的 dropout，过拟合明显时升到 0.05～0.1。

lora_target

"all" = 找模型里所有 nn.Linear 都加 LoRA。当 GPU 紧时可以缩到：

lora_target: q_proj,v_proj           # 只 attention 的 QV，最便宜
lora_target: q_proj,k_proj,v_proj,o_proj   # 全 attention
lora_target: all                       # 全 attention + MLP，效果最稳，默认推荐

6.4 QLoRA SFT

QLoRA = "4-bit 加载基座" + "fp16/bf16 LoRA"。本质：基座以极低精度只读放在显存里，LoRA 仍用混合精度训练。框架里只要再加两行：

quantization_method: bnb        # bitsandbytes
quantization_bit: 4
quantization_type: nf4
double_quantization: true

显存收益（来自 README 表）：

用已经量化好的模型做 LoRA

examples/train_qlora/llama3_lora_sft_gptq.yaml 演示了另一条路：加载预先用 GPTQ / AWQ 量化好的模型权重，再在上面挂 LoRA：

model_name_or_path: TechxGenus/Meta-Llama-3-8B-Instruct-GPTQ
# 注意：这里没有 quantization_bit，因为模型本身就已经是量化版

这种用法训完不能 merge（量化权重不可逆地损失精度，merge 回去会出错）；只能在推理时同样加载 GPTQ 模型 + LoRA 适配器。

6.5 Freeze SFT（局部微调）

finetuning_type: freeze
freeze_trainable_layers: 2          # 只放开 transformer 最后 2 层
freeze_trainable_modules: all       # 这 2 层里所有 module 都可训
# freeze_extra_modules: lm_head     # 额外把 lm_head 也放开

常用于：

• 资源中等 + 不想用 LoRA 的研究场景；
• 想精确控制"哪一层动、哪一层不动"做 probing 实验；
• 结合 freeze_extra_modules: embed_tokens 做 embedding 微调。

6.6 PT：持续预训练 vs SFT

注意 stage: pt 不属于 SFT，但流程极像。区别在数据形态：

仓库自带例子：examples/train_lora/qwen3_lora_pretrain.yaml。

6.7 长上下文 SFT

当 cutoff_len 超过 8K 时，几个字段必须配合修改：

典型计算：序列长度从 2048 → 32768，self-attention 显存按 $O(L^2)$ 飙升 256 倍。没有 FlashAttention-2 + gradient checkpointing 不可能跑得动。

6.9 init_adapter()：全参 / freeze / LoRA / OFT 的决策入口

本章描述的"全参 / LoRA / QLoRA / 长上下文"四条路，在源码层都走同一个分发函数：src/llamafactory/model/adapter.py:293 init_adapter()。这个函数按 finetuning_type 派发到三条具体路径：

三条路共享的 FP32 upcasting 规则

训练侧 trainable 参数默认会被 cast 回 FP32，但下面这些情形会跳过 upcast（adapter.py:313–325）：

• pure_bf16: true —— 全程 bf16，不升精度；
• use_badam: true —— BAdam 块坐标优化器要求半精度状态；
• quantization_bit is None and is_deepspeed_zero3_enabled() —— ZeRO-3 自己管 fp32 master，重复 cast 反而占内存。

6.10 LoRA 路径的 11 个分支

_setup_lora_tuning() 看似复杂，可拆成几条互斥分支。读这一节相当于把 LoRA 的"所有 yaml flag 怎么落到代码"看了一遍：

6.11 QLoRA 的三档量化路径

QLoRA = finetuning_type: lora + quantization_bit: 4 or 8。看 model/model_utils/quantization.py:82–217 能看到量化字段的三档优先级：

1. PTQ 模型（line 90–130）：模型本身已经 GPTQ / AWQ / AQLM / MXFP4 / FP8 量化好，加载即用。MXFP4 / FP8 与 ZeRO-3 / FSDP 互斥（line 97–101）；
2. 导出时量化（line 132–164）：export_quantization_bit: 4 / 8 + export_quantization_dataset，训完一次性 PTQ 出 GPTQ 格式；
3. on-the-fly 量化（line 166–217）：quantization_bit + quantization_method：
   • bnb：BitsAndBytes，最常用；4-bit 时 bnb_4bit_quant_storage=compute_dtype 对 FSDP+QLoRA 至关重要（line 178）；
   • hqq：HQQ，支持 1–8 bit；与 ZeRO-3/FSDP 互斥；
   • eetq：EETQ，8-bit only，同上互斥。

三档之间互斥：一个模型只能走一种量化路径。"导出时量化"不要和"on-the-fly 量化"同时写。

6.12 全参 SFT 的 forbidden_modules

全参 SFT 用户常误以为"全参 = 字面意义上所有参数都训"。实际 _setup_full_tuning（adapter.py:38–55）还是有 forbidden_modules 排除：

所以 VLM 全参 SFT 默认只训文本侧 + projector；想让 vision tower 也一起训，必须显式 freeze_vision_tower: false。

6.13 freeze 微调的三种范围选法

_setup_freeze_tuning（adapter.py:57–139）按 freeze_trainable_layers 的正负号决定意义：

额外可调整：freeze_extra_modules 加额外要训的模块（layer norm / embedding scale 等）；freeze_trainable_modules 指定每层内训哪些子模块（all / mlp / self_attn）。

6.14 SFT 调优经验清单