大模型微调实战：Transformers、PEFT与Axolotl五案例拆解

干这行久了你会发现，真正推动大模型落地到业务里的，往往不是从零预训练，而是微调。而说到微调，绕不开的就有三样东西：HuggingFace的Transformers，它把模型架构、数据 pipeline、Trainer 训练循环这些东西全包了；PEFT，它让低成本微调从"可能"变成了"默认选项"；还有Axolotl，它把微调配置化、模板化，让你不用天天跟训练代码死磕。

这篇文章我打算用一个比较实战的角度来写：我把过去一年多在不同项目里验证过的五类微调案例完整拆开，分别是通用中文LLM的LoRA微调、多模态视觉语言模型微调、目标检测模型微调、函数调用微调，以及基于Axolotl的全流程训练。每个案例都会给出我的选型理由、核心配置、训练过程中的真实数据和踩坑记录，而不是给你一堆大而全但落不了地的概念。如果你正准备用自己的数据微调模型，这篇文章可以直接当一份操作手册来用。

1. 微调为什么绕不开这三件套

先说一个很多新手容易搞混的问题：Transformers、PEFT、Axolotl 到底各管哪一段？

在我的理解里，它们不是同一层的东西。Transformers 是最底层的生态基座，提供模型结构、Tokenizer、Trainer、数据集工具和分布式训练支持；PEFT 是在这个基座上长出来的"节省显存和算力"的方案库，LoRA、QLoRA、Prefix Tuning、Prompt Tuning 这些都在里面；Axolotl 则是在更上层，它把 Transformers 的训练流水线和 PEFT 的配置封装成了一份 YAML 配置，让你不用写一堆样板代码。

如果做个类比的话：Transformers 像是给你一套发动机零件，PEFT 是省油改装套件，Axolotl 则是把整车装配好只留一个方向盘给你。日常工作中，我一般是这样选的：

• 需要精细控制训练过程、研究模型内部行为、或者需要写自定义训练循环的时候，直接裸用 Transformers + PEFT；
• 数据格式比较标准、模型也比较常见（Qwen、Llama、Mistral 这一挂）、想快速跑通实验的时候，直接上 Axolotl；
• 生产流水线里要反复迭代、要接自己的评估逻辑的时候，我会把核心训练逻辑抽象成 Python 脚本，基于 Transformers 的 Trainer 封装，PEFT 作为可插拔配置。

这也是为什么我建议你哪怕只用 Axolotl，也至少要把前两者的底层逻辑搞清楚。否则一旦配置报错或者效果不符合预期，你连排查的方向都没有。

还有一个容易被忽视的点：微调并不是"把模型放在你的数据上再训一遍"这么简单。它包含数据清洗、格式转换、模板适配、超参选择、评估验证一整套流程。很多团队微调效果差，问题往往出在数据上，而不是模型或代码上。这也是我在这篇文章里会在每个案例都强调数据格式和数据处理的原因。

2. 案例一：通用中文LLM的LoRA微调，从数据集到评估

2.1 业务背景与选型理由

先说第一个案例的原始需求：某个垂直行业客户有一批内部的问答数据，想让模型学会"用他们的口径回答问题"。数据量不大，大概三万条左右，全部是中文。预训练模型选的是当时的中文能力比较均衡的 Qwen2.5-7B-Instruct。为什么选 7B 而不是更大的 14B/72B？原因很简单：客户只有一张 A100-80G，而且对推理延迟有要求，7B 量化后部署在 V100 上也能跑得动，14B 的 FP16 推理延迟已经让他们觉得"有点笨重"了。

微调方法选了 LoRA。这里有个很多人会问的问题：既然有 80G 显存，为什么不干脆全参数微调？我的回答是：不是显存放不下，而是全参数微调的稳定性、灾难性遗忘控制、以及后续迭代成本都不如 LoRA 可控。尤其是只有三万条数据的情况下，全参数微调非常容易过拟合，把模型原有的通用能力破坏掉。LoRA 相当于在原始权重旁边加了一条"低秩旁路"，训练时只更新旁路参数，原始权重不动。这样模型在学会新知识的同时，大规模预训练得到的能力基本不会被冲掉。

LoRA 的原理可以一句话说清楚：对于权重矩阵 W，它不直接更新 W，而是学习一个低秩分解 W + ΔW ≈ W + BA，其中 B 和 A 是两个小矩阵，秩为 r。训练完成后，把 BA 合并回 W 就能得到微调后的模型。因为 B 和 A 参数量远小于 W，所以显存和训练时间都大幅下降。QLoRA 则更进一步，先把 W 用 4bit NF4 量化存起来，训练时反量化到 bf16 计算梯度，进一步省显存。

