# 保存为 GGUF

{% tabs %}
{% tab title="本地" %}
要保存为 GGUF，请使用以下方式在本地保存：

```python
Unsloth 支持直接保存为 GGUF：
model.save_pretrained_gguf("directory", tokenizer, quantization_method = "q4_k_m")
model.save_pretrained_gguf("directory", tokenizer, quantization_method = "q8_0")
```

要推送到 Hugging Face hub：

```python
或将 GGUF 推送到 Hugging Face：
model.push_to_hub_gguf("hf_username/directory", tokenizer, quantization_method = "q4_k_m")
```

以下列出了所有受支持的 `quantization_method` 量化选项：

```python
# 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 位极小型量化",
}
```

{% endtab %}

{% tab title="手动保存" %}
首先将你的模型保存为 16bit：

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

然后在终端中执行：

{% code overflow="wrap" %}

```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=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
```

{% endcode %}

或者按照 <https://rentry.org/llama-cpp-conversions#merging-loras-into-a-model> 上的步骤，使用模型名 "merged\_model" 合并为 GGUF。
{% endtab %}
{% endtabs %}

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

你有时可能会遇到这样的情况：模型在 Unsloth 上运行并产生良好结果，但在 Ollama 或 vLLM 等其他平台上使用时，结果很差或可能出现乱码、无尽/无限生成 *或* 重复输&#x51FA;**.**

* 此错误最常见的原因是使用了 <mark style="background-color:blue;">**不正确的聊天模板**</mark>**.** 在 Unsloth 训练模型时使用的聊天模板与你在另一个框架（例如 llama.cpp 或 Ollama）中运行时使用的模板必须相同。对已保存模型进行推理时，至关重要的是应用正确的模板。
* 你必须使用正确的 `eos token`。否则，在较长的生成中你可能会得到乱码。
* 这也可能是因为你的推理引擎添加了不必要的“序列开始”标记（或相反地缺少该标记），因此请确保同时检查这两种可能性！
* <mark style="background-color:green;">**使用我们的对话笔记本来强制聊天模板 - 这将修复大多数问题。**</mark>
  * 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)
  * **更多笔记本在我们的** [**笔记本文档**](https://unsloth.ai/docs/zh/kai-shi-shi-yong/unsloth-notebooks)

### 保存为 GGUF / vLLM 16bit 崩溃

你可以尝试在保存期间通过更改以减少最大 GPU 使用量 `maximum_memory_usage`.

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

### 如何手动保存为 GGUF？

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

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

像下面这样从源码编译 llama.cpp：

{% code overflow="wrap" %}

```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=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
```

{% endcode %}

然后，将模型保存为 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
```