在 macOS 上使用 Gemma 4 和 llama.cpp 設定本地編碼代理 (Coding Agent)\n\nA local coding agent setup on macOS 可以透過結合 llama.cpp、Gemma 4 26B 與 Multi-Token Prediction (MTP) 來實現可用且即時的效能。在配備 64GB 統一記憶體的 Apple M1 Max 上，此配置將生成速度從 58.2 提升至 72.2 tokens per second，為代理工具調用與編碼任務提供靈敏的體驗。\n\n## 使用 llama.cpp 進行高效能本地推理\n\n對於 macOS 用戶而言，使用 Metal 加速構建的 llama.cpp 在特定配置下通常優於 MLX-LM。在兩者的基準測試比較中，使用 MTP 的 llama.cpp 達到了 72.2 tok/s，而各種 MLX-LM 4-bit 實作的範圍則在 38.1 到 45.8 tok/s 之間。\n\n### Multi-Token Prediction (MTP) 的角色\n\nMulti-Token Prediction (MTP) 使用投機草稿模型 (speculative draft model) 來一次預測多個 token，在不犧牲準確度的情況下顯著提升生成吞吐量。\n\n在 M1 Max 上測試 --spec-draft-n-max 參數的不同值顯示，設定為 3 是最優的，可產生 72.2 tok/s。效能在 3 個草稿 token 時達到峰值，並隨著數值增加趨向 6 時開始下降。\n\n| --spec-draft-n-max | Prompt tok/s | Generation tok/s |\n| :--- | :--- | :--- |\n| 1 | 295.5 | 68.4 |\n| 2 | 299.1 | 72.0 |\n| 3 | 295.6 | 72.2 |\n| 4 | 297.3 | 70.7 |\n| 5 | 297.9 | 63.7 |\n| 6 | 296.3 | 61.2 |\n\n## 多模態能力與圖像支持\n\n為了讓編碼代理能夠處理截圖或 UI 圖像，需要一個多模態投影器 (multimodal projector)。雖然 Gemma 4 12B 模型原生支持多模態，但 26B 版本需要透過 llama.cpp 中的 --mmproj 標籤來載入 mmproj-BF16.gguf 投影器。\n\n添加多模態投影器不會導致文本生成速度出現可測量的減速，仍能維持 72.2 tok/s 的基準測試結果。\n\n## 逐步安裝指南\n\n### 1. 安裝 llama.cpp\n\n安裝必要的依賴項並使用 Metal 與 Accelerate 支持來構建 llama.cpp：\n\nbash\nbrew install cmake git tmux python@3.11\n\n# Clone and build\ngit clone https://github.com/ggml-org/llama.cpp\ncd llama.cpp\ncmake -B build \\n -DCMAKE_BUILD_TYPE=Release \\n -DGGML_METAL=ON \\n -DGGML_ACCELERATE=ON\n\ncmake --build build --config Release -j\n\n\n### 2. 下載模型文件\n\n使用 huggingface-cli 下載主模型、MTP 草稿模型以及多模態投影器：\n\nbash\npip install -U huggingface_hub hf_xet\n\n# Download Gemma 4 26B-A4B\nhuggingface-cli download unsloth/gemma-4-26B-A4B-it-GGUF \\n gemma-4-26B-A4B-it-UD-Q4_K_XL.gguf \\n mmproj-BF16.gguf \\n MTP/gemma-4-26B-A4B-it-Q8_0-MTP.gguf \\n --local-dir models/unsloth-gemma-4-26B-A4B-it-GGUF\n\n\n### 3. 啟動本地服務器\n\n運行 llama-server 以在 http://127.0.0.1:8080/v1 創建一個 OpenAI 相容的端點：\n\nbash\n./llama-server \\n -m models/unsloth-gemma-4-26B-A4B-it-GGUF/gemma-4-26B-A4B-it-UD-Q4_K_XL.gguf \\n --model-draft models/unsloth-gemma-4-26B-A4B-it-GGUF/MTP/gemma-4-26B-A4B-it-Q8_0-MTP.gguf \\n --mmproj models/unsloth-gemma-4-26B-A4B-it-GGUF/mmproj-BF16.gguf \\n --spec-type draft-mtp \\n --spec-draft-n-max 3 \\n -ngl 999 \\n -fa on \\n -c 65536 \\n --parallel 1 \\n --host 127.0.0.1 \\n --port 8080\n\n\n### 4. 配置 Pi Coding Agent\n\n將本地提供者添加到 ~/.pi/agent/models.json 以允許 Pi 與 llama.cpp 服務器通信。確保 input 字段包含 text 與 image 以啟用多模態支持：\n\njson\n{\n "providers": {\n "gemma4-local": {\n "name": "Gemma 4 Local",\n "baseUrl": "http://127.0.0.1:8080/v1",\n "api": "openai-completions",\n "apiKey": "apiKey",\n "authHeader": false,\n "models": [\n {\n "id": "gemma-4-26B-A4B-it-UD-Q4_K_XL.gguf",\n "name": "Gemma 4 26B-A4B Q4 + MTP",\n "input": ["text", "image"],\n "contextWindow": 65536,\n "maxTokens": 8192\n }\n ]\n }\n }\n}\n\n\n## 其他模型：Qwen 3.6\n\n雖然 Gemma 4 速度更快，但一些用戶建議 Qwen 3.6 35B-A3B 在品質方面是更優越的編碼代理。然而，這也伴隨著速度的代價；基準測試顯示其生成速度約為 55 tok/s，而 Gemma 4 為 72 tok/s。對於那些優先考慮準確度而非純粹速度的人來說，Qwen 3.6 是使用類似 llama.cpp 配置的可行替代方案。\n\n## 社群洞察與反對觀點\n\n開發者之間的討論突出了幾種權衡與替代工具：\n\n* Benchmarking Accuracy: 社群成員指出，短期的基準測試（例如 128 tokens）可能會誇大 MTP 的加速效果，因為在回應的開始階段，接受率通常較高。\n* Simplified Tooling: 幾位貢獻者建議，使用 Ollama, LM Studio, 或 oMLX 等工具可以比從源碼構建 llama.cpp 提供更簡化的安裝流程。\n* Model Quality vs. Speed: 一個反覆出現的批評是，如果模型產出的