LM Studio Headless CLI와 Claude Code로 로컬에서 Google Gemma 4 실행하는 방법과 의미

이 글은 Google Gemma 4를 로컬 환경에서 실행하고, LM Studio의 Headless CLI와 Claude Code를 연동해 완전 오프라인 AI 개발 환경을 구축하는 방법을 정리한 기술 블로그입니다.
클라우드 AI API의 비용과 제약에서 벗어나, 개발자가 직접 제어 가능한 로컬 추론 환경을 어떻게 구성할 수 있는지, 그리고 그 핵심 기술과 실전 활용 포인트는 무엇인지 단계별로 살펴봅니다.

반응형

---

왜 지금 로컬 AI 실행이 중요한가

클라우드 기반 AI API는 강력하지만, 실제 개발 환경에서는 여러 한계를 드러냅니다.

• 사용량에 따라 누적되는 API 비용
• 속도 제한과 요청 수 제한
• 코드와 데이터가 외부로 전송되는 구조
• 네트워크 상태에 따른 지연과 불안정성

코드 리뷰, 초안 작성, 프롬프트 테스트처럼 빠른 반복과 즉각적인 응답이 필요한 작업에서는 로컬 모델 실행이 훨씬 효율적입니다.
API 비용이 들지 않고, 데이터가 외부로 나가지 않으며, 언제든 사용할 수 있다는 점은 개발자에게 큰 장점입니다.

---

Gemma 4의 핵심 구조: MoE 기반 고효율 모델

Gemma 4는 Mixture-of-Experts(MoE) 구조를 사용하는 모델입니다.
이 구조의 핵심은 모든 파라미터를 항상 사용하는 것이 아니라, 필요한 일부 전문가(expert)만 선택적으로 활성화한다는 점입니다.

Gemma 4 26B-A4B 모델의 특징

• 총 26B 파라미터 중 약 3.8~4B만 활성화
• 10B급 모델에 가까운 품질을 4B급 비용으로 제공
• 저사양 하드웨어에서도 고성능 추론 가능
• 256K 컨텍스트 길이 지원
• 비전 입력, 함수 호출, 추론 모드 설정 가능

실제 테스트에서는 M4 Pro MacBook(48GB) 환경에서 초당 50 토큰 이상을 생성하며, 로컬 추론 모델로는 충분히 실용적인 성능을 보여줍니다.

---

Gemma 4 모델 계열 정리

Google은 Gemma 4를 여러 모델군으로 공개해 다양한 환경을 지원합니다.

• E 시리즈(E2B, E4B)
  Per-Layer Embeddings 구조를 사용하며 오디오 입력(음성 인식·번역) 지원
• 31B Dense 모델
  최고 성능 지향, 대규모 하드웨어 환경에 적합
• 26B-A4B MoE 모델
  로컬 실행에 최적화된 균형형 모델
  성능은 31B에 근접하지만 메모리와 비용 요구는 훨씬 낮음

특히 26B-A4B 모델은 로컬 추론 환경을 고려할 때 가장 현실적인 선택지입니다.

---

LM Studio 0.4.0의 변화: Headless CLI 시대

LM Studio 0.4.0의 가장 큰 변화는 Headless CLI 기반 실행 환경입니다.
이제 데스크톱 앱 없이도 CLI만으로 모든 작업이 가능합니다.

핵심 구성 요소

• llmster daemon
  백그라운드에서 모델 로드 및 추론 관리
• lms CLI
  모델 다운로드, 로드, 채팅, 서버 실행을 모두 처리
• 병렬 요청 처리
  연속 배칭으로 다중 요청 동시 처리
• Stateful REST API
  대화 이력을 유지하는 /v1/chat 엔드포인트 제공
• MCP(Model Context Protocol)
  로컬 컨텍스트 관리와 연동 가능

이 구조 덕분에 서버, 개발 환경, 자동화 워크플로우에 쉽게 통합할 수 있습니다.

---

설치와 Gemma 4 모델 다운로드

1. LM Studio CLI 설치

curl -fsSL https://lmstudio.ai/install.sh | bash

2. 데몬 실행

lms daemon up

3. 런타임 업데이트

lms runtime update llama.cpp
lms runtime update mlx

