Exécuter Gemma 4 en tant qu'agent autonome local avec Claude Code sur 16 Go de VRAM

Configuration d'un Agent Local avec Gemma 4 et Claude Code

Un développeur a documenté son processus de remplacement de l'API Claude d'Anthropic par un modèle Gemma 4 local de 31 milliards de paramètres pour créer un agent de codage autonome avec un accès complet au shell via Claude Code CLI. L'objectif était de permettre au LLM local non seulement d'écrire du code en chat, mais d'interagir de manière autonome avec le terminal, de créer des dossiers, de lire des structures et d'agir comme un agent de développement proactif.

Matériel et Pile Logicielle

• Système d'exploitation : Windows 11
• Processeur et RAM : Processeur Intel Core Ultra 9 285K avec 64 Go de RAM système
• Cartes graphiques : NVIDIA RTX 4060 (8 Go) + NVIDIA RTX 3050 (8 Go) = 16 Go de VRAM total
• Modèle principal : google_gemma-4-31B-it (GGUF V3)
• Pile logicielle :
  • llama.cpp (llama-server) - version b8672 la plus récente
  • Claude Code CLI - v2.1.92
  • LiteLLM + passerelle Python personnalisée (agent_router.py) pour relier les fragments de streaming Anthropic aux API OpenAI

Problème 1 : Échecs d'Analyse des Appels d'Outils

Initialement, Gemma 4 refusait d'exécuter des outils via le routage API personnalisé, optant pour des excuses plutôt que pour l'action. Lorsqu'il était forcé de produire des appels d'outils système nativement, Claude Code CLI générait des erreurs TypeScript : Cannot read properties of undefined (reading 'input_tokens').

La Solution : Gemma 4 utilise un bloc de raisonnement invisible <thought> avant de finaliser la sortie. Le script agent_router.py attendait des fragments de texte continus traditionnels, ce qui l'amenait à omettre l'envoi de l'événement Anthropic initial obligatoire message_start. Le développeur a modifié la boucle d'interception Python pour extraire et combiner explicitement reasoning_content avec les sorties standard, garantissant que le flux s'initialisait toujours avec des métriques d'utilisation complètes. La mise à niveau vers la version b8672 de llama.cpp était obligatoire pour une fonctionnalité correcte du tokenizer.

Problème 2 : Limitations de la Fenêtre de Contexte

Claude Code v2.1.92 fonctionne avec un énorme prompt système qui intègre l'arborescence des dossiers actifs et les instructions système, déversant 7 182 tokens dans le serveur local lors de l'initialisation. Le n_ctx initial (fenêtre de contexte) était limité à 4096 pour économiser la VRAM, provoquant des plantages immédiats du serveur.

La Solution : La fenêtre de contexte a été doublée à 16 384 pour accommoder le prompt initial et l'historique de la conversation.

Problème 3 : Défis d'Allocation de VRAM

Avec une fenêtre de contexte de 16K pour un modèle de 31B, l'allocation de VRAM est devenue problématique. Une fenêtre de contexte de 16K utilisant les paramètres par défaut nécessite environ 6,4 Go de cache KV seul. La surcharge WDDM de Windows réserve environ 20 % de la mémoire GPU pour les tampons d'affichage/arrière-plan, ne laissant que ~12,8 Go accessibles sur 16 Go de VRAM total avant les erreurs CUDA_out_of_memory.

Le calcul initial montrait : Modèle (13 Go) + Cache KV (6,4 Go) = 19,4 Go, dépassant la VRAM disponible.

Configuration Finale

Les Calculs et la Solution : Le développeur a abandonné le modèle Q3_K_M (~13,7 Go) et est passé au format IQ3_XS (~12,9 Go). La commande de démarrage optimisée du serveur :

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

Indicateurs clés :

• -ctk q8_0 -ctv q8_0 : Quantification du cache KV en 8 bits qui a réduit de moitié l'empreinte du cache KV de 6,4 Go
• -c 16384 : Fenêtre de contexte de 16K
• -ngl 38 : Nombre de couches GPU

Cette configuration exécute avec succès Gemma 4 comme un agent autonome local sur 16 Go de VRAM, bien que la source note qu'il fonctionne "presque" parfaitement avec quelques défis restants.