如何用 llama.cpp 本地运行 Gemma 4：GGUF 配置、硬件要求与量化指南

Gemma 4 于 2026 年 4 月 2 日发布，llama.cpp 在首日就提供了支持。如果你已经确定使用 llama.cpp——而不是 Ollama 或 LM Studio——本文将提供精确的命令和硬件参数，帮你快速完成首次稳定运行，再逐步进阶。

如果你还在考虑选择哪个本地推理框架，建议先跳到 llama.cpp 的适用场景 一节。

---

Gemma 4 模型规格速览

Gemma 4 共有四个版本。下载之前，请先对照下表确认你的硬件配置——这是最常见的踩坑来源。

版本	架构	上下文长度	支持模态	4-bit 显存	8-bit 显存	FP16 显存
E2B	Dense + PLE	128K	文字、图像、音频	~4 GB	~5–8 GB	~10 GB
E4B	Dense + PLE	128K	文字、图像、音频	~5.5–6 GB	~9–12 GB	~16 GB
26B-A4B	MoE（激活 4B）	256K	文字、图像	~16–18 GB	~28–30 GB	~52 GB
31B	Dense	256K	文字、图像	~17–20 GB	~34–38 GB	~62 GB

这里的"显存"指可用内存总量——即显存加上用于层卸载的系统内存，或 Apple Silicon 的统一内存。如果总量低于 4-bit 列的数值，llama.cpp 也可以通过部分磁盘卸载运行，但生成速度会明显下降。

快速选型参考：

• Mac mini M4（16 GB 统一内存）： E4B 用 Q8_0，或接受较慢速度的话选 26B-A4B 的 Q4。
• 16 GB 显存（RTX 4080、RTX 4090 12G）： E4B 的 Q8_0 绰绰有余；26B-A4B 的 Q4 也有余量。
• 24 GB 显存（RTX 3090 / 4090）： 26B-A4B 的 Q8_0 或 31B 的 Q4。
• 8 GB 显存： 仅限 E2B 或 E4B 的 Q4。

26B-A4B 和 31B 怎么选： MoE 架构的 26B 每次前向传播只激活 40 亿参数，因此比稠密的 31B 更快、更省内存。内存紧张或注重速度时选 26B-A4B；追求最高质量且内存充裕时选 31B。

---

llama.cpp 的适用场景

以下情况适合选用 llama.cpp：

• 精细控制 — 自定义采样参数、KV 缓存调优、带 OpenAI 兼容接口的服务器模式、语法约束生成。
• 以 CPU 为主的推理 — llama.cpp 是最优化的 C++ 推理运行时之一，原生支持 AVX2/AVX-512 和 Apple Metal。
• 脚本与 CI 流水线 — 单一二进制文件，无 Python 依赖，集成简单直接。
• 多模态推理 — 通过 llama-mtmd-cli 和带 --mmproj 参数的 llama-server 实现。

如果你想要最简单的首次体验——一条命令下载并开始对话——Ollama 或 LM Studio 的上手门槛更低。需要更多控制权时再回来用 llama.cpp。

---

第一步 — 构建 llama.cpp

首先克隆仓库。始终使用 master 分支——tagged 发布版本会滞后于 CUDA 和 Metal 的修复：

git clone https://github.com/ggml-org/llama.cpp
cd llama.cpp

Linux + NVIDIA GPU（CUDA）

确认 CUDA 工具链已安装（运行 nvcc --version 检查），然后执行：

apt-get update
apt-get install -y pciutils build-essential cmake curl libcurl4-openssl-dev

cmake llama.cpp -B llama.cpp/build \
  -DBUILD_SHARED_LIBS=OFF \
  -DGGML_CUDA=ON

cmake --build llama.cpp/build \
  --config Release -j --clean-first \
  --target llama-cli llama-mtmd-cli llama-server llama-gguf-split

cp llama.cpp/build/bin/llama-* llama.cpp/

