llama.cpp로 Gemma 4 실행하는 방법: GGUF 설정, 하드웨어 및 양자화 가이드

Gemma 4는 2026년 4월 2일에 출시되었으며, 출시 당일부터 llama.cpp 지원이 시작되었습니다. Ollama나 LM Studio가 아닌 llama.cpp를 사용하기로 결정했다면, 이 가이드에서 제공하는 정확한 명령어와 하드웨어 수치를 통해 안정적으로 첫 실행을 마치고 점진적으로 확장해 나갈 수 있습니다.

아직 어떤 로컬 런타임을 사용할지 고민 중이라면, llama.cpp가 적합한 경우 섹션을 먼저 확인해 보세요.

---

Gemma 4 모델 크기 한눈에 보기

Gemma 4는 네 가지 변체(variant)로 제공됩니다. 무엇이든 다운로드하기 전에 아래 표와 본인의 하드웨어를 대조해 보세요. 이는 문제 발생의 가장 흔한 원인 중 하나입니다.

변체	아키텍처	컨텍스트	모달리티	4-bit RAM	8-bit RAM	FP16 RAM
E2B	Dense + PLE	128K	텍스트, 이미지, 오디오	~4 GB	~5–8 GB	~10 GB
E4B	Dense + PLE	128K	텍스트, 이미지, 오디오	~5.5–6 GB	~9–12 GB	~16 GB
26B-A4B	MoE (4B 활성)	256K	텍스트, 이미지	~16–18 GB	~28–30 GB	~52 GB
31B	Dense	256K	텍스트, 이미지	~17–20 GB	~34–38 GB	~62 GB

여기서 RAM은 사용 가능한 전체 메모리를 의미합니다. 레이어를 오프로드(offload)하는 경우 VRAM과 시스템 RAM의 합계, 또는 Apple Silicon의 통합 메모리(unified memory)를 뜻합니다. 전체 메모리가 4-bit 열에 명시된 수치보다 적다면, llama.cpp는 일부 데이터를 디스크에 오프로드하여 실행할 수 있지만 생성 속도는 눈에 띄게 느려집니다.

빠른 선택 가이드:

• Mac mini M4 (16 GB 통합 메모리): E4B (Q8_0) 또는 속도 저하를 감수한다면 26B-A4B (Q4).
• 16 GB VRAM (RTX 4080, RTX 4090 12 GB): E4B (Q8_0)를 쾌적하게 사용 가능, 26B-A4B (Q4)도 여유롭게 가능.
• 24 GB VRAM (RTX 3090 / 4090): 26B-A4B (Q8_0) 또는 31B (Q4).
• 8 GB VRAM: E2B 또는 E4B (Q4 전용).

26B-A4B vs 31B: MoE 구조의 26B 모델은 포워드 패스(forward pass)당 40억 개의 파라미터만 활성화하므로 dense 구조인 31B보다 빠르고 가볍습니다. 속도가 중요하고 RAM이 빠듯하다면 26B-A4B를, 최고의 품질을 원하고 메모리 여유가 있다면 31B를 선택하세요.

---

llama.cpp가 적합한 경우

llama.cpp는 다음과 같은 상황에 최적의 선택입니다:

• 원시 제어가 필요한 경우 — 사용자 지정 샘플링 파라미터, KV 캐시 튜닝, OpenAI 호환 엔드포인트를 제공하는 서버 모드, 문법 제약 생성 등.
• CPU 위주의 추론 — llama.cpp는 AVX2/AVX-512 및 Apple Metal을 포함하여 CPU 전용 워크플로우에 가장 최적화된 C++ 런타임 중 하나입니다.
• 스크립팅 및 CI 파이프라인 — Python 의존성이 없는 단일 바이너리 형태로 제공되어 통합이 간편합니다.
• 멀티모달 추론 — llama-mtmd-cli 및 --mmproj 옵션을 사용하는 llama-server를 통해 가능합니다.

가장 쉬운 방법(명령어 하나로 다운로드 및 채팅)을 원하신다면 Ollama나 LM Studio가 더 적합할 수 있습니다. 더 정밀한 제어가 필요할 때 다시 이곳으로 돌아오세요.

---

1단계 — llama.cpp 빌드

먼저 리포지토리를 클론합니다. CUDA나 Metal 관련 최신 수정 사항이 빠르게 반영되는 master 브랜치를 항상 사용하는 것이 좋습니다.

git clone https://github.com/ggml-org/llama.cpp
cd llama.cpp

NVIDIA GPU 탑재 리눅스 (CUDA)

CUDA 툴킷이 설치되어 있는지 확인(nvcc --version)한 후 다음을 실행합니다:

apt-get update
apt-get install -y pciutils build-essential cmake curl libcurl4-openssl-dev

cmake llama.cpp -B llama.cpp/build \
  -DBUILD_SHARED_LIBS=OFF \
  -DGGML_CUDA=ON

cmake --build llama.cpp/build \
  --config Release -j --clean-first \
  --target llama-cli llama-mtmd-cli llama-server llama-gguf-split

cp llama.cpp/build/bin/llama-* llama.cpp/

빌드 후 GPU 오프로드가 작동하는지 확인합니다:

./llama.cpp/llama-cli -m your-model.gguf -p "Hello" -n 5 --n-gpu-layers 99

만약 offloaded 0/N layers라는 문구가 보인다면 CUDA 없이 컴파일된 것입니다. build/ 디렉토리를 비우고 처음부터 다시 빌드하세요.

macOS (Apple Silicon — Metal)

macOS에서는 Metal이 기본적으로 활성화되어 있습니다. -DGGML_CUDA=ON 옵션을 줄 필요 없이 정상적으로 빌드하면 됩니다.

brew install cmake

cmake llama.cpp -B llama.cpp/build \
  -DBUILD_SHARED_LIBS=OFF \
  -DGGML_CUDA=OFF

cmake --build llama.cpp/build \
  --config Release -j --clean-first \
  --target llama-cli llama-mtmd-cli llama-server

cp llama.cpp/build/bin/llama-* llama.cpp/

Apple Silicon에서 "VRAM"과 시스템 RAM은 동일한 통합 메모리 풀을 공유합니다. 따라서 24 GB M3 Pro 기기는 모델 가중치를 위해 24 GB 전체를 사용할 수 있습니다.

CPU 전용 (GPU 없음)

cmake llama.cpp -B llama.cpp/build \
  -DBUILD_SHARED_LIBS=OFF \
  -DGGML_CUDA=OFF

cmake --build llama.cpp/build \
  --config Release -j$(nproc) \
  --target llama-cli llama-server

cp llama.cpp/build/bin/llama-* llama.cpp/

CMake는 호스트 CPU의 AVX2/AVX-512를 자동으로 감지하여 적절한 최적화를 활성화합니다. CPU 추론은 더 느리지만 모든 기능을 정상적으로 사용할 수 있습니다.

---

2단계 — GGUF 선택 및 다운로드

어떤 양자화 버전을 골라야 할까요?

양자화	파일 크기 (근사치)	품질	용도
Q8_0	Q4 크기의 약 1배	FP16에 가장 근접	RAM 여유가 있는 경우 E2B 및 E4B 권장
Q4_K_M	중간	균형 잡힌 성능	24 GB VRAM 기반 26B-A4B 및 31B
UD-Q4_K_XL	Q4_K_M보다 약간 큼	Q4_K_M보다 우수	26B-A4B 및 31B용 Unsloth 동적 양자화
Q2_K	가장 작음	품질 저하가 큼	다른 대안이 전혀 없는 경우만 사용

주요 GGUF 컬렉션을 관리하는 Unsloth의 권장 시작점은 다음과 같습니다:

• E2B / E4B → Q8_0으로 시작
• 26B-A4B / 31B → UD-Q4_K_XL로 시작

