⚠️故障排查与常见问题

解决问题的技巧，以及常见问题。

如果你在版本或依赖方面仍然遇到任何问题，请使用我们的 Docker 镜像 ，其中会预装好一切。

如果你发现任何问题，请始终尝试更新 Unsloth。

pip install --upgrade --force-reinstall --no-cache-dir --no-deps unsloth unsloth_zoo

正在微调一个 Unsloth 不支持的新模型？

Unsloth 可与任何以下支持的模型配合使用 transformers。如果某个模型不在我们的上传列表中，或者无法即插即用运行，通常它仍然是受支持的；某些较新的模型可能只需要做一点手动调整，因为我们的优化方式所致。

在大多数情况下，你可以通过设置以下内容来启用兼容性： trust_remote_code=True 在你的微调脚本中。下面是一个使用 DeepSeek-OCR:

from huggingface_hub import snapshot_download
snapshot_download("unsloth/DeepSeek-OCR", local_dir = "deepseek_ocr")
model, tokenizer = FastVisionModel.from_pretrained(
    "./deepseek_ocr",
    load_in_4bit = False, # 使用 4bit 以减少内存占用。False 表示 16bit LoRA。
    auto_model = AutoModel,
    trust_remote_code = True, # 启用以支持新模型
    unsloth_force_compile = True,
    use_gradient_checkpointing = "unsloth", # 长上下文时使用 True 或 "unsloth"
)

在 Unsloth 中运行效果很好，但导出后在其他平台上运行时，结果很差

你有时可能会遇到这样的问题：模型在 Unsloth 上运行并产生良好结果，但当你在 Ollama 或 vLLM 等其他平台上使用它时，结果很差，或者会得到乱码、无限/无穷生成 或 重复输出.

• 这种错误最常见的原因是使用了 错误的聊天模板. 至关重要的是，在 Unsloth 中训练模型时使用的聊天模板，之后在你将其运行于其他框架（如 llama.cpp 或 Ollama）时，也必须使用同样的模板。从已保存模型进行推理时，应用正确的模板非常关键。

• 也可能是因为你的推理引擎添加了一个不必要的“序列开头”令牌（或者相反地缺少它），因此请确保同时检查这两个假设！

• 使用我们的对话式笔记本来强制使用聊天模板——这将修复大多数问题。

  • Qwen-3 14B 对话式笔记本 在 Colab 中打开

  • Gemma-3 4B 对话式笔记本 在 Colab 中打开

  • Llama-3.2 3B 对话式笔记本 在 Colab 中打开

  • Phi-4 14B 对话式笔记本 在 Colab 中打开

  • Mistral v0.3 7B 对话式笔记本 在 Colab 中打开

  • 更多笔记本请查看我们的 笔记本文档

保存为 GGUF / vLLM 16 位时崩溃

你可以通过修改以下参数来尝试降低保存期间的最大 GPU 使用量 maximum_memory_usage.

默认值是 model.save_pretrained(..., maximum_memory_usage = 0.75)。将其降低到例如 0.5，可使用 GPU 峰值内存的 50% 或更低。这可以减少保存时的 OOM 崩溃。

我如何手动保存为 GGUF？

首先通过以下方式将你的模型保存为 16 位：

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

像下面这样从源码编译 llama.cpp：

apt-get update
apt-get install pciutils build-essential cmake curl libcurl4-openssl-dev -y
git clone https://github.com/ggml-org/llama.cpp
cmake llama.cpp -B llama.cpp/build \
    -DBUILD_SHARED_LIBS=ON -DGGML_CUDA=ON -DLLAMA_CURL=ON
cmake --build llama.cpp/build --config Release -j --clean-first --target llama-quantize llama-cli llama-gguf-split llama-mtmd-cli
cp llama.cpp/build/bin/llama-* llama.cpp

然后，将模型保存为 F16：

python llama.cpp/convert_hf_to_gguf.py merged_model \
    --outfile model-F16.gguf --outtype f16 \
    --split-max-size 50G

# 对于 BF16：
python llama.cpp/convert_hf_to_gguf.py merged_model \
    --outfile model-BF16.gguf --outtype bf16 \
    --split-max-size 50G
    
# 对于 Q8_0：
python llama.cpp/convert_hf_to_gguf.py merged_model \
    --outfile model-Q8_0.gguf --outtype q8_0 \
    --split-max-size 50G

