GGUF 모델 포맷

개요

Ollama는 GGUF (Georgi Gerganov Unified Format) 파일 형식을 사용합니다. GGUF는 Georgi Gerganov가 개발한 llama.cpp 프로젝트의 핵심 모델 포맷으로, 로컬 환경에서 LLM을 효율적으로 실행하기 위해 설계되었습니다. 현재 Ollama, LM Studio, llama.cpp, GPT4All 등 대부분의 로컬 LLM 런타임이 GGUF를 표준 포맷으로 채택하고 있습니다.

GGML에서 GGUF로의 진화: 분산된 파일 → 단일 자기 완결적 파일

포맷 구조와 양자화

GGUF 버전 히스토리

GGUF는 출시 이후 지속적으로 발전해왔습니다. 각 버전은 하위 호환성을 유지하면서 새로운 기능을 추가합니다.

GGUF 포맷 버전 타임라인: GGML → v1 → v2 → v3 (현재 표준)

GGUF 파일 내부 구조

GGUF 파일은 바이너리 포맷으로, 정해진 구조에 따라 순차적으로 데이터를 배치합니다. 모든 정보가 하나의 파일에 포함되므로 별도의 설정 파일 없이 모델을 로드할 수 있습니다.

GGUF 파일 바이너리 레이아웃: Magic → Header → Metadata → Tensor Info → Tensor Data

GGUF의 핵심 설계 원칙은 자기 설명적(self-describing) 구조입니다. 파일 자체에 모델을 로드하는 데 필요한 모든 정보가 담겨 있으므로, 외부 설정 파일이나 코드 없이도 모델의 아키텍처, 양자화 방식, 토크나이저 종류를 파악할 수 있습니다.

# GGUF 파일 정보 확인 (llama.cpp 도구)
# gguf-dump: 메타데이터와 텐서 구조를 출력
$ python3 -c "
from gguf import GGUFReader
reader = GGUFReader('model.gguf')
print(f'GGUF Version: {reader.header.version}')
print(f'Tensor Count: {reader.header.tensor_count}')
print(f'Metadata KV Count: {reader.header.metadata_kv_count}')
for kv in reader.fields.values():
    print(f'  {kv.name}: {kv.data}')
"

# 출력 예시
GGUF Version: 3
Tensor Count: 291
Metadata KV Count: 23
  general.architecture: llama
  general.name: Llama 3.2 3B Instruct
  llama.context_length: 131072
  llama.embedding_length: 3072
  llama.block_count: 28
  llama.attention.head_count: 24
  tokenizer.ggml.model: gpt2
  general.quantization_version: 2

바이너리 헤더 Hex Dump

실제 GGUF 파일의 첫 바이트를 살펴보면 포맷의 구조를 직접 확인할 수 있습니다. 아래는 hexdump 명령으로 확인한 GGUF v3 파일의 헤더 영역입니다.

# GGUF 파일 헤더 Hex Dump 확인
$ hexdump -C model.gguf | head -n 4

00000000  47 47 55 46  03 00 00 00  17 00 00 00  00 00 00 00  |GGUF............|
00000010  23 01 00 00  00 00 00 00  14 00 00 00  00 00 00 00  |#...............|
         ╰─┬────────╯ ╰─┬────────╯ ╰─┬────────────────────╯ ╰─┬────────────────────╯
     Magic Number   Version=3    tensor_count=23(0x17)    metadata_kv_count=291(0x123)

# 상세 구조 해설
Offset  0x00-0x03: 47 47 55 46 → "GGUF" (ASCII, Little-Endian)
Offset  0x04-0x07: 03 00 00 00 → version = 3 (uint32_t LE)
Offset  0x08-0x0F: 17 00 00 00 00 00 00 00 → tensor_count = 23 (uint64_t LE)
Offset  0x10-0x17: 23 01 00 00 00 00 00 00 → metadata_kv_count = 291 (uint64_t LE)

# 파일 전체 구조 오프셋 확인
$ python3 -c "
import struct
with open('model.gguf', 'rb') as f:
    magic = f.read(4)
    version = struct.unpack('<I', f.read(4))[0]
    n_tensors = struct.unpack('<Q', f.read(8))[0]
    n_kv = struct.unpack('<Q', f.read(8))[0]
    print(f'Magic: {magic}')
    print(f'Version: {version}')
    print(f'Tensors: {n_tensors}')
    print(f'KV pairs: {n_kv}')
"
Magic: b'GGUF'
Version: 3
Tensors: 23
KV pairs: 291

메타데이터 KV 상세

GGUF 메타데이터는 Key-Value 쌍으로 구성됩니다. 키는 네임스페이스 규칙(general.*, {arch}.*, tokenizer.*)을 따릅니다.

메타데이터 값 타입

GGUF 메타데이터의 각 Key-Value 쌍에서 Value는 다음 타입 중 하나를 가집니다. 이 타입 시스템 덕분에 메타데이터를 파싱할 때 별도의 스키마 파일이 필요 없습니다.

