노트북에서 실행하려고 모델을 내려받은 적이 있다면, 아마 .gguf로 끝나는 파일이었을 것입니다.
작동 방식
ggml 명세는 GGUF를 GGML 및 GGML 기반 실행기에서 추론하기 위해 모델을 저장하는 바이너리 형식으로, 빠르게 불러오고 저장하도록 설계되었다고 설명합니다. 예전의 GGML, GGMF, GGJT 형식을 대체했습니다. 명시된 목표는 다음과 같습니다.
- 단일 파일. 추가 파일 없이 모델을 공유하고 불러올 수 있습니다.
- mmap 호환. 런타임이 가중치를 복사하지 않고 메모리 매핑할 수 있습니다.
- 확장 가능. 기존 모델을 깨뜨리지 않고 새 메타데이터를 추가할 수 있습니다.
- 완전한 정보. 모델을 불러오는 데 필요한 모든 것이 파일 안에 있습니다.
GGUF 파일은 헤더(매직 넘버, 형식 버전, 텐서 수와 메타데이터 수), 타입이 지정된 메타데이터 키-값 쌍, 텐서 이름·모양·타입·오프셋 표, 정렬 경계(기본 32바이트)까지의 패딩, 그리고 텐서 데이터 순으로 구성됩니다.
파일 이름에는 규칙이 있습니다. 명세의 예시 Mixtral-8x7B-v0.1-KQ2.gguf는 기본 이름, 크기 라벨(7B 전문가 8개, 전문가 혼합(MoE) 참고), 버전, 인코딩으로 나뉩니다.
대부분의 GGUF 파일은 양자화되어 있습니다. Hugging Face 표에 나온 주요 유형은 다음과 같습니다.
| 유형 | 가중치당 비트 | 비고 |
|---|---|---|
| Q8_0 | 8 | 레거시 최근접 반올림, 32개 가중치 블록 |
| Q6_K | 6.5625 | k-quant 슈퍼블록 |
| Q5_K | 5.5 | k-quant 슈퍼블록 |
| Q4_K | 4.5 | k-quant 슈퍼블록 |
| IQ4_XS | 4.25 | 중요도 행렬(importance matrix) 사용 |
| Q2_K | 2.625 | k-quant 슈퍼블록 |
왜 중요한가
- 로컬과 엣지 환경. Hugging Face는 GGUF를 쓰는 도구로 llama.cpp, LM Studio, GPT4All, Ollama를 꼽습니다. CPU, Mac, 소비자용 GPU 한 장에서 오픈 웨이트 모델을 실행하는 일반적인 방법입니다.
- 토크나이저가 가중치와 함께 다닙니다. 메타데이터가 파일 안에 있으므로, 변환 과정에서 채팅 템플릿이나 토크나이저 설정이 틀리거나 빠지면 출력 품질이 바뀔 수 있습니다.
- 품질은 양자화 유형에 달려 있습니다. 같은 모델이라도 Q2 파일과 Q8 파일은 실제로는 같은 모델이 아닙니다. 같은 조건끼리 비교하세요.
- GPU 서빙 형식과 다릅니다. vLLM 같은 서버 엔진도 지원 형식에 GGUF를 넣고 있지만, 프로덕션 GPU 서빙에서는 AWQ나 FP8 같은 형식을 더 많이 씁니다.
BroadNet Inference에서는
BroadNet API는 HTTP로 모델을 서빙합니다. GGUF 파일을 내려주지 않으며, 가중치를 직접 불러올 일도 없습니다. BroadNet 카탈로그에 따르면 실험실에서 Qwen3.8 27B를 llama.cpp에서 비전 프로젝터와 멀티 토큰 예측 드래프터를 붙인 GGUF Q4_K_M으로 실행했고, 이와 함께 AMD ROCm용 vLLM에서 AWQ INT4 빌드도 실행했습니다. 공개 API가 어떤 형식으로 서빙되는지는 밝히지 않습니다. 로컬 GGUF 구성과 API를 저울질하고 있다면 자체 호스팅 vs API 비용 가이드와 오픈 웨이트 vs 클로즈드 모델에서 장단점을 다룹니다.