Запуск Gemma 4 в качестве локального автономного агента с Claude Code на 16 ГБ видеопамяти

Настройка локального агента с Gemma 4 и Claude Code

Разработчик задокументировал процесс замены API Anthropic Claude на локальную модель Gemma 4 с 31 миллиардом параметров для создания автономного кодирующего агента с полным доступом к оболочке через CLI Claude Code. Цель состояла в том, чтобы локальная LLM могла не только писать код в чате, но и автономно взаимодействовать с терминалом, создавать папки, читать структуры и действовать как проактивный агент разработки.

Аппаратное и программное обеспечение

• ОС: Windows 11
• ЦП и ОЗУ: Intel Core Ultra 9 285K с 64 ГБ системной оперативной памяти
• Графические процессоры: NVIDIA RTX 4060 (8 ГБ) + NVIDIA RTX 3050 (8 ГБ) = 16 ГБ общей видеопамяти
• Основная модель: google_gemma-4-31B-it (GGUF V3)
• Программный стек:
  • llama.cpp (llama-server) - последняя сборка b8672
  • Claude Code CLI - v2.1.92
  • LiteLLM + пользовательский шлюз на Python (agent_router.py) для подключения потоковых фрагментов Anthropic к API OpenAI

Проблема 1: Сбои парсинга вызовов инструментов

Изначально Gemma 4 отказывалась выполнять инструменты через пользовательскую маршрутизацию API, выдавая извинения вместо действий. При принудительном выводе системных вызовов инструментов в нативном формате, Claude Code CLI выдавал ошибки TypeScript: Cannot read properties of undefined (reading 'input_tokens').

Решение: Gemma 4 использует невидимый блок рассуждений <thought> перед финализацией вывода. Скрипт agent_router.py ожидал традиционные непрерывные текстовые фрагменты, из-за чего пропускал отправку обязательного начального события Anthropic message_start. Разработчик модифицировал цикл перехвата Python для явного извлечения и объединения reasoning_content со стандартными выводами, гарантируя, что поток всегда инициализируется с полными метриками использования. Обновление до сборки llama.cpp b8672 было обязательным для корректной работы токенизатора.

Проблема 2: Ограничения контекстного окна

Claude Code v2.1.92 работает с огромным системным промптом, который включает активное дерево папок и системные инструкции, отправляя 7182 токена на локальный сервер при инициализации. Изначальное значение n_ctx (контекстное окно) было ограничено 4096 для экономии видеопамяти, что вызывало немедленные сбои сервера.

Решение: Контекстное окно было увеличено вдвое до 16 384 для размещения начального промпта и истории разговора.

Проблема 3: Проблемы с выделением видеопамяти

С контекстным окном 16K для модели 31B выделение видеопамяти стало проблематичным. Контекстное окно 16K при настройках по умолчанию требует примерно 6,4 ГБ только для KV-кэша. Накладные расходы Windows WDDM резервируют примерно 20% памяти GPU для дисплейных/фоновых буферов, оставляя доступными только ~12,8 ГБ из 16 ГБ общей видеопамяти до ошибок CUDA_out_of_memory.

Первоначальный расчёт показал: Модель (13 ГБ) + KV-кэш (6,4 ГБ) = 19,4 ГБ, что превышает доступную видеопамять.

Финальная конфигурация

Расчёты и решение: Разработчик отказался от модели Q3_K_M (~13,7 ГБ) и переключился на формат IQ3_XS (~12,9 ГБ). Оптимизированная команда запуска сервера:

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: 8-битная квантизация KV-кэша, которая сократила его объём вдвое с 6,4 ГБ
• -c 16384: Контекстное окно 16K
• -ngl 38: Количество слоёв на GPU

Эта конфигурация успешно запускает Gemma 4 в качестве локального автономного агента на 16 ГБ видеопамяти, хотя в источнике отмечается, что она работает «почти» идеально с некоторыми оставшимися проблемами.