GGUF(GGML Universal File)는 텐서와 메타데이터를 단일 파일에 저장하도록 설계된 이진 파일 형식으로, 모델 데이터의 빠른 저장 및 로딩을 가능하게 한다. 2023년 8월 llama.cpp 프로젝트에 의해 도입되었으며, 추가적인 모델 아키텍처 지원이 늘어남에 따라 이전 버전과의 호환성을 개선하기 위해 만들어졌다. GGUF는 프로젝트에서 사용하던 GGML과 같은 이전 형식을 대체했으며, 일반적으로 머신 러닝 라이브러리(예: PyTorch)로 개발된 모델을 변환하여 생성된다. 이 형식은 로컬 추론을 위한 양자화된 대규모 언어 모델 배포의 표준이 되었으며, llama.cpp, Ollama, LM Studio, GPT4All, Jan, koboldcpp와 같은 도구에서 기본적으로 지원된다. 2026년 기준으로 수만 개의 GGUF 체크포인트가 Hugging Face에 호스팅되어 있으며, Hugging Face는 메타데이터 뷰어, 추론 엔드포인트 서비스, JavaScript 파서 라이브러리를 포함한 일급 통합을 제공한다.
역사
llama.cpp 프로젝트에서 사용된 모델 파일 형식은 GGML, GGMF, GGJT, GGUF의 네 가지 명명된 단계를 거쳐 발전했다. 원래 GGML 형식은 로더 내부에 모델 하이퍼파라미터와 토크나이저 정보를 하드코딩하는 얇은 텐서 컨테이너였으며, 새로운 모델 아키텍처나 양자화 방식을 지원하려면 일반적으로 기존 파일과의 호환성을 깨뜨리는 코드 변경이 필요했다.
2023년 동안 llama.cpp가 Llama - Mistral, Falcon 등을 포함한 추가 아키텍처를 지원하면서 이러한 한계는 점점 관리하기 어려워졌다. GGUF는 2023년 8월 21일에 이전 버전과 호환되지 않는 후속 버전으로 도입되었으며, 사양은 ggerganov/ggml 저장소의 풀 리퀘스트 #302를 통해 공식화되었다. 이 형식은 GGJT의 전체 레이아웃을 계승하지만, 평면적인 하이퍼파라미터 목록을 구조화된 키-값 메타데이터 시스템으로 대체하여 로더를 수정하거나 기존 모델을 깨뜨리지 않고도 새 필드(아키텍처 세부 정보, 토크나이저 어휘, 학습 파라미터)를 추가할 수 있게 한다.
형식 자체는 세 가지 내부 버전을 거쳤다. 버전 1은 기본 구조를 확립했고, 버전 2는 메모리 매핑을 지원하기 위해 명시적 정렬 패딩을 추가했으며, 현재 버전인 버전 3은 선택적 빅엔디안 지원을 추가했다.
설계
GGUF는 모델 가중치의 정밀도를 줄이는 양자화에 중점을 둔다. 이는 모델 정확도 감소라는 대가를 치르더라도 메모리 사용량 감소와 속도 향상으로 이어질 수 있다. 이 형식은 다음과 같이 설계되었다:
- 자체 포함 - 단일 파일에 텐서, 토크나이저, 모델 로드 및 실행에 필요한 모든 메타데이터가 포함되어 별도의 구성 파일이 필요하지 않다.
- 메모리 매핑 가능 - 텐서 데이터는 (기본적으로 32바이트 경계에) 정렬되어 전체 파일을 RAM에 로드하지 않고도 포인터를 통해 가중치에 직접 접근할 수 있으며, 이를 통해 사용 가능한 메모리보다 큰 모델을 운영 체제 페이징을 통해 제공할 수 있다.
- 확장 가능 - 키-값 메타데이터 블록을 통해 기존 리더와의 호환성을 깨뜨리지 않고 새 필드를 추가할 수 있다.
GGUF는 2비트에서 8비트 양자화 정수 유형, float32, float16, bfloat16과 같은 일반적인 부동 소수점 데이터 형식, 1.58비트 양자화를 지원한다. 여러 "K-양자화" 변형(예: Q4_K, Q5_K, Q6_K)은 슈퍼 블록마다 별도의 스케일과 최소값을 가진 블록 기반 방식을 사용하며, 일반적으로 Q4_0 및 Q8_0과 같은 더 단순한 레거시 양자화보다 주어진 비트 폭에서 더 나은 품질을 제공한다. GGUF에는 토크나이저 어휘, 컨텍스트 길이, 텐서 정보 및 기타 속성과 같은 GPT 유사 언어 모델 실행에 필요한 정보가 포함되어 있다.
파일 구조
GGUF 파일은 고정 크기 헤더, 키-값 메타데이터 블록, 텐서 정보 블록, 텐서 데이터 자체의 네 가지 순차적 섹션으로 구성된다.
바이트 수준 구조(리틀엔디안)
버전 3 이전에는 파일이 암시적으로 리틀엔디안이었다. 버전 3은 빅엔디안 저장을 허용하지만 엔디안을 나타내는 플래그는 포함하지 않으므로 컨텍스트에서 추론해야 한다.
#### 메타데이터 블록
메타데이터 블록은 유형화된 키-값 쌍의 시퀀스이다. 키는 네임스페이스 문자열(예: general.*, tokenizer.* 또는 llama.*와 같은 아키텍처별 접두사)이며, 값은 스칼라, 문자열 또는 배열(다차원 배열 포함)일 수 있다.
#### 텐서 정보 블록
각 텐서에 대해 정보 블록은 이름, 차원 수, 형태, 데이터 유형 및 후속 tensor_data[] 영역 내의 바이트 오프셋을 저장한다. 명명 체계는 아키텍처 전반에 걸쳐 표준화되어(예: blk.0.ffn_gate.weight) 소스 프레임워크와 관계없이 로더가 가중치를 찾을 수 있다.
#### 텐서 데이터
텐서 데이터는 정보 블록 뒤에 오며 다음 정렬 경계에서 시작한다. 정렬 값 자체는 general.alignment 키 아래 메타데이터에 저장되며, 없으면 기본값은 32바이트이다. 이러한 방식으로 데이터를 정렬하면 파일을 직접 메모리 매핑할 수 있다. 텐서 가중치는 추가 복사 없이 포인터를 통해 읽을 수 있으며, 이는 SIMD 연산, GPU DMA 전송 및 CPU 캐시 효율성에 중요하다.
도구
다른 프레임워크에 저장된 모델은 일반적으로 llama.cpp에 번들된 convert_hf_to_gguf.py 스크립트를 사용하여 GGUF로 변환되며, 이 스크립트는 Hugging Face 체크포인트(일반적으로 safetensors 형식)를 읽고 f16 또는 bf16과 같은 선택된 기본 정밀도로 GGUF 파일을 생성한다. 결과 파일은 llama-quantize 유틸리티로 GGUF 정수 형식 중 하나로 재양자화할 수 있으며, 매우 큰 모델은 llama-gguf-split으로 여러 파일에 샤딩할 수 있다.
llama.cpp 프로젝트는 또한 GGUF 파일을 프로그래밍 방식으로 읽고 쓰기 위한 C/C++ API(ggml/include/gguf.h에 선언됨)와 Python 패키지 gguf-py를 제공한다.
채택
GGUF는 llama.cpp 및 추론 백엔드로 llama.cpp를 사용하는 Ollama의 기본 모델 형식이다. Ollama 레지스트리에서 가져온 모델은 내부적으로 GGUF 파일이며, Hugging Face의 임의 GGUF 파일은 hf.co/{user}/{repo}로 참조하여 로드할 수 있다. GGUF를 직접 사용하는 다른 추론 애플리케이션으로는 LM Studio, GPT4All, Jan, koboldcpp가 있다.
Hugging Face는 모델 허브에서 이 형식을 일급 시민으로 지원하며, GGUF 메타데이터 뷰어, gguf 태그로 필터링, 추론 엔드포인트 통합, 커뮤니티 업로드 GGUF 체크포인트의 대규모 컬렉션을 제공한다.