构建完成后验证 GPU 卸载是否生效：

./llama.cpp/llama-cli -m your-model.gguf -p "Hello" -n 5 --n-gpu-layers 99

如果看到 offloaded 0/N layers，说明二进制文件未编译 CUDA 支持——清空 build/ 目录并从头重新构建。

macOS（Apple Silicon — Metal）

macOS 上 Metal 默认启用，不需要加 -DGGML_CUDA=ON，直接正常构建即可：

brew install cmake

cmake llama.cpp -B llama.cpp/build \
  -DBUILD_SHARED_LIBS=OFF \
  -DGGML_CUDA=OFF

cmake --build llama.cpp/build \
  --config Release -j --clean-first \
  --target llama-cli llama-mtmd-cli llama-server

cp llama.cpp/build/bin/llama-* llama.cpp/

Apple Silicon 的"显存"和系统内存是同一个统一内存池——24 GB M3 Pro 可以将完整的 24 GB 用于模型权重。

仅 CPU（无 GPU）

cmake llama.cpp -B llama.cpp/build \
  -DBUILD_SHARED_LIBS=OFF \
  -DGGML_CUDA=OFF

cmake --build llama.cpp/build \
  --config Release -j$(nproc) \
  --target llama-cli llama-server

cp llama.cpp/build/bin/llama-* llama.cpp/

CMake 会自动检测宿主 CPU 的 AVX2/AVX-512 能力并启用相应优化。CPU 推理速度较慢，但功能完整。

---

第二步 — 选择 GGUF 并下载

如何选择量化方案

量化格式	文件大小（约）	质量	适用场景
Q8_0	~Q4 的 2 倍	最接近 FP16	内存充裕时的 E2B 和 E4B
Q4_K_M	中等	质量与大小均衡	24 GB 显存上的 26B-A4B 和 31B
UD-Q4_K_XL	略大于 Q4_K_M	优于 Q4_K_M	26B-A4B 和 31B；Unsloth 动态量化版本
Q2_K	最小	质量明显下降	别无选择时

Unsloth（主要 GGUF 维护者）推荐的起点：

• E2B / E4B → 从 Q8_0 开始
• 26B-A4B / 31B → 从 UD-Q4_K_XL 开始

通过 Hugging Face CLI 下载

安装一次 CLI 工具：

pip install huggingface_hub hf_transfer

然后下载所选模型。例如，26B-A4B 的 UD-Q4_K_XL 版本：

export LLAMA_CACHE="unsloth/gemma-4-26B-A4B-it-GGUF"

huggingface-cli download unsloth/gemma-4-26B-A4B-it-GGUF \
  --local-dir unsloth/gemma-4-26B-A4B-it-GGUF \
  --include "*UD-Q4_K_XL*"

如需多模态推理（图像），还需下载投影器文件：

huggingface-cli download unsloth/gemma-4-26B-A4B-it-GGUF \
  --local-dir unsloth/gemma-4-26B-A4B-it-GGUF \
  --include "*mmproj-BF16*" "*UD-Q4_K_XL*"

四个 GGUF 合集：

• unsloth/gemma-4-E2B-it-GGUF
• unsloth/gemma-4-E4B-it-GGUF
• unsloth/gemma-4-26B-A4B-it-GGUF
• unsloth/gemma-4-31B-it-GGUF

---

第三步 — 运行文字推理

llama.cpp 会自动设置上下文长度，无需手动传 -c。以下参数与 Google 官方推荐的默认值一致。

用 llama-cli 进行交互式对话

E4B（Q8_0）：

export LLAMA_CACHE="unsloth/gemma-4-E4B-it-GGUF"

./llama.cpp/llama-cli \
  -hf unsloth/gemma-4-E4B-it-GGUF:Q8_0 \
  --temp 1.0 \
  --top-p 0.95 \
  --top-k 64 \
  -cnv

