# llama_cpp.llama_cpp.LlamaError: 模型文件 'model.gguf' 不是有效的 GGUF 文件或已损坏。预期幻数 0x46554747，实际 0x00000000。

- **ID:** `llm/llama-cpp-gguf-model-mismatch`
- **领域:** llm
- **类别:** install_error
- **错误码:** `LLAMA-CPP-ERR-0003`
- **验证级别:** ai_generated
- **修复率:** 92%

## 根因

GGUF 模型文件要么不完整（下载截断），在传输过程中损坏，或者实际上不是 GGUF 文件（例如，PyTorch 检查点或其他格式重命名为 .gguf）。

## 版本兼容性

| 版本 | 状态 | 引入 | 弃用 |
|------|------|------|------|
| llama-cpp-python==0.2.60 | active | — | — |
| llama-cpp-python==0.2.70 | active | — | — |
| llama.cpp==b2775 | active | — | — |

## 解决方案

1. ```
   使用模型源（例如 Hugging Face）提供的 sha256 校验和验证 GGUF 文件完整性。如果校验和不匹配，则重新下载文件：`sha256sum model.gguf` 然后与发布的哈希值进行比较。示例：`curl -L -o model.gguf https://huggingface.co/TheBloke/Mistral-7B-Instruct-v0.2-GGUF/resolve/main/mistral-7b-instruct-v0.2.Q4_K_M.gguf`。
   ```
2. ```
   使用 llama.cpp 的 `convert.py` 脚本将 PyTorch 检查点转换为 GGUF：`python convert.py --outfile model.gguf /path/to/pytorch/model`。
   ```
3. ```
   检查文件的前几个字节以确认它是 GGUF：`head -c 4 model.gguf | od -A x -t x1z`。预期输出：`000000 47 47 55 46 >GGUF<`。如果显示为零或其他值，则文件已损坏或不是 GGUF。
   ```

## 无效尝试

- **** — The error is in the model file, not the library. Reinstalling the package does not repair a corrupted or invalid GGUF file. (98% 失败率)
- **** — llama.cpp only supports GGUF format. Changing the extension doesn't convert the file; the library will still try to parse it as GGUF and fail. (95% 失败率)
- **** — The quantization level is embedded in the GGUF file itself. You cannot change the quantization by renaming or modifying metadata; you need the correct GGUF file for that quantization. (85% 失败率)