1. 为什么要对 Unsloth 动刀

Unsloth 在开源社区里热度很高，核心卖点就一句话：让开源大模型的微调变得更省显存、更快上手。默认配置下跑一套 LoRA 微调脚本，速度确实能翻倍，显存占用也能压得很低。但实际做项目的人应该都有感受：不管是做垂直领域对话、改指令格式、扩展词表，还是做多轮记忆型任务，默认配置永远不够。拿到手的数据记录格式跟训练模板对不上，或者显存还是卡在某个数值上不去，再或者训练完合并权重导出量化格式时中间步骤报错——这些时候，你需要的不是重新看一遍 README，而是真正去改 Unsloth 相关的那一圈代码链路。

这篇文章讲的就是“Unsloth 修改”这件事。我不会只给你贴一段能跑的脚本，而是把修改的切入点和决策过程拆开讲清楚：哪些地方能改、为什么要改、改完以后怎么验证效果没有下降。适合的人群也很明确：准备用 LoRA / QLoRA 微调开源底座模型，但发现默认方案有瓶颈的人。不管是遇到显存不足、数据拼接错位，还是想给模型加自定义 token 从头做业务适配，这篇文章都能帮你少走弯路。

先说个大前提。Unsloth 的加速并不玄学，它的本质是绕过 PyTorch 里一些过度模板化的算子实现，把注意力层和前馈层里的一体化矩阵运算重写为手工调优的融合内核。这样可以在反向传播阶段减少中间张量的落地和搬运，内存则被大幅压缩。但正因为绕过了标准栈，Unsloth 对模型结构、输入长度、数据格式的假设也会更“倔”。你一旦不按照它的约定来组织数据，或者改了模型某个层，问题不会立刻显现在 API 层，而是等到显存暴涨或 loss 突变时才暴露出来。所以修改 Unsloth 的第一步，不是找一段网上流传的硬改代码，而是先理解它的默认机制和你的目标场景之间的偏差在哪。

2. 修改前的准备：先把基线环境复现跑通

我对任何“修改”都有一个铁律：先原样复现，再下手开改。很多同学一上来就改代码，最后报错时分不清到底是环境问题还是自己的改动问题。这个坏习惯在普通脚本项目里还能忍，在 Unsloth 这种跟 CUDA 内核、Triton 编译强绑定的项目里几乎等于自杀式调试。

修改前至少把三件事确认到位。

第一，确认依赖版本。Unsloth 对深度学习框架版本和 CUDA 版本都比较敏感。常用的 Triton 组件如果跟驱动版本不匹配，运行时会直接崩在“找不到内核”这一步，而且报错信息往往非常隐晦。我的做法是单独创建一个虚拟环境，显式固定某个经过验证的版本组合，把环境写在 requirements 文件里，改完还能回滚。不要直接在服务器全局环境里动 Unsloth，那样省了五分钟，后面赔进去五个小时。

第二，先跑一次官方样例。不要用你自己的业务数据跑首次实验，先用官方 demo 里自带的小数据集跑通完整流程。这样一来，你手里就有一个“黄金基线”：在这个环境里，默认 Unsloth 是能稳定产出结果的。之后再改任何东西，都以这个基线为参照。判断修改是否引入问题，就用“基线的结果”对比“修改后的结果”，而不是凭感觉看 loss。

第三，准备好一套带验证集的评测样本。修改训练框架时，最容易被“训练 loss 在降”这个现象误导。其实很多修改会让模型训得更快，但推理质量变差。比如你把数据集从 packing 模式改成普通 padding 模式后，显存上去了，训练反而更稳，但这不代表质量一定更好。所以准备一批固定不变的评测样本，每个改动点跑完后都拿同一批样本去比答案质量，这比盯着训练曲线管用得多。

我通常还会在修改前保存一份当前模型加载后的配置快照，包括词表大小、模型各类 shape、是否启用了梯度检查点，这样万一改乱了，可以快速对比参数结构差异，定位是不是结构层面的改动出了问题。

