macOS 本地编程代理部署指南：Gemma 4 与 Qwen3.6 实战解读

背景

近期，作者因网络中断导致无法使用云端 AI 编程代理，从而萌生了在本地 macOS 设备上部署高性能编程代理的想法。随着 Google 发布 Gemma 4 并引入多令牌预测（MTP, Multi-Token Prediction）技术，宣称推理速度提升 2 倍，作者决定尝试利用这一特性构建一个满足以下需求的本地环境：

1. 速度足够快：能够在 Mac 上实际用于编程工作，特别是在涉及大量工具调用的场景下。
2. OpenAI 兼容接口：通过标准的 OpenAI 兼容 API 提供服务，以便集成到各种第三方工具中。
3. 多模态支持：最好能处理截图或图像，以便将代理生成的代码界面截图反馈给模型进行迭代优化。

经过测试，作者在配备 Apple M1 Max 芯片和 64GB 统一内存、运行 macOS 15.7.7 的设备上成功实现了这一目标。最终的基准测试显示，该设置能够以每秒约 72 个 token 的速度生成文本，且处理提示词的速度基本保持不变，整体生成速度提升了约 24%，达到了实用级别。

核心内容

作者详细记录了从模型选择、性能调优到最终服务部署的全过程，主要涉及 llama.cpp、Gemma 4 模型以及 Pi 编程代理的配置。

1. 模型选型与架构

最终确定的本地编程代理栈包含以下组件：

• 推理引擎：基于 Metal 加速构建的 llama.cpp。
• 主模型：Gemma 4 26B-A4B（量化格式 GGUF）。
• 推测解码模型：Q8 精度的 MTP 草稿模型，用于推测解码（Speculative Decoding）。
• 多模态投影层：Gemma 4 多模态投影器（Multimodal Projector），用于支持图像输入。
• 代理前端：Pi（作为终端编程代理）。

2. 性能基准测试与 MTP 调优

作者使用了一个基准提示词：“编写一个紧凑的 Python 函数来解析统一差异（unified diff）并返回更改的文件路径，然后解释两个边缘情况。”每个基准测试生成约 128 个 token。

• 基线测试：仅使用 llama.cpp + Metal 运行主模型，速度为 58 tokens/秒。虽然可用，但对于需要频繁工具调用的编程代理来说不够快。
• 引入 MTP：加载 Q8 精度的 MTP 草稿模型进行推测解码。
  • 初始测试使用 --spec-draft-n-max 4，速度提升至 69.2 tokens/秒。
  • 参考 Unsloth 的建议，作者对 --spec-draft-n-max 参数进行了从 1 到 6 的扫描测试。
  • 最佳结果：在 M1 Max 上，设置 --spec-draft-n-max 3 时达到最高速度 72.2 tokens/秒。设置值为 2 时性能接近，但 3 为最优。高于 3 的值反而导致速度下降。
  • 结论：MTP 在保持提示词处理速度不变的情况下，使生成速度提升了约 24%。

3. 与 MLX 的性能对比

作者还测试了 Apple 官方优化的 MLX 框架（通过 mlx-lm 和 gemma-4-swift-mlx）。

• 预期 MLX 在 Mac 上表现最佳，但实际测试中，llama.cpp 的速度优于 MLX。
• 结合 MTP 的 llama.cpp 显然是最佳选择。作者推测这得益于 llama.cpp 长期以来的跨平台优化努力。
• 此外，尝试使用 gemma-4-swift-mlx 时遇到了权重键不匹配的问题，且为了避免重新下载模型和调试，最终放弃了 MLX 路线。

4. 多模态支持配置

为了让 Pi 代理能够发送图像（如截图），需要进行额外配置：

• 模型定义：原本 Pi 的本地模型配置仅声明支持文本（"input": ["text"]），这导致 Pi 无法正确发送图像工具输出。需修改为支持图像。
• 投影器加载：llama.cpp 服务器需要加载 Gemma 4 的多模态投影器（mmproj-BF16.gguf）才能启用多模态功能（注意：Gemma 4 中仅 12B 版本原生支持多模态，26B 版本需额外加载投影器）。
• 速度影响：加载投影器后重新运行文本基准测试，发现并未造成文本生成速度的显著下降。

5. 部署步骤详解

环境准备与构建 llama.cpp

1. 安装依赖：brew install cmake git tmux [email protected]。
2. 克隆并构建 llama.cpp，关键编译参数包括：
   • -DCMAKE_BUILD_TYPE=Release
   • -DGGML_METAL=ON (启用 Metal GPU 加速)
   • -DGGML_ACCELERATE=ON (启用 Apple Accelerate 框架)
   • -DGGML_BLAS=ON 及 -DGGML_BLAS_VENDOR=Apple

下载模型文件 使用 huggingface_hub 下载以下文件至 models/unsloth-gemma-4-26B-A4B-it-GGUF 目录：

• 主模型：gemma-4-26B-A4B-it-UD-Q4_K_XL.gguf (约 16GB)
• MTP 草稿模型：MTP/gemma-4-26B-A4B-it-Q8_0-MTP.gguf
• 多模态投影器：mmproj-BF16.gguf

启动本地服务器 使用以下命令启动 llama-server，提供 OpenAI 兼容接口：

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

作者提供了一个 start_server.sh 脚本，利用 tmux 在后台运行服务器，并将日志输出到文件。

配置 Pi 代理 在 ~/.pi/agent/models.json 中添加本地提供商配置：

• 设置 baseUrl 为 http://127.0.0.1:8080/v1。
• 设置 apiKey 为 local。
• 在模型定义中，将 input 设置为 ["text", "image"] 以启用多模态。
• 设置 contextWindow 为 65536，maxTokens 为 8192。

关键要点

• MTP 显著提升速度：在 Gemma 4 26B 模型上，配合 Q8 精度的 MTP 草稿模型和推测解码，推理速度