2.2 数据处理与模板设计

数据是客户给的 Excel，两个字段：问题、答案。这里面就有很多坑。最开始我们直接把"问题\n答案"喂给模型，效果极其不稳定，模型经常生成一堆无关内容。后来才意识到，指令微调不是把文本塞进去就完事，而是要让模型学会"指令-输入-输出"的映射关系。

我最终把数据转换成了 Alpaca 格式的三段式：

{ "instruction": "请根据客户提供的产品知识回答下面的问题，回答要简洁、准确，不得编造。", "input": "XX产品支持的最大并发连接数是多少？", "output": "XX产品在标准配置下支持的最大并发连接数为 10000。" }

然后通过 Chat Tokenizer 的模板，把这条数据渲染成对话序列：

<|im_start|>system 请根据客户提供的产品知识回答下面的问题，回答要简洁、准确，不得编造。<|im_end|> <|im_start|>user XX产品支持的最大并发连接数是多少？<|im_end|> <|im_start|>assistant XX产品在标准配置下支持的最大并发连接数为 10000。<|im_end|> <|im_end|>

这里强烈建议直接用tokenizer.apply_chat_template()来渲染，而不是自己拼接字符串。因为不同模型的对话模板差异很大，Qwen 和 Llama 的模板格式就完全不一样，手写容易写错，一旦模板错误，微调出来的模型回复会很奇怪。

为了让模型在训练时不把 system 和 user 部分的 loss 也算进去，我用了 PEFT 训练里标配的DataCollatorForCompletionOnlyLM，只保留 assistant 部分作为标签。没有这一步，模型会在用户输入部分也去计算损失，学出来会很"啰嗦"。

2.3 训练配置与超参心得

训练代码核心部分用的是 Transformers 的 Trainer，模型用 PEFT 包成 LoRA 可训练结构。具体配置如下：

from transformers import ( AutoModelForCausalLM, AutoTokenizer, Trainer, TrainingArguments, DataCollatorForCompletionOnlyLM ) from peft import LoraConfig, get_peft_model, prepare_model_for_kbit_training model_name = "Qwen/Qwen2.5-7B-Instruct" model = AutoModelForCausalLM.from_pretrained( model_name, torch_dtype="auto", device_map="auto" ) tokenizer = AutoTokenizer.from_pretrained(model_name) lora_config = LoraConfig( r=16, lora_alpha=32, target_modules=["q_proj", "k_proj", "v_proj", "o_proj", "gate_proj", "up_proj", "down_proj"], lora_dropout=0.05, bias="none", task_type="CAUSAL_LM", ) model = get_peft_model(model, lora_config) training_args = TrainingArguments( output_dir="./qwen-lora-ckpt", per_device_train_batch_size=2, gradient_accumulation_steps=16, learning_rate=2e-4, lr_scheduler_type="cosine", warmup_ratio=0.03, num_train_epochs=3, logging_steps=10, save_strategy="epoch", bf16=True, gradient_checkpointing=True, remove_unused_columns=False, )

几个参数我说下我的理解：

• r=16是一个比较中庸的选择。r 越大，可训练参数量越多，拟合能力越强，但过拟合风险和显存占用也越高。对于三万条数据，8 到 16 是甜点区间；如果你有几百万条高质量数据，可以试着上 32 或 64。
• lora_alpha=32，也就是缩放系数是 r 的两倍。这个比例（alpha/r）决定 LoRA 旁路最终对原始权重的扰动强度。实际经验是，在数据量不是特别大的情况下，alpha 不要设太高，否则很容易把模型"带偏"，输出风格突变。
• target_modules我加了所有注意力投影和 MLP 的投影矩阵。有人只改 q_proj 和 v_proj，那样参数少、效果也还凑合，但如果你要让模型学习特定领域的表述习惯和知识，把 gate_proj/up_proj/down_proj 也加进去效果会明显更好，因为 FFN 层才是知识存储的主要地方。

梯度累积 16、batch size 2，实际等效 batch size 是 32。这个等效 batch size 对 7B 模型来说比较稳妥，太大容易收敛不稳定，太小则 loss 震荡。学习率 2e-4 是 LoRA 微调非常常见的起点，如果发现 loss 不稳定，先降到 1e-4 再试。

2.4 训练中遇到的显存与稳定性问题

这个案例里踩过一个比较大的坑：一开始没有开gradient_checkpointing，7B 模型在 batch size 2 的情况下，FP16 训练显存大概会吃掉 55-60G 左右。虽然 A100 能扛住，但一旦序列长度从 512 涨到 1024，显存立刻逼近极限。打开 gradient checkpointing 之后，显存降到 35G 左右，代价是训练速度慢 20% 到 30%。对于大多数微调任务，我建议直接开，因为省下的显存可以让你把序列长度拉长、batch size 加大，收益远大于那点速度损失。