지원 아키텍처

general.architecture 키는 모델의 아키텍처 종류를 지정합니다. GGUF는 현재 다양한 Transformer 변형 아키텍처를 지원하며, 지속적으로 확장되고 있습니다.

GGUF가 지원하는 다양한 아키텍처: 하나의 포맷으로 수십 종의 모델을 통합

GGUF 지원 데이터 타입

GGUF는 원본 부동소수점부터 극도로 압축된 양자화 타입까지 다양한 데이터 타입을 지원합니다. 각 타입은 메모리 효율과 추론 품질 사이의 트레이드오프를 제공합니다.

블록 양자화 동작 원리

GGUF의 양자화는 블록 단위로 작동합니다. 가중치를 작은 블록(보통 32개씩)으로 나누고, 각 블록마다 스케일 팩터와 양자화된 정수 값을 저장합니다. 추론 시에는 역양자화(dequantization)하여 부동소수점으로 복원합니다.

Q4_0 블록 양자화: 32개 FP16 가중치(64B) → 스케일+양자화값(18B)으로 72% 압축

양자화 기법 심화 비교

GGUF는 세 가지 주요 양자화 패밀리를 지원합니다. 각 기법은 정밀도와 성능의 트레이드오프가 다릅니다.

세 가지 양자화 기법 비교: Legacy(속도) vs K-Quant(균형, 추천) vs i-Quant(품질)

모델 크기별 양자화 벤치마크

실제 모델에 양자화를 적용했을 때의 파일 크기와 품질(Perplexity) 변화입니다. Perplexity(PPL)는 낮을수록 좋으며, 언어 모델이 텍스트를 얼마나 잘 예측하는지를 나타냅니다.

7B 모델 양자화 트레이드오프: Q4_K_M이 크기 대비 품질의 최적점(Sweet Spot)

다른 모델 포맷과의 비교

주요 모델 포맷 비교: GGUF는 로컬 CPU/GPU 추론에 최적화된 포맷

메모리 매핑(mmap)과 GGUF

GGUF가 빠르게 모델을 로드할 수 있는 핵심 비결은 메모리 매핑(mmap)입니다. 일반적인 파일 로딩은 디스크→RAM 전체 복사가 필요하지만, mmap은 운영체제의 가상 메모리 시스템을 활용하여 파일을 직접 메모리 공간에 매핑합니다.

일반 파일 로딩 vs mmap: GGUF는 mmap을 통해 즉시 로딩과 메모리 공유를 실현

GPU 오프로딩 (Partial Offload)

GGUF 기반 추론 엔진(llama.cpp, Ollama)은 모델의 레이어를 GPU와 CPU에 분산하여 배치할 수 있습니다. 이를 GPU 오프로딩이라 하며, VRAM이 모델 전체를 수용하지 못할 때 핵심적인 기능입니다. --n-gpu-layers (줄여서 -ngl) 파라미터로 GPU에 올릴 레이어 수를 지정합니다.

GPU 오프로딩 시나리오: CPU Only → Partial → Full GPU (속도 10~20배 차이)

# Ollama에서 GPU 레이어 수 지정
OLLAMA_NUM_GPU_LAYERS=20 ollama run llama3.2:3b

# llama.cpp 직접 사용 시
./llama-cli -m model.gguf -ngl 99  # 전체 GPU 오프로드
./llama-cli -m model.gguf -ngl 20  # 20개 레이어만 GPU
./llama-cli -m model.gguf -ngl 0   # CPU 전용 (GPU 미사용)

# VRAM 사용량 실시간 모니터링
watch -n 1 nvidia-smi  # NVIDIA GPU
# macOS: 활성 상태 보기 → GPU 히스토리

GGUF 변환 워크플로

Hugging Face의 SafeTensors/PyTorch 모델을 GGUF로 변환하는 과정입니다. llama.cpp 프로젝트의 convert_hf_to_gguf.py 스크립트를 사용합니다.

# 1. llama.cpp 클론 및 빌드
git clone https://github.com/ggerganov/llama.cpp
cd llama.cpp
pip install -r requirements.txt

# 2. Hugging Face 모델을 GGUF F16으로 변환
python convert_hf_to_gguf.py \
  /path/to/hf-model \
  --outfile model-f16.gguf \
  --outtype f16

# 3. 양자화 적용 (F16 → Q4_K_M)
./llama-quantize model-f16.gguf model-q4km.gguf Q4_K_M

# 중요도 행렬(imatrix) 기반 양자화 (더 높은 품질)
# 먼저 imatrix 생성
./llama-imatrix \
  -m model-f16.gguf \
  -f calibration-data.txt \
  -o imatrix.dat

# imatrix를 사용한 양자화
./llama-quantize \
  --imatrix imatrix.dat \
  model-f16.gguf \
  model-iq4xs.gguf IQ4_XS

