现象
从模型仓库下了一个 GGUF 3.0 权重,执行 ./llama-CLI -m model.gguf -p "你好" 后进程直接退出,日志最后一行是 unknown model architecture: 'qwen3'。换 llama.cpp 自带的示例模型又能推理,说明程序本身没坏。
原因
GGUF 文件头里的 general.architecture 记录了模型结构名,llama.cpp 只有在源码里注册过对应架构才能构建计算图。本地这份是几个月前编译的,新架构合入主线的时间晚于它,于是直接报未知架构。也有转换脚本把架构名写成自定义字符串,或者把多模态的 mmproj 文件当主模型加载的情况。
解决步骤
第一步,读出文件头确认架构名。用 gguf-py 自带的脚本打印元数据,确认 general.architecture 的值和量化类型,避免拿错文件。
python gguf-py/scripts/gguf_dump.py model.gguf | head -20
git log -1 --oneline
第二步,把 llama.cpp 升到支持该架构的版本。拉取最新源码后重新编译,升级前先看仓库的 release 说明里有没有提到这个架构,编译参数按原来的显卡环境保留。
第三步,主线还没合入时换转换方式。架构太新时用作者提供的分支,或用 convert_hf_to_gguf.py 从原始权重重新转换,指定 --outtype q4_k_m 后再加载验证。
验证
启动日志里出现 model type、n_ctx、n_layer 等参数,不再有 unknown model architecture;生成一段中文能正常输出且不重复,显存占用与参数量相符。
小结
这个报错几乎都是版本和架构不匹配,不是权重损坏。先用 gguf_dump 看清架构名,再对齐 llama.cpp 版本或重新转换,比反复重下模型有效。
