Ejecutando Gemma 4 como un Agente Autónomo Local con Claude Code en 16 GB de VRAM

Configuración de Agente Local con Gemma 4 y Claude Code

Un desarrollador documentó su proceso de reemplazar la API de Claude de Anthropic con un modelo Gemma 4 local de 31 mil millones de parámetros para crear un agente de codificación autónomo con acceso completo al shell mediante Claude Code CLI. El objetivo era permitir que el LLM local no solo escribiera código en el chat, sino que interactuara autónomamente con la terminal, creara carpetas, leyera estructuras y actuara como un agente de desarrollo proactivo.

Pila de Hardware y Software

• Sistema Operativo: Windows 11
• CPU y RAM: CPU Intel Core Ultra 9 285K con 64GB de RAM del sistema
• GPUs: NVIDIA RTX 4060 (8GB) + NVIDIA RTX 3050 (8GB) = 16GB total de VRAM
• Modelo Principal: google_gemma-4-31B-it (GGUF V3)
• Pila de Software:
  • llama.cpp (llama-server) - compilación más reciente b8672
  • Claude Code CLI - v2.1.92
  • LiteLLM + puerta de enlace personalizada en Python (agent_router.py) para conectar fragmentos de transmisión de Anthropic con las APIs de OpenAI

Problema 1: Fallos en el Análisis de Llamadas a Herramientas

Inicialmente, Gemma 4 se negaba a ejecutar herramientas a través del enrutamiento personalizado de la API, optando por disculpas en lugar de acciones. Cuando se forzó a generar llamadas a herramientas del sistema de forma nativa, Claude Code CLI arrojó errores de TypeScript: Cannot read properties of undefined (reading 'input_tokens').

La Solución: Gemma 4 utiliza un bloque de razonamiento invisible <thought> antes de finalizar la salida. El script agent_router.py esperaba fragmentos de texto continuo tradicionales, lo que hacía que omitiera el envío del evento inicial obligatorio message_start de Anthropic. El desarrollador modificó el bucle de intercepción en Python para extraer y combinar explícitamente reasoning_content con las salidas estándar, asegurando que el flujo siempre se inicializara con métricas de uso completas. La actualización a la compilación b8672 de llama.cpp fue obligatoria para la funcionalidad adecuada del tokenizador.

Problema 2: Limitaciones de la Ventana de Contexto

Claude Code v2.1.92 opera con un mensaje de sistema masivo que incrusta el árbol de carpetas activo y las instrucciones del sistema, volcando 7,182 tokens en el servidor local durante la inicialización. El n_ctx inicial (ventana de contexto) estaba limitado a 4096 para ahorrar VRAM, causando caídas inmediatas del servidor.

La Solución: La ventana de contexto se duplicó a 16,384 para acomodar el mensaje inicial y el historial de conversación.

Problema 3: Desafíos en la Asignación de VRAM

Con una ventana de contexto de 16K para un modelo de 31B, la asignación de VRAM se volvió problemática. Una ventana de contexto de 16K usando configuraciones predeterminadas requiere aproximadamente 6.4 GB solo para la Caché KV. La sobrecarga de Windows WDDM reserva aproximadamente el 20% de la memoria de la GPU para búferes de pantalla/fondo, dejando solo ~12.8 GB accesibles de los 16GB totales de VRAM antes de errores CUDA_out_of_memory.

El cálculo inicial mostró: Modelo (13 GB) + Caché KV (6.4 GB) = 19.4 GB, excediendo la VRAM disponible.

Configuración Final

Las Matemáticas y la Solución: El desarrollador abandonó el modelo Q3_K_M (~13.7GB) y cambió al formato IQ3_XS (~12.9GB). El comando optimizado de inicio del servidor:

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

Banderas clave:

• -ctk q8_0 -ctv q8_0: Cuantización de Caché KV de 8 bits que redujo a la mitad la huella de la Caché KV de 6.4 GB
• -c 16384: Ventana de contexto de 16K
• -ngl 38: Número de capas de GPU

Esta configuración ejecuta exitosamente a Gemma 4 como un agente autónomo local en 16GB de VRAM, aunque la fuente señala que funciona "casi" perfectamente con algunos desafíos restantes.