还有一个非常隐蔽的问题：remove_unused_columns。如果数据集里除了 instruction/input/output 之外还有其它列，Trainer 默认会把"模型 forward 里用不到的列"删掉。但当我们用自定义的 tokenize 函数时，有时候会依赖这些列做后续处理，一旦被删就会出现奇怪的报错。所以自定义数据集的场景下，建议直接设成False。

2.5 效果评估：不要只看Loss

训练完看 loss 曲线下降到 0.7 附近，感觉一切正常。但真正验证的时候发现，模型在回答某些问题时喜欢在结尾额外加一句"如有其他问题，请随时咨询"。这个现象在数据里并不明显，但模型自己"学会"了这种客服腔。这其实是过拟合信号的一种：模型过度模仿了训练数据里的句式特征。

我的评估方式是：在训练集之外的 500 条测试数据上做生成，然后人工打分，从准确性、格式规范性、幻觉程度三个维度给 1-5 分。另外还会拿一批训练前就表现良好的通用问题去测试，看看通用能力有没有下降。最后把 LoRA 权重合并回基座模型，导出成完整模型权重，然后转成 AWQ 4bit 给生产环境部署。这一步合并权重非常重要，因为单独加载 LoRA 适配器在服务环境下会增加加载失败的风险，尤其是如果你用的推理框架对 PEFT 适配器支持不完整的时候。

3. 案例二：多模态VLM微调，视觉语言模型也能低成本改造

3.1 为什么 VLM 微调和纯文本不一样

第二个案例来自一个文档解析项目：需要让模型理解特定行业的票据截图，输出结构化 JSON 字段，比如单据类型、金额、日期、发票号。一开始想直接让 GPT-4V 做，但数据合规要求数据不能出内网，所以必须本地部署。选型最后落到了 Qwen2-VL-7B 上，因为它在中文 OCR 和文档理解方面表现不错，7B 的体量配合 QLoRA 也能在单卡上训得动。

VLM 微调和纯文本 LLM 的一个关键区别：图像编码器（Vision Tower）和视觉-语言连接层（Projector）是否要被冻结。很多教程默认冻结视觉分支，只训练语言模型部分的 LoRA。这样做的好处是显存占用低、训练速度快，而且对于大多数"理解类"任务，预训练好的视觉编码器已经够用了。但在票据、截图、报表这种文字密度很高的图像上，我实际对比下来，把language模块和projector都加上 LoRA，比只训练语言模型的效果要好不少，因为视觉特征和文本特征之间的对齐方式需要针对领域做调整。

不过这里不建议直接对视觉塔本身加 LoRA，原因一是显存会涨，二是图像编码器一旦被扰动太狠，会产生视觉特征退化的问题。我见过有人把visual模块的 LoRA 设得太大，结果模型对图像的感知明显变差，反而还不如不训。

3.2 数据准备：LLaVA格式与多轮对话

VLM 微调数据格式比较成熟的是 LLaVA 格式：一张图对应一条或多轮对话。数据标注是用 Label Studio 做的，标注员框出票据区域，填写对应的结构化字段。后期通过脚本把这些标注转成如下格式：

[ { "id": "invoice_0001", "image": "images/0001.jpg", "conversations": [ { "from": "human", "value": "请提取这张单据中的发票号、金额、开票日期和销售方名称，以JSON格式输出。" }, { "from": "gpt", "value": "{\"invoice_id\": \"12345678\", \"amount\": \"1,234.56\", \"date\": \"2025-03-18\", \"seller\": \"某某科技有限公司\"}" }, { "from": "human", "value": "这张单据属于什么类型？" }, { "from": "gpt", "value": "增值税普通发票" } ] } ]

注意图片路径是相对路径，实际训练时需要把 base_path 拼上，还需要把图像解码成像素值，转换成模型期望的尺寸。Qwen2-VL 对图像输入会做动态分辨率切分，也就是说它会把大图切成若干小块，每块再过 ViT。这块逻辑 Transformers 官方已经实现了，直接用AutoProcessor处理即可，不要自己手动 resize 成固定尺寸，否则会丢失票据上小字号文字的信息。

在处理数据时有个常见误区：把所有图片都 resize 成 448x448。对于文档票据这种密集文字图像，暴力压缩会让很多信息直接丢失。建议保留原始分辨率，靠模型自带的切图机制处理。如果训练时显存不够，优先减小 batch size，而不是降低图像分辨率。

3.3 训练方案与关键细节

