GGUF란 무엇인가: 로컬 LLM 모델 파일 포맷의 개념과 동작 방식

GGUF는 로컬에서 LLM을 실행하기 위해 쓰는 모델 파일 포맷이다.

여기서 먼저 구분해야 한다. GGUF는 LLM 앱이 아니다. Ollama도 아니고 LM Studio도 아니고 llama.cpp 자체도 아니다. 또한 모델의 알고리즘 이름도 아니다.

GGUF는 모델을 담는 파일 형식이다.

비유하면 이렇게 볼 수 있다.

• PDF는 문서를 여러 reader가 열 수 있게 만든 파일 형식이다.
• MP4는 영상을 여러 player가 재생할 수 있게 만든 파일 형식이다.
• GGUF는 LLM 모델을 로컬 실행기가 읽고 실행할 수 있게 만든 파일 형식이다.

즉 GGUF 파일은 보통 이런 이름으로 존재한다.

llama-3.1-8b-instruct-q4_k_m.gguf
qwen3-reranker-0.6b-q8_0.gguf
qmd-query-expansion-1.7B-q4_k_m.gguf

파일 하나처럼 보이지만, 그 안에는 모델 가중치와 실행에 필요한 여러 정보가 들어 있다.

LLM 모델 파일이란 무엇인가

LLM은 거대한 프로그램처럼 보이지만, 핵심은 수많은 숫자다. 이 숫자를 weight, 즉 가중치라고 부른다.

모델이 “지식을 기억한다”고 표현할 때가 많지만, 실제로는 문장을 보고 다음 토큰을 계산하는 데 필요한 가중치 행렬들이 저장되어 있는 것이다.

예를 들어 사용자가 문장을 입력하면 LLM은 다음 과정을 반복한다.

1. 입력 문장을 token으로 나눈다.
2. token을 숫자 벡터로 바꾼다.
3. 여러 layer의 weight를 통과시키며 다음 token 확률을 계산한다.
4. 가장 그럴듯한 다음 token을 고른다.
5. 다시 다음 token을 계산한다.

이 계산에 필요한 weight가 모델 파일의 본체다.

하지만 weight만 있다고 모델을 실행할 수는 없다. 실행기는 다음 정보도 알아야 한다.

• 이 모델이 Llama 계열인지 Qwen 계열인지
• layer가 몇 개인지
• hidden size가 얼마인지
• context length가 얼마인지
• tokenizer가 어떤 규칙을 쓰는지
• weight가 어떤 dtype 또는 quantization 형식인지
• 각 tensor가 파일 어디에 있는지

GGUF는 이런 정보를 한 파일에 담는 포맷이다.

GGUF 파일 안에는 무엇이 들어 있나

공식 GGUF 문서의 핵심 설명은 이렇다. GGUF는 GGML 및 GGML 기반 executor에서 inference용 모델을 저장하기 위한 binary format이다. 빠른 loading/saving, 읽기 쉬운 구조, 단일 파일 배포, mmap 호환성, 확장 가능한 metadata를 목표로 한다.

GGUF 파일은 대략 다음 요소로 구성된다.

Header는 이 파일이 GGUF인지, 버전이 무엇인지, metadata와 tensor가 몇 개인지 알려주는 시작 정보다.

Metadata는 key-value 형태의 정보다. 모델 이름, 아키텍처, context length, tokenizer, quantization 정보 같은 실행 설정이 들어간다. GGUF가 이전 포맷보다 나아진 중요한 지점이 이 metadata 구조다. 새로운 정보를 추가해도 기존 reader와의 호환성을 유지하기 쉽다.

Tensor info는 각 weight tensor의 이름, shape, type, 파일 안에서의 위치를 알려준다. 실행기는 이 정보를 보고 필요한 weight를 찾아 읽는다.

Tensor data는 실제 모델 가중치다. 이 부분이 파일 크기의 대부분을 차지한다. Q4_K_M, Q8_0 같은 양자화 형식으로 저장될 수 있다.

Alignment는 데이터를 메모리에서 효율적으로 읽기 위한 정렬이다. GGUF가 mmap 기반 빠른 loading에 유리한 이유와 관련된다.

정리하면 GGUF는 단순히 weight만 던져놓은 파일이 아니다. 실행기가 모델을 해석하고 바로 올릴 수 있도록 “weight + 설명서 + 위치표”를 함께 담은 파일이다.

왜 PyTorch나 Safetensors를 그대로 쓰지 않나