Hugging Face CLI로 다운로드

먼저 CLI를 설치합니다:

pip install huggingface_hub hf_transfer

그 후 선택한 모델을 다운로드합니다. 예: UD-Q4_K_XL 버전의 26B-A4B 모델:

export LLAMA_CACHE="unsloth/gemma-4-26B-A4B-it-GGUF"

huggingface-cli download unsloth/gemma-4-26B-A4B-it-GGUF \
  --local-dir unsloth/gemma-4-26B-A4B-it-GGUF \
  --include "*UD-Q4_K_XL*"

멀티모달 추론(이미지)을 원한다면 프로젝터(projector) 파일도 함께 다운로드하세요:

huggingface-cli download unsloth/gemma-4-26B-A4B-it-GGUF \
  --local-dir unsloth/gemma-4-26B-A4B-it-GGUF \
  --include "*mmproj-BF16*" "*UD-Q4_K_XL*"

네 가지 모델의 GGUF 컬렉션 주소:

• unsloth/gemma-4-E2B-it-GGUF
• unsloth/gemma-4-E4B-it-GGUF
• unsloth/gemma-4-26B-A4B-it-GGUF
• unsloth/gemma-4-31B-it-GGUF

---

3단계 — 텍스트 추론 실행

llama.cpp는 컨텍스트 길이를 자동으로 설정하므로 -c 옵션을 따로 줄 필요가 없습니다. Google에서 공식적으로 권장하는 기본 파라미터를 사용하세요.

llama-cli로 대화형 채팅 실행

E4B (Q8_0):

export LLAMA_CACHE="unsloth/gemma-4-E4B-it-GGUF"

./llama.cpp/llama-cli \
  -hf unsloth/gemma-4-E4B-it-GGUF:Q8_0 \
  --temp 1.0 \
  --top-p 0.95 \
  --top-k 64 \
  -cnv

26B-A4B (UD-Q4_K_XL):

export LLAMA_CACHE="unsloth/gemma-4-26B-A4B-it-GGUF"

./llama.cpp/llama-cli \
  -hf unsloth/gemma-4-26B-A4B-it-GGUF:UD-Q4_K_XL \
  --temp 1.0 \
  --top-p 0.95 \
  --top-k 64 \
  -cnv

31B (UD-Q4_K_XL):

export LLAMA_CACHE="unsloth/gemma-4-31B-it-GGUF"

./llama.cpp/llama-cli \
  -hf unsloth/gemma-4-31B-it-GGUF:UD-Q4_K_XL \
  --temp 1.0 \
  --top-p 0.95 \
  --top-k 64 \
  -cnv

OpenAI 호환 서버 실행 (llama-server)

OpenAI 클라이언트를 사용하는 모든 도구에서 호출할 수 있도록 8080 포트에서 로컬 서버를 가동합니다:

./llama.cpp/llama-server \
  -m unsloth/gemma-4-26B-A4B-it-GGUF/gemma-4-26B-A4B-it-UD-Q4_K_XL.gguf \
  --temp 1.0 \
  --top-p 0.95 \
  --top-k 64 \
  --port 8080

그 후 curl 명령어로 테스트해 보세요:

curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemma-4",
    "messages": [{"role": "user", "content": "Explain attention in one paragraph."}]
  }'

권장 추론 파라미터

파라미터	값	비고
--temp	1.0	Google 공식 기본값
--top-p	0.95	Google 공식 기본값
--top-k	64	Google 공식 기본값
--repeat-penalty	1.0 (비활성화)	생성 내용이 반복될 때만 활성화 권장
컨텍스트 길이	자동	llama.cpp에서 자동으로 설정함

컨텍스트 제한: E2B 및 E4B는 최대 128K 토큰을 지원하며, 26B-A4B 및 31B는 최대 256K를 지원합니다. 실제 사용 시에는 빠른 응답성을 위해 32K로 시작하고, 긴 문서 처리가 필요할 때만 늘리는 것이 좋습니다.