模型加载使用AutoModelForVision2Seq，然后照例用 PEFT 包 LoRA。这里我只选择性地把 Qwen2VL 里的language_model（语言解码器）和merger（视觉融合层）加入 LoRA target_modules。训练数据的 padding 策略也和纯文本不同：图像 token 占据了序列长度的很大一部分，所以训练时要让模型忽略图像 token 的损失，这个AutoProcessor会自动处理好，但我们拿到数据后要检查一下labels是不是已经正确屏蔽了图像部分。

超参数和案例一类似，但我把学习率降到了 1.5e-4，因为多模态任务比纯文本任务更敏感，学习率稍微高一点就会出现 loss 突然飙升的情况。另外我把 epochs 调到了 4，因为票据数据比较规则，4 轮之后模型基本能学会输出固定 schema。这里有张我实际跑实验时记录的对比表：

从表格能看出，全量微调和"语言模型 + Projector LoRA"的差距已经很小，但显存和训练成本差别巨大，所以生产上我最终选了第二种方案。

3.4 常见的VLM微调失败模式

多模态微调的失败模式比纯文本更隐蔽。我总结几个高频问题：

第一，图像 token 的 attention mask 没弄对。有些框架在组装 batch 的时候会处理不当，导致模型在图像部位也产生损失，训练 loss 会很低，但推理时表现混乱。验证方法是把第一条训练样本的 labels 打印出来，把被屏蔽的位置和图像 token 位置对比一下，确保它们一致。

第二，图片和文本没有对齐。我在早期做数据 pipeline 时，有一次把图片文件名的排序和对话列表的排序搞错了，结果训练时模型一直在看"A图回答B图的问题"，训练 loss 还诡异地降得很低。这是因为模型强大的拟合能力让它强行记住了这种错配关系，导致验证集上表现极差。解决方式是每次训练前做一个可视化抽样，把 image_path + conversations 呈现出来人工检查一遍。

第三，评估指标被 JSON 格式干扰。模型输出的 JSON 只要有一个字段名不对，字符串匹配层级的准确率就会暴跌。所以我后来评估时先尝试把输出 parse 成 JSON，再对关键字段单独做匹配，这样能更好反映模型真实能力。

4. 案例三：目标检测类微调，用PEFT思路改Deformable DETR

4.1 目标检测模型的微调现状

第三个案例和前面两个不太一样，因为它不是生成式模型，而是判别式的目标检测模型。项目背景是工业质检场景里需要检测一类非常细小的表面缺陷，这类缺陷和常规公开数据集里的目标差异很大，所以必须做领域微调。模型选型上，我对比了 YOLO 系列和 Deformable DETR 系列。最终选了 Deformable DETR，原因是客户对召回率要求极高，而且缺陷形态多变，DETR 类模型在端到端检测里对形态变化的鲁棒性更好。

可能有人会问，Deformable DETR 不是和 PEFT 八竿子打不着吗？目标检测模型怎么做 LoRA？其实 LoRA 的本质是"低秩增量更新"，它并不绑定语言模型，只要网络里有权重矩阵，就可以套用这个思路。HuggingFace 的transformers仓库里就有 Deformable DETR 的实现，PEFT 的LoraConfig也可以用在它的 backbone 和 encoder/decoder 的 linear 层上。

不过这里我必须说一个反直觉的经验：对于 Deformable DETR 这种模型，直接给 backbone 加 LoRA 收益并不大，真正的瓶颈在 encoder 里的 multi-scale deformable attention。这个模块负责在多尺度特征图上做可变形采样，是最能吸收领域特征的模块。因此我把 LoRA 加在了 multi-scale deformable attention 的三个线性投影（sampling_offsets、attention_weights 和 value_proj）上。

4.2 数据组织与损失函数的变化

目标检测数据是标准的 COCO 格式：一张图对应一个 JSON 里的annotations列表，每个标注包含 bbox 和 category_id。这里的数据清洗比较花时间，因为工业缺陷样本太少。我做了三类增强：随机裁剪、马赛克、以及"负样本增强"——即把没有缺陷的正常样本也混入训练集，让模型学会区分"没有目标"的情况。这一步对降低误检率非常关键。

训练时我们不使用 PEFT 封装的 Trainer，因为目标检测的损失函数是分类损失加边界框回归损失的组合，和语言模型的交叉熵完全不同。Deformable DETR 里每个物体查询（object query）还会通过匈牙利匹配算法和 GT 做一对一的匹配，这套逻辑 Transformers 的检测 pipeline 已经写好，我只需要在它的基础上把指定模块替换成 LoRA 版本即可。