4. Gemma 4 모델 다운로드 및 로드

lms get google/gemma-4-26b-a4b
lms load google/gemma-4-26b-a4b

기본 양자화는 Q4_K_M이며, 약 18GB 메모리를 사용합니다.

---

로컬 모델 관리와 대화 실행

• 설치된 모델 확인
• lms ls
• 대화 시작 및 성능 확인
• lms chat google/gemma-4-26b-a4b --stats

실제 결과 예시:

• 초당 약 51 토큰 생성
• 첫 토큰 응답 시간 약 1.5초

로컬 상호작용용으로 충분히 빠른 수준입니다.

---

컨텍스트 길이와 메모리 계획의 중요성

Gemma 4는 긴 컨텍스트를 지원하지만, 컨텍스트 길이는 곧 메모리 사용량입니다.

• 기본 모델 메모리: 약 17.6GiB
• 컨텍스트 길이 2배 증가 시 3~4GiB 추가
• 48K 컨텍스트: 약 21GiB
• 256K 컨텍스트: 약 37GiB

사전에 메모리를 예측할 수 있습니다.

lms load google/gemma-4-26b-a4b --estimate-only --context-length 48000

OOM 방지를 위한 필수 단계입니다.

---

하드웨어별 성능 튜닝 포인트

• 컨텍스트 길이
  OS 사용 메모리를 제외한 여유 범위 내에서 설정
• GPU 오프로딩
  Apple Silicon은 통합 메모리 구조로 GPU 100% 활용 가능
  NVIDIA 환경에서는 VRAM 비율 조절
• 병렬 요청
  연속 배칭으로 처리량 향상
  48GB 시스템 기준 병렬 2개가 안정적
• TTL 자동 언로드
  비활성 시 자동 메모리 해제
• Flash Attention
  긴 컨텍스트에서 메모리 절약 효과
• Speculative Decoding
  Gemma 4에서는 비효율적이므로 비활성 권장

---

API 서버로 Gemma 4 제공하기

lms server start

• OpenAI 호환 API: http://localhost:1234/v1
• Anthropic 호환 엔드포인트: /v1/messages
• 요청 시 자동 모델 로드, TTL 후 자동 언로드
• 네트워크 내 다른 장치에서도 접근 가능

이 구조 덕분에 로컬 모델을 하나의 AI 서버처럼 활용할 수 있습니다.

---

Claude Code를 완전 오프라인으로 사용하는 방법

Anthropic 호환 엔드포인트를 활용하면 Claude Code를 로컬 모델로 대체할 수 있습니다.

환경 변수 설정 예시:

export ANTHROPIC_BASE_URL=http://localhost:1234
export ANTHROPIC_MODEL="gemma-4-26b-a4b"

이후 Claude Code 실행 시 모든 요청이 로컬 Gemma 4로 라우팅됩니다.

• 48K 컨텍스트
• 8K 토큰 출력 제한
• 완전 오프라인 코드 어시스턴트 구성 가능

대규모 작업에는 한계가 있지만, 코드 리뷰와 소규모 수정, 탐색 작업에는 충분히 실용적입니다.

---

728x90

이번 구성에서 얻을 수 있는 핵심 교훈은 명확합니다.

• MoE 모델은 로컬 추론의 현실적인 해답
• Gemma 4 26B-A4B는 성능과 비용의 균형이 뛰어남
• Headless CLI 기반 워크플로우는 개발 자동화에 적합
• 컨텍스트 길이가 메모리 사용의 가장 큰 변수
• Claude Code까지 오프라인으로 대체 가능

로컬 AI 실행은 더 이상 실험적인 영역이 아닙니다.
비용, 개인정보, 속도를 동시에 잡고 싶은 개발자라면, Gemma 4와 LM Studio 기반 로컬 AI 환경은 충분히 실용적인 선택지가 되고 있습니다.

앞으로 다양한 MoE 모델과의 비교 테스트가 이어진다면, 로컬 AI 개발 환경은 더욱 빠르게 성숙해질 것으로 기대됩니다.

300x250

https://ai.georgeliu.com/p/running-google-gemma-4-locally-with

Running Google Gemma 4 Locally With LM Studio’s New Headless CLI & Claude Code