LM Studio Headless CLI와 Claude Code로 로컬에서 Google Gemma 4 실행하기

6 days ago 6

Gemma 4는 mixture-of-experts 구조로 일부 파라미터만 활성화해 저사양 하드웨어에서도 고성능 추론을 지원
LM Studio 0.4.0은 새로운 Headless CLI(llmster) 를 도입해 데스크톱 앱 없이 모델 다운로드·로드·채팅·API 서버 실행이 가능
OpenAI·Anthropic 호환 API를 통해 Gemma 4를 로컬 서버로 제공하고, Claude Code를 완전 오프라인 코드 어시스턴트로 활용 가능
컨텍스트 길이·GPU 오프로딩·병렬 요청 등 세밀한 하드웨어 튜닝으로 성능과 메모리 효율을 조정할 수 있음
MoE 모델 기반 로컬 추론은 API 비용 없이 빠른 코드 리뷰와 프롬프트 테스트를 가능하게 하며, 개발자용 오프라인 AI 환경 구축의 핵심 기술로 부상

로컬에서 Google Gemma 4 실행하기 — LM Studio의 새로운 Headless CLI와 Claude Code 연동

로컬 실행의 필요성
- 클라우드 AI API는 요금, 속도 제한, 개인정보, 네트워크 지연 등의 제약 존재
- 코드 리뷰, 초안 작성, 프롬프트 테스트 등 빠른 반복 작업에는 로컬 모델 실행이 유리
- 로컬 실행은 API 비용 0, 데이터 외부 전송 없음, 항상 사용 가능이라는 장점 제공
- Gemma 4는 mixture-of-experts(MoE) 구조로 26B 모델 중 4B 파라미터만 활성화되어저사양 하드웨어에서도 고성능 실행 가능
  - M4 Pro MacBook(48GB)에서 초당 51토큰 생성 속도 기록, Claude Code 내에서는 다소 느려짐
Gemma 4 모델 계열
- Google은 Gemma 4를 4가지 모델군으로 공개, 다양한 하드웨어에 최적화
- E 시리즈(E2B, E4B) 는 Per-Layer Embeddings를 사용하며 오디오 입력(음성 인식·번역) 지원
- 31B dense 모델은 MMLU Pro 85.2%, AIME 2026 89.2% 성능
- 26B-A4B 모델은 128개 전문가 중 8개(3.8B 파라미터)만 활성화되어 10B급 품질에 4B급 비용으로 동작
- MMLU Pro 82.6%, AIME 88.3%로 31B dense 모델에 근접하며 Elo 1441로 400B+ 모델과 경쟁
- 256K 컨텍스트, 비전 입력, 함수 호출, 추론 모드 설정 지원으로 로컬 추론에 적합
LM Studio 0.4.0의 주요 변화
- llmster라는 독립형 추론 엔진 도입으로데스크톱 앱 없이 CLI로 완전 실행 가능
  - lms CLI를 통해 모델 다운로드, 로드, 채팅, 서버 실행 모두 수행 가능
  - 주요 기능:
  - llmster daemon: 백그라운드에서 모델 로드·추론 관리
  - 병렬 요청 처리: 연속 배칭으로 여러 요청 동시 처리
  - Stateful REST API: /v1/chat 엔드포인트로 대화 이력 유지
  - MCP 통합: 로컬 Model Context Protocol 지원
설치 및 모델 다운로드
- 설치 명령: curl -fsSL https://lmstudio.ai/install.sh | bash
- 데몬 실행: lms daemon up
- 런타임 업데이트: lms runtime update llama.cpp, lms runtime update mlx
- Gemma 4 26B 모델 다운로드: lms get google/gemma-4-26b-a4b
- 기본 양자화는 Q4_K_M (17.99GB)
- 다운로드 후 lms load google/gemma-4-26b-a4b로 로드
로컬 모델 관리
- 설치된 모델 목록 확인: lms ls
- 예시 출력에는 Gemma 4, Qwen 3.5, GLM 4.7 Flash 등 MoE 모델 다수 포함
- MoE 모델은 활성 파라미터 일부만 사용하여 효율적 추론 가능
대화 실행 및 성능
- 대화 시작: lms chat google/gemma-4-26b-a4b --stats
- 출력 예시: Tokens/Second: 51.35 Time to First Token: 1.551s
- 51 tok/sec, 1.5초 초기 응답으로 상호작용에 충분한 속도
모델 상태 및 메모리 확인
- 로드된 모델 확인: lms ps
- 예시: 17.99GB 메모리 사용, 48K 컨텍스트, 2개 병렬 요청, TTL 1시간
- JSON 출력(lms ps --json | jq)에서 확인 가능한 주요 항목:
  - "architecture": "gemma4"
  - "quantization": {"name": "Q4_K_M", "bits": 4}
  - "vision": true, "trainedForToolUse": true
  - "maxContextLength": 262144, "parallel": 2
