如何用llama.cpp将模型转换为GGUF格式?

选择语言:

快速回答

针对Hugging Face格式的模型目录运行llama.cpp的转换脚本,并指定输出类型,例如f16(全精度)或q4_k_m这样的量化格式。脚本会读取模型的权重和配置,将其写入单个.gguf文件,该文件可以直接由llama.cpp、Ollama或LM Studio加载。

更新于: 2026年7月15日

Technique & Concept Explainers中级

关键要点

转换流程

转换在实践中分三步:准备源模型,使用指定的输出类型运行转换脚本,如果转换为全精度,之后再进行量化。

▸**1. 准备源模型:** 转换脚本需要一个Hugging Face格式的目录,其中包含模型的权重文件(相比传统的PyTorch `.bin`检查点,更推荐safetensors),以及配置文件和分词器文件。目录下载不完整或手动拼凑、缺少分词器文件,是导致转换失败的最常见原因。
▸**2. 使用指定的输出类型运行转换脚本:** `python convert_hf_to_gguf.py --outtype f16` 会生成一个全精度的GGUF文件。传入量化的`--outtype`(例如`q8_0`)可以在转换的同时一步完成量化,但相比先转换为f16、再用专门的量化工具单独量化,控制粒度更粗。
▸**3. 单独量化以获得更精细的控制(可选但推荐):** 从一个f16的GGUF文件出发,运行llama.cpp的量化工具,从同一个全精度源生成多个量化版本(例如q4_k_m、q5_k_m),这样就能比较质量与体积的权衡,而不必每次都重新运行转换。

大多数转换失败可以归为几类,几乎都可以追溯到源模型本身,而不是脚本本身的问题。

▸**无法识别的架构:** 转换脚本维护着一份内部支持的模型架构列表。非常新或不常见的架构可能尚未被支持——在断定模型文件损坏之前,先检查工具当前的架构支持列表。
▸**缺少分词器文件:** 转换除了权重之外还需要分词器配置。只有权重文件而没有分词器文件的模型目录,会在转换过程中途失败。
▸**文件格式预期不匹配:** 传统的PyTorch `.bin`检查点有时需要先额外转换为safetensors,具体取决于工具版本——建议优先下载已经以safetensors格式提供的模型,以完全避免这个问题。
▸**转换过程中磁盘空间或内存不足:** 转换会在写出之前把全精度模型加载到内存中,因此大致需要与模型全精度大小相当的内存,再加上同时容纳源文件和输出GGUF文件所需的磁盘空间。

我应该在转换时量化,还是先转换为全精度?▾

如果你打算比较多个量化级别,请先转换为全精度(f16)——之后从同一个f16源单独量化,比在转换时直接从源模型量化得到的结果更准确,并且能让你在不重复转换步骤的情况下生成多个量化版本。

转换成功了,为什么转换后的GGUF文件无法在Ollama或LM Studio中加载?▾

转换成功并不保证加载工具支持该特定架构或GGUF版本。请检查你的加载工具版本是否为最新——GGUF格式和架构支持都在不断演进,较旧版本的工具可能无法识别由更新的转换脚本生成的文件。

转换需要多少磁盘空间?▾

需要同时预留源模型的完整大小和输出GGUF文件的大小——对于全精度转换,这大致会在过程中使模型的占用空间翻倍。量化后的输出文件更小,但在转换完成之前,源文件仍需保留。

我可以转换一个已经微调过的模型吗?▾

可以——只要微调后的权重以标准的、与Hugging Face兼容的格式保存,转换流程在微调模型上的工作方式与在基础模型上完全相同。如果微调使用的是适配器权重(如LoRA)而不是完整权重,请先将适配器合并到基础模型中,再转换合并后的结果。