如何将微调模型转为GGUF格式？Unsloth操作指南

如何将微调模型转为GGUF格式？Unsloth操作指南

1. 引言：为什么需要把模型转成 GGUF？

你有没有遇到过这种情况：辛辛苦苦在云端用 Unsloth 微调了一个大模型，效果不错，但想把它拿回本地运行时却发现——太难了！加载慢、依赖多、环境复杂，甚至根本跑不起来。

这时候，GGUF 格式就是你的救星。

GGUF（GPT-Generated Unified Format）是一种专为本地部署设计的模型存储格式。它把模型权重、分词器、配置信息全都打包进一个文件里，支持多种量化级别（比如 4bit、8bit），让你能在普通电脑上流畅运行大模型，哪怕没有高端显卡也行。

而Unsloth这个框架，不仅能让微调速度快 2 倍、显存占用降 70%，还直接内置了save_pretrained_gguf功能，一键就能把训练好的模型导出为 GGUF 格式，省去了繁琐的手动转换流程。

本文将手把手带你完成：

• 在 Unsloth 环境中微调模型
• 将微调结果保存为 GGUF 格式
• 上传到 Hugging Face
• 用 Ollama 在本地轻松运行

整个过程小白友好，代码可复制粘贴，适合所有想把 AI 模型“带回家”的开发者和爱好者。

2. 准备工作：搭建 Unsloth 环境

2.1 检查 Conda 环境是否正常

如果你使用的是预装 Unsloth 的镜像环境（如 CSDN 星图平台提供的镜像），首先确认环境已正确加载。

conda env list

你会看到类似如下输出：

# conda environments: # base * /opt/conda unsloth_env /opt/conda/envs/unsloth_env

确保unsloth_env存在。

2.2 激活 Unsloth 虚拟环境

conda activate unsloth_env

激活后，命令行前缀会变成(unsloth_env)，表示你现在处于正确的环境中。

2.3 验证 Unsloth 安装成功

运行以下命令检查 Unsloth 是否安装完整：

python -m unsloth

如果出现版本号或帮助信息，说明安装成功；如果有报错，请重新安装：

pip uninstall unsloth -y && pip install --upgrade --no-cache-dir git+https://github.com/unslothai/unsloth.git

3. 加载并微调你的模型

3.1 导入模型与 tokenizer

我们以unsloth/DeepSeek-R1-Distill-Llama-8B为例，这是一个经过优化的小型 Llama 变体，适合快速实验。

from unsloth import FastLanguageModel import torch max_seq_length = 2048 dtype = None load_in_4bit = True model, tokenizer = FastLanguageModel.from_pretrained( model_name="unsloth/DeepSeek-R1-Distill-Llama-8B", max_seq_length=max_seq_length, dtype=dtype, load_in_4bit=load_in_4bit, )

这段代码做了三件事：

1. 下载模型（首次运行）
2. 启用 4bit 量化，大幅降低显存占用
3. 自动选择最优数据类型（float16 或 bfloat16）

提示：如果你要访问私有模型或上传到 Hugging Face，记得设置 token。

3.2 配置 LoRA 进行高效微调

LoRA（Low-Rank Adaptation）是当前最主流的轻量级微调技术。它不修改原始模型参数，而是添加少量可训练层，实现“打补丁”式更新。

model = FastLanguageModel.get_peft_model( model, r=16, target_modules=["q_proj", "k_proj", "v_proj", "o_proj", "gate_proj", "up_proj", "down_proj"], lora_alpha=16, lora_dropout=0, bias="none", use_gradient_checkpointing="unsloth", random_state=3407, )

关键参数解释：

• r=16：控制新增参数规模，越大越强但也更耗资源
• target_modules：指定哪些模块应用 LoRA，这里覆盖了注意力和 FFN 层
• use_gradient_checkpointing：开启梯度检查点，节省显存

3.3 准备训练数据集

我们使用中文医疗数据集shibing624/medical来演示如何格式化输入。

from datasets import load_dataset EOS_TOKEN = tokenizer.eos_token dataset = load_dataset("shibing624/medical", "finetune", split="train[:200]", trust_remote_code=True) print("数据字段：", dataset.column_names) # 输出：['instruction', 'input', 'output']

定义提示模板，让模型学会“像医生一样思考”：

prompt_template = """以下是描述任务的指令，以及提供进一步上下文的输入。 请写出一个适当完成请求的回答。 在回答之前，请仔细思考问题，并创建一个逻辑连贯的思考过程，以确保回答准确无误。 ### 指令： 你是一位精通医学知识的医生，能够回答关于疾病、治疗方案和健康建议的问题。 请回答以下医疗问题。 ### 问题： {} ### 回答： <思考> {} </思考> {}"""

格式化函数：

