llama.cpp 量化前 convert_hf_to_gguf.py 报 KeyError 缺字段错误怎么修

现象

在 llama.Cpp 里执行 convert_hf_to_gguf.py 把 Qwen2.5 的权重转成 GGUF,脚本读了几秒就抛 KeyError: 'qwen2',同一份权重用别的工具能正常加载,说明文件本身没坏,问题出在脚本这一侧。

原因

转换脚本靠 config.json 里的 architectures 字段匹配模型类,老版本脚本里没有新架构的映射就直接 KeyError。另一种情况是 config 缺字段,比如 tie_word_embeddings 或 rope_scaling 没有写,脚本读取默认值时抛异常。用 pip 单独装的老版 gguf 包也会和脚本接口对不上,报错位置看起来却在读配置。

解决步骤

第一步,确认脚本版本。把仓库更新到较新的 release 再跑一次,很多新架构是后来才补上映射的。

git -C llama.cpp pull --ff-only
python llama.cpp/convert_hf_to_gguf.py ./qwen7b \
  --outtype f16 --outfile qwen2-7b-f16.gguf

第二步,检查 config.json。确认 architectures 的值与脚本里支持的类名一致,缺字段时从官方原始仓库重新下载配置文件,不要凭记忆手写,否则字段类型很容易写错。

第三步,缩小范围定位。先加 --vocab-only 只导出词表,能过说明问题在权重映射而不是词表;再对着报错缺的键去 modeling 文件里核对,必要时换脚本版本而不是改源码。

验证

转换结束生成 gguf 文件,用 llama-CLI 加载后能正常对话,中文不乱码;再跑一次量化脚本,产出的 Q4_K_M 文件大小与同规模模型接近。

小结

转换失败先看版本和配置,不要急着怀疑权重。更新脚本、补齐字段、用 vocab-only 缩小范围,是排查这类 KeyError 最快的路径。

您可以还会对下面的文章感兴趣: