⚠️故障排除与常见问题

解决问题的提示和常见问题解答。

如果您仍遇到与版本或依赖项相关的问题，请使用我们的 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 可减少内存使用。16bit LoRA 请设为 False。
    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 16bit 崩溃

您可以尝试在保存期间通过更改来降低最大 GPU 使用率： maximum_memory_usage.

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

如何手动保存为 GGUF？

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

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/ggerganov/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,   # 您可以增加此项来包含更大的 batch_size
        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，这可将内存减少一半。

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

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 机器上使用 bf16_full_eval=True 默认情况下，截至 2025 年 6 月，Unsloth 应该已将这些标志默认开启。

如何实现早停（Early Stopping）？

如果您想在评估损失不再下降时停止微调/训练运行，可以使用早停来终止训练过程。使用 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,           # 评估损失越低越好
    ),
    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,     # 如果评估损失不下降，我们将等待多少次评估步
                                     # 例如损失可能会上升，但在 3 次评估后下降
    early_stopping_threshold = 0.0,  # 可以设置更高——设定在多大幅度的损失下降后
                                     # 我们才认为满足早停条件。例如 0.01 表示若损失从
                                     # 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 导入之前。此外请尽快提交错误报告，谢谢！

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

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

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}}
}