3. 最值得改的几个切入点

“Unsloth 修改”不是一个单点操作，而是围绕加载、数据、训练、保存这四个环节的系列调整。我梳理了五个常见修改场景，几乎覆盖了 90% 的业务定制需求。

下面几个小节，我把每个切入点背后的逻辑和注意事项展开讲。

3.1 扩充词表与特殊 token 的修改

业务对话里经常需要给模型加一些固定标记，比如<|order_start|>、<|note|>。默认情况下 Unsloth 加载的是原始 tokenizer，词表是固定的，你往训练文本里硬塞这些标记，tokenizer 会把它们拆成一堆无关字符的子词，训练出来的效果基本等于没有。这不是模型笨，是分词阶段就把语义粒度打碎了。

修改方式也不复杂：先调用 tokenizer 的add_tokens/add_special_tokens方法把新标记注册进去，然后用模型的resize_token_embeddings去扩展词表大小。这个操作大多数人都会，但真正的坑在扩展之后。新加入的 token 对应那部分 embedding 是随机初始化的，如果直接用 Unsloth 默认的 LoRA 配置训练，LoRA 只会挂在标准的注意力层和 MLP 层上，不一定会去更新 embedding。结果就是训了几百步，新 token 依然没有学到合理的语义表示。

我的修改建议是，在get_peft_model阶段显式指定modules_to_save，把嵌入层和输出层一并纳入可训练范围。这里注意不要用target_modules硬塞嵌入层，因为嵌入层和线性层的 LoRA 处理逻辑不完全一致，强行塞进去容易出现维度报错。modules_to_save是更稳妥的接口，它会先把原模块完整复制一份，再在训练时更新复制后的参数。代价是多耗一点显存，但这个开销换取词表扩展的有效训练，非常值得。

3.2 长文本截断与拼接策略的调整

Unsloth 对长文本的处理其实有两派需求。一派是希望模型能处理更长的上下文，所以max_seq_length越调越大；另一派是数据里有大量短文本，如果每条样本都 padding 到固定长度，显存就浪费在无意义的 padding token 上。

默认情况下，Unsloth 支持把多个短文本 pack 在一起，减少 padding 比例。听起来很美，但它会引入一个隐患：packing 会把多条不相关的文本拼成一个长序列，模型在训练时可能跨越样本边界去学习“上下文”。如果你的任务对上下文连续性要求很高，比如多轮对话或整段文档理解，packing 会引入严重的语义污染，导致 loss 看着漂亮，具体对话时答非所问。

修改策略通常有两种。第一种是无脑关闭 packing，代价是训练速度下降、显存稍微上升。第二种是保留 packing，但在数据构造时给每条样本末尾插入清晰的结束标记，并利用 instruction 模板把“答案开始”和“答案结束”框起来。我更推荐先做统计分析：如果业务数据里超过 60% 的样本本来就有一定长度，直接关掉 packing，稳定优先；如果业务数据以短问答为主，再开 packing 并用结束符强隔离。

3.3 只监督答案部分的 Loss Mask

指令微调的核心是让模型学会“看到问题后给出答案”，而不是背下整个问答模板。默认训练脚本是把完整文本作为监督信号，模型会把指令、格式符号、甚至提示词里的固定文本也一并当成需要预测的内容。结果就是，生成格式容易飘，模板细节记不住。

Unsloth 本身不做这种区分，因为这是数据侧的事。但很多人在修改 Unsloth 时以为要写回调去 hack 内部逻辑，其实没必要。你可以在数据集预处理阶段，把 instruction 对应的那一段 token 的标签设为 -100，只保留 answer 部分的标签。在 training objective 里，-100 的位置不会贡献 loss 值。这个修改点在“数据 pipeline”层面，却会直接影响训练质量。