26B-A4B（UD-Q4_K_XL）：

export LLAMA_CACHE="unsloth/gemma-4-26B-A4B-it-GGUF"

./llama.cpp/llama-cli \
  -hf unsloth/gemma-4-26B-A4B-it-GGUF:UD-Q4_K_XL \
  --temp 1.0 \
  --top-p 0.95 \
  --top-k 64 \
  -cnv

31B（UD-Q4_K_XL）：

export LLAMA_CACHE="unsloth/gemma-4-31B-it-GGUF"

./llama.cpp/llama-cli \
  -hf unsloth/gemma-4-31B-it-GGUF:UD-Q4_K_XL \
  --temp 1.0 \
  --top-p 0.95 \
  --top-k 64 \
  -cnv

OpenAI 兼容服务器（llama-server）

在 8080 端口启动本地服务器，任何支持 OpenAI 客户端的工具都可以直接调用：

./llama.cpp/llama-server \
  -m unsloth/gemma-4-26B-A4B-it-GGUF/gemma-4-26B-A4B-it-UD-Q4_K_XL.gguf \
  --temp 1.0 \
  --top-p 0.95 \
  --top-k 64 \
  --port 8080

然后用 curl 测试：

curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemma-4",
    "messages": [{"role": "user", "content": "用一段话解释 Attention 机制。"}]
  }'

推理参数推荐值

参数	值	说明
--temp	1.0	Google 官方默认值
--top-p	0.95	Google 官方默认值
--top-k	64	Google 官方默认值
--repeat-penalty	1.0（禁用）	仅在出现循环重复时启用
上下文长度	自动	llama.cpp 自动设置

上下文长度限制： E2B 和 E4B 最长支持 128K token；26B-A4B 和 31B 最长支持 256K。实际使用时建议从 32K 起步以获得更快的响应，仅在需要处理长文档时才增大。

开启思维链模式

Gemma 4 支持推理/思考模式。在系统提示词开头加入 <|think|> 即可启用。若要在服务器模式下关闭：

./llama.cpp/llama-server \
  -m your-model.gguf \
  --chat-template-kwargs '{"enable_thinking":false}'

在 Windows PowerShell 中需要转义引号：

--chat-template-kwargs "{\"enable_thinking\":false}"

---

第四步 — 多模态（图像）推理

Gemma 4 从首日起就在 llama.cpp 中支持图像输入，但需要第二个 GGUF 文件：多模态投影器（mmproj）。投影器负责在语言模型处理输入前对图像进行编码。

所需文件

1. 语言模型 GGUF（与文字推理相同）
2. 同一 Hugging Face 仓库中的 mmproj-BF16.gguf

如果你之前下载时使用了 --include "*mmproj-BF16*" 参数，这两个文件已经都在本地了。

用 llama-mtmd-cli（命令行）运行

./llama.cpp/llama-mtmd-cli \
  --model unsloth/gemma-4-26B-A4B-it-GGUF/gemma-4-26B-A4B-it-UD-Q4_K_XL.gguf \
  --mmproj unsloth/gemma-4-26B-A4B-it-GGUF/mmproj-BF16.gguf \
  --temp 1.0 \
  --top-p 0.95 \
  --top-k 64

在对话中使用 [img]path/to/image.jpg[/img] 语法引用图像。

用 llama-server（API 接口）运行

./llama.cpp/llama-server \
  --model unsloth/gemma-4-26B-A4B-it-GGUF/gemma-4-26B-A4B-it-UD-Q4_K_XL.gguf \
  --mmproj unsloth/gemma-4-26B-A4B-it-GGUF/mmproj-BF16.gguf \
  --temp 1.0 \
  --top-p 0.95 \
  --top-k 64 \
  --port 8080

关于音频： E2B 和 E4B 原生支持音频输入，但截至 2026 年 4 月，llama.cpp 对音频的支持仍在积极开发中。文字和图像推理已完全稳定。

