invalid magic characters：不是 GGUF 文件

报错原文

gguf_init_from_reader: invalid magic characters: '<xxxx>', expected 'GGUF'

尖括号 <…> 里的内容每次运行都会不同。

是什么意思

每个 GGUF 文件都以 "GGUF" 这四个字节开头。这个文件不是，所以它根本不是 GGUF 文件 —— 通常是网页、Git LFS 指针文件，或改名成 .gguf 的 safetensors 文件。

为什么会出现

• 下载保存的是 Hugging Face 的网页（用了 /blob/ 链接而不是 /resolve/），或者是受限仓库的登录页。
• 没装 Git LFS 就 git clone，权重位置只留下一个很小的文本指针。
• 文件是其他格式（safetensors、PyTorch），需要先转换。文件被截断时报的则是 "failed to read magic"。

怎么解决

1. 看文件开头：head -c 4 model.gguf 应该输出 GGUF。文件特别小也是一个明显信号。
2. 用 Hugging Face 命令行下载：hf download <repo> <file>.gguf --local-dir .
3. safetensors 需要先用 llama.cpp 的 convert_hf_to_gguf.py 转换。

相关指南

• 将自己的模型量化为 GGUF

相关报错

• llama.cpp 报 wrong number of tensors