保存为 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/ggerganov/llama.cpp/blob/master/examples/quantize/quantize.cpp#L19
# 来自 https://mlabonne.github.io/blog/posts/Quantize_Llama_2_models_using_ggml.html
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 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/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