# 故障排查与常见问题 如果你在版本或依赖方面仍然遇到任何问题，请使用我们的 [Docker 镜像](/docs/zh/kai-shi-shi-yong/install/docker.md) ，其中会预装好一切。 {% hint style="success" %} **如果你发现任何问题，请始终尝试更新 Unsloth。** `pip install --upgrade --force-reinstall --no-cache-dir --no-deps unsloth unsloth_zoo` {% endhint %} ### 正在微调一个 Unsloth 不支持的新模型？ Unsloth 可与任何以下支持的模型配合使用 `transformers`。如果某个模型不在我们的上传列表中，或者无法即插即用运行，通常它仍然是受支持的；某些较新的模型可能只需要做一点手动调整，因为我们的优化方式所致。 在大多数情况下，你可以通过设置以下内容来启用兼容性： `trust_remote_code=True` 在你的微调脚本中。下面是一个使用 [DeepSeek-OCR](/docs/zh/mo-xing/tutorials/deepseek-ocr-how-to-run-and-fine-tune.md): 
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 中打开**](https://colab.research.google.com/github/unslothai/notebooks/blob/main/nb/Qwen3_\(14B\)-Reasoning-Conversational.ipynb) * Gemma-3 4B 对话式笔记本 [**在 Colab 中打开**](https://colab.research.google.com/github/unslothai/notebooks/blob/main/nb/Gemma3_\(4B\).ipynb) * Llama-3.2 3B 对话式笔记本 [**在 Colab 中打开**](https://colab.research.google.com/github/unslothai/notebooks/blob/main/nb/Llama3.2_\(1B_and_3B\)-Conversational.ipynb) * Phi-4 14B 对话式笔记本 [**在 Colab 中打开**](https://colab.research.google.com/github/unslothai/notebooks/blob/main/nb/Phi_4-Conversational.ipynb) * Mistral v0.3 7B 对话式笔记本 [**在 Colab 中打开**](https://colab.research.google.com/github/unslothai/notebooks/blob/main/nb/Mistral_v0.3_\(7B\)-Conversational.ipynb) * **更多笔记本请查看我们的** [**笔记本文档**](/docs/zh/kai-shi-shi-yong/unsloth-notebooks.md) ### 保存为 GGUF / vLLM 16 位时崩溃 你可以通过修改以下参数来尝试降低保存期间的最大 GPU 使用量 `maximum_memory_usage`. 默认值是 `model.save_pretrained(..., maximum_memory_usage = 0.75)`。将其降低到例如 0.5，可使用 GPU 峰值内存的 50% 或更低。这可以减少保存时的 OOM 崩溃。 ### 我如何手动保存为 GGUF？ 首先通过以下方式将你的模型保存为 16 位： ```python model.save_pretrained_merged("merged_model", tokenizer, save_method = "merged_16bit",) ``` 像下面这样从源码编译 llama.cpp： ```bash 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： ```bash python llama.cpp/convert_hf_to_gguf.py merged_model \ --outfile model-F16.gguf --outtype f16 \ --split-max-size 50G ``` ```bash # 对于 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 的默认选择，以减少性能损失。 ### 如何进行评估 要在训练运行中设置评估，你首先必须将数据集拆分为训练集和测试集。你应该 **始终打乱数据集的选择**，否则你的评估结果就是错误的！ ```python 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 行之类。 ```python 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，这样可以将内存减半。 先将你的训练数据集拆分为训练集和测试集。将训练器的评估设置为： ```python 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 步之后不再下降时停止训练运行。 ```python 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"], ) ``` 然后我们添加回调，也可以进行自定义： ```python 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 导入之前。 ```python import os os.environ["UNSLOTH_STABLE_DOWNLOADS"] = "1" from unsloth import FastLanguageModel ``` ### RuntimeError: CUDA error: device-side assert triggered 重启并重新运行全部，但请把这段放在最开始、任何 Unsloth 导入之前。也请尽快提交 bug 报告，谢谢！ ```python 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 超参数指南**](/docs/zh/kai-shi-shi-yong/fine-tuning-llms-guide/lora-hyperparameters-guide.md) 了解更多细节。 对于 Llama 3.1、3.2、3.3 类型的模型，请使用下面的内容： ```python 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 模型，请使用下面的内容： ```python from unsloth.chat_templates import train_on_responses_only trainer = train_on_responses_only( trainer, instruction_part = "user\n", response_part = "model\n", ) ``` ### Unsloth 比预期的更慢？ 如果你一开始感觉速度更慢，很可能是因为 `torch.compile` 通常需要约 5 分钟（或更久）来预热并完成编译。请确保你测量吞吐量 **在** 它完全加载之后，因为在较长运行中，Unsloth 应该会快得多。 要禁用，请使用： ```python 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 参见 在一个新单元中，运行下面的内容： ```python 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}} } ``` [^1]: 启用这行代码，看看是否有效。 --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://unsloth.ai/docs/zh/ji-chu/troubleshooting-and-faqs.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.