Ausführen von Gemma 4 als lokaler autonomer Agent mit Claude Code auf 16 GB VRAM

Lokale Agent-Einrichtung mit Gemma 4 und Claude Code

Ein Entwickler dokumentierte seinen Prozess, bei dem er die Anthropic Claude API durch ein lokales 31-Milliarden-Parameter-Gemma-4-Modell ersetzte, um einen autonomen Coding-Agent mit vollem Shell-Zugriff über Claude Code CLI zu erstellen. Das Ziel war es, dem lokalen LLM nicht nur das Schreiben von Code im Chat zu ermöglichen, sondern ihm auch eine autonome Interaktion mit dem Terminal, das Erstellen von Ordnern, das Lesen von Strukturen und das Agieren als proaktiver Entwicklungsagent zu erlauben.

Hardware- und Software-Stack

• Betriebssystem: Windows 11
• CPU & RAM: Intel Core Ultra 9 285K CPU mit 64 GB System-RAM
• GPUs: NVIDIA RTX 4060 (8 GB) + NVIDIA RTX 3050 (8 GB) = 16 GB Gesamt-VRAM
• Kernmodell: google_gemma-4-31B-it (GGUF V3)
• Software-Stack:
  • llama.cpp (llama-server) - neueste b8672-Version
  • Claude Code CLI - v2.1.92
  • LiteLLM + benutzerdefinierte Python-Gateway (agent_router.py), um Anthropic-Streaming-Chunks mit OpenAI-APIs zu verbinden

Problem 1: Tool-Call-Parsing-Fehler

Zunächst weigerte sich Gemma 4, Tools über das benutzerdefinierte API-Routing auszuführen, und entschuldigte sich stattdessen. Wenn es gezwungen wurde, systemeigene Tool-Calls auszugeben, warf Claude Code CLI TypeScript-Fehler: Cannot read properties of undefined (reading 'input_tokens').

Die Lösung: Gemma 4 verwendet einen unsichtbaren <thought>-Denkblock, bevor es die Ausgabe finalisiert. Das agent_router.py-Skript erwartete traditionelle kontinuierliche Text-Chunks, wodurch es das Senden des obligatorischen initialen message_start-Anthropic-Events übersprang. Der Entwickler modifizierte die Python-Interceptionsschleife, um explizit reasoning_content mit Standardausgaben zu extrahieren und zu kombinieren, wodurch sichergestellt wurde, dass der Stream immer mit vollständigen Nutzungsmetriken initialisiert wurde. Ein Upgrade auf llama.cpp Build b8672 war für eine ordnungsgemäße Tokenizer-Funktionalität erforderlich.

Problem 2: Kontextfenster-Beschränkungen

Claude Code v2.1.92 arbeitet mit einem massiven System-Prompt, der den aktiven Ordnerbaum und Systemanweisungen einbettet und beim Initialisieren 7.182 Tokens auf den lokalen Server lädt. Das anfängliche n_ctx (Kontextfenster) war auf 4096 begrenzt, um VRAM zu sparen, was zu sofortigen Serverabstürzen führte.

Die Lösung: Das Kontextfenster wurde auf 16.384 verdoppelt, um den initialen Prompt und die Konversationshistorie aufzunehmen.

Problem 3: VRAM-Zuweisungsprobleme

Mit einem 16K-Kontextfenster für ein 31B-Modell wurde die VRAM-Zuweisung problematisch. Ein 16K-Kontextfenster mit Standardeinstellungen erfordert allein für den KV-Cache etwa 6,4 GB. Der Windows-WDDM-Overhead reserviert ungefähr 20 % des GPU-Speichers für Display-/Hintergrundpuffer, wodurch nur ~12,8 GB von 16 GB Gesamt-VRAM zugänglich sind, bevor CUDA_out_of_memory-Fehler auftreten.

Die anfängliche Berechnung zeigte: Modell (13 GB) + KV-Cache (6,4 GB) = 19,4 GB, was den verfügbaren VRAM überstieg.

Endgültige Konfiguration

Die Berechnung & Lösung: Der Entwickler verwarf das Q3_K_M-Modell (~13,7 GB) und wechselte zum IQ3_XS-Format (~12,9 GB). Der optimierte Server-Startbefehl:

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

Wichtige Flags:

• -ctk q8_0 -ctv q8_0: 8-Bit-KV-Cache-Quantisierung, die den KV-Cache-Fußabdruck von 6,4 GB halbierte
• -c 16384: 16K-Kontextfenster
• -ngl 38: Anzahl der GPU-Layer

Diese Konfiguration führt Gemma 4 erfolgreich als lokalen autonomen Agent auf 16 GB VRAM aus, obwohl die Quelle anmerkt, dass es "fast" perfekt funktioniert, mit einigen verbleibenden Herausforderungen.