将 HuggingFace 模型转换为 GGUF 及使用 ollama 运行 —— 以 Qwen2-0.5B 为例

前言

最近，阿里发布了Qwen2的系列模型，包括0.5B, 1.5B, 7B, 57B-A14B 和 72B，中英文效果都很好。

因为模型太新，目前还没有 GGUF 版本可以下载，于是转下GGUF，并分享转换教程。

什么是 GGUF？

GGUF 格式的全名为（GPT-Generated Unified Format），提到 GGUF 就不得不提到它的前身 GGML（GPT-Generated Model Language）。GGML 是专门为了机器学习设计的张量库，最早可以追溯到 2022/10。其目的是为了有一个单文件共享的格式，并且易于在不同架构的 GPU 和 CPU 上进行推理。但在后续的开发中，遇到了灵活性不足、相容性及难以维护的问题。

为什么要转换 GGUF 格式

在传统的 Deep Learning Model 开发中大多使用 PyTorch 来进行开发，但因为在部署时会面临相依 Lirbrary 太多、版本管理的问题于才有了 GGML、GGMF、GGJT 等格式，而在开源社群不停的迭代后 GGUF 就诞生了。

GGUF 实际上是基于 GGJT 的格式进行优化的，并解决了 GGML 当初面临的问题，包括：

1. 可扩展性：轻松为 GGML 架构下的工具添加新功能，或者向 GGUF 模型添加新 Feature，不会破坏与现有模型的兼容性。
2. 对 mmap（内存映射）的兼容性：该模型可以使用 mmap 进行加载（原理解析可见参考），实现快速载入和存储。（从 GGJT 开始导入，可参考 GitHub）
3. 易于使用：模型可以使用少量代码轻松加载和存储，无需依赖的 Library，同时对于不同编程语言支持程度也高。
4. 模型信息完整：加载模型所需的所有信息都包含在模型文件中，不需要额外编写设置文件。
5. 有利于模型量化：GGUF 支持模型量化（4 位、8 位、F16），在 GPU 变得越来越昂贵的情况下，节省 vRAM 成本也非常重要。

动手来转档、量化和上传

整个转档的步骤如下：

1. 从 HuggingFace 下载 Model
2. 使用 llama.cpp 来进行转档
3. 使用 llama.cpp 来进行量化模型
4. 将转换和量化后的 GGUF 模型上传到 Huggingface Repo

可以参考llama.cpp作者写的教程：Tutorial: How to convert HuggingFace model to GGUF format

从 HuggingFace 下载 Model

最直觉是用 git clone 来下载模型，但是因为 LLM 每个一部分都按 GB 来计算，避免出现 OOM Error 的情况，简单用 Python 写一个 download.py 比较简单。

pip install huggingface_hub

新增download.py，写入：

from huggingface_hub import snapshot_download
model_id="Qwen/Qwen2-0.5B-Instruct"
snapshot_download(repo_id=model_id, local_dir="qwen2_0.5b_instruct",
                          local_dir_use_symlinks=False, revision="main")

运行下载：

接下来，把刚刚从 HuggingFace 下载的 Model 转换成 GGUF 格式。

开始转换hf模型为gguf

需要用llama.cpp仓库的convert_hf_to_gguf.py脚本来转换。

git clone https://github.com/ggerganov/llama.cpp.git
pip install -r llama.cpp/requirements.txt
python llama.cpp/convert_hf_to_gguf.py -h

执行转换：

# 如果不量化，保留模型的效果
python llama.cpp/convert_hf_to_gguf.py ./qwen2_0.5b_instruct  --outtype f16 --verbose --outfile qwen2_0.5b_instruct_f16.gguf
# 如果需要量化（加速并有损效果），直接执行下面脚本就可以
python llama.cpp/convert_hf_to_gguf.py ./qwen2_0.5b_instruct  --outtype q8_0 --verbose --outfile qwen2_0.5b_instruct_q8_0.gguf

这里--outtype是输出类型，代表含义：

• q2_k：特定张量（Tensor）采用较高的精度设置，而其他的则保持基础级别。
• q3_k_l、q3_k_m、q3_k_s：这些变体在不同张量上使用不同级别的精度，从而达到性能和效率的平衡。
• q4_0：这是最初的量化方案，使用 4 位精度。
• q4_1 和 q4_k_m、q4_k_s：这些提供了不同程度的准确性和推理速度，适合需要平衡资源使用的场景。
• q5_0、q5_1、q5_k_m、q5_k_s：这些版本在保证更高准确度的同时，会使用更多的资源并且推理速度较慢。
• q6_k 和 q8_0：这些提供了最高的精度，但是因为高资源消耗和慢速度，可能不适合所有用户。
• fp16 和 f32: 不量化，保留原始精度。

使用ollama运行gguf

转换好的 GGUF 模型可以使用以下的工具来运行：

• ollama(推荐): 简化 AI 模型的本地部署与使用
• llama.cpp：GGUF 的源项目。提供 CLI 和 Server 选项。
• text-generation-webui：最广泛使用的网络界面，具有许多功能和强大的扩展。支持 GPU 加速。
• GPT4All：一个免费且开源的本地运行图形用户界面，支持 Windows、Linux 和 macOS，并支持 GPU 加速。
• LM Studio：一个易于使用且功能强大的本地图形用户界面，适用于 Windows 和 macOS（Silicon），支持 GPU 加速。
• llama-cpp-python：支持 GPU 加速、LangChain 和 OpenAI 兼容 API 服务器的 Python 库。
• candle：一个使用 Rust 编写的机器学习框架，具有 GPU 支持和易于使用的特点，适合追求性能的开发者。

可以使用ollama Modelfile，基于gguf模型文件快速部署并运行模型。

安装ollama

curl -fsSL https://ollama.com/install.sh | sh   

启动ollama服务

nohup ollama serve &

创建ModelFile

复制模型路径，创建名为“ModelFile”的meta文件，内容如下：

FROM /mnt/workspace/qwen2-0.5b-instruct-q8_0.gguf

# set the temperature to 0.7 [higher is more creative, lower is more coherent]
PARAMETER temperature 0.7
PARAMETER top_p 0.8
PARAMETER repeat_penalty 1.05
TEMPLATE """{{ if .System }}<|im_start|>system
{{ .System }}<|im_end|>
{{ end }}{{ if .Prompt }}<|im_start|>user
{{ .Prompt }}<|im_end|>
{{ end }}<|im_start|>assistant
{{ .Response }}<|im_end|>"""
# set the system message
SYSTEM """
You are a helpful assistant.
"""

创建自定义模型

使用ollama create命令创建自定义模型

ollama create qwen2_0.5b_instruct --file ./ModelFile

运行模型：
ollama run qwen2_0.5b_instruct

测试自定义模型，使用终端与您的自定义模型聊天，以确保其行为符合预期。验证它是否根据自定义的系统提示和模板做出响应。

Reference

什么是 GGUF 和 GGML？
GGUF 与 GGML：为什么 GGUF 是更好的文件格式