为什么 Q8_K_XL 比 Q8_0 GGUF 更慢？

在 Mac 设备上，BF16 似乎可能比 F16 更慢。Q8_K_XL 会将某些层上转为 BF16，因此会变慢。我们正在积极调整转换流程，让 F16 成为 Q8_K_XL 的默认选择，以减少性能损失。

如何进行评估

要在训练运行中设置评估，你首先必须将数据集拆分为训练集和测试集。你应该 始终打乱数据集的选择，否则你的评估结果就是错误的！

new_dataset = dataset.train_test_split(
    test_size = 0.01, # 测试集大小为 1%，也可以是行数的整数
    shuffle = True, # 应始终设为 True！
    seed = 3407,
)

train_dataset = new_dataset["train"] # 用于训练的数据集
eval_dataset = new_dataset["test"] # 用于评估的数据集

然后，我们可以设置训练参数来启用评估。提醒一下，评估可能会非常非常慢，尤其是如果你设置了 eval_steps = 1 这意味着你每一步都在进行评估。如果是这样，试着把 eval_dataset 的大小缩小到比如 100 行之类。

from trl import SFTTrainer, SFTConfig
trainer = SFTTrainer(
    args = SFTConfig(
        fp16_full_eval = True,         # 这样设置以减少内存使用
        per_device_eval_batch_size = 2,# 增大此值会使用更多内存
        eval_accumulation_steps = 4,   # 你可以增加这个值，类似于批大小
        eval_strategy = "steps",       # 每隔若干步或若干轮运行一次评估。
        eval_steps = 1,                # 每多少个训练步执行一次评估
    ),
    train_dataset = new_dataset["train"],
    eval_dataset = new_dataset["test"],
    ...
)
trainer.train()

评估循环 - 内存不足或崩溃。

当你遇到 OOM 时，一个常见问题是批大小设置得太高。把它设为小于 2 的值以使用更少的显存。还可以使用 fp16_full_eval=True 在评估中使用 float16，这样可以将内存减半。

先将你的训练数据集拆分为训练集和测试集。将训练器的评估设置为：

new_dataset = dataset.train_test_split(test_size = 0.01)

from trl import SFTTrainer, SFTConfig
trainer = SFTTrainer(
    args = SFTConfig(
        fp16_full_eval = True,
        per_device_eval_batch_size = 2,
        eval_accumulation_steps = 4,
        eval_strategy = "steps",
        eval_steps = 1,
    ),
    train_dataset = new_dataset["train"],
    eval_dataset = new_dataset["test"],
    ...
)

这不会导致 OOM，并且会稍快一些。你也可以在 bf16_full_eval=True 用于 bf16 机器。默认情况下，从 2025 年 6 月起，Unsloth 应该已经默认设置这些标志。

我该如何进行早停？

如果你想因为评估损失没有下降而停止微调 / 训练运行，那么你可以使用早停来停止训练过程。使用 EarlyStoppingCallback.

和往常一样，先设置好你的 trainer 和评估数据集。下面的设置用于在 eval_loss （评估损失）在大约 3 步之后不再下降时停止训练运行。

from trl import SFTConfig, SFTTrainer
trainer = SFTTrainer(
    args = SFTConfig(
        fp16_full_eval = True,
        per_device_eval_batch_size = 2,
        eval_accumulation_steps = 4,
        output_dir = "training_checkpoints", # 用于早停的已保存检查点位置
        save_strategy = "steps",             # 每 N 步保存一次模型
        save_steps = 10,                     # 多少步之后保存模型
        save_total_limit = 3,                # 仅保留 3 个已保存检查点以节省磁盘空间
        eval_strategy = "steps",             # 每 N 步评估一次
        eval_steps = 10,                     # 多少步之后进行评估
        load_best_model_at_end = True,       # 早停时必须使用
        metric_for_best_model = "eval_loss", # 我们希望用于早停的指标
        greater_is_better = False,           # eval loss 越低越好
    ),
    model = model,
    tokenizer = tokenizer,
    train_dataset = new_dataset["train"],
    eval_dataset = new_dataset["test"],
)

然后我们添加回调，也可以进行自定义：