实操时我最常踩的坑是：设定好的 answer 起始符和 tokenizer 实际分词结果对不上。比如你写了一个"\n### Answer:"作为匹配串，但 tokenizer 可能把\n单独拆成一个 token，也可能把它和###合并。匹配不上时，整个监督区间等于没生效，全量监督仍然在跑。修改完以后，一定要手动检查数据集中第一个样本的labels，确认非 -100 的位置确实只在答案部分。

3.4 合并导出格式的修改

训练做完，最终要落地的往往不是 LoRA 适配器，而是合并后的完整权重。Unsloth 提供了比较便捷的合并导出接口，默认情况下一行代码就能导出 16 位或 4 位量化版本。但这个接口也经常被修改，因为不同版本把导出方法改名或换了参数结构，导致网上抄来的代码在你环境里直接报错。

真正需要修改的往往不是接口本身，而是导出前的模型状态。量化导出的原理是在“基础模型权重 + LoRA 增量”合并完成之后做一次重新量化，所以如果 LoRA 权重里有新扩展的 token embedding，导出时就必须确保 embedding 层和 lm_head 也参与了合并。有些导出报错不是模型的问题，而是保存路径中缺少必要的 tokenizer 配置文件，加载到部署端时词表就是旧的。

修改建议是：合并前先model.eval()，关闭梯度功能并把模型切到推理状态；导出后立刻用未量化的对照组跑同一批评测样本，看合并过程是否丢失了训练时学到的格式控制能力。这一步看似多余，但能帮你筛掉大量“训练好但部署差”的幻觉。

3.5 优化器与精度参数的调整

很多人修改 Unsloth 是为了解决训练过程的不稳定，而不是资源不够。常见的表现是：loss 在某个 step 突然跳高，然后又慢慢降下来。这类问题大多数不在框架本身，而在超参数和量化策略的配合上。

LoRA 微调和 QLoRA 微调对学习率的敏感度差别很大。QLoRA 场景下，4 位基底模型的反向传播计算本身带有量化误差，学习率稍微大一点，前几步就会把 LoRA 权重推到不合适的区域。默认脚本常用的2e-4在部分模型上会偏激进，我会习惯性地在修改脚本里加入一个“学习率扫描”：准备三组小实验，分别用1e-4、2e-4、5e-5，每组只跑五十步，看 loss 的下降曲线。哪个组合最平缓，再拿去跑完整训练。这是性价比最高的修改。

另外，paged_adamw_8bit优化器在小显存场景里作用明显，但它和某些自定义 dataloader 一起用时可能触发显存碎片问题。如果训练中途爆显存，可以试试把优化器切成普通adamw_8bit，两者效果接近，但显存分配行为不一样。

4. 一次完整的修改实操记录

理论说再多，不如跑一遍。我拿一个典型场景来演示：假设要用一套内部业务数据微调一个开源底座模型，要求是支持自定义特殊标记，并且只监督答案部分。这个场景同时涉及词表扩充、数据 mask 和训练配置修改，能完整覆盖 Unsloth 修改的主链路。

先写加载和词表扩展部分：

import torch from unsloth import FastLanguageModel from transformers import TrainingArguments from trl import SFTTrainer from datasets import Dataset # 修改点1：加载时就指定 bf16，避免默认精度不稳定 model, tokenizer = FastLanguageModel.from_pretrained( model_name="unsloth/某个基座模型在4bit下的分支", # 务必换成你自己的模型路径 max_seq_length=4096, dtype=torch.bfloat16, load_in_4bit=True, ) # 修改点2：扩展词表，注册业务特殊标记 custom_tokens = ["<|order_start|>", "<|order_end|>", "<|note|>"] num_added = tokenizer.add_tokens(custom_tokens, special_tokens=True) if tokenizer.pad_token is None: tokenizer.add_special_tokens({"pad_token": "<|pad|>"}) # 嵌入层和输出层需要resize，量化模型同样适用 model.resize_token_embeddings(len(tokenizer))

