GGUF

GGUF (llama.cpp 양자화 포맷)

llama.cpp 기반 추론을 쓰는 분이라면 GGUF라는 이름을 봤을 거예요. GGUF는 모델의 메타데이터와 텐서를 담는 단일 파일 포맷으로, 다양한 양자화 데이터 타입을 지원해서 메모리를 크게 아껴줍니다. 이 가이드에서는 Transformers에서 GGUF 모델을 로딩·서빙하는 방법을 살펴봐요.

출처: GGUF - Hugging Face Transformers 공식문서

GGUF란?

GGUF는 GGML로 추론하기 위해 모델을 저장하는 단일 파일 포맷으로, 모델 메타데이터와 텐서를 담고 있어요. 양자화 타입 표를 참고하면 알 수 있듯 다양한 양자화 데이터 타입을 지원해서 상당한 메모리를 절약합니다.

GGUF 모델 로딩

from transformers import AutoModelForCausalLM, AutoTokenizer

model_id = "unsloth/Qwen3.5-4B-GGUF"
filename = "Qwen3.5-4B-Q4_K_M.gguf"

model = AutoModelForCausalLM.from_pretrained(model_id, gguf_file=filename)
tokenizer = AutoTokenizer.from_pretrained(model_id, gguf_file=filename)

가중치는 Metal(MPS) 기기에서만 GGUF 블록 상태로 유지됩니다. 그곳에서는 Hub에서 가져온 llama.cpp 커널이 압축된 블록 위에서 직접 matmul을 수행해 추론 속도를 유지해요.

현재 지원되는 아키텍처는 Qwen3.5뿐이고, 나머지는 폴백됩니다. 다른 기기나 양자화 타입에서는 로딩 시점에 모델이 디양자화되고, 아직 지원되지 않는 아키텍처는 레거시 로더를 거칩니다.

어텐션

Metal에서 어텐션에도 ggml 커널이 있어요: llama.cpp가 flash attention에서 쓰는 것과 같은 ggml-attn이 decode와 prefill 모두에 동작합니다.

model = AutoModelForCausalLM.from_pretrained(
    model_id, gguf_file=filename, attn_implementation="transformers-community/ggml-attn"
)

디양자화

디양자화(dequantize)는 로딩 시점에 모든 가중치를 풀어서 일반 dense 모델로 되돌립니다. 빠른 압축 경로를 쓸 수 없을 때의 폴백이며, GgufConfig로 명시적으로 요청할 수도 있어요.

import torch

from transformers import AutoModelForCausalLM, GgufConfig

quantization_config = GgufConfig(dequantize=True)
model = AutoModelForCausalLM.from_pretrained(
    model_id, gguf_file=filename, quantization_config=quantization_config, dtype=torch.bfloat16
)

결과 모델은 일반 dense 모델이므로, 이 방식으로 GGUF 체크포인트를 원하는 dtype으로 가져갈 수도 있습니다. Qwen3.5 이외의 아키텍처는 레거시 로더가 읽으며, 이 로더도 모델을 디양자화합니다.

[!TIP] 레거시 로더는 Llama, Mistral, Qwen2, Qwen2Moe, Phi3, Bloom, Falcon, StableLM, GPT2, Starcoder2 등을 지원합니다. 더 자세한 목록은 ggml.py에서 확인하세요.

서빙

transformers serve는 GGUF 모델을 <repo>:<file>.gguf 로 지정해요. 저장소에 여러 양자화가 들어 있으므로 id가 어떤 것을 로딩할지 명시해야 하기 때문이에요. 요청도 같은 방식으로 이름을 붙입니다.

transformers serve unsloth/Qwen3.5-4B-GGUF:Qwen3.5-4B-Q4_K_M.gguf

더 알아보기 (Learn more)