온디바이스 LLM 추론의 핵심인 GGUF 형식과 llama.cpp의 아키텍처, 설치와 사용법, 성능 최적화, 그리고 주요 프론트엔드 도구를 다룹니다.
2장에서 모델 양자화의 원리를 배웠습니다. 이 장에서는 양자화된 모델을 실제로 실행하는 가장 대표적인 도구인 llama.cpp와 그 모델 형식인 GGUF를 다룹니다. llama.cpp는 순수 C/C++로 작성된 LLM 추론 엔진으로, CPU에서 GPU까지 거의 모든 하드웨어를 지원합니다.
Georgi Gerganov가 2023년에 시작한 오픈소스 프로젝트로, MacBook에서 LLaMA 모델을 실행하겠다는 목표로 시작되었습니다. 현재는 사실상 로컬 LLM 추론의 표준이 되었습니다.
GGUF(GPT-Generated Unified Format)는 GGML 형식의 후속으로, 2023년에 도입되었습니다.
GGUF 파일 구조:
┌─────────────────────┐
│ Magic Number (GGUF) │
├─────────────────────┤
│ Version │
├─────────────────────┤
│ 메타데이터 (KV 쌍) │ ← 모델 이름, 아키텍처, 토크나이저, 양자화 정보
├─────────────────────┤
│ 텐서 정보 │ ← 각 텐서의 이름, 형태, 오프셋
├─────────────────────┤
│ 텐서 데이터 │ ← 양자화된 가중치 바이너리
└─────────────────────┘
.gguf 파일로 모델 배포 완료GGUF는 K-Quants라는 혼합 정밀도 양자화를 지원합니다.
| 유형 | 평균 비트 | 설명 |
|---|---|---|
| Q2_K | ~2.6 | 초저비트, 상당한 품질 저하 |
| Q3_K_S | ~3.4 | 3비트, 작은 크기 |
| Q3_K_M | ~3.9 | 3비트, 중간 품질 |
| Q4_0 | 4.0 | 4비트, 단순 양자화 |
| Q4_K_S | ~4.4 | 4비트, 작은 크기, K-quants |
| Q4_K_M | ~4.8 | 4비트, 중간 크기 — 가장 인기 |
| Q5_K_S | ~5.4 | 5비트, 작은 크기 |
| Q5_K_M | ~5.7 | 5비트, 중간 크기 — 최적 균형 |
| Q6_K | ~6.6 | 6비트, 높은 품질 |
| Q8_0 | 8.0 | 8비트, 거의 무손실 |
Q4_K_M은 크기와 품질의 균형이 좋아 가장 널리 사용됩니다. 메모리 여유가 있다면 Q5_K_M, 품질을 최우선으로 한다면 Q6_K를 선택하세요. 모델 이름에서 이 접미사를 확인하면 양자화 수준을 즉시 파악할 수 있습니다.
# 소스 클론
git clone https://github.com/ggerganov/llama.cpp
cd llama.cpp
# macOS (Metal 가속)
cmake -B build -DGGML_METAL=ON
cmake --build build --config Release -j
# Linux (CUDA)
cmake -B build -DGGML_CUDA=ON
cmake --build build --config Release -j
# Vulkan (크로스 플랫폼 GPU)
cmake -B build -DGGML_VULKAN=ON
cmake --build build --config Release -j# 대화형 모드
./build/bin/llama-cli \
-m models/llama-3.2-3b-q4_k_m.gguf \
-p "한국의 수도는" \
-n 100 \
--temp 0.7 \
-ngl 99 # GPU로 모든 레이어 오프로드
# 채팅 모드
./build/bin/llama-cli \
-m models/llama-3.2-3b-instruct-q4_k_m.gguf \
--chat-template llama3 \
-cnv # 대화 모드./build/bin/llama-server \
-m models/llama-3.2-3b-instruct-q4_k_m.gguf \
--host 0.0.0.0 \
--port 8080 \
-ngl 99 \
-c 4096 \ # 컨텍스트 길이
--parallel 4 # 동시 요청 수import requests
response = requests.post("http://localhost:8080/v1/chat/completions", json={
"model": "llama-3.2-3b",
"messages": [
{"role": "system", "content": "한국어로 답변하세요."},
{"role": "user", "content": "양자화란 무엇인가요?"},
],
"temperature": 0.7,
"max_tokens": 500,
})
print(response.json()["choices"][0]["message"]["content"])llama.cpp 서버는 OpenAI API 호환 엔드포인트를 제공하므로, 기존 OpenAI SDK 코드를 거의 수정 없이 사용할 수 있습니다.
from openai import OpenAI
client = OpenAI(
base_url="http://localhost:8080/v1",
api_key="not-needed",
)
response = client.chat.completions.create(
model="llama-3.2-3b",
messages=[{"role": "user", "content": "안녕하세요"}],
)
print(response.choices[0].message.content)# HF 모델을 GGUF로 변환
python convert_hf_to_gguf.py \
./models/llama-3.2-3b \
--outfile models/llama-3.2-3b-f16.gguf \
--outtype f16
# 양자화 적용
./build/bin/llama-quantize \
models/llama-3.2-3b-f16.gguf \
models/llama-3.2-3b-q4_k_m.gguf \
Q4_K_M대부분의 인기 모델은 이미 GGUF로 변환되어 Hugging Face에 업로드되어 있습니다.
# huggingface-cli 사용
huggingface-cli download \
bartowski/Llama-3.2-3B-Instruct-GGUF \
Llama-3.2-3B-Instruct-Q4_K_M.gguf \
--local-dir models/-ngl (number of GPU layers) 파라미터로 GPU에 오프로드할 레이어 수를 지정합니다.
# 전체 레이어를 GPU로 (충분한 VRAM이 있을 때)
-ngl 99
# 절반만 GPU로 (VRAM 부족 시)
-ngl 16
# CPU만 사용
-ngl 0컨텍스트 길이는 KV 캐시 메모리에 직접 영향을 줍니다.
KV 캐시 메모리 ≈ 2 × 레이어 수 × 헤드 수 × 헤드 차원 × 컨텍스트 길이 × 정밀도
예: Llama 3.2 3B, 컨텍스트 4096, FP16 KV 캐시
≈ 2 × 28 × 32 × 128 × 4096 × 2 bytes ≈ 1.8 GB
llama.cpp는 Flash Attention을 지원하여 긴 컨텍스트에서의 메모리 사용을 최적화합니다.
# Flash Attention 활성화
-faApple Silicon에서 llama.cpp는 Metal 가속으로 매우 효율적입니다. M4 Pro 기준으로 Llama 3.2 3B Q4_K_M 모델이 약 60~80 tok/s를 달성합니다. Apple의 통합 메모리 아키텍처 덕분에 GPU 오프로딩이 VRAM 제약 없이 가능합니다.
llama.cpp를 직접 CLI로 사용하는 것 외에, 사용자 친화적인 프론트엔드가 많습니다.
| 도구 | 유형 | 특징 |
|---|---|---|
| Ollama | CLI + 서버 | 가장 간편한 설치, Docker 형태 모델 관리 |
| LM Studio | 데스크탑 앱 | GUI, 모델 검색/다운로드, 대화 인터페이스 |
| Jan | 데스크탑 앱 | 오픈소스, 확장 가능 |
| Open WebUI | 웹 인터페이스 | ChatGPT 유사 UI, 다중 모델 지원 |
| text-generation-webui | 웹 인터페이스 | 다양한 백엔드 지원, 고급 옵션 |
# 설치 (macOS)
brew install ollama
# 모델 실행 (자동 다운로드)
ollama run llama3.2:3b
# API 서버로 사용 (OpenAI 호환)
curl http://localhost:11434/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{
"model": "llama3.2:3b",
"messages": [{"role": "user", "content": "Hello"}]
}'llama.cpp는 GGUF 형식과 K-Quants 양자화를 기반으로 거의 모든 하드웨어에서 LLM을 실행할 수 있는 범용 추론 엔진입니다. OpenAI API 호환 서버 모드, GPU 오프로딩, Flash Attention 등을 통해 효율적인 로컬 추론이 가능합니다. Ollama, LM Studio 등의 프론트엔드를 활용하면 더 간편하게 사용할 수 있습니다.
다음 장에서는 GGUF 외의 양자화 기법인 AWQ와 GPTQ를 비교하고, GPU 추론에 최적화된 양자화 전략을 다룹니다.
이 글이 도움이 되셨나요?
관련 주제 더 보기
GPU 추론에 최적화된 AWQ와 GPTQ 양자화 기법의 원리, 차이점, 그리고 GGUF와의 비교를 통해 상황별 최적 양자화 전략을 제시합니다.
모델 양자화의 핵심 원리, 부동소수점과 정수 표현, 양자화 형식(대칭/비대칭, 채널/그룹), 품질-크기 트레이드오프를 체계적으로 다룹니다.
WebGPU를 활용한 브라우저 내 LLM 추론의 원리, WebLLM과 MLC LLM의 아키텍처, 실전 구현, 그리고 브라우저 AI의 가능성과 한계를 다룹니다.