llama.cpp将safetensors模型转换为gguf

前言 🔖

不同本地部署工具支持的模型格式不同， Ollama、 llama.cpp支持GGUF，PyTorch支持safetensors，本文讲解格式转换方法。

llama.cpp提供了各种LLM的处理工具，其中convert_hf_to_gguf.py，就可以帮助我们将safetensors模型转换为gguf格式，其中，模型的大小不会改变，只是格式被修改了。

转换步骤 🔖

🔹1.克隆官方项目

git clone https://github.com/ggerganov/llama.cpp.git

🔹2.创建并且激活Python虚拟环境

为了防止环境污染，最好用用Python虚拟环境。

#创建Pyhon 虚拟环境
python -m venv python-llama

# 激活虚拟环境
source python-llama/bin/activate

🔹3.安装项目依赖

# cd 到下载好的llama.cpp工程目录
cd /Users/xx/Documents/llama_cpp/llama.cpp 

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

🔹4.下载好需要转换的safetensors模型文件到本地目录

🔹5.使用convert_hf_to_gguf.py进行转换

用下面的命令可以转换生成gguf文件。

python ./convert_hf_to_gguf.py /Users/xxx/Documents/llama_cpp/safetensors --outtype q8_0

参数说明

参数	说明
`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 量化，体积最小，精度有一定损失

92IT