사고(Thinking) 모드 활성화

Gemma 4는 추론/사고 모드를 지원합니다. 시스템 프롬프트 시작 부분에 <|think|>를 추가하여 활성화할 수 있습니다. 서버 사용 시 이를 비활성화하려면 다음과 같이 하세요:

./llama.cpp/llama-server \
  -m your-model.gguf \
  --chat-template-kwargs '{"enable_thinking":false}'

Windows PowerShell에서는 따옴표를 이스케이프 처리해야 합니다:

--chat-template-kwargs "{\"enable_thinking\":false}"

---

4단계 — 멀티모달 (이미지) 추론

Gemma 4는 출시 시점부터 llama.cpp에서 이미지 입력을 지원하지만, 언어 모델 외에 멀티모달 프로젝터(mmproj)라는 추가 GGUF 파일이 필요합니다. 프로젝터는 언어 모델이 처리하기 전에 이미지를 인코딩하는 역할을 합니다.

준비물

1. 언어 모델 GGUF (텍스트 추론용과 동일)
2. 동일한 Hugging Face 리포지토리에 있는 mmproj-BF16.gguf 파일

위의 다운로드 명령어 단계에서 --include "*mmproj-BF16*" 플래그를 사용했다면 이미 둘 다 다운로드된 상태입니다.

llama-mtmd-cli로 실행 (CLI)

./llama.cpp/llama-mtmd-cli \
  --model unsloth/gemma-4-26B-A4B-it-GGUF/gemma-4-26B-A4B-it-UD-Q4_K_XL.gguf \
  --mmproj unsloth/gemma-4-26B-A4B-it-GGUF/mmproj-BF16.gguf \
  --temp 1.0 \
  --top-p 0.95 \
  --top-k 64

실행 후 대화 중에 [img]경로/이미지.jpg[/img] 문법을 사용하여 이미지를 참조할 수 있습니다.

llama-server로 실행 (API)

./llama.cpp/llama-server \
  --model unsloth/gemma-4-26B-A4B-it-GGUF/gemma-4-26B-A4B-it-UD-Q4_K_XL.gguf \
  --mmproj unsloth/gemma-4-26B-A4B-it-GGUF/mmproj-BF16.gguf \
  --temp 1.0 \
  --top-p 0.95 \
  --top-k 64 \
  --port 8080

오디오 관련 참고 사항: E2B 및 E4B는 기본적으로 오디오 입력을 지원하지만, 2026년 4월 기준 llama.cpp의 오디오 지원은 활발히 개발 중인 단계입니다. 텍스트 및 이미지 추론은 현재 매우 안정적입니다.

---

일반적인 문제 해결 (Troubleshooting)

빌드 후 "offloaded 0 layers"라고 뜸

CUDA 빌드가 제대로 링크되지 않았습니다. 빌드 디렉토리를 완전히 삭제하고 다시 시도하세요:

rm -rf llama.cpp/build
# 그 후 -DGGML_CUDA=ON 옵션을 포함하여 cmake 단계 재실행

모델 로딩 시 메모리 부족 (OOM) 발생

양자화 후에도 전체 메모리가 모델 크기보다 작습니다. 다음 옵션을 고려하세요:

1. 더 높은 압축률의 양자화 사용 (Q4_K_M → Q2_K, 또는 UD-Q4_K_XL → Q4_K_M).
2. 더 작은 모델 변체로 변경 (31B → 26B-A4B, 또는 26B-A4B → E4B).
3. --n-gpu-layers N 옵션에서 N 값을 낮춰 VRAM 오프로드 비중을 줄이세요. 나머지는 시스템 RAM을 사용하며 속도는 느려집니다.

--image-min-tokens 사용 시 GGML_ASSERT 또는 충돌 발생

Gemma 4 사용 시 --image-min-tokens 옵션을 주지 마세요. 이 플래그는 Gemma 4의 non-causal attention 아키텍처와 충돌하여 어설션 오류를 유발합니다. 기본 이미지 토큰 설정을 그대로 사용하세요.

