GGUF 포맷 스펙 — 단일 파일·확장 가능한 구조

GGUF 포맷 스펙 — 단일 파일·확장 가능한 구조

모델을 PyTorch로 학습했다면, GGML에서 쓰려면 보통 GGUF로 변환해야 해요. GGUF는 이전 포맷(GGML, GGMF, GGJT)의 후속으로, 모델을 읽는 데 필요한 모든 정보를 파일 하나에 담도록 설계됐어요.

출처: https://github.com/ggml-org/ggml/blob/master/docs/gguf.md

GGUF가 추구하는 특징을 보면 이런 것들이 있어요.

  • 단일 파일 배포: 별도 외부 파일 없이 배포·로드 가능.
  • 확장 가능: GGML 기반 실행기에 신규 기능을 추가하거나 모델에 새 정보를 더해도 기존 호환성을 깨지 않음.
  • mmap 호환: mmap으로 로드해 빠르게 저장·로드.
  • 사용하기 쉬움: 외부 라이브러리 없이 작은 코드로 로드·저장 가능, 언어 무관.
  • 완전한 정보: 모델 로드를 위한 모든 정보가 파일 안에 들어 있어 사용자가 따로 제공할 필요 없음.

GGJT와 GGUF의 핵심 차이는 하이퍼파라미터(이제는 메타데이터)를 무타입 값 목록 대신 키-값 구조로 담는다는 점이에요. 이 덕분에 기존 모델 호환성을 깨지 않으면서 새 메타데이터를 추가할 수 있어요.

파일 구조는 크게 네 부분으로 나뉘어요. 매직 넘버(선택적 버전), 모델별 하이퍼파라미터(층 수, 헤드 수 같은 메타데이터와 대부분 텐서 타입을 설명하는 ftype), 임베디드 어휘(문자열 목록), 그리고 마지막으로 길이가 붙은 이름·타입·데이터를 가진 텐서 목록이에요. 포맷 자체는 v1(초기), v2(대부분의 countable 값을 uint32에서 uint64로), v3(big-endian 지원)로 버전이 올라갔어요.

더 알아보기