---

常见问题排查

构建后出现"offloaded 0 layers"

CUDA 链接不正确。彻底清空构建目录并重新构建：

rm -rf llama.cpp/build
# 然后重新执行带 -DGGML_CUDA=ON 的 cmake 步骤

加载时内存不足（OOM）

量化后的总内存仍低于模型大小。解决方案：

1. 切换到更小的量化格式（Q4_K_M → Q2_K，或 UD-Q4_K_XL → Q4_K_M）。
2. 降级到更小的模型版本（31B → 26B-A4B，或 26B-A4B → E4B）。
3. 使用 --n-gpu-layers N 并调低 N 值，减少卸载到显存的层数——其余层使用速度较慢的系统内存。

使用 --image-min-tokens 时崩溃或 GGML_ASSERT

不要对 Gemma 4 传入 --image-min-tokens。该参数与 Gemma 4 的非因果注意力架构冲突，会导致断言失败。使用默认的图像 token 预算即可。

生成出现循环或重复内容

添加 --repeat-penalty 1.05 来打破重复循环。正常情况下保持 1.0（禁用）——Gemma 4 的架构默认不需要此参数。

macOS 上 Metal 已启用但生成仍然很慢

确认二进制文件正在使用 Metal：

./llama.cpp/llama-cli -m your-model.gguf -p "hi" -n 1 --verbose

在后端信息行中查找 Metal。如果只看到 CPU，请显式设置 --n-gpu-layers 99 强制进行层卸载。

---

常见问题解答

llama.cpp 是否官方支持 Gemma 4？ 是的。Gemma 4 支持已于 2026 年 4 月 2 日发布时纳入 llama.cpp。四种模型规格均可在 llama-cli、llama-server 和 llama-mtmd-cli 中正常使用。

Mac mini 能运行 Gemma 4 吗？ 可以。16 GB 统一内存的 Mac mini M4 能流畅运行 E4B 的 Q8_0，或以可接受的速度运行 26B-A4B 的 Q4。M4 Pro（24 GB）可以运行 26B-A4B 的 Q8_0。

必须有 GPU 吗？ 不需要。llama.cpp 支持纯 CPU 推理。GPU 卸载（CUDA 或 Metal）能显著提升每秒 token 数，但 CPU 推理完全可用，对 E2B 和 E4B 等小模型来说也很实用。

Q4_K_M 和 UD-Q4_K_XL 有什么区别？ Q4_K_M 是标准 llama.cpp 4-bit 量化。UD-Q4_K_XL 是 Unsloth 的动态 4-bit 格式，对最重要的层使用更高精度，对不太关键的层使用更低精度。实际测试中，UD-Q4_K_XL 在文件大小相近的情况下质量更高。

如何在 Cursor 或 Continue 等编程 Agent 中使用 Gemma 4？ 在 8080 端口（或任意端口）启动 llama-server，然后将 Agent 的 OpenAI base URL 指向 http://localhost:8080/v1。/v1/chat/completions 接口完全兼容 OpenAI 格式。

---

下一步

文字推理稳定后，自然的进阶路线是：

• 尝试 26B-A4B，以较小的硬件代价获得明显优于 E4B 的质量提升。
• 如果使用的是 26B-A4B 或更小的模型，尝试用 llama-mtmd-cli 进行多模态图像输入。
• 如果想要更简便的日常使用体验，并且愿意用部分控制权换取便利性，可以对比 llama.cpp 与 Ollama。

最常见的错误是还没确认小模型能稳定运行就去下载最大的模型。一个稳定的 E4B 配置比一个跑到 1 token/秒的 31B 配置实用得多。

相关教程

• Gemma 4 硬件要求
• Gemma 4 各规格对比
• 如何在 Ollama 中运行 Gemma 4
• 如何在 LM Studio 中运行 Gemma 4
• Gemma 4 API 指南