保存为 GGUF

将模型保存为 16 位以生成 GGUF，以便在 Ollama、Jan AI、Open WebUI 等中使用！

本地

要保存为 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.vw 和 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 位超小型量化",
}

手动保存

在 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 以使用 50% 的 GPU 峰值内存或更低。这可以在保存期间减少 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