跳到正文
北京时间
原文
Hacker News 热门（buzzing.cc 中文翻译）· kkm·· 2026-06-13精选AI 评分70

如何在macOS上设置本地编码代理

如何在 macOS 上设置本地编码代理

AI 导读

来自ikyle.me的教程，指导在macOS上搭建本地编码代理，获Hacker News社区104个点赞。

推荐理由

这篇文章不是泛泛的「本地跑大模型」，而是给 Mac 开发者一个实测过的、能打的生产环境编码代理方案，尤其 MTP 加速让速度不再鸡肋，可以直接抄作业。

正文 · AI 翻译

我最近遇到过几次断网，导致我手头没有可用的编码智能体，所以当我看到 “Gemma 4 现在借助 MTP 运行速度提升 2 倍” 这一针对 Gemma 4 的 Multi-Token Prediction 更新时，我决定试着把它跑起来。

我想要一套本地编码智能体配置，它要：

  • 快到能在我的 Mac 上真正用起来
  • 通过 OpenAI 兼容 API 工作（这样我就能在其他工具里使用它）
  • 并且最好在需要时能处理截图/图像，这样我就能把它生成内容的截图喂给它。

我做到了！这个视频是实时的，展示了智能体以完全可用的速度作出响应。

经过一番测试，我最终采用的配置是：

  • 在 macOS 上用 Metal 构建的 llama.cpp
  • GGUF 格式的 Gemma 4 26B-A4B
  • 用于投机解码的 Q8 MTP 草稿模型
  • Gemma 4 多模态投影器
  • 用 Pi 作为终端编码智能体

这是在配备 64 GB 统一内存的 Apple M1 Max 上测试的，运行的是 macOS 15.7.7。

模型

主模型是：gemma-4-26B-A4B-it-UD-Q4_K_XL.gguf。

Huggingface 上的链接：models/unsloth-gemma-4-26B-A4B-it-GGUF/gemma-4-26B-A4B-it-UD-Q4_K_XL.gguf

该文件约为 16 GB。加上 MTP 草稿头和 multimodal projector 后，模型文件夹约为 17 GB。

基准测试提示词为：

Write a compact Python function that parses a unified diff and returns the changed file paths. Then explain two edge cases.

每次基准测试大约生成 128 个 token。

基线：llama.cpp + Metal

首先，我通过 llama.cpp 并启用 Metal 加速直接运行主模型：

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

结果：

配置 提示词 tok/s 生成 tok/s
Gemma 4 26B-A4B Q4，llama.cpp Metal 298.0 58.2

58 tokens/秒不算快，但可用，不过对于编码智能体工作，你希望它尽可能快，尤其是当智能体进行大量工具调用时。

添加 MTP 草稿模型

Gemma 4 现在有了可用的 MTP 草稿模型：

MTP/gemma-4-26B-A4B-it-Q8_0-MTP.gguf

这可以由 llama.cpp 作为投机草稿模型加载：

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

首次使用 MTP 运行时，使用 4 个草稿 token 达到了 69.2 tokens/秒。然而，Unsloth 关于如何运行 MTP 模型的指南中包含这样一条说明：

“我们发现 --spec-draft-n-max 2 是最佳起点，但不要假设 2 就是最优的，因为性能取决于硬件。尝试从 1 到 6 的任意值，并使用对你的系统来说最快的那个。”

在遍历 --spec-draft-n-max 之后，最佳结果是使用 3 个草稿 token 达到 72.2 tokens/秒。

设置 提示词 tok/s 生成 tok/s 加速比
仅主模型 298.0 58.2 1.00x
主模型 + Q8 MTP 草稿 295.6 72.2 1.24x

有用的部分是，提示词处理基本保持不变，而生成速度提升了约 24%。

调优 MTP

我测试了 --spec-draft-n-max 从 1 到 6 的取值。

--spec-draft-n-max 提示词 tok/s 生成 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 是最快的，2 也足够接近，两者都行。再往上数值就更慢了。

MLX 对比

我还通过 mlx-lm 测试了 MLX 模型，想弄清楚在 Mac 上运行模型哪种方式更快，是 llama.cpp 还是 mlx。

运行时 模型 生成 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

