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
• GPUs: 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 할당 문제

310억 모델에 16K 컨텍스트 창을 사용하면 VRAM 할당이 문제가 되었습니다. 기본 설정을 사용하는 16K 컨텍스트 창은 KV 캐시만으로도 약 6.4GB가 필요합니다. Windows WDDM 오버헤드는 디스플레이/백그라운드 버퍼에 GPU 메모리의 약 20%를 예약하여 CUDA_out_of_memory 오류 발생 전 총 16GB VRAM 중 약 12.8GB만 접근 가능하게 합니다.

초기 계산 결과: 모델 (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.4GB에서 절반으로 줄인 8비트 KV 캐시 양자화
• -c 16384: 16K 컨텍스트 창
• -ngl 38: GPU 레이어 수

이 구성은 16GB VRAM에서 Gemma 4를 로컬 자율 에이전트로 성공적으로 실행하지만, 소스에서는 여전히 몇 가지 남은 과제와 함께 "거의" 완벽하게 작동한다고 언급합니다.