ローカルの大規模モデルは「かろうじて使える」という分水嶺を超えました。GoogleがこのたびリリースしたGemma 4シリーズの助けを借りれば、2022年モデルのM2 Mac（メモリ64GB）1台で、エージェントによるコーディング、スクリプトのリファクタリング、ユニットテストの作成などをこなせ、ループの正確性と速度はおよそ最先端モデルの75%に達します。このチュートリアルでは、ローカルAgentワークフロー全体を再現可能なステップに分解します。プライバシー環境やオフラインシーンでAIコーディングアシスタントを走らせたい開発者に向いています。

始める前の準備

• ハードウェア：Apple Silicon Mac（M2以上）を推奨。ユニファイドメモリ16GB以上、64GBならなお良い（KVキャッシュがメモリを食い尽くします）
• ソフトウェア：Docker Desktop、LM Studio（ローカル推論サービス）、Piエージェントフレームワーク
• モデル：Gemma 4シリーズ。gemma-4-12b-qat（より新しく、より小さく、より速く、正確性の劣化は小さい）か gemma-4-26b-a4b を推奨
• 所要時間：初回設定は約30分

ローカルモデルはいまどんなレベルか

OpenAIが2025年8月にGPT-OSSをリリースする以前は、ローカルモデルはほとんどのプログラミングタスクで精度不足でした。Gemma 4シリーズのリリース後、作者は実際にこれらのタスクをそれでこなしました。

• Pythonノートブックを5-6モジュールのリポジトリへリファクタリング
• モジュールのコード検査を行い、ジェネリック型ヒントを修正
• ブログ記事の校正、ユニットテストの作成
• 双塔モデル（two-tower）ベースの推薦システムのリポジトリ骨格をゼロから構築

いずれも6か月前のローカルモデルにはまったく手に負えなかったタスクです。

ステップ1：LM Studio でローカル推論サービスを起動

1. LM Studio をインストールして開きます。
2. モデルマーケットで gemma-4-12b-qat をダウンロードします。
3. Local Serverを起動します。デフォルトで http://localhost:1234/v1 をリッスンします（OpenAI互換インターフェース）。

起動すると、LM StudioはOpenAI形式の推論エンドポイントを提供し、Piはこのエンドポイント経由でローカルモデルを呼び出します。

ヒント：LM Studioの代わりにOllama、llama.cpp、Open WebUIを使うこともできます。llama.cppを直接使うほうが速く、あとで試す価値のある最適化方向です。

ステップ2：Pi を LM Studio へ向けて設定

Piは models.json でモデルを設定します。次の設定を ~/.pi/agent/models.json に書き込み、エンドポイントをDockerホスト上のLM Studioへ向けます。

{
  "lmstudio": {
    "baseUrl": "http://host.docker.internal:1234/v1",
    "api": "openai-completions",
    "apiKey": "not-needed",
    "models": [
      {
        "id": "google/gemma-4-12b-qat",
        "input": ["text", "image"]
      }
    ]
  }
}

host.docker.internal は、Dockerコンテナからホストマシンへアクセスするためのエイリアスです。本物のOpenAI APIも同時に使っている場合は、衝突を避けるため OPENAI_API_BASE に別のbaseを指定する必要があります。

ステップ3：Docker Compose で Pi を実行（安全サンドボックス）

Piは権限を絞ったDockerコンテナで動かし、bash権限だけを与えて、物理ドライブを直接読み書きさせないことを強くおすすめします。

