模型导出：merge / GGUF / 推理服务

Unsloth 训出的模型本质是"4bit 基座 + LoRA adapter"，不能直接部署。 本章覆盖几条主流"出口"：merge 成完整 HF 模型、转 GGUF 跑 Ollama / llama.cpp、转 vLLM、转 GPTQ / AWQ。

12.1训完之后的三条路

12.2导出 API 总览

12.3路径 A：不 merge 直接推理

训完后：

model.save_pretrained("lora_model")
tokenizer.save_pretrained("lora_model")

下次加载推理：

from unsloth import FastLanguageModel

# 加载 base 模型（Unsloth 优化版）
model, tokenizer = FastLanguageModel.from_pretrained(
    "unsloth/llama-3-8b-bnb-4bit",
    max_seq_length=2048, load_in_4bit=True,
)
# 挂上自己的 LoRA
model.load_adapter("lora_model")

# 切推理模式
FastLanguageModel.for_inference(model)

用途：

• 多个 LoRA 切换（多 task / 多用户）；
• 不想占盘上传 16GB；
• 开发期反复迭代。

12.4路径 B：merge 成完整 HF 模型

model.save_pretrained_merged(
    "merged_16bit",
    tokenizer,
    save_method = "merged_16bit",     # 完整 fp16
)

会得到标准 HF 目录：

merged_16bit/
├── config.json
├── generation_config.json
├── model.safetensors.index.json
├── model-00001-of-00004.safetensors
├── ...
├── tokenizer.json
├── tokenizer_config.json
└── special_tokens_map.json

合并参数说明

用合并后模型推理

from transformers import AutoModelForCausalLM, AutoTokenizer
import torch

tok = AutoTokenizer.from_pretrained("merged_16bit")
model = AutoModelForCausalLM.from_pretrained(
    "merged_16bit",
    torch_dtype=torch.bfloat16,
    device_map="auto",
)
# 不需要 Unsloth，原生 HF 就能跑

vLLM serve

vllm serve ./merged_16bit \
  --tensor-parallel-size 1 \
  --max-model-len 8192 \
  --port 8000

12.5路径 C：GGUF 量化部署

GGUF 是 llama.cpp 的统一量化格式，Ollama / LM Studio / mobile 端都用它。 Unsloth 一行导出：

model.save_pretrained_gguf(
    "gguf_q4",
    tokenizer,
    quantization_method = "q4_k_m",
)

底层流程（Unsloth 自动完成）：

1. 把 4bit base + LoRA 合并成 fp16；
2. 自动下载 / 编译 llama.cpp；
3. 调 convert_hf_to_gguf.py 转 fp16 GGUF；
4. 用 llama-quantize 量化到目标精度。

支持的量化方法

推荐：

• q4_k_m：平衡精度 / 速度 / 大小，默认首选；
• q5_k_m：在意精度的话；
• q8_0：精度极致；
• q3_k_m / q2_k：手机 / 边缘设备。

一次出多份

model.save_pretrained_gguf(
    "gguf_multi",
    tokenizer,
    quantization_method = ["q4_k_m", "q5_k_m", "q8_0"],
)
# 会生成 3 个文件，分别对应三种精度

12.6Ollama 部署

第 10 章演示过。完整版 Modelfile（含 system prompt）：

# Modelfile
FROM ./gguf_q4/unsloth.Q4_K_M.gguf

TEMPLATE """{{ if .System }}<|start_header_id|>system<|end_header_id|>

{{ .System }}<|eot_id|>{{ end }}{{ if .Prompt }}<|start_header_id|>user<|end_header_id|>

{{ .Prompt }}<|eot_id|>{{ end }}<|start_header_id|>assistant<|end_header_id|>

{{ .Response }}<|eot_id|>"""

SYSTEM """你是一个友好的中文 AI 助手。"""