我实现了一个很简单的PeftDeformableDetr包装类：在初始化时构建一个LoraConfig，然后使用get_peft_model包装整个模型，但在配置里用正则表达式把 target_modules 指向上面说的那几个层。pipeline 其余部分保持不变。实际训练超参如下：

• 输入分辨率：1333x800（保持 COCO 默认）
• 优化器：AdamW，初始学习率 1e-4
• 训练 36 个 epoch，前 10 个 epoch 冻结 backbone，之后解冻 backbone（但 backbone 不加 LoRA）
• Batch size：每卡 1，8 卡并行
• 学习率调度：StepLR，在第 24、33 个 epoch 降一次

在 500 张标注图片的小数据集上，这个方案能把目标类别 mAP@0.5 从预训练权重的 42.3% 提升到 78.6%。全量微调基线大概是 81.2%，但训练时间长了将近三倍，而且需要更多显存。考虑到只有 500 张数据，78.6% 的表现已经足够支撑产线试用。这里可以明显看到 PEFT 思路的普适价值：它不光是 NLP 领域的省显存技巧，在视觉模型上同样适用。

4.3 踩坑：多尺度特征下的低秩扰动

这个案例里面最值得记录的坑是：给sampling_offsets加 LoRA 时，如果秩设得太大（比如 r=32），模型训练前期 loss 会非常稳定，但到中后期出现剧烈震荡。原因是sampling_offsets输出的是采样点坐标偏移量，它对数值太敏感，低秩旁路带来的扰动如果超过一定幅度，会直接破坏特征采样的稳定性。后来把 r 调到 8、lora_alpha 调到 16，问题立刻缓解。

另一个很容易忽略的问题是不同模块 LoRA 应该单独设置 dropout。我在实验里对 attention_weights 相关投影用 0.1 的 dropout，对 value_proj 用 0.05，因为采样权重对随机失活更敏感，dropout 太高会让模型在训练初期很难稳定匹配到正确的特征点。这种细粒度控制用 PEFT 的默认配置做不了，需要预先拆分模块、分别 wrap，虽然代码量增加了一些，但换来的稳定性提升非常值得。

4.4 检测类模型微调的效果评估

检测模型评估不能只看 mAP，还要看类别维度上的召回率和误检数。工业质检场景里，漏检的代价远大于误检，所以我会额外关注每个类别在低置信度阈值下的召回率曲线。另外还有一项很实际的评估：把模型在产线实拍视频上跑一段时间，统计每小时的误报警次数。因为训练集来自不同光照条件，如果模型在某一特定光照下频繁误检，通常需要补充该场景的数据做增量训练，而不是盲目调阈值。

基于这个项目的经验，我后来做 SAM 系列分割模型微调时也套用了同样的思路——把 PEFT 加在 prompt encoder 和 mask decoder 的线性层上，冻结 image encoder。分割任务里 image encoder 是通用视觉特征的顶梁柱，冻结它能最大程度保留模型对不同物体的泛化能力。这也是为什么我一直强调"不是所有层都需要被微调"——找到任务的瓶颈模块，只在该动的地方动，往往才是最优解。

5. 案例四：函数调用微调，让模型真正学会调用工具

5.1 函数调用微调的本质问题

第四个案例来自一个 agent 项目：我们希望在 agent 场景里让模型根据用户指令选择函数并生成调用参数，而不是靠 prompt 硬撑。当时实测 ChatGPT 的 function calling 很强，但我们的模型需要私有部署，而且需要调用的是内部 API，函数数量多、参数 schema 复杂，用通用模型 + 工具定义的方案经常会生成非法参数。所以就规划了一个专门的函数调用微调。

这里需要先理清一个概念：函数调用微调不是让模型"学会写代码调 API"，而是让模型学会"在给定工具清单和用户请求时，输出符合特定 schema 的结构化内容"。本质上是把"意图识别 + 参数抽取 + 映射到工具定义"这三个任务压到一个模型里。所以数据质量的关键不在代码量，而在工具描述的规范性和对话场景的多样性。

训练数据格式我采用了类 ShareGPT 的多轮格式，并在每条数据开头附加了工具说明段落：

{ "messages": [ { "role": "system", "content": "你是一个智能助手，可以根据用户指令调用以下工具：\n" } ] }

实际上更常见的做法是使用 OpenAI 风格的tools字段，然后通过模板渲染成模型能理解的文本。Qwen 系的模型在后续版本中已经支持了原生 tool calling token（比如<tool_call>），微调时用这些特殊 token 能显著提升输出的结构稳定性。

5.2 数据合成与数据清洗

函数调用微调最大的难点是标注数据太贵。3 万条高质量的人写对话要耗费大量人力。我当时的做法是分两步走：