GGUF 변환 파이프라인: HuggingFace 모델 → F16 → 양자화 → Ollama 실행

GGUF 핵심 특징 요약

GGUF Split — 대용량 모델 분할

70B 이상의 대형 모델은 단일 GGUF 파일이 수십 GB에 달합니다. 일부 파일 시스템(FAT32 등)은 4GB 제한이 있고, 대용량 파일 전송 시 문제가 될 수 있습니다. GGUF v3부터 파일 분할(Split)을 공식 지원합니다.

# GGUF 파일 분할 (llama.cpp 도구)
./llama-gguf-split --split-max-size 8G model-70b-q4km.gguf model-70b-q4km

# 결과: 분할된 파일들
model-70b-q4km-00001-of-00005.gguf  # 8GB
model-70b-q4km-00002-of-00005.gguf  # 8GB
model-70b-q4km-00003-of-00005.gguf  # 8GB
model-70b-q4km-00004-of-00005.gguf  # 8GB
model-70b-q4km-00005-of-00005.gguf  # 나머지

# 분할된 파일 다시 병합
./llama-gguf-split --merge model-70b-q4km-00001-of-00005.gguf merged-model.gguf

# Ollama는 분할 파일도 직접 사용 가능
# Modelfile에서 첫 번째 파일만 지정하면 나머지를 자동 탐지
FROM ./model-70b-q4km-00001-of-00005.gguf

Transformer 블록과 GGUF 텐서 매핑

GGUF 파일 내부의 텐서 이름은 Transformer 아키텍처의 각 구성 요소에 직접 매핑됩니다. 텐서 이름을 이해하면 모델의 구조를 파일 레벨에서 파악할 수 있습니다.

Llama 아키텍처의 GGUF 텐서 이름: blk.{i}.attn_q/k/v, ffn_gate/up/down 등

# GGUF 파일의 텐서 목록 확인
$ python3 -c "
from gguf import GGUFReader
reader = GGUFReader('llama-3.2-3b-q4km.gguf')
for tensor in reader.tensors:
    dims = ' × '.join(str(d) for d in tensor.shape)
    print(f'{tensor.name:40s} [{dims}] {tensor.tensor_type.name}')
"

# 출력 예시 (Llama 3.2 3B)
token_embd.weight                        [128256 × 3072] Q4_K
blk.0.attn_norm.weight                   [3072] F32
blk.0.attn_q.weight                      [3072 × 3072] Q4_K
blk.0.attn_k.weight                      [3072 × 1024] Q4_K
blk.0.attn_v.weight                      [3072 × 1024] Q6_K
blk.0.attn_output.weight                 [3072 × 3072] Q4_K
blk.0.ffn_norm.weight                    [3072] F32
blk.0.ffn_gate.weight                    [3072 × 8192] Q4_K
blk.0.ffn_up.weight                      [3072 × 8192] Q4_K
blk.0.ffn_down.weight                    [8192 × 3072] Q6_K
... (blk.1 ~ blk.27 동일 패턴 반복)
output_norm.weight                       [3072] F32
output.weight                            [128256 × 3072] Q6_K

HuggingFace에서 GGUF 모델 찾기

HuggingFace Hub에서 GGUF 모델을 효율적으로 찾고 올바른 양자화 버전을 선택하는 방법입니다.

# HuggingFace Hub에서 GGUF 모델 검색
# https://huggingface.co/models?library=gguf

# 주요 GGUF 양자화 제공자
# ① bartowski — 가장 활발한 GGUF 변환자, imatrix 적용
# ② unsloth  — Llama/Mistral 계열 최적화 변환
# ③ mmnga    — 일본어/다국어 모델 GGUF 변환

# huggingface-cli로 직접 다운로드
pip install huggingface-hub
huggingface-cli download \
  bartowski/Llama-3.2-3B-Instruct-GGUF \
  --include "*Q4_K_M.gguf" \
  --local-dir ./models

# 특정 양자화만 골라서 다운로드 (와일드카드)
huggingface-cli download \
  bartowski/Qwen2.5-7B-Instruct-GGUF \
  --include "*Q5_K_M.gguf" \
  --local-dir ./models

# Ollama에서 직접 Hugging Face GGUF 사용 (v0.4+)
ollama run hf.co/bartowski/Llama-3.2-3B-Instruct-GGUF:Q4_K_M

GGUF 생태계 도구 모음

GGUF 생태계: 소스 모델 → 변환 → .gguf → 다양한 런타임 → 외부 앱 통합

GGUF 자주 묻는 질문 (FAQ)

실무 팁

• GGUF 모델은 Q4_K_M 양자화가 대부분의 용도에서 최적의 품질/크기 균형을 제공합니다.
• GPU VRAM이 부족하면 -ngl 옵션으로 일부 레이어만 GPU에 올리세요.
• HuggingFace에서 GGUF 모델을 받을 때는 bartowski, unsloth 등 활발한 변환자의 모델을 선택하세요.