컨텍스트 길이에 따른 메모리 추정
- --estimate-only 옵션으로 메모리 요구량 예측 가능
- 기본 모델 약 17.6GiB, 컨텍스트 2배마다 3~4GiB 증가
- 48K 컨텍스트 시 약 21GiB 필요, 256K에서는 37.48GiB
- 명령 예시: lms load google/gemma-4-26b-a4b --estimate-only --context-length 48000
- 컨텍스트 길이와 메모리의 선형 관계로 용량 계획에 유용
하드웨어별 로드 튜닝
- 컨텍스트 길이
  - OS 사용량(4~6GB)을 제외한 메모리 한도 내에서 설정
  - 예: lms load google/gemma-4-26b-a4b --context-length 128000
- GPU 오프로딩
  - Apple Silicon은 통합 메모리 구조, --gpu=1.0으로 전체 GPU 사용 가능
  - NVIDIA 시스템은 VRAM 한도 내에서 --gpu=0.5 등으로 분할 가능
- 병렬 요청
  - 연속 배칭(continuous batching) 으로 여러 요청 동시 처리
  - GUI에서 Max Concurrent Predictions 설정 (기본 4)
  - Gemma 4의 경우 48GB 시스템에서 48K 컨텍스트, 병렬 2개가 적절
- TTL 자동 언로드
  - --ttl 1800으로 30분 비활성 시 자동 해제
  - 기본 1시간, 0 또는 -1로 비활성화 가능
- 모델별 기본값 저장
  - 데스크톱 앱의 My Models → 설정 아이콘에서 GPU, 컨텍스트, Flash Attention 기본값 저장
- 추측 디코딩(Speculative Decoding)
  - MoE 모델에서는 비효율적, Gemma 4에서는 비활성 권장
  - Mixtral 테스트 결과 코드 작업 39% 향상, 수학 작업 54% 저하
- Flash Attention
  - KV 캐시 메모리 절감으로 긴 컨텍스트 지원
  - Apple Silicon에서 활성화 시 메모리 절약 효과
LM Studio 데스크톱 앱
- GUI에서 서버 상태, 모델 로드, API 엔드포인트, 로그 스트림 시각화
- Anthropic 프로토콜(POST /v1/messages) 포함
- 비전 기능으로 이미지 분석 가능
- 예시: Timezone Scheduler 이미지 분석 시 504토큰 생성, 54.51 tok/sec
- 시스템 모니터링 결과:
  - 메모리 사용 46.69GB/48GB, 스왑 27.49GB
  - GPU 90% 활용, CPU 91°C, GPU 92°C
  - 전력 23.56W (CPU 11.06W, GPU 13.32W)
- 통합 메모리 구조로 CPU/GPU 간 데이터 복사 불필요
API 서버로 모델 제공
- 서버 시작: lms server start
- OpenAI 호환 API: http://localhost:1234/v1
- Anthropic 호환 엔드포인트: POST /v1/messages
- 포트 변경: --port 8080
- JIT 모델 로딩으로 요청 시 자동 로드 및 TTL 후 자동 언로드
- 실시간 로그 스트림: lms log stream --source model --stats
- 네트워크 내 다른 장치에서도 접근 가능, API 토큰 인증 지원
Claude Code와의 연동
- Anthropic 호환 엔드포인트를 통해 Claude Code를 로컬 모델로 실행 가능
- ~/.zshrc에 claude-lm 함수 추가: export ANTHROPIC_BASE_URL=http://localhost:1234 export ANTHROPIC_MODEL="gemma-4-26b-a4b" ... claude "$@"
- 모든 Claude Code 모델 호출(Opus, Sonnet, Haiku)을 Gemma 4로 라우팅
- 48K 컨텍스트, 8K 토큰 출력 제한, 로컬 전용 환경 구성
- claude-lm 실행 시 완전 오프라인 코드 어시스턴트 사용 가능
- 속도는 클라우드 대비 느리지만 코드 리뷰·소규모 수정·탐색 작업에 적합
주요 교훈
- MoE 모델이 로컬 추론의 핵심: Gemma 4 26B-A4B는 10B급 품질에 4B급 비용
- Headless 데몬으로 완전 CLI 기반 워크플로우 가능
- 컨텍스트 길이가 메모리 사용의 주요 변수
- --estimate-only로 OOM 방지
- Anthropic 호환 엔드포인트로 Claude Code를 로컬에서 완전 오프라인 실행 가능
한계점
- lms chat에서 모델 이름을 직접 표시하지 않음
- 기본 48K 컨텍스트는 보수적이며, 메모리 여유 시 확장 권장
- Claude Code 로컬 실행은 Anthropic API 완전 대체 불가, 대규모 작업에는 제약 존재
- 48GB 시스템에서는 메모리 압박 및 스왑 사용 발생, 64GB 이상 권장
다음 단계
- Qwen 3.5 35B, GLM 4.7 Flash, Nemotron 3 Nano 등과의 비교 테스트 예정
- 실행 절차 요약: curl -fsSL https://lmstudio.ai/install.sh | bash lms daemon up lms get google/gemma-4-26b-a4b lms chat google/gemma-4-26b-a4b --stats
- Claude Code 연동: claude-lm 함수 추가 후 claude-lm 실행
- 로컬 AI 워크플로우 구축 및 웹앱·개발자 환경 통합에 활용 가능