第一步，从线上日志里捞真实请求，但去掉涉及隐私的参数，再通过已部署的大模型做一轮伪标注。具体做法是：把真实用户问题 + 候选工具列表 + 期望输出 schema 喂给一个能力强的大模型，让它生成"用户问题→函数名→参数 JSON"的映射，然后人工抽检修正。这一步能把标注成本降到原来的三分之一。

第二步，做负样本增强。真实的 agent 场景里，模型经常会面对"没有合适工具可以调用"的情况，如果训练数据里全是"用户一问、模型一答、调用工具"，模型就会养成"必须调用某个工具"的坏习惯。所以我在数据里混入了大约 15% 的负例——用户请求明明不需要调用工具，模型应该直接回答。这一步对防止幻觉非常有效。

清洗时还有个关键点：工具描述必须和推理时保持一致。很多人训练时用一套工具 schema，推理时又换了另一套，字段命名和描述不一致，模型性能会直线下降。我们在训练和推理环境里维护了一个完全相同的tools.py，每次 revision 都通过 CI 校验，确保两侧描述一致。

5.3 训练细节：让LoRA专注在"格式学习"上

函数调用微调我用的基座是 Llama-3.1-8B-Instruct，LoRA 秩设得比较小（r=8），因为函数调用任务里模型主要学的是格式转换和 schema 映射，不需要记忆大量新知识。target_modules 配置和案例一基本一样，但我额外加了lm_head。你可能会觉得加lm_head很奇怪，但在函数调用场景里，输出层对特殊 token 的预测分布影响很大，让 lm_head 也能被微调有助于模型学会输出<tool_call>这类专用 token。如果不加，模型偶尔会把方括号写歪、把 JSON 截断。

训练损失这里有一点要说明：labels只对 assistant 的回复部分计算损失。有些实现会把 system 里的工具描述也作为标签让学生去预测，这是不对的。工具描述在每次请求里都会提供，模型不需要背下来，只需要理解并遵循。如果让模型去预测工具描述，它会浪费大量模型容量在记忆固定文本上，反而影响对用户请求的理解。

5.4 函数调用效果评估与失败分析

评估函数调用不能只看"生成的内容能否被 JSON 解析"，还要看函数名是否正确、参数是否符合 schema、是否产生幻觉调用。我开发了一套启发式评估脚本：先把模型输出里<tool_call>包围的内容抽取出来，逐个字段和 schema 比对类型、必填项、枚举值。然后统计四类指标：调用准确率、参数合法率、不必要调用率、必要调用漏调率。

头几版模型训练完之后，调用准确率已经到 90% 以上，但在复杂参数嵌套场景（比如一个参数是数组，数组元素是对象）下，参数合法率只有 80% 出头。排查发现，问题出在训练数据里嵌套 schema 的样本太少，大模型伪标出来的结果本身就不够规范，导致模型学到了一些错误对齐。后来我把这些复杂样本单独抽出来，做了人工修正，把嵌套场景在训练集里的占比从 5% 提到 20%，参数合法率涨到了 94%。这说明这类任务里，"难样本覆盖度"比"总体样本量"更重要。

6. 案例五：Axolotl零配置微调，一份YAML跑通全流程

6.1 什么时候从手写代码切换到Axolotl

前四个案例都是手写 Transformers + PEFT 的训练脚本，但这不意味着我每次都这么干。当训练任务比较标准、数据已经是 instruction 格式、基座模型是生态内常见模型时，我会直接使用 Axolotl。它能帮我把很多容易出错的细节自动化掉：比如 sequence packing、flash attention 配置、数据集格式转换、以及 optimizer 和 scheduler 的推荐组合。

Axolotl 本质上是一个封装层，它把 Transformers 的Trainer、PEFT 的LoraConfig/QLoraConfig、以及各种数据集格式整合进一个 YAML 配置文件里。同一份配置，在单卡还是多卡、bf16 还是 fp16、是否使用 flash attention 之间切换非常方便，这让实验管理变得很干净。

我把它用在了一个 UIE 信息抽取模型迁移的项目上：要把一个抽取模型从旧领域迁到新的合同审查领域。之前用 PaddleNLP 的 UIE 微调脚本，虽然也能跑，但每次换模型、换参数都要改 Python 代码，协作效率很低。后来切换到 Axolotl，把数据和配置分开管理，任何团队成员都能通过修改几行 YAML 来跑一个新实验。

6.2 一份可复用的Axolotl配置与参数解读

下面是一份我实际使用的 Axolotl 配置，模型是 Qwen2.5-7B-Instruct，用 QLoRA 微调：