PARAMETER stop "<|eot_id|>"
PARAMETER stop "<|end_of_text|>"
PARAMETER stop "<|start_header_id|>"
PARAMETER stop "<|end_header_id|>"
PARAMETER temperature 0.7
PARAMETER top_p 0.9
PARAMETER num_ctx 4096

ollama create my-llama3 -f Modelfile
ollama run my-llama3
ollama list
ollama push my-llama3        # 推到 Ollama Hub

12.7llama.cpp 直接部署

不用 Ollama 也行，llama.cpp 自己有 server：

cd llama.cpp
./build/bin/llama-server \
  -m /path/to/gguf_q4/unsloth.Q4_K_M.gguf \
  --port 8080 \
  -c 4096 \
  --chat-template llama3

会起一个 OpenAI 兼容的 HTTP server，curl 测试：

curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "default",
    "messages": [{"role": "user", "content": "你好"}]
  }'

12.8vLLM 部署（推荐用 merged_16bit）

vllm serve ./merged_16bit \
  --tensor-parallel-size 1 \
  --gpu-memory-utilization 0.9 \
  --max-model-len 8192 \
  --port 8000

vLLM 比 llama.cpp 吞吐高 5-10×（continuous batching + PagedAttention），但只支持 GPU 推理。 单用户场景 llama.cpp 也够用；高并发 API 服务用 vLLM。

12.9GPTQ / AWQ 量化（替代 GGUF）

vLLM 不支持 GGUF（截至 0.10），但支持 GPTQ / AWQ。从 Unsloth merged 模型转：

# 用 AutoGPTQ
from auto_gptq import AutoGPTQForCausalLM, BaseQuantizeConfig

quantize_config = BaseQuantizeConfig(bits=4, group_size=128, desc_act=False)
model = AutoGPTQForCausalLM.from_pretrained("./merged_16bit", quantize_config)
model.quantize(calibration_data)
model.save_quantized("./gptq_4bit")

或者用 AWQ：

from awq import AutoAWQForCausalLM

model = AutoAWQForCausalLM.from_pretrained("./merged_16bit")
model.quantize(tokenizer, quant_config={"q_group_size": 128, "w_bit": 4})
model.save_quantized("./awq_4bit")

# vLLM serve
vllm serve ./awq_4bit --quantization awq --max-model-len 8192

12.10推送到 HuggingFace Hub

# 推 LoRA
model.push_to_hub("yourname/llama3-zh-lora", token="hf_xxx")
tokenizer.push_to_hub("yourname/llama3-zh-lora", token="hf_xxx")

# 推合并后完整模型
model.push_to_hub_merged(
    "yourname/llama3-zh-chat",
    tokenizer,
    save_method="merged_16bit",
    token="hf_xxx",
)

# 推 GGUF
model.push_to_hub_gguf(
    "yourname/llama3-zh-chat-gguf",
    tokenizer,
    quantization_method=["q4_k_m", "q8_0"],
    token="hf_xxx",
)

12.11导出体积 / 速度对照

Llama-3-8B 训完导出对比（4090 / 同一 chat 任务）：

12.12导出清单

正式发布模型前的最小检查：

1. ✅ config.json 有正确的 chat_template；
2. ✅ tokenizer.json 完整复制；
3. ✅ 不带 adapter 直接推理也对（merged 测试）；
4. ✅ Modelfile 里的 stop tokens 写全（<|eot_id|> 等）；
5. ✅ 跑一次评测对比 base 模型；
6. ✅ README.md 说明训练数据、license、prompt 范例；
7. ✅ 上 HF Hub 时打 tag（base / language / size）。

12.13这章带走的

• 训完不能直接用，必须 merge 或导出 GGUF；
• 三条出口：纯 LoRA / merged HF / GGUF 量化；
• GGUF q4_k_m 是部署到 Ollama / llama.cpp 的默认选择；
• vLLM 高吞吐场景用 merged_16bit 或 AWQ；
• Unsloth 一行 save_pretrained_gguf 包办下载 + 编译 + 转换 + 量化；
• 导出后必须验证不带 adapter 推理也对。