PythonLoRA/QLoRA微调实战教程

本文深入解析了Python中LoRA/QLoRA高效微调的关键实操细节，直击新手最易踩坑的四大核心问题：target_modules必须严格匹配不同模型（如LLaMA、Phi-3、Qwen2）的实际模块命名，否则训练瞬间崩溃；bnb_4bit_compute_dtype需按GPU型号精准选择（A100/H100用bfloat16，RTX3090/4090仅支持float16），且必须与Trainer混合精度设置完全一致；prepare_model_for_kbit_training务必在get_peft_model之前调用，顺序错误将导致梯度消失和loss突变；合并权重时必须先model.eval()再merge_and_unload()，导出fp16还需额外to(torch.float16)，否则保存的是不可直接加载的量化状态——每一步都附带原理说明、报错溯源与可验证的检查方法，助你避开玄学报错，稳定跑通全流程。

LoRA 微调时 target_modules 怎么选才不报错

选错 target_modules 是 LoRA 最常见的崩溃原因——模型加载不报错，但训练一启动就提示 KeyError: 'xxx' 或 Module not found。根本原因是 Hugging Face 的 peft 库只对模块名做字符串匹配，不自动适配不同模型结构。

• LLaMA / Mistral 系列（LlamaForCausalLM）：固定用 ["q_proj", "k_proj", "v_proj", "o_proj"]；加 "gate_proj" 和 "up_proj" 能提升效果，但必须确认模型确实有这些层（比如 LLaMA-3 有，LLaMA-2 没有 gate_proj）
• Phi-3 / Gemma：必须包含 "q_proj", "k_proj", "v_proj", "o_proj"，"down_proj" 可选；漏掉 o_proj 会导致梯度无法回传到注意力头
• 别硬套教程里的列表：用 model.named_modules() 打印前 20 行，搜 "proj" 看实际名字；有些模型（如 Qwen2）的 v_proj 实际叫 value_proj
• QLoRA 下如果开了 load_in_4bit=True，target_modules 必须在量化前就确定——改了列表再 reload 模型会触发 RuntimeError: Cannot re-initialize CUDA in forked subprocess

QLoRA 训练中 bnb_4bit_compute_dtype 设成 torch.float16 还是 torch.bfloat16

这个参数不决定显存占用，只影响计算精度和硬件兼容性。设错不会报错，但可能让 loss 飙升或收敛变慢。

• A100 / H100：优先用 torch.bfloat16，矩阵乘更稳，尤其 batch size > 4 时；float16 在长序列上容易 underflow
• RTX 3090 / 4090：只能用 torch.float16，bfloat16 不被原生支持，强行设会静默退化为 float32，显存暴涨且速度不增
• 混合精度训练（fp16=True 或 bfloat16=True 在 Trainer 中）必须和 bnb_4bit_compute_dtype 一致，否则 Trainer 会跳过某些层的梯度缩放，loss 曲线锯齿状抖动
• 检查方法：print(model.base_model.model.model.layers[0].self_attn.q_proj.weight.dtype) —— 输出应和你设的 compute_dtype 完全一致

prepare_model_for_kbit_training 必须在 get_peft_model 之前调用

顺序反了会导致梯度全部为 None，训练几步后 loss 突然变成 nan，但不报错。这是因为 prepare_model_for_kbit_training 做了两件事：插入梯度检查点（gradient_checkpointing_enable）和重置 layernorm 的 dtype；如果 LoRA adapter 已经 wrap 了模块，再调用它就失效了。

• 正确顺序只有这一种：model = prepare_model_for_kbit_training(model) → peft_config = LoraConfig(...) → model = get_peft_model(model, peft_config)
• 常见错误：在 AutoModelForCausalLM.from_pretrained 后直接 get_peft_model，忘了 prep；或者把 prepare_model_for_kbit_training 放在 Trainer 初始化之后
• 如果你用了 load_in_4bit=True 但没调这个函数，model.forward() 能跑，Trainer.train() 会卡在第一个 step，GPU 显存占满不动，nvidia-smi 看不到计算活动

微调后合并权重时 model.merge_and_unload() 报 RuntimeError: can't detach tensor that requires grad

这说明模型还在训练模式下强行合并，PyTorch 拒绝破坏计算图。不是 bug，是保护机制。

• 必须先 model.eval()，再 model.merge_and_unload()；如果用 Trainer，要在 Trainer.train() 结束后手动加这行
• QLoRA 合并后默认仍是 4-bit 权重，想导出为 fp16 模型，得额外调 model = model.to(torch.float16)，否则 save_pretrained() 存的是量化状态，下次 load 会报 AttributeError: 'int4' object has no attribute 'shape'
• 合并后验证：用 model("Hello") 跑一次前向，输出 logits 形状应和原始模型一致；如果 shape 少一维，说明 merge_and_unload 没生效，大概率是忘关 eval 模式
• 小模型（model.save_pretrained("merged") + from_pretrained(..., device_map="auto") 加载，避免合并时 OOM

事情说清了就结束。最常卡住的地方不是代码写错，而是模型状态（train/eval）、量化配置、LoRA 插入顺序这三者之间互相咬死——调一个，另外两个必须同步确认。

以上就是《PythonLoRA/QLoRA微调实战教程》的详细内容，更多关于的资料请关注golang学习网公众号！