def format_prompts(examples): instructions = examples["instruction"] inputs = examples["input"] outputs = examples["output"] texts = [] for inst, inp, out in zip(instructions, inputs, outputs): text = prompt_template.format(inst, inp, out) + EOS_TOKEN texts.append(text) return {"text": texts} dataset = dataset.map(format_prompts, batched=True)

3.4 开始训练

使用 Hugging Face 的SFTTrainer（监督微调训练器）进行训练。

from trl import SFTTrainer from transformers import TrainingArguments from unsloth import is_bfloat16_supported trainer = SFTTrainer( model=model, tokenizer=tokenizer, train_dataset=dataset, dataset_text_field="text", max_seq_length=max_seq_length, dataset_num_proc=2, packing=False, args=TrainingArguments( per_device_train_batch_size=2, gradient_accumulation_steps=4, warmup_steps=5, max_steps=75, learning_rate=2e-4, fp16=not is_bfloat16_supported(), bf16=is_bfloat16_supported(), logging_steps=1, optim="adamw_8bit", weight_decay=0.01, lr_scheduler_type="linear", seed=3407, output_dir="outputs", report_to="none", ), ) trainer.train()

训练完成后，模型的 LoRA 权重会被保存在outputs文件夹中。

4. 将微调模型导出为 GGUF 格式

这才是本文的核心：如何把训练好的模型变成可以直接运行的.gguf文件？

Unsloth 提供了极其简单的接口：

# 保存为 8-bit 量化 GGUF（推荐平衡版） model.save_pretrained_gguf("my_medical_model", tokenizer, quantization_method="Q8_0") # 或者保存为 4-bit 量化（更小，适合低配设备） # model.save_pretrained_gguf("my_medical_model", tokenizer, quantization_method="q4_k_m") # 或者保存为 f16 全精度（最大，质量最高） # model.save_pretrained_gguf("my_medical_model", tokenizer, quantization_method="f16")

执行后，你会得到一个名为my_medical_model的文件夹，里面包含：

• ggml-model-Q8_0.gguf：主模型文件
• tokenizer.json：分词器
• special_tokens_map.json：特殊标记映射
• config.json：模型配置

这些文件就可以直接用于本地推理了！

5. 上传到 Hugging Face 并用 Ollama 运行

5.1 设置 Hugging Face Token

你需要先获取 HF Token：

1. 登录 huggingface.co
2. 点击右上角头像 → Settings → Access Tokens
3. 创建一个具有write权限的新 token
4. 复制并保存

然后在 Colab 或终端中设置环境变量：

from google.colab import userdata HUGGINGFACE_TOKEN = userdata.get('HUGGINGFACE_TOKEN')

或者在 Linux/Mac 终端：

export HUGGINGFACE_TOKEN="your_token_here"

5.2 创建仓库并上传模型

from huggingface_hub import create_repo # 创建公开仓库 create_repo("your_username/medical-gguf", token=HUGGINGFACE_TOKEN, exist_ok=True) # 推送 GGUF 模型 model.push_to_hub_gguf( repo_id="your_username/medical-gguf", tokenizer=tokenizer, token=HUGGINGFACE_TOKEN )

上传成功后，你会在 Hugging Face 上看到一个包含.gguf文件的仓库。

5.3 使用 Ollama 本地运行模型

Ollama 支持直接拉取 Hugging Face 上的 GGUF 模型！

打开终端，运行：

ollama run hf.co/your_username/medical-gguf

第一次运行会自动下载模型文件（根据量化等级，大小在 3GB~8GB 不等），之后即可离线使用。

你可以像这样提问：

我最近总是头晕，可能是什么原因？

模型会以“医生”身份给出专业建议，而且是完全本地运行，隐私安全有保障。

6. 总结：从微调到本地部署的完整路径

6.1 关键步骤回顾

我们走完了从零开始的全流程：

1. 准备环境：激活unsloth_env，验证安装
2. 加载模型：使用FastLanguageModel.from_pretrained加载基础模型
3. 配置 LoRA：通过get_peft_model实现高效微调
4. 训练模型：用SFTTrainer在小数据集上完成微调
5. 导出 GGUF：调用save_pretrained_gguf一键生成.gguf文件
6. 上传 HF：使用push_to_hub_gguf分享成果
7. 本地运行：通过ollama run hf.co/...在本机启动模型

每一步都简洁明了，无需手动编译、无需第三方工具链。

6.2 为什么这个组合如此强大？

这三者结合，真正实现了“云端训练 + 本地推理”的理想闭环。

6.3 实用建议

• 推荐量化方式：Q8_0最佳平衡，q4_k_m适合低配设备
• ❌不要频繁修改模板：一旦训练完成，prompt 模板应保持一致
• 可以合并 LoRA 权重：若想永久固化微调效果，可用model.merge_and_unload()合并进原模型
• 注意 Token 安全：不要在公开代码中硬编码HUGGINGFACE_TOKEN

获取更多AI镜像

想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。