Chapter 11
常见错误：动态编译失败、kernel 兼容性
Unsloth 通过 monkey patch + Triton JIT 编译来加速，意味着错误类型也跟普通框架不同。 本章按"安装 / 训练 / 推理 / 导出" 四阶段列出最常见的错误，给一份"看到这种现象 → 怎么修"的对照表。
11.1调试金线
Unsloth 出错的优先排查顺序：
- 看启动 log 顶部的 Unsloth banner：Transformers / PyTorch / CUDA / Triton 版本是否在支持范围；
- 看 patcher report：哪些 kernel 是 TRITON、哪些是 PYTORCH（fallback）；
- 是否能在官方 Colab notebook 上复现：能 → 环境问题；不能 → 数据 / 代码问题；
- git log 找最近的版本变化：Unsloth 高频迭代，可能上周还能跑的代码这周 break；
- 实在不行 → Unsloth Discord #help 频道，社区响应非常快。
11.2安装阶段错误
| 现象 | 原因 | 修复 |
|---|---|---|
ImportError: cannot import name 'XXX' from 'transformers' |
transformers 升级后破坏 Unsloth patch | 降级到 Unsloth README 推荐版本；或升级 Unsloth 到最新 |
ModuleNotFoundError: No module named 'unsloth_zoo' |
缺依赖库 | pip install unsloth-zoo |
| Windows 上 Triton import 错误 | 装了 triton 而不是 triton-windows |
pip uninstall triton && pip install triton-windows |
RuntimeError: CUDA driver too old |
driver 比 PyTorch 编译版本低 | 更新 NVIDIA driver |
bitsandbytes: GPU not detected |
bitsandbytes 是 CPU-only 版 | pip install -U bitsandbytes；Windows 用 jllllll whl |
flash-attn 编译失败 |
没限并行 | MAX_JOBS=4 pip install flash-attn --no-build-isolation；或不装，Unsloth 有 fallback |
| install.sh 卡在某一步 | 网络问题 / 镜像源 | 设 HF_ENDPOINT=https://hf-mirror.com |
11.3训练阶段错误
OOM
| 现象 | 原因 | 修复 |
|---|---|---|
| 加载模型时就 OOM | 模型不是 4bit / 太大 | 用 unsloth/*-bnb-4bit 预量化版 |
| 训练第 1 步 OOM | batch / seq / r 太大 | 第 6 章 11 条优化路径 |
| 训了几百步后 OOM | 遇到长样本 | SFTTrainer 加 max_seq_length 卡住；或开 packing=True |
| 验证 / eval 时 OOM | eval 时 batch / 长度不一样 | 降 per_device_eval_batch_size；或干脆关掉 eval |
Triton 编译错误
| 现象 | 修复 |
|---|---|
RuntimeError: Triton compilation failed |
Triton 版本和 PyTorch / CUDA 不兼容；试 pip install triton==3.0.0 |
| 训练第 1 步特别慢（几分钟） | 正常，Triton kernel 首次 JIT 编译；之后会快 |
OutOfResources: Out of registers |
block size 太大；多半是 hidden_size 异常；试降 LoRA r 或换 base 模型 |
| 不同 GPU 上结果不一致 | SM 架构不同，Triton kernel 自动选不同 block size |
数值 / NaN
| 现象 | 原因 | 修复 |
|---|---|---|
| 第 1 步就 loss=nan | 数据格式坏 / template 错 | 检查样本；用 tokenizer.apply_chat_template 重新拼 |
| fp16 下 NaN | 数值溢出 | 用 bf16=True（Ampere+ 默认） |
| 训到一半 NaN | lr 太大 / 数据 outlier | 降 lr；查 outlier |
| loss 一直 = 0 | train_on_responses_only 配错 | 核对 instruction_part / response_part 字符串 |
速度异常
| 现象 | 原因 | 修复 |
|---|---|---|
| 速度没比 HF + PEFT 快 | patch 没生效 | 看启动 log "patcher report"，是否有 = TRITON |
| 训了几百步速度突然变慢 | 遇到长 seq batch，激活搬运慢 | 开 packing 让长度均匀 |
| GPU 利用率低（< 80%） | dataloader 太慢 | 升 dataloader_num_workers |
| chat_template 不一致导致 loss 下降异常 | 训练用一个模板、推理用另一个 | 训练和推理都用 get_chat_template(...) |
11.4推理阶段错误
| 现象 | 原因 | 修复 |
|---|---|---|
| 训完模型推理时全是乱码 | 没切 for_inference 模式 |
FastLanguageModel.for_inference(model) |
| 推理速度非常慢 | 同上 + 没开 use_cache | model.generate(..., use_cache=True) |
chat 输出夹特殊 token（<|eot_id|> 等） |
generate 没设 stop tokens | 用 tokenizer.apply_chat_template(..., add_generation_prompt=True) 拼输入 |
| 生成结果重复啰嗦 | temperature=0 + greedy | temperature 升到 0.7-0.9；加 repetition_penalty=1.1 |
| 从 LoRA 适配器加载后推理乱码 | 没 patch 基座模型 | 用 FastLanguageModel.from_pretrained() 加载 base，然后 model.load_adapter() |
11.5导出 / 量化阶段错误
| 现象 | 原因 | 修复 |
|---|---|---|
save_pretrained_merged OOM |
合并 LoRA 时显存爆 | 用 save_method="merged_4bit"；或 device_map="cpu" |
save_pretrained_gguf 报 llama.cpp 编译错 |
llama.cpp 没装好 | Unsloth 会自动 clone llama.cpp 并编译；如果失败手动 git clone + make |
| GGUF 转换后推理乱码 | chat_template 没正确写到 Modelfile | 在 Modelfile 显式写 TEMPLATE，参考第 10 章 |
| 合并后模型比基座大很多 | 没 merge，只是叠加 | 用 save_method="merged_16bit" |
11.6chat template 相关坑（最高频）
Unsloth 用户 50% 的"训完模型不对劲"都是 chat template 问题。三条原则：
- 训练 / 推理 / 导出全部用同一个 template；
- 用
get_chat_template(tokenizer, chat_template="...")统一管理； - 导出 Ollama / vLLM 时显式把 template 写到 Modelfile / generation_config。
常见错配：
| 训练用 | 推理用 | 结果 |
|---|---|---|
| llama-3 | chatml | 模型不知道何时停，啰嗦 |
| alpaca | llama-3 | system prompt 失效 |
| 自定义 | tokenizer 默认 | 整个对话格式错位 |
11.7"为什么 Unsloth 没起作用" 自检
如果跑完发现速度 / 显存和 HF + PEFT 一样，按这个清单查：
print(unsloth.__version__)是否 ≥ 2026.5；- 启动 log 顶部是否有
==((====))== Unsloth 2026.x: Fast Llama patching； - 是否有
RMSNorm = TRITON/LoRA = TRITON这类字样； - 是否用了
FastLanguageModel，而不是直接AutoModelForCausalLM； - 是否用了
FastLanguageModel.get_peft_model，而不是直接peft.get_peft_model； use_gradient_checkpointing是否设为字符串"unsloth"而不是True；- 设
UNSLOTH_DEBUG=1，看 fallback 提示。
11.8提 issue 的最小清单
- Unsloth / unsloth-zoo / transformers / PyTorch / CUDA / Triton 版本；
- GPU 型号；
- 启动 log 的完整 banner + patcher report；
- 能否在官方 Colab 上复现？
- 能否在 max_steps=2 + 最小样本上复现？
- 完整 Python stack trace。
11.9心法
三句话
1. Unsloth 出错时，先看启动 log 的 patcher report，确认 TRITON 全开；
2. chat_template 训推一致，省 50% 的"训完不对劲"问题；
3. 不要手动升级 transformers，跟着 Unsloth pin 走。