修复 llama.cpp 中的 "unknown model architecture" 错误：gemma4 和 diffusion-gemma

如果你看到以下任一错误：

error loading model: unknown model architecture: 'gemma4'

error loading model: unknown model architecture: 'diffusion-gemma'

它们看起来相似，但原因完全不同。不要对两者采用相同的修复方法。

你遇到的是哪个错误？

错误字符串	含义	修复方法
unknown model architecture: 'gemma4'	你的运行时早于 Gemma 4 发布。	更新 llama.cpp、Ollama 或你的应用。
unknown model architecture: 'diffusion-gemma'	DiffusionGemma 还未在任何已发布的 llama.cpp 版本中。	从 PR #24423 构建，或使用不同的运行时。

核心区别：gemma4 支持存在于 llama.cpp 主线和当前 Ollama/LM Studio 版本中，更新即可解决。diffusion-gemma 支持不在任何官方版本中——它存在于一个未合并的 PR (#24423)。更新到最新官方版本无法解决此问题。

---

修复 unknown model architecture: 'gemma4'

此错误表示你的运行时早于 Gemma 4 的 2026 年 4 月发布日期。修复方法是更新。

llama.cpp

cd llama.cpp
git pull
cmake -B build
cmake --build build --config Release -j

# 验证运行的是新二进制文件
./build/bin/llama-cli --version

然后确认你的 shell 使用的是正确的二进制文件：

which llama-cli
llama-cli --version

如果版本仍然很旧，说明系统找到的是旧版已安装的副本。直接从 build 目录调用二进制文件，或更新已安装的版本。

Homebrew

brew update && brew upgrade llama.cpp
llama-cli --version

如果 Homebrew 包仍落后于上游，临时从源码构建。

Ollama

ollama pull gemma4
ollama run gemma4

Ollama 维护了一个管理的 gemma4 模型。如果只是想运行标准 Gemma 4，通过 Ollama 拉取通常比管理自定义 GGUF 更简单。

LM Studio

通过 LM Studio 内置的更新程序更新。当前版本支持 gemma4 架构。

---

修复 unknown model architecture: 'diffusion-gemma'

这个错误不同。截至本文写作时，DiffusionGemma 支持尚未合并到 llama.cpp 主线。它只存在于 PR #24423 中，该 PR 还引入了一个独立的专用二进制文件 llama-diffusion-cli。

将 llama.cpp 更新到最新官方版本无法修复此问题。 你需要：

1. 从 PR #24423 分支构建，或者
2. 使用已经支持 DiffusionGemma 的其他运行时

选项 A：从 PR #24423 构建

git clone https://github.com/ggml-org/llama.cpp
cd llama.cpp
git fetch origin pull/24423/head:diffusion-gemma-pr
git checkout diffusion-gemma-pr

# 仅 CPU：
cmake -B build
cmake --build build --config Release -j

# NVIDIA CUDA：
cmake -B build -DGGML_CUDA=ON
cmake --build build --config Release -j

# 你需要的二进制文件：
./build/bin/llama-diffusion-cli

注意：即使从这个分支运行，也必须使用 llama-diffusion-cli，而不是 llama-cli。对 DiffusionGemma GGUF 运行 llama-cli 仍会失败。

选项 B：使用其他运行时

运行时	DiffusionGemma 支持
Unsloth Studio	是，自 2026 年 6 月 12 日（v0.1.463-beta）起。最简单的选项。
vLLM	是，自 2026 年 6 月 10 日起。最适合服务部署。
HF Transformers	是，通过官方 Google 权重。
Ollama	否。Issue #16664 待解决。
LM Studio	否。Bug #2037 待解决。

---

这些做法无效

• 重命名 GGUF 文件。架构元数据在文件内部，不在文件名中。
• 更改上下文长度或采样设置。加载器在推理开始前就失败了。
• 换一个不同的提示词。原因相同。
• 从不同来源下载但使用相同运行时。如果运行时不认识架构，没有任何 GGUF 能加载。
• 通过 Ollama 运行（如果遇到的是 diffusion-gemma 错误）。Ollama 的捆绑运行时有相同限制。

---

如何确认模型文件是否有效

使用最新主线 llama.cpp 测试：

./build/bin/llama-cli -m /path/to/your/model.gguf -p "Hello." -n 10

结果	含义
成功加载	你的运行时是最新的。如果其他应用失败，那个应用的运行时落后了。
unknown model architecture: 'gemma4'	更新运行时。
unknown model architecture: 'diffusion-gemma'	需要 PR #24423 或其他运行时。
其他错误（文件损坏、格式错误）	文件可能不完整或来自不可信来源。

可信的 Gemma 4 GGUF 来源：ggml-org、Unsloth、bartowski、mradermacher。

---

常见问题

我更新到最新 llama.cpp 后仍然出现 diffusion-gemma 错误。为什么？
因为 PR 尚未合并。最新主线不包含 DiffusionGemma 支持。你需要专门使用 PR 分支。

从 PR 分支构建安全吗？
用于个人测试，是的。用于生产，请将其视为尚未经过项目完整评审流程的预发布代码。

llama-cli 和 llama-diffusion-cli 可以使用同一个 GGUF 吗？
不可以。它们处理不同的架构。DiffusionGemma GGUF 需要 llama-diffusion-cli。标准 Gemma 4 GGUF 使用标准 llama-cli。

我的应用说它使用 llama.cpp，但仍然报错。怎么办？
该应用捆绑了自己的 llama.cpp 版本，可能比上游落后几周。查看应用的发布说明，确认是否有 DiffusionGemma 或 diffusion-gemma 架构支持。在应用更新捆绑的运行时之前，无法通过该应用使用 DiffusionGemma。

相关指南：

• DiffusionGemma 能用 llama.cpp 运行吗？
• DiffusionGemma 能在 LM Studio 中运行吗？
• Gemma 4 Q4 还是 Q8：下载哪个量化版本