保存为 GGUF

将模型保存为 GGUF 的 16 位格式，这样你就可以将其用于 Unsloth Studio、Ollama、llama.cpp 等更多工具！

本地

要保存为 GGUF，请使用下面的方法本地保存：

model.save_pretrained_gguf("directory", tokenizer, quantization_method = "q4_k_m")
model.save_pretrained_gguf("directory", tokenizer, quantization_method = "q8_0")
model.save_pretrained_gguf("directory", tokenizer, quantization_method = "f16")

推送到 Hugging Face hub：

model.push_to_hub_gguf("hf_username/directory", tokenizer, quantization_method = "q4_k_m")
model.push_to_hub_gguf("hf_username/directory", tokenizer, quantization_method = "q8_0")

所有受支持的量化选项，适用于 quantization_method 如下所示：

# https://github.com/ggml-org/llama.cpp/blob/master/examples/quantize/quantize.cpp#L19
ALLOWED_QUANTS = \
{
    "not_quantized"  : "推荐。转换快。推理慢，文件大。",
    "fast_quantized" : "推荐。转换快。推理尚可，文件大小尚可。",
    "quantized"      : "推荐。转换慢。推理快，文件小。",
    "f32"     : "不推荐。保留 100% 准确率，但超级慢且占用大量内存。",
    "f16"     : "转换最快 + 保留 100% 准确率。慢且占用大量内存。",
    "q8_0"    : "转换快。资源占用高，但通常可接受。",
    "q4_k_m"  : "推荐。对 attention.wv 和 feed_forward.w2 张量的一半使用 Q6_K，其余使用 Q4_K",
    "q5_k_m"  : "推荐。对 attention.wv 和 feed_forward.w2 张量的一半使用 Q6_K，其余使用 Q5_K",
    "q2_k"    : "对 attention.wv 和 feed_forward.w2 张量使用 Q4_K，对其他张量使用 Q2_K。",
    "q3_k_l"  : "对 attention.wv、attention.wo 和 feed_forward.w2 张量使用 Q5_K，其余使用 Q3_K",
    "q3_k_m"  : "对 attention.wv、attention.wo 和 feed_forward.w2 张量使用 Q4_K，其余使用 Q3_K",
    "q3_k_s"  : "对所有张量使用 Q3_K",
    "q4_0"    : "原始量化方法，4 位。",
    "q4_1"    : "准确率高于 q4_0，但不如 q5_0。不过推理速度比 q5 模型更快。",
    "q4_k_s"  : "对所有张量使用 Q4_K",
    "q4_k"    : "q4_k_m 的别名",
    "q5_k"    : "q5_k_m 的别名",
    "q5_0"    : "更高的准确率、更高的资源占用和更慢的推理。",
    "q5_1"    : "更高的准确率、资源占用和更慢的推理。",
    "q5_k_s"  : "对所有张量使用 Q5_K",
    "q6_k"    : "对所有张量使用 Q8_K",
    "iq2_xxs" : "2.06 bpw 量化",
    "iq2_xs"  : "2.31 bpw 量化",
    "iq3_xxs" : "3.06 bpw 量化",
    "q3_k_xs" : "3 位超小量化",
}

手动保存

先将你的模型保存为 16 位：

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

然后使用终端执行：

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=OFF -DGGML_CUDA=ON -DLLAMA_CURL=ON
cmake --build llama.cpp/build --config Release -j --clean-first --target llama-cli llama-mtmd-cli llama-server llama-gguf-split
cp llama.cpp/build/bin/llama-* llama.cpp

python llama.cpp/convert_hf_to_gguf.py FOLDER --outfile OUTPUT --outtype f16

或者按照 https://rentry.org/llama-cpp-conversions#merging-loras-into-a-model 中的步骤，使用模型名 "merged_model" 合并为 GGUF。

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

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

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

• 你必须使用正确的 eos 令牌。否则，在较长的生成中你可能会得到乱码。

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

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

  • 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=OFF -DGGML_CUDA=ON -DLLAMA_CURL=ON
cmake --build llama.cpp/build --config Release -j --clean-first --target llama-cli llama-mtmd-cli llama-server llama-gguf-split
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