加载完成后，要用 PeftModel 去配置 LoRA。与默认脚本不同的是，我把modules_to_save加上了嵌入层和输出层，因为这一步只做一次，后续所有训练都会用到：

model = FastLanguageModel.get_peft_model( model, r=16, target_modules=[ "q_proj", "k_proj", "v_proj", "o_proj", "gate_proj", "up_proj", "down_proj", ], lora_alpha=16, lora_dropout=0, bias="none", use_gradient_checkpointing="unsloth", random_state=42, modules_to_save=["embed_tokens", "lm_head"], )

接下来构造数据集。我先定义一条统一的模板，把问题和回答用自定义标记包住，再写一个 mask 函数把问题部分对应的 token 标签置为 -100。这里我不依赖黑盒的“自动只监督回答”，而是显式生成labels：

def tokenize_and_mask(sample): prompt = ( "<|order_start|>用户：" + sample["question"] + "\n" "<|note|>助手：" ) answer = sample["answer"] + "\n<|order_end|>" full_text = prompt + answer enc = tokenizer( full_text, truncation=True, max_length=4096, return_tensors="pt", ) labels = enc["input_ids"].clone() # 找到 answer 起始位置，它之前全部设为 -100 note_token_id = tokenizer.convert_tokens_to_ids("<|note|>") positions = (labels == note_token_id).nonzero(as_tuple=True)[1] if positions.numel() > 0: start_pos = positions[0].item() + 1 labels[:, :start_pos] = -100 return { "input_ids": enc["input_ids"][0], "attention_mask": enc["attention_mask"][0], "labels": labels[0], } train_dataset = Dataset.from_list(raw_data).map(tokenize_and_mask, remove_columns=["question", "answer"])

这里有个易错细节：普通tokenizer返回的attention_mask在量化模型里通常够用，但如果改了 padding 策略，建议同时检查attention_mask和labels的长度是否一致。出现长度不一致时，最常见的错误就是用add_special_tokens=True后没把新增的 token 长度算进去。

训练配置我直接写成一个可复现的参数组，关键修改点是学习率调低、梯度累积加大，并把 packing 明确关掉：

training_args = TrainingArguments( per_device_train_batch_size=1, gradient_accumulation_steps=16, learning_rate=1e-4, lr_scheduler_type="cosine", optim="paged_adamw_8bit", logging_steps=10, max_steps=300, output_dir="./unsloth_modified_run", report_to="none", seed=42, ) trainer = SFTTrainer( model=model, tokenizer=tokenizer, train_dataset=train_dataset, args=training_args, max_seq_length=4096, dataset_num_proc=2, packing=False, ) trainer.train()

训练结束后，如果只是想保存 LoRA 适配器，直接trainer.save_model()即可。如果要合并成完整权重，推荐使用 Unsloth 的合并接口：

model.save_pretrained_merged( "./merged_model", tokenizer, save_method="merged_16bit", )

合并这一步也是我所有修改里最容易出问题的地方。如果你在get_peft_model阶段改了modules_to_save，合并时模型会尝试把 embedding 相关的参数也合并进去，此时如果 tokenizer 词表没同步，最终导出的模型推理时会出现“摸不着输出 token”的现象。所以合并完以后，我会立刻写一小段推理脚本验证自定义标记是否能被完整保留，并检查输出文本里的格式符是否正常。

5. 改完之后，收益和风险一起算

修改 Unsloth 不是越猛越好，每一步都在用可解释性、稳定性、资源消耗做交换。我习惯训练完成后用一张表把修改前和修改后的结果摆在一起，才能判断这套改动到底值不值。

显存下降不是白来的。我关掉 packing、加入modules_to_save、调低学习率，这些都让单步训练成本上升，但因为 loss 曲线更稳，整体需要的有效步数反而减少了。最后实际跑完，总训练时间几乎持平，而模型质量的可控性明显提高。