모델은 보통 PyTorch나 Safetensors 형태로 배포된다. 이 포맷들은 학습, 파인튜닝, 연구, 대규모 서빙 환경에 잘 맞는다.

하지만 로컬 실행 도구는 목표가 다르다.

로컬 실행기는 보통 다음을 원한다.

• Python이나 PyTorch 없이 실행
• 작은 런타임으로 실행
• CPU에서도 실행 가능
• 일부 layer를 GPU에 올릴 수 있음
• 모델을 빠르게 load
• quantized weight를 효율적으로 읽음
• tokenizer와 설정을 한 파일에서 확인

GGUF는 이 목적에 맞춰 만들어진 inference 친화적인 포맷이다.

즉 PyTorch/Safetensors가 모델 개발과 학습에 가까운 포맷이라면, GGUF는 로컬 inference 실행에 가까운 포맷이다.

변환과 실행 흐름

일반적인 흐름은 다음과 같다.

먼저 모델은 PyTorch나 Safetensors 형태로 학습되고 배포된다. Hugging Face에서 받는 원본 모델은 이 형태인 경우가 많다.

그 다음 변환 도구가 모델 구조와 weight를 GGUF 구조에 맞게 바꾼다. 이때 tokenizer 정보와 아키텍처 metadata도 함께 들어간다.

이후 필요하면 quantization을 한다. 예를 들어 16-bit weight를 8-bit, 4-bit 수준으로 줄인다. 이렇게 하면 파일 크기와 메모리 사용량이 크게 줄어든다.

마지막으로 llama.cpp, Ollama, LM Studio, node-llama-cpp 같은 로컬 실행기가 GGUF 파일을 읽어 inference를 수행한다.

QMD도 이 방식을 쓴다. QMD의 embedding, rerank, query expansion 모델은 GGUF로 제공되고, node-llama-cpp를 통해 로컬에서 실행된다.

GGUF와 llama.cpp의 관계

GGUF를 이해할 때 llama.cpp와의 관계를 혼동하면 안 된다.

llama.cpp는 로컬에서 LLM을 실행하는 C/C++ 기반 inference engine이다. CPU에서도 동작하고, Metal, CUDA 같은 backend를 활용할 수 있다.

GGUF는 llama.cpp 같은 실행기가 읽는 모델 파일 포맷이다.

따라서 관계는 이렇게 정리하면 된다.

• GGUF: 모델을 담는 파일 형식
• llama.cpp: GGUF를 읽고 모델을 실행하는 엔진
• Ollama/LM Studio: 내부적으로 llama.cpp 계열 실행기를 활용해 사용자에게 편한 앱/서버 형태로 제공하는 도구
• node-llama-cpp: Node.js에서 llama.cpp를 사용할 수 있게 해주는 바인딩

사용자는 Ollama에서 모델을 실행한다고 느끼지만, 실제 아래쪽에서는 GGUF 파일을 읽는 로컬 inference 계층이 동작하는 경우가 많다.

Quantization은 왜 같이 나오나

GGUF를 이야기하면 Q4_K_M, Q5_K_M, Q8_0 같은 이름이 자주 나온다. 이것은 quantization, 즉 양자화와 관련 있다.

LLM weight는 원래 보통 16-bit 또는 32-bit 부동소수점으로 저장될 수 있다. 정확도는 좋지만 파일 크기와 메모리 사용량이 크다.

양자화는 이 weight를 더 낮은 정밀도로 압축해 저장하는 방식이다.

예를 들어 아주 단순화해서 보면 다음과 같다.

• FP16: 품질은 좋지만 크고 무겁다.
• Q8_0: 8-bit 수준으로 줄여 크기를 낮춘다.
• Q4_K_M: 4-bit 계열로 더 작게 줄인다.
• Q2/Q3 계열: 더 작지만 품질 손실이 커질 수 있다.

중요한 trade-off는 명확하다.

작게 만들수록 실행은 쉬워지지만, 품질 손실 가능성이 커진다. 반대로 정밀도를 높이면 품질은 좋아질 수 있지만, 더 많은 메모리와 저장 공간이 필요하다.

그래서 모델 파일 이름의 quantization 표기는 중요하다.

model-q8_0.gguf
model-q4_k_m.gguf
model-f16.gguf

같은 모델이라도 어떤 quantization을 선택했는지에 따라 속도, 메모리 사용량, 답변 품질이 달라진다.

GGUF가 잘 맞는 사용처

