Gemma 4 튜토리얼 – Pi 에이전트로 로컬 코딩 에이전트 구축하기

Gemma 4 모델 선택
1단계: LM Studio 설치
2단계: Gemma 4 다운로드
3단계: LM Studio 서버 시작
4단계: 컨텍스트 크기 설정
5단계: Pi 설치
6단계: Pi를 로컬 모델에 연결
7단계: 스킬 추가
주의사항
참고 자료

LM Studio와 Pi 코딩 에이전트, Gemma 4 26B A4B를 조합하면 인터넷 연결 없이 완전 로컬로 작동하는 AI 코딩 에이전트를 구축할 수 있다. Gemma 4는 네이티브 함수 호출, 시스템 프롬프트, 사고 모드(thinking mode)를 지원해 로컬 모델 중에서도 에이전트형 작업에 적합하다.

대상: 클라우드 API 비용 없이 로컬 코딩 에이전트를 실험하고 싶은 개발자 준비물: macOS/Windows/Linux, GPU(권장 VRAM 20 GB 이상)

Gemma 4 모델 선택

모델	아키텍처	컨텍스트	특징
Gemma 4 E2B	Dense	128K	초경량, VRAM 적게 사용
Gemma 4 E4B	Dense	128K	작은 모델 중 성능 우수
Gemma 4 26B A4B	MoE	256K	권장 — 품질·속도 균형 최적
Gemma 4 31B	Dense	256K	최고 품질, 높은 VRAM

26B A4B를 권장하는 이유: MoE(Mixture-of-Experts) 구조로 26B 파라미터 중 토큰당 4B만 활성화된다. 추론 속도는 소형 모델 수준이면서 품질은 훨씬 높다. 단, 고속 라우팅을 위해 전체 26B 파라미터가 메모리에 로드되어야 하므로 VRAM 요구량은 밀집 26B 모델과 비슷하다.

1단계: LM Studio 설치

LM Studio를 다운로드해 설치한다. 모델 다운로드, 양자화, OpenAI 호환 로컬 API 서버를 GUI로 관리할 수 있다. Ollama나 llama.cpp의 llama-server도 동일한 OpenAI 호환 엔드포인트를 제공하므로 대체 사용 가능하다.

2단계: Gemma 4 다운로드

LM Studio 검색창에서 gemma-4-26b-a4b를 검색해 GGUF 양자화 버전을 다운로드한다.

양자화	파일 크기	품질
Q4_K_M	18 GB	균형 (권장)
Q6_K	24 GB	고품질
Q8_0	28 GB	원본에 가깝게

Apple Silicon Mac이라면 GGUF보다 MLX 버전이 더 빠를 수 있다.

3단계: LM Studio 서버 시작

LM Studio Developer 탭 진입
Gemma 4 모델 선택
Start Server 클릭

기본 주소 http://localhost:1234로 서버가 실행된다.

# 서버 동작 확인
curl http://localhost:1234/v1/models

4단계: 컨텍스트 크기 설정

Model Settings에서 컨텍스트 크기와 GPU 오프로드를 조정한다.

사용 케이스	컨텍스트	추가 VRAM
단일 파일 편집	16K	~1 GB
일반 코딩 세션	64K	~4 GB
멀티 파일 리팩터	128K	~8 GB
전체 저장소	256K	~16 GB

코딩 에이전트는 세션이 길어질수록 컨텍스트가 쌓이므로 128K를 권장한다. GPU 오프로드는 VRAM이 허용하는 최대치로 설정한다.

5단계: Pi 설치

Pi는 Mario Zechner가 만든 최소주의 터미널 코딩 하네스다. 에이전트에게 read, write, edit, bash 4개 툴만 제공해 토큰 효율이 높고, 스킬·확장·테마로 커스터마이즈할 수 있다.

npm install -g @mariozechner/pi-coding-agent

6단계: Pi를 로컬 모델에 연결

~/.pi/agent/models.json을 생성하거나 수정한다.

{
  "providers": {
    "lmstudio": {
      "baseUrl": "http://localhost:1234/v1",
      "api": "openai-completions",
      "apiKey": "lm-studio",
      "models": [
        {
          "id": "google/gemma-4-26b-a4b",
          "input": ["text", "image"]
        }
      ]
    }
  }
}

id 값은 LM Studio 서버 탭에 표시된 모델명과 정확히 일치해야 한다.

pi
# /model 명령으로 로컬 LM Studio 모델 선택

7단계: 스킬 추가

스킬은 Pi의 기능을 확장하는 온디맨드 마크다운 파일로, Agent Skills 표준을 따른다.

# 프로젝트 레벨 설치
git clone https://github.com/badlogic/pi-skills .pi/skills/pi-skills

주의사항

Pi는 기본적으로 확인 없이 bash 명령을 실행한다. 로컬 모델은 간혹 위험한 명령을 환각할 수 있으므로, permission-gate 확장을 설치해 파괴적 명령 실행 전 확인 단계를 추가하는 것을 권장한다.

# 컨테이너 격리를 원하면 cco 도구 참고
# https://github.com/nikvdp/cco

gemma — Gemma 모델 전체 개요 agent-harness — 에이전트 하네스 엔지니어링 원칙

참고 자료

How to run a local coding agent with Gemma 4 and Pi — patloeber.com (2026-04-29)
Pi coding agent — 공식 사이트
Gemma models overview — Google AI for Developers

Like?

AI Sparkup