这里说一个很多人忽略的收益：修改数据 mask 后，指令模板本身不再参与 loss 计算，模型不用在“记住固定格式”这件事上花显存和算力，它可以把更多容量放在真正需要学习的业务答案上。这个收益不会直观体现在训练 loss 上，但在评测样本的格式严格遵守率上会有明显差异。所以我在项目验收时，除了看常规指标，还会单列一项“格式规则命中率”，比如<|order_start|>是否都出现在输出开头，<|order_end|>是否都正常闭合。

风险也要说清楚。词表扩充的随机初始化部分如果不在modules_to_save里，训练结束后模型相当于没有学到新 token 的任何语义。此外，embed_tokens参与 LoRA 训练后，合并导出对 tokenizer 的一致性要求更高，任何一边版本不一致都会造成部署端埋雷。所以每次改完，都要把“训练时 tokenizer 的 hash”和“部署时 tokenizer 的 hash”放在一起核对，别信文件名一样就等于一样的鬼话。

6. 踩坑与疑难排查实录

修改 Unsloth 的过程，本质上是一个反反复复撞墙的过程。我把自己踩过且比较有代表性的问题整理成一张表，方便你直接对照排查。

除了表格这些，我再分享一个不太容易排查的坑：use_gradient_checkpointing="unsloth"这个选项自带 Unsloth 定制的检查点逻辑，正常情况下能省显存，但它与modules_to_save的组合在某些版本里会多出一次额外的显存分配。遇到显存瓶颈时，可以尝试把use_gradient_checkpointing改成字符串"unsloth"之外的其他值，或者直接显式设置False，观察显存是否符合预期。它不会影响最终模型质量，只影响训练峰值。

另外，训练数据里如果包含大量极短样本，比如只有十几个 token 的询问，padding 会很严重。我见过有人在修改 data collator 时，把短样本重复拼接到接近max_seq_length，想提高显存利用率，结果模型反复背诵同一句话，生成时出现无限循环。我的建议是，不要默认复制短样本。要么去掉长度低于阈值的样本，要么利用 mask 策略让 padding 部分完全不影响 loss，而不是靠复制伪造训练信号。

调试的时候，我习惯在训练脚本里加上一段 hook，每二十步打印首批样本的 input_ids 解码结果和 labels 的非 -100 占比。这样一旦数据 pipeline 被改坏，问题会在前二十步暴露，而不是等到训练结束才在输出里发现格式问题。这个习惯花不了几分钟，但能把排查时间缩短好几个小时。

7. 一点个人经验收尾

改动 Unsloth 这么久，我最大的体会是：这个框架能不能发挥价值，不取决于你对它源码有多熟，而取决于你对训练数据的理解有多细。很多人卡在“为什么我的模型用 Unsloth 训完还是不行”，其实问题不在框架，而在数据输入形态没有对齐模型的训练目标。词表扩展了，但嵌入层没参与训练；答案 mask 没生效；或者 packing 让几条无关样本互相污染——这些才是真正让模型变笨的原因。

另外一个容易被忽略的地方是“修改要留痕”。Unsloth 的版本更新很频繁，合并接口和训练入口的签名都变过，网上随便搜到的修改代码很可能跑不通。我现在的做法是在项目里单独维护一个 modified_notes 目录，把每个改动点、改动的参数、测试结果都记下来，特别是“为什么这么改”一定要写清楚。否则三个月后再回来调这个项目，看着一段诡异的modules_to_save配置，你会怀疑当初的自己是不是喝多了。

最后，如果你时间有限，只记住一件事：任何修改都以“可复现的基线”为锚。先跑通默认流程，再做单点修改，每改一处都对比基线的 loss 曲线和评测结果。改动激进不可怕，可怕的是改完不知道自己改了什么、为什么改、影响在哪里。