GGUF는 로컬 실행에 특히 잘 맞는다.

개인 PC나 Mac에서 Ollama, LM Studio, llama.cpp로 모델을 돌릴 때 적합하다.

서버 없이 로컬에서 개인정보를 유지하며 inference를 하고 싶을 때도 유리하다. 문서를 외부 API로 보내지 않고 local reranker, local embedding, local assistant를 구성할 수 있다.

작은 모델을 여러 개 역할별로 돌릴 때도 좋다. 예를 들어 QMD처럼 embedding 모델, reranker 모델, query expansion 모델을 각각 GGUF로 받아 로컬에서 실행할 수 있다.

에이전트 시스템에서도 유용하다. main LLM은 외부 API를 쓰더라도, 검색 보조 모델이나 reranker는 로컬 GGUF로 돌려 비용과 지연을 줄일 수 있다.

GGUF의 한계

GGUF가 모든 상황에 최선은 아니다.

첫째, 학습용 포맷이 아니다. GGUF는 주로 inference용 포맷이다. 모델을 본격적으로 학습하거나 파인튜닝하려면 PyTorch, Safetensors, training framework 쪽이 중심이 된다.

둘째, 변환 품질과 호환성이 중요하다. 모델 아키텍처가 실행기에서 지원되지 않거나 metadata가 맞지 않으면 GGUF로 변환해도 제대로 실행되지 않을 수 있다.

셋째, 양자화는 손실 압축이다. Q4 모델이 항상 충분한 품질을 내는 것은 아니다. 코딩, 수학, 긴 문맥, 도구 호출 같은 작업에서는 quantization 차이가 체감될 수 있다.

넷째, GGUF 파일만 있다고 서비스 운영이 끝나는 것은 아니다. prompt template, tokenizer, context size, GPU offload, batch 설정, serving API, 동시성 관리는 별도 문제다.

다섯째, 최신 대규모 production serving에는 다른 선택지가 더 적합할 수 있다. vLLM, TensorRT-LLM, SGLang 같은 서버형 추론 엔진은 대량 동시 요청과 고성능 GPU serving에 초점을 둔다. GGUF는 특히 개인/로컬/간단한 서버 실행 쪽에서 강하다.

QMD에서 GGUF가 왜 중요한가

QMD는 로컬 Markdown 검색 엔진이다. QMD가 지향하는 방향은 외부 API에 모든 것을 맡기는 것이 아니라, 검색에 필요한 일부 모델을 로컬에서 실행하는 것이다.

QMD에서 GGUF는 세 군데와 연결된다.

• embedding 모델: 문서와 query를 vector로 바꾸는 모델
• reranker 모델: query와 후보 chunk의 관련성을 다시 평가하는 모델
• query expansion 모델: 짧은 질문을 lex, vec, hyde 검색어로 확장하는 모델

이 모델들이 GGUF로 제공되면 QMD는 node-llama-cpp를 통해 로컬에서 실행할 수 있다. 사용자는 Markdown 문서를 외부 서버로 보내지 않고도 semantic search, rerank, query expansion을 구성할 수 있다.

그래서 QMD 글에서 GGUF가 등장한 것이다. QMD 자체가 GGUF 포맷을 만든 것은 아니지만, QMD의 로컬 LLM 실행 전략은 GGUF 생태계 위에 올라가 있다.

정리

GGUF는 로컬 LLM 실행을 위한 모델 파일 포맷이다.

모델의 weight, tokenizer, architecture metadata, tensor 위치 정보, quantization 정보를 하나의 binary file에 담는다. llama.cpp, Ollama, LM Studio, node-llama-cpp 같은 도구는 이 파일을 읽어 로컬 inference를 수행한다.

GGUF를 이해할 때 가장 중요한 구분은 이것이다.

GGUF는 모델도 아니고 실행기도 아니다. 모델을 로컬 실행기가 읽을 수 있게 담아놓은 파일 형식이다.

그래서 GGUF를 알면 로컬 LLM 생태계가 더 명확하게 보인다. 모델 원본은 Hugging Face의 PyTorch/Safetensors에서 오고, 변환과 양자화를 거쳐 GGUF가 되며, 실행기는 그 GGUF를 읽어 실제 토큰 생성을 수행한다.

참고

• GGML 공식 GGUF 문서: https://github.com/ggml-org/ggml/blob/master/docs/gguf.md
• llama.cpp: https://github.com/ggml-org/llama.cpp
• QMD: https://github.com/tobi/qmd