services:
  pi:
    build:
      context: .
      dockerfile: Dockerfile
    image: pi-agent:0.74.0
    init: true
    stdin_open: true
    tty: true
    extra_hosts:
      - "host.docker.internal:host-gateway"
    environment:
      ANTHROPIC_API_KEY: ${ANTHROPIC_API_KEY:-}
      OPENAI_API_KEY: ${OPENAI_API_KEY:-not-needed}
      GEMINI_API_KEY: ${GEMINI_API_KEY:-}
      OPENAI_API_BASE: ${OPENAI_API_BASE:-http://host.docker.internal:1234/v1}
    volumes:
      - ${HOME}/.pi/agent/models.json:/config/models.json
      - ${WORKSPACE:-.}:/workspace
      - pi-config:/config
      - pi-sessions:/sessions
    working_dir: /workspace

volumes:
  pi-config:
  pi-sessions:

重要なポイント：現在の作業ディレクトリを /workspace としてマウントすれば、Piはあなたのコードリポジトリ内でファイルを操作でき、コンテナ外のシステムディレクトリには触れません。

ステップ4：起動スクリプトを書く

以下は推奨の pi 起動スクリプトです。作業ディレクトリからコンテナ名を自動生成し、より厳格なサンドボックスを有効にする --sandbox オプションに対応します。

#!/usr/bin/env bash
# Pi — Start the containerized Pi agent.

SCRIPT_DIR="$(cd -- "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
WORKSPACE_DIR="${WORKSPACE:-$(pwd)}"
case "$WORKSPACE_DIR" in
  /) ;;
  *) WORKSPACE_DIR="$(cd -- "$WORKSPACE_DIR" && pwd)" ;;
esac
export WORKSPACE="$WORKSPACE_DIR"

sandbox="${PI_SANDBOX:-0}"
pi_args=()
while (($#)); do
  case "$1" in
    --sandbox)    sandbox=1 ;;
    --no-sandbox) sandbox=0 ;;
    *)            pi_args+=("$1") ;;
  esac
  shift
done

compose_files=(-f "$SCRIPT_DIR/docker-compose.yml")
if [[ "$sandbox" == "1" ]]; then
  compose_files+=(-f "$SCRIPT_DIR/docker-compose.sandbox.yml")
fi

repo_slug="$(basename -- "$WORKSPACE_DIR" | tr -c 'a-zA-Z0-9_.-' '-' | sed 's/^-//')"
[[ -z "$repo_slug" ]] && repo_slug="workspace"
container_name="pi-${repo_slug}-$$"

api_key_args=(-e OPENAI_API_KEY -e DEEPSEEK_API_KEY -e ANTHROPIC_API_KEY -e GEMINI_API_KEY)

cmd=(docker compose --project-directory "$SCRIPT_DIR" "${compose_files[@]}" run --rm --name "$container_name" "${api_key_args[@]}" pi)
if ((${#pi_args[@]})); then cmd+=("${pi_args[@]}"); fi
exec "${cmd[@]}"

検証結果

編集中のコードリポジトリのディレクトリで ./pi を実行すると、PiがDockerを起動して /workspace に入ります。検証として、こんなことを頼んでみてください。

• Piに現在のリポジトリのモジュールを1つリファクタリングさせ、ファイルを正しく分割できるか観察する
• 型ヒントが正しいか検査させる
• LM Studioの画面でトークンの推論過程、KVキャッシュの占有、コンテキストウィンドウの変化をリアルタイムで観察する

うまく動けば、PiがDocker内でファイルを修正しbashを呼び出し、ローカルモデルがバックグラウンドでトークンを1つずつ推論している様子が見られます。

よくある質問

• 推論速度が遅い：ローカルモデルはハードウェアの制約を受け、コンテキストウィンドウが小さくなります。より小さい量子化モデル（12B QATなど）に変えるか、コンテキスト長を減らしましょう。
• プロンプトテンプレートが合わない：初期バージョンによくある問題です。LM StudioとHuggingFaceの「このモデルを使用」ボタンでたいていは素早く修復できます。ツールを最新に保ちましょう。
• KVキャッシュがパンパンになる：64GBのメモリも長いコンテキストで埋まることがあります。メモリ使用を監視し、必要ならセッションを再起動しましょう。
• 本番のソフトウェア開発に使えるか？ 現時点ではまだ完全に成熟していませんが、高速でパーソナライズされたローカルのドキュメント照会と補助コーディングとしてはすでに十分実用的で、特にプライバシー敏感シーンでは投資する価値があります。