from transformers import EarlyStoppingCallback
early_stopping_callback = EarlyStoppingCallback(
    early_stopping_patience = 3,     # 如果 eval loss 没有下降，我们会等待多少步
                                     # 例如，loss 可能会上升，但会在 3 步后下降
    early_stopping_threshold = 0.0,  # 可以设置得更高——用于设置 loss 需要下降多少才
                                     # 我们认为应该早停。例如 0.01 表示如果 loss 从
                                     # 0.02 降到 0.01，我们就认为应该提前停止该运行。
)
trainer.add_callback(early_stopping_callback)

然后像往常一样通过以下方式训练模型 trainer.train() 。

下载卡在 90% 到 95%

如果你的模型长时间卡在 90%、95% 处，在你之前可以禁用一些快速下载流程，强制下载同步并输出更多错误信息。

只需使用 UNSLOTH_STABLE_DOWNLOADS=1 在任何 Unsloth 导入之前。

import os
os.environ["UNSLOTH_STABLE_DOWNLOADS"] = "1"

from unsloth import FastLanguageModel

RuntimeError: CUDA error: device-side assert triggered

重启并重新运行全部，但请把这段放在最开始、任何 Unsloth 导入之前。也请尽快提交 bug 报告，谢谢！

import os
os.environ["UNSLOTH_COMPILE_DISABLE"] = "1"
os.environ["UNSLOTH_DISABLE_FAST_GENERATION"] = "1"

你的数据集中的所有标签都是 -100。训练损失都会是 0。

这意味着你对 train_on_responses_only 的使用对该特定模型来说是不正确的。train_on_responses_only 允许你屏蔽用户问题，并以更高权重训练模型输出助手回复。已知这可将准确率提高 1% 或更多。请参阅我们的 LoRA 超参数指南 了解更多细节。

对于 Llama 3.1、3.2、3.3 类型的模型，请使用下面的内容：

from unsloth.chat_templates import train_on_responses_only
trainer = train_on_responses_only(
    trainer,
    instruction_part = "<|start_header_id|>user<|end_header_id|>\n\n",
    response_part = "<|start_header_id|>assistant<|end_header_id|>\n\n",
)

对于 Gemma 2、3、3n 模型，请使用下面的内容：

from unsloth.chat_templates import train_on_responses_only
trainer = train_on_responses_only(
    trainer,
    instruction_part = "<start_of_turn>user\n",
    response_part = "<start_of_turn>model\n",
)

Unsloth 比预期的更慢？

如果你一开始感觉速度更慢，很可能是因为 torch.compile 通常需要约 5 分钟（或更久）来预热并完成编译。请确保你测量吞吐量 在 它完全加载之后，因为在较长运行中，Unsloth 应该会快得多。

要禁用，请使用：

import os
os.environ["UNSLOTH_COMPILE_DISABLE"] = "1"

Gemma3nForConditionalGeneration 的某些权重没有从模型检查点初始化

这是一个严重错误，因为这意味着某些权重没有被正确解析，这会导致输出不正确。通常可以通过升级 Unsloth 来修复

pip install --upgrade --force-reinstall --no-cache-dir --no-deps unsloth unsloth_zoo

然后升级 transformers 和 timm：

pip install --upgrade --force-reinstall --no-cache-dir --no-deps transformers timm

但是如果问题仍然存在，请尽快提交 bug 报告！

NotImplementedError: 需要 UTF-8 区域设置。得到的是 ANSI

参见 https://github.com/googlecolab/colabtools/issues/3409

在一个新单元中，运行下面的内容：

import locale
locale.getpreferredencoding = lambda: "UTF-8"

引用 Unsloth

如果你要引用我们模型上传的使用，请使用下面的 Bibtex。这是针对 Qwen3-30B-A3B-GGUF Q8_K_XL 的：

@misc{unsloth_2025_qwen3_30b_a3b,
  author       = {Unsloth AI and Han-Chen, Daniel and Han-Chen, Michael},
  title        = {Qwen3-30B-A3B-GGUF:Q8\_K\_XL},
  year         = {2025},
  publisher    = {Hugging Face},
  howpublished = {\url{https://huggingface.co/unsloth/Qwen3-30B-A3B-GGUF}}
}

如果要引用我们 GitHub 包的使用，或一般性地引用我们的工作：

@misc{unsloth,
  author       = {Unsloth AI and Han-Chen, Daniel and Han-Chen, Michael},
  title        = {Unsloth},
  year         = {2025},
  publisher    = {Github},
  howpublished = {\url{https://github.com/unslothai/unsloth}}
}