GGUF
GGUF는 llama.cpp가 LLM의 가중치, 토크나이저, 메타데이터를 저장하는 단일 파일 형식으로, 로컬 하드웨어에서 사용하기 위해 보통 4~8비트로 양자화됩니다.
GGUF는 llama.cpp의 기반이 되는 C 텐서 라이브러리 GGML과 이를 기반으로 한 도구에서 실행되는 모델을 저장하는 바이너리 파일 형식입니다. GGUF 파일 하나에는 대규모 언어 모델(LLM)을 실행하는 데 필요한 모든 정보가 담깁니다. 아키텍처와 하이퍼파라미터, 토크나이저 어휘, 채팅 템플릿, 모델 가중치가 포함되며, 가중치는 보통 모델 양자화를 통해 가중치당 2~8비트로 압축됩니다. llama.cpp 프로젝트는 기존 GGML, GGMF, GGJT 형식을 대체하기 위해 2023년 8월 GGUF를 도입했습니다. 이후 노트북 CPU, Apple Silicon Mac 또는 일반 사용자용 GPU에서 로컬 추론을 실행하기 위한 오픈 웨이트 모델 공유의 표준 형식이 되었으며, Hugging Face에는 수천 개의 GGUF 저장소가 있습니다.
GGUF 파일 내부#
GGUF 사양은 네 부분이 순서대로 이어지도록 정의합니다. 헤더에는 매직 바이트 GGUF, 형식 버전(현재 3), 텐서 및 메타데이터 항목 수가 들어갑니다. 이어서 general.architecture, llama.context_length, tokenizer.ggml.tokens, tokenizer.chat_template와 같은 유형이 지정된 키-값 메타데이터가 배치되며, 파일 자체에 모델의 토큰화 정보와 프롬프트 형식을 포함합니다. 다음 표에는 각 텐서의 이름, 모양, 데이터 유형, 오프셋이 나열되고, 마지막에는 텐서 데이터가 저장됩니다. 텐서 데이터는 기본적으로 32바이트 경계에 맞춰 패딩되므로 런타임에서 파일을 메모리 매핑하고 거의 즉시 로드할 수 있습니다. 리더는 키를 통해 메타데이터를 조회하므로 기존 파일을 손상시키지 않고 새 아키텍처와 필드를 추가할 수 있습니다.
각 텐서는 자체 유형을 가지므로 하나의 파일에 여러 정밀도를 혼합할 수 있습니다. llama.cpp 저장소에서 관리하는 Python 패키지 gguf는 이 형식을 쓰고 읽으며 여러 양자화 유형을 구현합니다.
import numpy as np
from gguf import GGMLQuantizationType, GGUFReader, GGUFWriter
from gguf.quants import dequantize, quantize
weights = np.random.default_rng(0).standard_normal((1024, 1024)).astype(np.float32)
# A GGUF file holds metadata key-value pairs plus named tensors, each with its own type
writer = GGUFWriter("tiny.gguf", arch="llama")
writer.add_context_length(4096)
for qtype in [GGMLQuantizationType.F16, GGMLQuantizationType.Q8_0, GGMLQuantizationType.Q4_0]:
writer.add_tensor(f"weight.{qtype.name}", quantize(weights, qtype), raw_dtype=qtype)
writer.write_header_to_file()
writer.write_kv_data_to_file()
writer.write_tensors_to_file()
writer.close()
# Read the file back: metadata keys, then each tensor's bits per weight and rounding error
reader = GGUFReader("tiny.gguf")
print([name for name in reader.fields if not name.startswith("GGUF.")])
for tensor in reader.tensors:
error = np.abs(dequantize(tensor.data, tensor.tensor_type).reshape(weights.shape) - weights).mean()
print(f"{tensor.tensor_type.name}: {8 * tensor.n_bytes / weights.size:.1f} bits per weight, mean error {error:.4f}")이 도구는 메타데이터 키 general.architecture과 llama.context_length 두 개를 나열한 다음, F16의 경우 가중치당 16.0비트와 평균 오차 0.0001, Q8_0의 경우 8.5비트와 0.0045, Q4_0의 경우 4.5비트와 0.0719를 보고합니다. Q8_0과 Q4_0은 가중치 32개로 구성된 블록마다 FP16 스케일 하나를 저장하며, 여기서 추가 0.5비트가 발생합니다.
양자화 유형#
GGUF 양자화 유형은 세 세대로 나뉩니다. Q4_0 및 Q8_0과 같은 초기 블록 형식은 가중치 32개당 스케일 하나를 사용합니다. Q4_K 및 Q6_K와 같은 K-quant는 블록을 가중치 256개로 구성된 슈퍼 블록으로 묶고 양자화된 스케일을 사용합니다. Q4_K_M과 같은 파일 이름은 가장 민감한 텐서를 더 높은 정밀도로 유지하는 혼합 방식을 나타냅니다. IQ2_XXS 및 IQ4_XS와 같은 I-quant는 가중치당 약 2~4비트에 도달하며, 보통 llama-imatrix이 샘플 텍스트를 바탕으로 계산하는 중요도 행렬을 사용해 영향력이 큰 가중치에 가장 높은 정밀도를 유지합니다. 최신 추가 형식으로는 OpenAI가 gpt-oss를 공개할 때 사용한 4비트 부동소수점 형식 MXFP4가 있습니다. 공개된 GGUF 파일 대부분은 같은 변환 경로를 거칩니다.
GGUF와 다른 모델 형식 비교#
- GGML, GGMF, GGJT: 이전 llama.cpp 형식은 하이퍼파라미터를 아키텍처 필드 없이 유형이 지정되지 않은 목록으로 저장했으므로, 파라미터를 추가하면 기존 파일이 깨졌습니다.
- Safetensors: Hugging Face의 원시 텐서 안전 저장 형식입니다. 보통 전체 또는 반정밀도로 저장하며, 설정과 토크나이저는 별도 파일에 보관합니다.
- ONNX: 가중치와 함께 전체 계산 그래프를 저장하므로 ONNX 호환 런타임이라면 아키텍처별 코드 없이 모델을 실행할 수 있습니다.
GGUF 모델 실행#
llama.cpp는 명령줄에서 GGUF 파일을 실행하거나 OpenAI 호환 API를 제공하는 llama-server으로 실행할 수 있습니다. 또한 원하는 수의 레이어를 GPU로 오프로드하고 나머지는 CPU에서 실행할 수 있어, GPU 메모리보다 큰 모델도 실행할 수 있습니다. Ollama와 LM Studio는 모델 라이브러리와 채팅 인터페이스를 통해 GGUF 모델을 실행하며, Hugging Face Hub는 브라우저에서 각 GGUF 파일의 메타데이터와 텐서 유형을 보여줍니다. 로컬 추론은 프롬프트를 기기에 보관하므로 데이터 프라이버시와 오프라인 엣지 AI 사용에 중요합니다. Ultralytics LLM 인터페이스는 OpenAI 호환 Chat Completions 엔드포인트를 통해 llama-server 또는 Ollama가 제공하는 GGUF 모델을 호출할 수 있습니다. 따라서 YOLO26 파이프라인은 데이터를 클라우드 API로 전송하지 않고 로컬 모델에 탐지 결과 설명을 요청할 수 있습니다. 이 형식은 언어 모델을 넘어섭니다. ComfyUI-GGUF 커스텀 노드는 FLUX.1과 같은 양자화된 확산 모델을 GGUF 파일에서 로드해 일반 사용자용 GPU 메모리에 들어가도록 합니다.










