macOS で Gemma 4 と llama.cpp を使用してローカルコーディングエージェントをセットアップする

A macOS 上のローカルコーディングエージェントのセットアップは、llama.cpp と Gemma 4 26B、および Multi-Token Prediction (MTP) を組み合わせることで、実用的なリアルタイム性能を実現できます。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) は、投機的ドラフトモデルを使用して複数のトークンを一度に予測し、精度を損なうことなく生成スループットを大幅に向上させます。

M1 Max で --spec-draft-n-max パラメータの異なる値をテストした結果、3 が最適であり、72.2 tok/s を実現しました。パフォーマンスは 3 つのドラフトトークンでピークに達し、値が 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

マルチモーダル機能と画像サポート

コーディングエージェントがスクリーンショットや 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 コーディングエージェントの設定

Pi が llama.cpp サーバーと通信できるように、~/.pi/agent/models.json にローカルプロバイダーを追加します。マルチモーダルサポートを有効にするために、input フィールドに text と image の両方が含まれていることを確認してください：

{

Sources