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를 로컬 자율 에이전트로 성공적으로 실행하지만, 소스에서는 여전히 몇 가지 남은 과제와 함께 "거의" 완벽하게 작동한다고 언급합니다.
📖 전체 소스 읽기: r/LocalLLaMA
👀 See Also
다중 AI 에이전트 조율: 디스코드, 크론 잡, 명확한 위계 구조
개발자가 세 개의 OpenClaw 에이전트를 운영하면서 Discord를 공유 커뮤니케이션 채널로 사용하여 조정 문제를 해결했습니다. Paperclip의 고비용 하트비트 시스템을 에이전트별 cron 작업으로 대체하고, Claude Max와 OpenAI 모델 간에 명확한 리더십 계층을 구축했습니다.
ALMA 실험: 100달러와 지침 없이 자율 AI 에이전트를 두 달 동안 운영하기
한 개발자가 암호화폐 100달러, 인터넷 접속, 그리고 지침 없이 ALMA라는 AI 에이전트를 두 달간 운영했습니다. 이 에이전트는 인간의 개입 없이 135개의 독창적인 글을 작성하고, 자선 단체에 기부하며, 일관된 패턴을 발전시켰습니다.
리눅스에서 FreeBSD로 Wi-Fi 드라이버 포팅에 AI 활용: 사례 연구
한 개발자가 Claude Code와 Pi 에이전트를 사용해 Broadcom BCM4350 Wi-Fi 칩용 Linux brcmfmac 드라이버를 FreeBSD로 포팅하려 시도했습니다. 먼저 직접적인 코드 번역을 시도했고, 이후 클린룸 구현을 위한 11장으로 구성된 상세한 명세서를 생성했습니다.
클로드 코드로 코딩 없이 AI 에이전트 구축하기: 세 가지 실용적인 예시
레딧 사용자가 Claude Code를 사용하여 AI 에이전트를 만드는 개인 설정을 공유하며, 이메일, 할 일, 캘린더에서 정보를 가져오는 자동화된 아침 브리핑 에이전트, Substack 기사를 캡처하기 위한 tmux 기반 파이프라인, 회의 요약 에이전트 등 세 가지 구체적인 구현 사례를 설명합니다.