base_model: Qwen/Qwen2.5-7B-Instruct model_type: AutoModelForCausalLM tokenizer_type: AutoTokenizer load_in_8bit: false load_in_4bit: true strict: false datasets: - path: ./data/train.jsonl type: alpaca train_on_split: train dataset_prepared_path: ./data/prepared val_set_size: 0.05 output_dir: ./outputs/qwen-lora-axolotl sequence_len: 2048 sample_packing: true pad_to_sequence_len: true 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 train_on_inputs: false group_by_length: false bf16: auto fp16: false tf32: true gradient_checkpointing: true gradient_accumulation_steps: 8 per_device_train_batch_size: 2 per_device_eval_batch_size: 2 num_epochs: 3 warmup_ratio: 0.03 learning_rate: 2e-4 lr_scheduler: cosine optimizer: adamw_torch logging_steps: 10 eval_steps: 100 save_steps: 500 save_total_limit: 2

这里最容易被忽略的是lora_modules_to_save。它的意思是：除了 LoRA 旁路更新的参数之外，还有哪些模块需要被完整保存和更新。默认情况下embed_tokens和lm_head是不在 LoRA 范围内的，因为它们本身就是巨大的 embedding 矩阵，加 LoRA 会导致参数量剧增。但在中文任务里，如果词表扩展了新词（比如领域术语被拆成了 unk），就不得不解冻 embedding。每一种微调任务调这个字段的意义不同，但你必须知道自己为了什么而调。

sample_packing: true会在不改变数据顺序的前提下把多个短样本拼接到一个序列里，这样能显著减少 padding 带来的算力浪费。但注意 pack 之后 attention mask 会被重排，可能导致模型在样本边界处产生"跨样本注意力泄漏"。Axolotl 处理这个问题的方式已经比较成熟，但如果你的数据里存在大量非常长的上下文，建议关闭 packing，以免影响注意力计算。

6.3 使用Axolotl时的数据格式坑

Axolotl 支持的数据格式很多：alpaca、sharegpt、chatml、ultrachat等等。每种格式对应不同的字段解析规则。我见过很多人把 Alpaca 格式的数据文件扩展名写成.json，但文件里其实是多行 JSONL；或者反过来。Axolotl 会静默跳过部分无法解析的行，导致训练集实际只加载了一半，模型效果自然很差。

所以每次启动前，我会跑一句python -m axolotl.cli.preprocess config.yml，然后去看预处理后保存的数据目录里的dataset_info.json，确认num_examples和源文件行数对得上。这一步很重要，能帮你避免"练了一个失效模型"这种尴尬。

另外val_set_size: 0.05是从训练集里随机抽 5% 做验证。如果原始数据本身是按某种顺序排列（比如按类别聚集），随机抽样得到的验证集可能和训练集分布不一致。我在合同审查数据上就遇到过这种情况：数据按合同类型排序，随机抽样导致某些类型的合同在验证集中过多或过少。后来我把val_set_size改成按数据文件的末尾片段切分，效果才稳定下来。Axolotl 支持这种设置，但需要在配置里改一行val_set_size为实际文件路径。具体 API 每个版本略有差异，用之前建议查一下当前版本的文档。

6.4 从Axolotl导出并部署模型

Axolotl 训练完的输出目录是 HuggingFace 格式的 checkpoint，包含 adapter_model.bin 和 adapter_config.json。合并权重可以用它自带的 CLI 工具，也可以直接用 PEFT 的merge_and_unload()。我自己习惯用一个独立的导出脚本，把 base model + adapter 合并成完整模型，然后传给 vLLM 做部署测试。

这个导出步骤里要注意的是：合并前要确保微调和导出时的torch_dtype一致，否则会出现轻微的数值偏差。在 7B 模型上这个偏差可能不明显，但在敏感的输出格式任务上，偶尔会有 token 采样差异。另外一个常见问题是：如果你在 Axolotl 里用了lora_modules_to_save，合并脚本也要能正确处理这些额外模块，否则导出的模型会丢掉 embedding 的更新，导致新词表永远无法生效。这个坑我踩过一次，排查了很久才发现是导出脚本没有读取modules_to_save配置。

7. 那些文档里不会写的微调经验

7.1 先用小模型快速验证流程

我现在的习惯是：数据到位之后，不直接拿 7B 甚至 14B 去训练。先用 0.5B 或 1.5B 的小模型跑通全流程——包括数据加载、预处理、tokenize、模板渲染、训练、合并、部署、评估。小模型跑一次只要十几分钟，能把 90% 的 pipeline bug 暴露出来。等流程稳定了，再换成大模型正式训练。这样做省下的时间，远比直接跑 7B 然后发现 loader 有 bug 要浪费时间少得多。

