
2026/06/13 2:34
macOS にローカルコーディングエージェントを設定する方法
RSS: https://news.ycombinator.com/rss
要約▶
Japanese Translation:
元のサマリーは、詳細な技術的な性質を持つ「要点」としては高すぎる抽象度であり、真の「Stage 3」の結論としては不適切である。これは特定の実装に関する包括的なレビューよりもむしろ要約(abstract)に近い読後感を与える。以下に、不足している重要なデータポイントを取り込みながら流れを保つ改訂版を示す。
改善されたサマリー
本文は、macOS 15.7.7 を用いた Apple M1 Max ハードウェア(64 GB ユニファイドメモリ)上でコーディングエージェント(Pi)を実行するための非常に効率的なローカル設定について詳述している。Metal および Accelerate で最適化された llama.cpp ビルド内での Multi-Token Prediction (MTP) を活用することで、この構成は 72.2 tokens per second という驚異的な生成速度を達成しており、MTP を使用しない Q4 ベースライン(58.2 tok/s)に対して著しく改善されている。チューニングの結果、
--spec-draft-n-max 3 が最適なパフォーマンスをもたらすことが分かり、高い値は速度を低下させる;特に、このスタックは類似のハードウェア上で約 45–46 tok/s とのみ達成した競合する MLX-LM セットアップを上回る。この設定には、画像入力を実現しつつテキスト生成速度を犠牲にしない Q8 MTP ドRAFT モデルおよびマルチモーダルプロジェクターが含まれる。Qwen3.6 35B-A3B は代替としてテストされたが、55 tokens/sec で低速であることが確認された。全体としてのストレージフットプリントは約 17 GBであり、このストリームライン化されたスタックにより、開発者はクラウドサービスに依存せず 127.0.0.1:8080で実行される OpenAI 互換 API を通じてテキストと画像をローカルで処理することができ、コストとレイテンシを大幅に削減できる。本文
Gemma 4 MTP 活用によるローカルコーディングエージェント構築と速度向上検証
ネット接続の不具合によりコーディングエージェントが使用不能となった折、Gemma 4 の「MTP(Multi-Token Prediction)」活用による 2 倍高速化発表を受け、すぐに実装を試みました。
🎯 目標:ローカル環境向けエンティティ構築の要件
Mac 上で実用的に動作するコーディングエージェントを以下の条件で構築することを目的としました。
- Mac での高速動作: マシンの実力を最大限に活用した速度確保。
- OpenAI 互換 API: 他のツールやアプリケーションとの汎用的な連携を実現するため。
- 多モーダル対応: スクリーンショットや画像の処理、可視化機能を実装可能にするため。
この目標は完全に達成できました!動画ではリアルタイムでの高速応答を確認可能です。
⚙️ 最終構成と環境詳細
テストを経て採用した最終的なシステム構成は以下の通りです。
- 推論ランタイム:
(MacOS Metal 対応ビルド)llama.cpp - メインモデル:
(GGUF 形式、Q4_K_XL)Gemma 4 26B-A4B - 推論加速: 疑似推論(Speculative Decoding)用 MTP 草案モデル (
精度採用)Q8_0 - 多モーダル対応: Gemma 4 マルチモーダル射影器 (Projector) の接続
- エージェント:
(コーディングエージェント)Pi
🖥️ 検証環境
- OS: macOS 15.7.7
- CPU/GPU: Apple M1 Max (統合メモリ 64GB)
📊 モデル構成詳細とベンチマーク
ベースライン: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
結果 (Q4 メタル): 1 秒あたり 58.2 トークン生成
| 設定 | プロンプト処理速度 (tok/s) | 生成速度 (tok/s) |
|---|---|---|
| Gemma 4 26B-A4B Q4 (llama.cpp Metal) | 298.0 | 58.2 |
実用レベルですが、コーディングエージェントのようなツール呼び出しが多い場合はさらに高速化が必要です。
✨ MTP(疑似推論)の追加
Gemma 4 の草案モデル(
MTP/gemma-4-26B-A4B-it-Q8_0-MTP.gguf)を導入しました。
コマンド:
repos/llama.cpp/build/bin/llama-cli \ -m models/.../gemma-4-26B-A4B-it-UD-Q4_K_XL.gguf \ --model-draft models/.../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 を調整した結果、3 トークンが最速となりました。
| 設定 | プロンプト処理速度 (tok/s) | 生成速度 (tok/s) | 速度向上倍率 |
|---|---|---|---|
| メインモデルのみ | 298.0 | 58.2 | 1.00x |
| メインモデル + Q8 MTP ドラフト | 295.6 | 72.2 | 1.24x |
- 改善点: プロンプト処理速度の低下をほぼ抑えつつ、生成速度が約 24% (0.3 tok/s) 向上。
- 最適なパラメータ: M1 Max では
が最速で、3
も良好な結果を示しました。2
🆚 MLX との比較検証
Mac 特化の MLX-LM との速度比較を行いました。
| 実行環境 | モデル | 生成速度 (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 が最速と予測しましたが、今回の構成では llama.cpp + MTP が明確に最強でした。クロスプラットフォームかつ MacOS で十分に最適化されている
llama.cpp の評価が再確認されました。
🖼️ 画像処理機能の追加
Pi でスクリーンショットを扱えるようにするため、マルチモーダル射影器 (
mmproj) を接続しました。
- 注意点: Gemma 4 はテキストモデルであり、LLM サーバーに
を読み込むことで多モーダル対応を実現します。mmproj
速度への影響:
| 設定 | プロジェクター (mmproj) | 生成速度 (tok/s) |
|---|---|---|
| なし | - | 71.4 |
| あり | | 72.2 |
射影器のロードにより、テキスト生成速度が劣化することはありませんでした。
🛠️ 実装設定方法
1. llama.cpp のインストールとビルド
brew install cmake git tmux python@3.11 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 \ -DGGML_BLAS=ON \ -DGGML_BLAS_VENDOR=Apple cmake --build build --config Release -j
2. モデルファイルのダウンロード
Unsloth リポジトリから必要な GGUF ファイルをダウンロードします。
mkdir -p models/unsloth-gemma-4-26B-A4B-it-GGUF cd 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 .
3. ローカルサーバーの起動 (llama-server)
OpenAI 互換 API エンドポイント (
:8080) を提供します。
重要な設定:
: コンテキストウィンドウを 64K に拡張-c 65536
: MTP の最適パラメータ--spec-draft-n-max 3
cd 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
4. Pi (コーディングエージェント) の設定
Pi にローカルサーバーを登録します (
~/.pi/providers.json を編集)。
設定のポイント:
: ローカル API アドレスbaseUrl
:input
にセット(画像認識を有効化するため重要)["text", "image"]
{ "providers": { "gemma4-local": { "name": "Gemma 4 Local", "baseUrl": "http://127.0.0.1:8080/v1", "api": "openai-completions", "apiKey": "local", "authHeader": 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 } ] } } }
Pi を実行して認識を確認:
pi --offline --list-models gemma # 期待される出力: gemma4-local (画像処理:はい、コンテキスト:65.5K)
使い方の例:
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"
🏁 最終スタック一覧
| レイヤー | 採用事項 |
|---|---|
| 推論ランタイム | |
| OS アクセラレーション | Metal + Accelerate |
| メインモデル | |
| ドラフトモデル | (MTP 用) |
| MTP 設定 | |
| マルチモーダル射影器 | |
| API エンドポイント | |
| エージェント | (テキスト + 画像入力) |
💡 結論:MTP は必須か?
今回の検証から、MTP ドラフトモデルの導入は非常に価値があります。
- 単体モデル: 58.2 tok/s
- MTP 活用: 72.2 tok/s (約 1.24 倍高速化)
これにより、OpenAI 互換サーバーとしてのシンプルさを持ちつつ、実用的な速度を実現できました。
🔄 P.S.: 代替案 - Qwen3.6
Gemma 4 ではなく Qwen3.6 を使う場合のベンチマーク比較です。
- Gemma 構成:
+ MTP ➔ 72 tok/s ⚡Q4_K_XL - Qwen 構成:
+ MTP ➔ 55 tok/s (ただしコーディング能力は Gemma より優れている可能性あり)Q4_K_XL
待機時間を含めた総合的なパフォーマンスを考慮すると、Gemma 4 の方がこの環境では有利です。
Qwen3.6 サーバー起動例
repos/llama.cpp/build/bin/llama-server \ -m models/Qwen3.6-35B-A3B-UD-Q4_K_XL.gguf \ --model-draft models/Qwen3.6-35B-A3B-MTP-GGUF/Qwen3.6-35B-A3B-MTP-Q8_0.gguf \ --spec-type draft-mtp \ --spec-draft-n-max 3 \ -c 65536 \ --host 127.0.0.1 \ --port 8081
P.S.: モデルは Unsloth リポジトリから GGUF 形式でダウンロード可能です。