Hugging Face模型转为GGUF格式

说明

Ollama 主要使用 GGUF（GPT生成统一格式）文件格式来存储和加载模型。GGUF 取代了早期的 GGML 格式，为量化模型提供了更好的兼容性、元数据处理和性能优化，使得拥有大量参数的模型能够在显存（VRAM）有限的机器上运行。因此我们在本文档中将Hugging Face模型转为GGUF格式运行。

下载转换工具

下载llama.cpp

我们使用llama.cpp仓库的convert_hf_to_gguf.py进行转换

sh 复制代码

git clone https://github.com/ggml-org/llama.cpp.git

安装依赖

创建虚拟环境

sh 复制代码

conda create -n llama.cpp python=3.12

安装依赖

sh 复制代码

# 进入目录
cd llama.cpp

# 激活虚拟环境
conda activate llama.cpp

# 安装依赖
pip install -r requirements.txt

下载测试模型

我们使用如下脚本从Hugging Face下载Qwen大模型

python 复制代码

from huggingface_hub import snapshot_download
import os
os.environ['HTTP_PROXY'] = 'http://192.168.0.11:7897'
os.environ['HTTPS_PROXY'] = 'http://192.168.0.11:7897'

# 1. 设置本地保存的指定目录
local_dir = "./my_qwen_model"  # 替换为你想要的本地绝对或相对路径
os.makedirs(local_dir, exist_ok=True)

# 2. 设置模型 ID (注意：目前 Qwen 官方发布的是 Qwen2.5，这里以 Qwen2.5-2B 为例)
# 如果确实有 Qwen3.5-2B，请将下面的 repo_id 替换为准确的 HuggingFace 仓库路径
repo_id = "Qwen/Qwen3.5-2B" 

# 3. 执行下载
try:
    snapshot_download(
        repo_id=repo_id,
        local_dir=local_dir,
        # 如果模型需要登录才能下载，请取消下面这行的注释并填入你的 HF Token
        # token="hf_你的Token", 
        resume_download=True,  # 支持断点续传
    )
    print(f"✅ 模型已成功下载到: {os.path.abspath(local_dir)}")
except Exception as e:
    print(f"❌ 下载失败: {e}")

执行转换

不量化，保留模型的效果

下面的命令中my_qwen_model为我们模型下载的路径。

sh 复制代码

python convert_hf_to_gguf.py  ./my_qwen_model --outtype f16 --verbose --outfile Qwen3.5-2B-gguf.gguf

参数说明

参数	说明
`python convert_hf_to_gguf.py`	调用 `llama.cpp` 仓库中用于将 HuggingFace 格式模型转换为 GGUF 格式的 Python 脚本
`./my_qwen_model`	位置参数，指定 HuggingFace 模型所在的本地目录路径。该目录下应包含 `config.json` 和 `.safetensors` 权重文件
`--outtype f16`	指定输出模型的精度类型。`f16` 代表 16-bit 半精度浮点数（不量化，保留原始精度）。其他可选值包括 `f32`、`bf16` 或量化格式（如 `q8_0`、`q4_k_m` 等）
`--verbose`	开启详细输出模式，在转换过程中打印详细的日志信息，方便排查问题或查看转换进度
`--outfile Qwen3.5-2B-gguf.gguf`	指定转换后生成的 GGUF 文件的保存路径和文件名

常用量化类型参考

类型	说明
`f16`	16-bit 半精度，不量化，保留原始精度
`f32`	32-bit 全精度，体积最大
`bf16`	Brain Float 16，与 f16 类似，部分硬件支持更好
`q8_0`	8-bit 量化，精度较高，体积约为 f16 的一半
`q4_k_m`	4-bit 量化（推荐），在准确性和推理速度之间取得良好平衡，适合本地运行
`q4_0`	4-bit 量化，体积最小，精度有一定损失

量化

sh 复制代码

 python convert_hf_to_gguf.py  ./my_qwen_model --outtype q8_0 --verbose --outfile Qwen3.5-2B-gguf_q8_0.gguf

可以看到量化后的文件明显小

使用Ollama运行模型

创建ModelFile

创建ModelFile文件，内容如下，其中路径是我们之前生成的模型的路径

bash 复制代码

FROM /home/gillbert/Downloads/code/llama.cpp/Qwen3.5-2B-gguf_q8_0.gguf

创建自定义模型

使用ollama create 创建自定义模型

sh 复制代码

ollama create qwen3.5-2B-q8_0 --file ./ModelFile

查看模型列表

可以看到模型列表里面有我们刚刚创建的模型

sh 复制代码

(llama.cpp) ➜  llama.cpp git:(master) ✗ ollama list
NAME                      ID              SIZE      MODIFIED       
qwen3.5-2B-q8_0:latest    71e54e372755    2.1 GB    19 seconds ago    
qwen3.5:2b                324d162be6ca    2.7 GB    4 days ago        
qwen3.5:4b                2a654d98e6fb    3.4 GB    3 months ago

运行模型

sh 复制代码

ollama run qwen3.5-2B-q8_0:latest

遇到的错误

错误一

根本原因是 Ollama 底层的模型加载器（llama.cpp）不支持 Qwen3.5 这种较新的模型架构。.解决办法，升级ollama到最新版本。

sh 复制代码

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