在 macOS 上使用 Gemma 4 和 llama.cpp 设置本地编程代理

通过将 llama.cpp 与 Gemma 4 26B 以及 Multi-Token Prediction (MTP) 相结合，在 macOS 上设置的本地编程代理可以实现可用的实时性能。在配备 64GB 统一内存的 Apple M1 Max 上，此配置将生成速度从 58.2 提升至 72.2 tokens per second，为代理工具调用和编程任务提供响应式体验。

使用 llama.cpp 实现高性能本地推理

对于 macOS 用户，使用 Metal 加速构建的 llama.cpp 通常在特定配置下优于 MLX-LM。在对比两者的基准测试中，带有 MTP 的 llama.cpp 达到了 72.2 tok/s，而各种 MLX-LM 4-bit 实现的范围在 38.1 到 45.8 tok/s 之间。

Multi-Token Prediction (MTP) 的作用

Multi-Token Prediction (MTP) 使用投机草稿模型来一次性预测多个 token，在不牺牲准确性的情况下显著提高生成吞吐量。

在 M1 Max 上测试 --spec-draft-n-max 参数的不同值显示，值为 3 时效果最佳，可达到 72.2 tok/s。性能在 3 个草稿 token 时达到顶峰，并随着数值增加向 6 靠近时开始下降。

--spec-draft-n-max Prompt tok/s Generation tok/s
1 295.5 68.4
2 299.1 72.0
3 295.6 72.2
4 297.3 70.7
5 297.9
6 296.3 61.2

多模态能力与图像支持

为了使编程代理能够处理截图或 UI 图像，需要一个多模态投影器。虽然 Gemma 4 12B 模型原生支持多模态，但 26B 版本需要通过 llama.cpp 中的 --mmproj 标志加载 mmproj-BF16.gguf 投影器。

添加多模态投影器不会导致文本生成速度出现可衡量的下降，仍能保持 72.2 tok/s 的基准测试速度。

分步安装指南

1. 安装 llama.cpp

安装必要的依赖并使用 Metal 和 Accelerate 支持构建 llama.cpp：

brew install cmake git tmux python@3.11

# Clone and build
git clone https://github.com/ggml-org/llama.cpp
cd llama.cpp
cmake -B build \
  -DCMAKE_BUILD_TYPE=Release \
  -DGGML_METAL=ON \
  -DGGML_ACCELERATE=ON

cmake --build build --config Release -j

2. 下载模型文件

使用 huggingface-cli 下载主模型、MTP 草稿模型和多模态投影器：

pip install -U huggingface_hub hf_xet

# Download Gemma 4 26B-A4B
huggingface-cli download unsloth/gemma-4-26B-A4B-it-GGUF \
  gemma-4-26B-A4B-it-UD-Q4_K_XL.gguf \
  mmproj-BF16.gguf \
  MTP/gemma-4-26B-A4B-it-Q8_0-MTP.gguf \
  --local-dir models/unsloth-gemma-4-26B-A4B-it-GGUF

3. 启动本地服务器

运行 llama-server 以在 http://127.0.0.1:8080/v1 创建一个 OpenAI 兼容的端点：

./llama-server \
  -m models/unsloth-gemma-4-26B-A4B-it-GGUF/gemma-4-26B-A4B-it-UD-Q4_K_XL.gguf \
  --model-draft models/unsloth-gemma-4-26B-A4B-it-GGUF/MTP/gemma-4-26B-A4B-it-Q8_0-MTP.gguf \
  --mmproj models/unsloth-gemma-4-26B-A4B-it-GGUF/mmproj-BF16.gguf \
  --spec-type draft-mtp \
  --spec-draft-n-max 3 \
  -ngl 999 \
  -fa on \
  -c 65536 \
  --parallel 1 \
  --host 127.0.0.1 \
  --port 8080

4. 配置 Pi Coding Agent

将本地提供商添加到 ~/.pi/agent/models.json 以允许 Pi 与 llama.cpp 服务器通信。确保 input 字段包含 both text and image 以启用多模态支持：

{
  "providers": {
    "gemma4-local": {
      "name": "Gemma 4 Local",
      "baseUrl": "http://127.0.0.1:8080/v1",
      "api": "openai-completions",
      "apiKey": "apiKey": "local",
      "authHeader": false,
      "models": [
        {
          "id": "gemma-4-26B-A4B-it-UD-Q4_K_XL.gguf",
          "name": "Gemma 4 26B-A4B Q4 + MTP",
          "input": ["text", "image"],
          "contextWindow": 65536,
          "maxTokens": 8192
        }
      ]
    }
  }
}

其他模型：Qwen 3.6

虽然 Gemma 4 速度更快，但一些用户建议 Qwen 3.6 35B-A3B 在质量方面是更优秀的编程代理。然而，这需要以速度为代价；基准测试显示其生成速度约为 55 tok/s，而 Gemma 4 为 72 tok/s。对于那些优先考虑准确性而非单纯的速度，使用类似的 llama.cpp 设置，Qwen 3.6 是一个可行的替代方案。

社区洞察与反思

开发者之间的讨论突出了几个权衡与替代工具：

  • 基准测试准确性： 一些用户指出，短基准测试（例如 128 tokens）可能会夸大 MTP 的加速效果，因为响应开始时的接受率通常较高。
  • 简化工具链：" Ollama, LM Studio, 或 oMLX 提供比从源码构建 llama.cpp 更为精简的设置过程。
  • 模型质量 vs. 速度： 一个反复出现的批评是，如果模型产生

Sources