在 Mac 上搭建本地编程 Agent：llama.cpp + Gemma 4 + MTP 投机解码完整指南

原文来源：How to Setup a Local Coding Agent on macOS — 在 M1 Max Mac 上搭建断网可用的本地编程 Agent：llama.cpp + Gemma 4 26B + MTP 投机解码 + Pi 终端 Agent，实测生成速度 72 token/s。

几次断网把作者困在没有编程 Agent 的状态，于是他决定在 Mac 上搭一套完全本地的方案。目标很明确：速度快到真能用、走 OpenAI 兼容 API（方便接入其他工具）、最好能看图——把 Agent 做出来的界面截图喂回去。这篇文章完整记录了他的搭建过程、性能调优和踩坑，所有命令都能直接抄。

最终方案一览

在 M1 Max（64GB 统一内存，macOS 15.7.7）上，作者最终确定的组合是：

llama.cpp（用 Metal 编译）
Gemma 4 26B-A4B 的 GGUF 模型（约 16GB）
Q8 MTP draft 模型做投机解码
Gemma 4 多模态投影器（支持看图）
Pi 作为终端编程 Agent

—— 广告 ——

基线：单模型直接跑

先看不加任何优化时 llama.cpp 跑主模型的成绩：

code

repos/llama.cpp/build/bin/llama-cli \
  -m models/unsloth-gemma-4-26B-A4B-it-GGUF/gemma-4-26B-A4B-it-UD-Q4_K_XL.gguf \
  -ngl 999 -fa on -c 4096 -n 128

结果：prompt 处理 298 token/s，生成 58.2 token/s。58 token/s 能用但不够快——编程 Agent 要频繁调用工具，等待感很明显。

MTP 投机解码：关键加速

Gemma 4 有一个 MTP（Multi-Token Prediction）draft 模型，可以作为投机解码的草稿模型挂在主模型前面。加载方式是在 llama.cpp 命令里加 draft 模型参数：

code

repos/llama.cpp/build/bin/llama-cli \
  -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 \
  --spec-type draft-mtp \
  --spec-draft-n-max 3 \
  -ngl 999 -fa on -c 4096 -n 128

关键参数是 --spec-draft-n-max，控制每次投机生成的草稿 token 数。作者扫了 1 到 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	63.7
6	296.3	61.2

在 M1 Max 上 3 最快（72.2 token/s），2 也很接近。超过 4 反而变慢。这印证了 Unsloth 文档的建议：--spec-draft-n-max 2 是好起点，但最优值依赖硬件，1 到 6 都值得扫一遍。

最终效果：生成速度从 58.2 提升到 72.2 token/s，提速约 24%，而 prompt 处理速度基本不变。注意投机解码是有损的——draft token 被主模型验证，不一致的会被丢弃重来，所以输出质量不降。

MLX 对比：llama.cpp 居然更快

作者顺手对比了 MLX（Apple 官方优化框架）：

运行时	模型	Generation tok/s
llama.cpp Metal + MTP	Unsloth GGUF Q4 + Q8 MTP	72.2
llama.cpp Metal	Unsloth GGUF Q4	58.2
MLX-LM	Unsloth UD MLX 4-bit	45.8
MLX-LM	mlx-community 4-bit	43.9
MLX-LM	mlx-community OptiQ 4-bit	38.1

结论出人意料：专为 Mac 优化的 MLX 反而慢。llama.cpp 多年积累的优化（包括对 macOS 的打磨）在这个场景下明显占优，加上 MTP 后差距更大。

加图片支持：多模态投影器

Gemma 4 26B 不是原生多模态的（只有 12B 是），需要加载多模态投影器 mmproj-BF16.gguf。在 llama.cpp 里加 --mmproj 参数后，服务器会通告多模态支持。Pi 那边则要把模型声明为 "input": ["text", "image"]，否则 Pi 不会把图片工具输出传给模型。

实测加载投影器对文本生成速度没有影响（72.2 token/s 不变）。

完整部署：llama-server + Pi

第一步：编译 llama.cpp

code

brew install cmake git tmux python@3.11
mkdir -p ~/Developer/ML-Models/Gemma4/repos
cd ~/Developer/ML-Models/Gemma4
git clone https://github.com/ggml-org/llama.cpp repos/llama.cpp
cd repos/llama.cpp
cmake -B build -DCMAKE_BUILD_TYPE=Release -DGGML_METAL=ON -DGGML_ACCELERATE=ON
cmake --build build --config Release -j

第二步：下载模型文件

code

cd ~/Developer/ML-Models/Gemma4
python3.11 -m venv .venv
source .venv/bin/activate
pip install -U huggingface_hub hf_xet
 
mkdir -p models/unsloth-gemma-4-26B-A4B-it-GGUF
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

第三步：启动服务器

code

repos/llama.cpp/build/bin/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

OpenAI 兼容端点就是 http://127.0.0.1:8080/v1。作者还用 tmux 封装了 start_server.sh 方便后台常驻。

第四步：配置 Pi

Pi 的模型配置在 ~/.pi/agent/models.json，添加本地 Provider：

code

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

要点：input 必须同时声明 text 和 image（否则 Pi 按纯文本处理、不传图）；本地服务器 authHeader 设 false。验证命令：

code

pi --offline --list-models gemma
pi -p --provider gemma4-local --model gemma-4-26B-A4B-it-UD-Q4_K_XL.gguf "解释这个仓库是干什么的"

替代方案：Qwen3.6 35B-A3B

文末作者补充了一个对比：论编程能力 Qwen3.6 35B-A3B 比 Gemma 4 强不少，但同样配置下只有 55 token/s（vs 72）。取舍就是质量换速度。作者也给出了 Qwen 版本的完整下载和配置命令，一键切换。

小结

这套方案的核心价值在 MTP 投机解码——它让一个 26B 模型在 M1 Max 上跑到 72 token/s，达到了"真的能用"的体验门槛。对经常断网、或者在意数据不出本机的开发者来说，这是一套经过实测、命令可复制的完整方案。想要更好编程质量就换 Qwen3.6，想要更快就保持 Gemma 4，配置文件的切换成本很低。

在 Mac 上搭建本地编程 Agent：llama.cpp + Gemma 4 + MTP 投机解码完整指南

最终方案一览

基线：单模型直接跑

MTP 投机解码：关键加速

MLX 对比：llama.cpp 居然更快

加图片支持：多模态投影器

完整部署：llama-server + Pi

替代方案：Qwen3.6 35B-A3B

小结

相关文章

把本地开源模型接进 OpenClaw：llama.cpp 自托管完整教程（零成本跑 Agent）

在 13 年前的 Xeon 服务器上跑 Gemma 4 26B：一份实操指南

Qwen3.8-27B 本地部署实操：从 GGUF 到 vLLM，一块 24GB 显卡就能跑