我本以为 MLX（针对 Mac 做了优化）会是最快的。
然而，在这个特定配置下，llama.cpp 比 MLX 更快，而带 MTP 的 llama.cpp 显然是最佳选择。

我猜，长期以来投入到 llama.cpp 的所有努力和调优，意味着尽管它是跨平台的，但在 macOS 上已经优化得相当好了。

我还通过 gemma-4-swift-mlx 尝试了 Gemma 4 MTP，但测试的 26B 4-bit MLX checkpoint 与加载器预期的权重键不匹配，而且我已经有了之前的 MLX 测试结果，所以就没有继续下去，而不是重新下载新模型并尝试调整以匹配。

添加图像支持

对于 Pi，我还希望能够附加截图。我最初为它设置的本地模型条目将该模型声明为纯文本：

"input": ["text"]

这意味着 Pi 没有将图像工具的输出正确发送给模型。

llama.cpp 服务器还需要 Gemma 4 多模态投影器，多模态部分才能正常工作（只有 12B 是原生多模态的）：

mmproj-BF16.gguf

当使用 --mmproj 加载时，llama.cpp 会声明支持多模态，Pi 就可以发送图像了。

我在加载投影器的情况下重新运行了文本基准测试，只是为了检查它是否改变了速度：

设置 投影器 提示词 tok/s 生成 tok/s
llama.cpp Metal + MTP 无 120.3 71.4
llama.cpp Metal + MTP mmproj-BF16.gguf 297.4 72.2

使用投影器的最后一次运行未出现文本生成速度下降。

接下来是安装说明：

安装 llama.cpp

安装依赖项：

brew install cmake git tmux python@3.11

克隆并构建 llama.cpp：

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

我测试的构建版本包含：

GGML_METAL=ON
GGML_ACCELERATE=ON
GGML_BLAS=ON
GGML_BLAS_VENDOR=Apple

下载模型文件

创建 Python 环境：

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

你最终应该得到：

models/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

启动本地服务器

这是最终的服务器命令：

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

我用了一个小的 start_server.sh 包装脚本，让它能在 tmux 里运行：

#!/usr/bin/env bash
set -euo pipefail

ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
SESSION_NAME="${SESSION_NAME:-gemma4-server}"
HOST="${HOST:-127.0.0.1}"
PORT="${PORT:-8080}"
CTX_SIZE="${CTX_SIZE:-65536}"
PARALLEL="${PARALLEL:-1}"

LLAMA_SERVER="$ROOT_DIR/repos/llama.cpp/build/bin/llama-server"
MODEL="$ROOT_DIR/models/unsloth-gemma-4-26B-A4B-it-GGUF/gemma-4-26B-A4B-it-UD-Q4_K_XL.gguf"
DRAFT_MODEL="$ROOT_DIR/models/unsloth-gemma-4-26B-A4B-it-GGUF/MTP/gemma-4-26B-A4B-it-Q8_0-MTP.gguf"
MMPROJ="$ROOT_DIR/models/unsloth-gemma-4-26B-A4B-it-GGUF/mmproj-BF16.gguf"
LOG_FILE="$ROOT_DIR/logs/llama-server-mtp.log"

mkdir -p "$ROOT_DIR/logs"

tmux new-session -d -s "$SESSION_NAME" -c "$ROOT_DIR" \
  "$LLAMA_SERVER \
    -m '$MODEL' \
    --model-draft '$DRAFT_MODEL' \
    --mmproj '$MMPROJ' \
    --spec-type draft-mtp \
    --spec-draft-n-max 3 \
    -ngl 999 \
    -fa on \
    -c '$CTX_SIZE' \
    --parallel '$PARALLEL' \
    --host '$HOST' \
    --port '$PORT' \
    2>&1 | tee -a '$LOG_FILE'"

启动它：

chmod +x start_server.sh
./start_server.sh

检查服务器是否正在运行：

curl http://127.0.0.1:8080/v1/models

配置 Pi

Pi 从以下位置读取模型提供商：

~/.pi/agent/models.json

添加一个本地提供商：

{
  "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
          }
        }
      ]
    }
  }
}

关键的几个部分是：

  • baseUrl 指向 llama.cpp 的 OpenAI 兼容服务器。
  • api 是 openai-completions。
  • authHeader 是 false，因为这是一个本地服务器。
  • input 同时包含 text 和 image，否则 Pi 会把它当作纯文本处理。

