MLX-format vs GGUF — 언제 어느 거

두 형식, 두 유산

llama.cpp 또는 Ollama 썼다면, GGUF 봤어 — weight, config, tokenizer, metadata 담은 단일 binary 파일. mlx-lm 썼다면, MLX 형식 봤어 — 표준 파일들의 디렉토리 (lesson 1 에서 다룸). 두 형식 모두 같은 일반 목적 — 추론 준비된 양자화 LLM 출하. 다른 trade-off 만들고, 어느 거 고를지는 어디 배포하느냐에 달림.

각 형식의 모양

GGUF 가 단일 self-contained binary. Weight, tokenizer, config — 다 안에 패키지. Cross-platform CPU 와 GPU 추론용 (llama.cpp 의 CPU 세상에서 자랐어). 출하 쉬움 — 한 파일, 복사하고 실행. 살피거나 수정 어려움 — 안에 뭐 있는지 읽으려면 GGUF-aware 도구 필요. llama.cpp, Ollama, LM Studio, 그리고 그 ecosystem 의 나머지와 함께 출하되는 loader 용으로 최적화.

MLX 형식 이 표준 파일들의 디렉토리 (safetensors + JSON config + tokenizer 파일). Apple Silicon 의 unified-memory 하드웨어용. 파일들이 MLX 의 예상 메모리 레이아웃에 직접 매핑, 로드 시간 번역 안 필요. 살피거나 hack 쉬움 — 어떤 에디터에서든 열어. 출하 더 무거움 — 여러 파일, 수백 킬로바이트의 metadata.

각각이 이기는 곳

Apple-전용 ecosystem 안에 배포 (mlx-lm, mlx-vlm, mlx-audio, MLX Swift, v0.19 부터 Mac 의 Ollama) → MLX 형식. Native dispatch, 번역 overhead 없음, dispatcher 가 표준 config 직접 읽음.
Mac / Linux / Windows 머신 섞인 이질적 팀에 binary 넘김 → GGUF. 한 파일, 어떤 플랫폼의 llama.cpp 에서든 동작, 어떤 플랫폼의 Ollama 에서든 동작.
모델 fine-tune 또는 수정 원함 → MLX 형식. 디렉토리 레이아웃이 layer swap, config 수정, adapter merge (Track 4 가 다룸) 쉽게 만듦.
크기 frontier 에 있음 (매우 작은 칩, 매우 엄격한 메모리) → GGUF 가 역사적으로 CPU 의 가장 낮은-bit 양자화에 약간의 우위. MLX 의 최근 양자화 작업으로 갭이 좁아짐; Mac-native 사용엔 MLX 가 GPU 경로에서 이김.
Mac 에서 Ollama 돌림 → 두 형식 다 동작; v0.19 이후 Ollama 가 MLX 위에 빌드, 그래서 MLX-format 이 native 경로. GGUF 가 여전히 legacy import 로 동작.

둘 사이 변환

MLX → GGUF 또는 GGUF → MLX 변환 가능, 근데 one-line 명령 아냐 — 양 방향이 중간 도구 필요 (전형적으로 HF transformers 의 표현 통과). 대부분 워크플로엔, 미리 어느 형식 원하는지 결정하고 upstream PyTorch source 에서 직접 변환. Cross-format 변환은 한 형식 가지고 다른 거 필요한 엣지 케이스용.

비-결정

이 quest 전체가 사는 곳인 Mac-전용 Apple Silicon 작업엔, MLX 형식이 기본. Apple-아닌 배포 타겟에 적극적으로 출하 안 하면 GGUF 에 대해 생각하지 마. 레슨이 존재하는 이유는 GGUF 가 맞는 호출일 때 (이질적 팀, llama.cpp-기반 파이프라인) 알아볼 수 있게, 로컬 Mac 작업에 대한 선택에 시간 쓰지 않게.

Code

디스크에서 형식 차이 알아보기·bash

# MLX-format model: directory of standard files
ls ~/.cache/huggingface/hub/models--mlx-community--Llama-3.2-1B-Instruct-4bit/snapshots/*/
# config.json  model.safetensors  tokenizer.json  tokenizer_config.json  ...

# GGUF model: single binary file (path varies by uploader)
find ~/.cache/huggingface/hub -name "*.gguf" 2>/dev/null | head -3
# /Users/.../models--Qwen--Qwen2-0.5B-Instruct-GGUF/snapshots/.../qwen2-0_5b-instruct-q8_0.gguf

Weight 로드 안 하고 GGUF 파일 metadata 살피기·python

# Requires `pip install gguf` — it's a small package separate from llama.cpp.
# (Don't install in your `mlx` env unless you want it; this is illustrative.)
from gguf import GGUFReader

# Path to any .gguf file you have
path = "/path/to/some-model.gguf"
reader = GGUFReader(path)

print(f"Architecture: {reader.fields.get('general.architecture').contents()}")
print(f"Quantization: {reader.fields.get('general.file_type').contents()}")
print(f"Tensors:      {len(reader.tensors)}")

Exercise

네 머신에 어떤 GGUF 모델 있으면 (또는 HF 에서 작은 거 잡아 — 많은 모델이 두 형식 다로 업로드됨), 같은 모델의 GGUF 와 MLX 버전을 나란히 살펴. 파일 구조 차이 (단일 binary vs 파일 디렉토리), 디스크 크기 차이 (보통 ~10% 안에서 비슷), 로드-시간 차이 (MLX 가 Apple Silicon 에서 mmap 전형적으로 더 빠름) 알아채. 어느 형식이 네 전형 워크플로에 더 자연스럽게 느껴지는지 두 문장.