我自己写的一份 QLoRA 微调教程，目标很具体：让一个没有显卡的人，在 Colab 免费层的 T4（15GB 显存）上，把”训练一个微调模型 → 合并权重 → 量化成 GGUF 能本地跑”这整条链路走通一遍。
写教程和写能跑的代码是两件事。网上能跑的 QLoRA 脚本很多，但大多是”复制执行即可”，出了问题你不知道从哪查。我这份的取舍是优先把每个选择的「为什么」讲透，代码反而是次要的。
一个我觉得有用的小设计：三档标注
教程里每段代码都打了标签：
[必须改]——每次用都得按你的情况改（比如数据集路径、模型名）；[不用改]——固定逻辑，直接复制；[可选改]——有默认经验值，理解含义后按需调。
这个标注解决了新手最大的痛点：面对一段长代码，不知道哪些是骨架、哪些是该填的空。把”该动的”和”别碰的”分开，照着走就不容易错。
把原理讲到能自己排查
教程开头先回答三个”为什么”，因为不理解这些，出问题时根本无从下手：
为什么用 LoRA 不全量微调。 Qwen2.5-3B 有 30 亿参数，光模型权重 float16 就 6GB，加上梯度和优化器状态，全量微调要 40GB+，T4 的 15GB 装不下。LoRA 的思路是不动原权重，在旁边插两个小矩阵 A、B，只训这俩，训练完把结果加回去：
W_new = W_original + (alpha / r) × A × B实际只训约 0.6% 的参数，显存从 40GB 压到 6GB 以内，效果接近全量。
r、alpha、dropout 怎么设。 这三个参数我用一张表讲清楚含义和经验值——r 控制表达能力（数据少用 8/16，数据多用 32/64），真正的缩放比例是 alpha/r，dropout 防过拟合。不是甩一组默认值，而是说清楚什么时候该往哪调。
三阶段闭环：很多教程只讲第一段
大多数 QLoRA 教程到”训练完得到一个 adapter”就停了，但那东西没法直接用。这份把链路补完整：
- QLoRA 训练——得到 LoRA adapter；
- 权重合并——把 adapter 合回基座，得到一个完整模型；
- GGUF 量化——转成 GGUF 格式量化，这样才能在 llama.cpp / Ollama 里本地跑，甚至 CPU 推理。
只有走到第三步，“微调一个能在自己电脑上跑的模型”这件事才算真的闭环。
还包含的实用部分
- 5 个高发错误：把新手最容易撞的坑集中列出来，配怎么排查。
- 换数据集 / 换模型怎么改：两个独立附录，把”这套流程怎么迁移到你自己的任务”讲明白。
- 参数调优速查：常用参数的快速参考。
- Colab 里怎么快速测 GGUF 模型：验证量化后的模型是否还正常。
小结
这份教程对我自己也是一次梳理——把 QLoRA 从”会跑”变成”讲得清每一步为什么”。能讲清楚，才说明真的懂了。它现在是我几个仓库里 star 最多的一个，说明”把原理讲透 + 标清哪里该改”这个取舍，对真正想学的人是有用的。