可选地，将其设为默认值，位置在：

~/.pi/agent/settings.json

{
  "defaultProvider": "gemma4-local",
  "defaultModel": "gemma-4-26B-A4B-it-UD-Q4_K_XL.gguf",
  "defaultThinkingLevel": "minimal"
}

然后检查 Pi 能否看到它：

pi --offline --list-models gemma

预期结果：

provider      model                               context  max-out  thinking  images
gemma4-local  gemma-4-26B-A4B-it-UD-Q4_K_XL.gguf  65.5K    8.2K     no        yes

使用本地模型运行 Pi：

pi --provider gemma4-local --model gemma-4-26B-A4B-it-UD-Q4_K_XL.gguf

或使用非交互模式：

pi -p --provider gemma4-local --model gemma-4-26B-A4B-it-UD-Q4_K_XL.gguf \
  "Explain what this repository does"

截图：

pi -p @"/path/to/screenshot.png" "Describe this image and point out anything relevant to the UI"

最终配置

最终的本地编码智能体技术栈为：

层级 选择
推理运行时 llama.cpp
macOS 加速 Metal + Accelerate
主模型 gemma-4-26B-A4B-it-UD-Q4_K_XL.gguf
草稿模型 gemma-4-26B-A4B-it-Q8_0-MTP.gguf
MTP 设置 --spec-draft-n-max 3
多模态投影器 mmproj-BF16.gguf
服务器 llama-server 在 127.0.0.1:8080 上
API OpenAI 兼容 /v1
编程智能体 Pi
Pi 模型输入 ["text", "image"]

主要结论是 MTP 草稿模型值得一用。在这台机器上，它把 Gemma 4 从 58.2 tokens/秒提升到了 72.2 tokens/秒，同时配置依然足够简单，可以作为本地 OpenAI 兼容服务器运行。

附注：有人建议用 Qwen3.6 35B-A3B 代替 Gemma 4 26B-A4B。根据我能找到的基准测试，Qwen 作为编程智能体比 Gemma 4 强得多。
不过，它也更慢。Qwen3.6-35B-A3B-UD-Q4_K_XL.gguf + unsloth-Qwen3.6-35B-A3B-MTP-GGUF + mmproj-BF16.gguf 的结果是 55 tk/s，而不是 72 tk/s。当你坐在那里等它的时候，这个差距相当明显。

下载模型：

mkdir -p models/unsloth-Qwen3.6-35B-A3B-MTP-GGUF

huggingface-cli download unsloth/Qwen3.6-35B-A3B-MTP-GGUF \
  Qwen3.6-35B-A3B-UD-Q4_K_XL.gguf \
  mmproj-BF16.gguf \
  --local-dir models/unsloth-Qwen3.6-35B-A3B-MTP-GGUF

启动服务器：

LLAMA_SERVER=/Users/kylehowells/Developer/ML-Models/Gemma4/repos/llama.cpp/build/bin/llama-server

$LLAMA_SERVER \
  -m models/unsloth-Qwen3.6-35B-A3B-MTP-GGUF/Qwen3.6-35B-A3B-UD-Q4_K_XL.gguf \
  --mmproj models/unsloth-Qwen3.6-35B-A3B-MTP-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 8081

Pi 配置：

{
  "providers": {
    "qwen36-local": {
      "name": "Qwen3.6 Local",
      "baseUrl": "http://127.0.0.1:8081/v1",
      "api": "openai-completions",
      "apiKey": "local",
      "authHeader": false,
      "compat": {
        "supportsDeveloperRole": false,
        "supportsReasoningEffort": false
      },
      "models": [
        {
          "id": "Qwen3.6-35B-A3B-UD-Q4_K_XL.gguf",
          "name": "Qwen3.6 35B-A3B Q4 + MTP",
          "reasoning": true,
          "input": ["text", "image"],
          "contextWindow": 65536,
          "maxTokens": 8192,
          "cost": {
            "input": 0,
            "output": 0,
            "cacheRead": 0,
            "cacheWrite": 0
          }
        }
      ]
    }
  }
}

参考文献：

来源：Hacker News 热门（buzzing.cc 中文翻译） · ikyle.me

#开源生态#教程/实践#端侧#编码