생성이 무한 반복됨

반복 루프를 끊기 위해 --repeat-penalty 1.05 옵션을 추가하세요. 일반적인 상황에서는 1.0(비활성화)으로 두는 것이 좋습니다. Gemma 4 아키텍처는 기본적으로 이 옵션이 필요하지 않습니다.

Metal 활성화 상태임에도 macOS에서 생성이 느림

이진 파일이 실제로 Metal을 사용 중인지 확인하세요:

./llama.cpp/llama-cli -m your-model.gguf -p "hi" -n 1 --verbose

백엔드 줄에서 Metal을 확인하세요. 만약 CPU만 보인다면, --n-gpu-layers 99를 명시적으로 설정하여 오프로드를 강제해 보세요.

---

자주 묻는 질문 (FAQ)

llama.cpp에서 Gemma 4를 공식적으로 지원하나요? 네. 2026년 4월 2일 출시와 동시에 지원이 포함되었으며 관련 기여 내역은 llama.cpp 리포지토리에서 확인할 수 있습니다. 네 가지 모델 크기 모두 llama-cli, llama-server, llama-mtmd-cli에서 작동합니다.

Mac mini에서 Gemma 4를 실행할 수 있나요? 네. 16 GB 통합 메모리의 Mac mini M4는 E4B (Q8_0)를 쾌적하게 실행할 수 있으며, 26B-A4B (Q4)를 수용 가능한 속도로 구동할 수 있습니다. 24 GB 사양의 M4 Pro는 26B-A4B (Q8_0)를 무리 없이 다룹니다.

GPU가 반드시 필요한가요? 아니요. llama.cpp는 CPU만으로도 작동합니다. GPU 오프로드(CUDA 또는 Metal)를 사용하면 초당 토큰(TPS) 속도가 크게 향상되지만, E2B나 E4B 같은 소형 모델은 CPU 추론만으로도 충분히 실용적입니다.

Q4_K_M과 UD-Q4_K_XL의 차이는 무엇인가요? Q4_K_M은 표준 llama.cpp 4-bit 양자화 방식입니다. UD-Q4_K_XL은 Unsloth의 동적(Dynamic) 4-bit 형식으로, 중요한 레이어에는 더 정밀한 압축을 적용합니다. 실제 사용 시 비슷한 파일 크기에서 UD-Q4_K_XL의 품질이 더 높습니다.

Cursor나 Continue 같은 코딩 에이전트에서 Gemma 4를 어떻게 사용하나요? llama-server를 8080 포트(또는 다른 포트)로 실행한 후, 에이전트의 OpenAI 베이스 URL을 http://localhost:8080/v1으로 설정하세요. /v1/chat/completions 엔드포인트는 OpenAI와 완벽하게 호환됩니다.

---

다음 단계

텍스트 추론이 안정적으로 작동한다면 다음 단계로 나가보세요:

• E4B보다 훨씬 높은 품질을 제공하면서도 적당한 하드웨어에서 구동 가능한 26B-A4B를 시도해 보세요.
• 26B-A4B 이하 모델을 사용 중이라면 llama-mtmd-cli로 멀티모달 입력을 테스트해 보세요.
• 더 간편한 일상용 워크플로우를 원하고 일부 정밀한 제어권을 양보할 수 있다면 llama.cpp를 Ollama와 비교해 보세요.

가장 흔한 실수는 소형 모델이 잘 작동하는지 확인하기도 전에 가장 큰 모델부터 다운로드하는 것입니다. 초당 1토큰으로 실행되는 31B보다는 안정적인 E4B 설정이 훨씬 유용합니다.

---

관련 가이드

• Gemma 4 하드웨어 요구 사항
• Gemma 4 모델 비교 가이드
• Ollama에서 Gemma 4 실행하기
• LM Studio에서 Gemma 4 실행하기
• Gemma 4 API 사용 가이드