16GB VRAMでClaude Codeを使用してGemma 4をローカル自律エージェントとして実行する

Gemma 4とClaude Codeを使ったローカルエージェントのセットアップ

ある開発者が、AnthropicのClaude APIをローカルの310億パラメータのGemma 4モデルに置き換え、Claude Code CLIを通じて完全なシェルアクセスを持つ自律的なコーディングエージェントを作成するプロセスを記録しました。目標は、ローカルLLMがチャットでコードを書くだけでなく、ターミナルと自律的に対話し、フォルダを作成し、構造を読み取り、積極的な開発エージェントとして機能できるようにすることでした。

ハードウェアとソフトウェアスタック

• OS: Windows 11
• CPU & RAM: Intel Core Ultra 9 285K CPU、64GBシステムRAM
• GPU: NVIDIA RTX 4060 (8GB) + NVIDIA RTX 3050 (8GB) = 合計16GB VRAM
• コアモデル: google_gemma-4-31B-it (GGUF V3)
• ソフトウェアスタック:
  • llama.cpp (llama-server) - 最新のb8672ビルド
  • Claude Code CLI - v2.1.92
  • LiteLLM + カスタムPythonゲートウェイ (agent_router.py) - AnthropicのストリーミングチャンクをOpenAI APIにブリッジするため

問題1: ツール呼び出しのパース失敗

最初、Gemma 4はカスタムAPIルーティングを通じてツールを実行することを拒否し、アクションではなく謝罪をデフォルトとしました。システムツール呼び出しをネイティブに出力するように強制すると、Claude Code CLIはTypeScriptエラーをスローしました: Cannot read properties of undefined (reading 'input_tokens')。

修正: Gemma 4は出力を確定する前に不可視の<thought>推論ブロックを使用します。agent_router.pyスクリプトは従来の連続テキストチャンクを期待していたため、必須の初期message_start Anthropicイベントの送信をスキップしていました。開発者はPythonインターセプションループを修正し、reasoning_contentを標準出力と明示的に抽出・結合し、ストリームが常に完全な使用メトリクスで初期化されるようにしました。適切なトークナイザー機能のため、llama.cppビルドb8672へのアップグレードが必須でした。

問題2: コンテキストウィンドウの制限

Claude Code v2.1.92は、アクティブなフォルダツリーとシステム指示を埋め込んだ大規模なシステムプロンプトで動作し、初期化時に7,182トークンをローカルサーバーにダンプします。初期のn_ctx（コンテキストウィンドウ）はVRAMを節約するために4096に制限されており、即座にサーバークラッシュを引き起こしました。

解決策: コンテキストウィンドウを16,384に倍増し、初期プロンプトと会話履歴に対応できるようにしました。

問題3: VRAM割り当ての課題

31Bモデルで16Kコンテキストウィンドウを使用すると、VRAM割り当てが問題となりました。デフォルト設定で16Kコンテキストウィンドウを使用するには、KVキャッシュだけで約6.4 GBが必要です。Windows WDDMオーバーヘッドは、表示/背景バッファー用にGPUメモリの約20%を予約するため、CUDA_out_of_memoryエラーが発生する前に、合計16GB VRAMのうち約12.8 GBしかアクセスできません。

初期計算では、モデル（13 GB）+ KVキャッシュ（6.4 GB）= 19.4 GBとなり、利用可能なVRAMを超えていました。

最終設定

計算と解決策: 開発者はQ3_K_Mモデル（約13.7GB）を放棄し、IQ3_XS形式（約12.9GB）に切り替えました。最適化されたサーバー起動コマンド:

bat.\llm-server\llama-server.exe -m D:\gemma4\google_gemma-4-31B-it-IQ3_XS.gguf -c 16384 -ngl 38 -ctk q8_0 -ctv q8_0 --host 127.0.0.1 --port 8080

主要フラグ:

• -ctk q8_0 -ctv q8_0: KVキャッシュフットプリントを6.4 GBから半減させる8ビットKVキャッシュ量子化
• -c 16384: 16Kコンテキストウィンドウ
• -ngl 38: GPUレイヤー数

この設定により、Gemma 4を16GB VRAMでローカル自律エージェントとして実行することに成功しましたが、ソースでは「ほぼ」完璧に動作し、いくつかの課題が残っていると記されています。