在我处理过的项目里，"数据格式有问题但没被发现"的概率远比想象中高。比如 instruction 字段为空、output 被截断、系统提示词混入训练标签等。小模型虽然能力弱，但对这些异常非常"诚实"——它学不出来好的效果，反而更容易暴露数据问题。大模型拟合能力强，可能硬生生把脏数据也背下来了，测试时你甚至分不清模型是真的学会了，还是在背答案。

7.2 显存不足时的第一优先级是序列长度，不是模型大小

很多人一遇到 OOM 就把模型换小一号，或者把 LoRA rank 调小。但实际上，对于大多数指令微调场景，sequence_len才是影响精度的首要因素。如果训练数据里经常有超过 1024 token 的长文档，而你把 sequence_len 设成 512，那所有长样本都会被截断，模型根本学不到完整上下文，换更大的模型也救不回来。我的建议是：先满足数据本身的长度需求，把 seq_len 设为 2048 或 4096；如果显存不够，再用 gradient checkpointing、量化、减小 batch size 来腾空间，而不是砍序列长度。

7.3 Warmup、学习率和过拟合的相互作用

LoRA 微调有很多超参，但最值得认真调的是学习率和 warmup。有过拟合倾向时，我通常不是先加 dropout，而是先降低学习率、多跑几个 epoch 看 loss 在验证集上的变化。LoRA 本身已经带了一定正则效果，所以 dropout 加太多反而让训练变得迟钝。warmup ratio 一般设 3% 就够，但如果数据非常脏或者任务和基座模型能力差距太大（比如让一个英文为主的模型学中文格式），我会把 warmup 提到 10%，给模型更长的时间去适应。

我在做函数调用微调时，曾经遇到过 loss 下降到 0.8 之后开始震荡的情况。当时以为是学习率太高，于是降到 5e-5，震荡确实消失了，但验证集上的调用准确率反而下降了。后来发现震荡的原因是数据里混入了一批工具描述特长的样本，它们的 loss 天然更高，和普通样本交替出现，曲线看起来就像震荡。处理方式是改成按长度 bucketing，让类似长度的样本在一个 batch 里，训练瞬间就稳定了。这个经验让我后来特别关注"训练样本长度方差对 loss 曲线的影响"。

7.4 微调后的模型必须重新跑一遍"通用能力回归"

这个建议我已经在多个案例里重复提到，因为它真的太重要了。微调前先准备一组覆盖面广的通用测试题——数学、常识、推理、翻译、写作各来几条，记录微调前的回答。微调完成后用相同的问题、相同的采样参数重新问一遍，逐条对比有没有明显退化。如果微调后模型在通用能力上大降，通常说明数据量太少或学习率太高，模型被"带偏"了。

我有一次在 7B 模型上做了函数调用微调，训练完发现模型在通用知识问答上的表现明显下降，尤其在数字计算题上错误率飙升。排查下来，是因为训练数据里有大量带 JSON 输出的样本，模型过度拟合了"输出 JSON"的模式，影响了正常的文本生成能力。后来我把训练集里通用问答数据的比例从 10% 提到 40%，问题就消失了。所以微调不是"只管领域数据"，通用能力保底数据同样要覆盖到。

7.5 训练记录和可复现性是你的安全网

最后说一个不那么"技术"但很实用的建议：每次训练跑完，把 YAML 配置、数据版本、代码 commit、loss 曲线、评估结果汇总成一条实验记录。我在团队里会强制要求每次训练实验都覆盖这几个字段：模型版本、数据集版本、LoRA 参数、学习率、全局 batch size、sequence_len、评估指标、部署状态。项目进行到第三个月时，这种记录的价值会变得非常大——你会频繁遇到"咦，上个月那个效果最好的版本是用了哪个 config 来的？"这种问题，没有实验记录就只能靠猜。

纯手写代码微调的项目，可以用一份train_config.json备份超参；Axolotl 项目则直接把最终运行的 YAML 保存到 checkpoint 目录里。麻烦是麻烦一点，但这是你后续迭代和说服团队"为什么这个方案有效"的最有力依据。

我自己一路实践下来的体会是：Transformers、PEFT、Axolotl 这三者的关系不是"选哪个"，而是"什么时候用哪个"。当你想快速验证想法、把数据流程跑通的时候，Axolotl 是最快的；当你需要精细控制训练细节、定位模型失效原因的时候，你得能下沉到 Transformers + PEFT 的层面去改代码、调配置。五个案例走下来，没有哪个方案放之四海而皆准，搞清楚每一步背后的"为什么"，你才能真正把自己的数据变成可靠的能力提升。