모델 파일 포맷

모델 릴리스는 파일 하나가 아닙니다. 엔진마다 다시 포장되는 체크포인트입니다. 이 페이지는 로컬에서 실제로 만나게 될 포맷을 지도화합니다. llama.cpp 세계의 GGUF, PyTorch/HF 스택의 safetensors, 엔진 네이티브 GPU quant, 엣지 런타임의 ONNX. 엔진을 먼저 고르세요. 포맷은 따라옵니다.

GGUF: 파일 하나에 전부

.gguf 파일은 모델 가중치, 토크나이저 어휘, 챗 템플릿, 텐서별 메타데이터를 단일 바이너리에 담습니다. 다운로드 한 번, 설정 제로, GGUF를 말하는 모든 앱이 같은 파일을 돌립니다. llama.cpp와 llama-server, Ollama, LM Studio, Jan, KoboldCpp. 포맷은 메모리 매핑이 가능해서 가중치가 디스크에서 페이지 단위로 스트리밍됩니다 — 시작이 빠르고 OS 페이지 캐시가 캐싱을 공짜로 해줍니다.

Qwen3-8B-Q4_K_M.gguf의 파일명 해부, 필드별로:

GGUF를 로드하지 않고 들여다보기:

python gguf-py/gguf/scripts/gguf_dump.py model.gguf

general.architecture     : qwen3
general.name             : Qwen3 8B
qwen3.context_length     : 32768
tokenizer.ggml.model     : gpt2 (BPE)
tokenizer.chat_template  : {%- ... a Jinja template ... %}

이 메타데이터 블록이 GGUF가 서로 다른 다섯 앱에서 "그냥 되는" 이유입니다. 엔진이 아키텍처를 읽고, 그래프를 구성하고, 토크나이저를 로드하고, 챗 프론트엔드가 내장된 템플릿을 적용합니다. 설정 찾기도 없고, 어휘 불일치도 없고, 별도 토크나이저 다운로드도 없습니다.

Safetensors: Hugging Face 네이티브

safetensors은 의도적으로 지루한 컨테이너입니다. 텐서 이름, shape, dtype의 JSON 헤더 뒤에 날것 바이트가 따라옵니다. 텐서만 저장합니다 — 무작정 로드하면 안전하지 않은 pickle 계열 .bin 체크포인트와 달리 실행 코드가 없습니다 — 그리고 제로카피 mmap을 지원해서 PyTorch 시작이 빠릅니다. Transformers, vLLM, SGLang, TRL, 파인튜닝 생태계 전체가 네이티브로 말합니다.

텐서만 저장하므로, 동작하는 모델은 저장소 디렉터리 전체입니다:

model-00001-of-00004.safetensors   ← 가중치 샤드 (각 ~5 GB)
model-00002-of-00004.safetensors
model-00003-of-00004.safetensors
model-00004-of-00004.safetensors
model.safetensors.index.json        ← 샤드 맵: 텐서 이름 → 샤드 파일
config.json                         ← 아키텍처 + 하이퍼파라미터
generation_config.json              ← 기본 샘플링 설정
tokenizer.json                      ← 토크나이저 자체
tokenizer_config.json               ← 챗 템플릿이 여기에

샤딩이 존재하는 이유는 70B FP16 체크포인트가 ~140 GB이기 때문입니다 — 파일 하나라면 감당이 안 됩니다. vLLM으로 서빙하면 샤드 전체를 다운로드합니다. safetensors 릴리스 안에 "4비트 파일만" 지름길은 없습니다. 양자화 서빙은 별도 저장소입니다(같은 모델의 AWQ 또는 GPTQ 변형).

엔진 네이티브 GPU quant: AWQ, GPTQ, EXL2

이 포맷들은 GPU 추론 서버를 위해 존재합니다. 파일 편의보다 처리량이 중요한 곳:

• AWQ — 활성화 인지(activation-aware) 양자화. 캘리브레이션 프롬프트로 활성화가 가장 의존하는 상위 ~1% 가중치 채널을 찾고, 그것만 보호된 스케일링을 받고 나머지는 4비트로 갑니다. 4비트에서 원본 근처 품질과 빠른 커널. vLLM의 기본 4비트 선택.
• GPTQ — 최적 뇌 양자화에서 내려온 고전 GPU quant. 층별로 양자화하며, 아직 양자화되지 않은 가중치에 대해 각 층의 오차를 보상합니다. 4비트, GPU 전용 커널, 서빙 설정에 여전히 널려 있습니다.
• EXL2 — exllamav2의 가변 비트 per 가중치 포맷. 한 저장소가 2–8비트 텐서를 섞어 총량이 VRAM 상한 바로 아래에 정확히 착륙하게, 예컨대 4.65 bpw로 앉을 수 있습니다. Q4는 안 들어가는데 Q3는 아플 때의 도구.

셋 다 캘리브레이션 데이터와 일회성 변환 실행이 필요하고, 셋 다 CPU에서는 돌지 않습니다.

ONNX, MLX, 날것 FP16/BF16

ONNX는 휴대용 연산 그래프 포맷입니다. transformers 모델을 한 번 내보내면 onnxruntime이 도는 어디서든 실행됩니다 — CUDA 없는 윈도우 박스, 폰, 브라우저 WebGPU 데모. onnxruntime은 그래프를 CPU용 INT8으로 양자화할 수도 있습니다. 설정 마찰과 종종 최고 속도를 지불하고, PyTorch 스택 없는 기계로의 이식성을 얻습니다. 엣지와 임베디드가 본진이지 데스크톱 챗이 아닙니다.

MLX는 Apple Silicon용 Apple의 배열 프레임워크입니다. mlx-community 조직이 주요 릴리스 대부분을 4비트와 8비트 포함해 MLX 포맷으로 재포장합니다. M 시리즈 맥에서 mlx-lm을 돌린다면 그것이 당신의 포맷입니다 — Apple Silicon 참고.

날것 FP16/BF16 체크포인트는 무손실 기준, 파인튜닝 베이스, 변환 원본이 필요할 때 중요합니다. BF16은 FP32의 8비트 지수 범위를 유지하고 가수 비트를 그것과 맞바꿉니다 — FP16보다 학습에서 훨씬 안정적이고, 가중치당 2바이트는 같습니다. FP16/BF16의 7–8B 모델은 컨텍스트를 세기도 전에 가중치만 ~16 GB입니다.

어느 엔진에 어느 포맷

포맷 섞기가 클래식 초보 실수입니다. vLLM에게 .gguf를 갖다 대거나, llama.cpp에게 safetensors 샤드를 갖다 대는 것. 둘 다 안 됩니다 — 엔진은 에러를 내거나 먼저 변환 단계가 필요합니다.

변환 경로

Hugging Face 저장소에서 로컬 파일로 가는 표준 경로는 두 단계입니다 — 체크포인트를 16비트 GGUF로 변환하고, 그다음 양자화합니다:

git clone https://github.com/ggerganov/llama.cpp
pip install -r llama.cpp/requirements.txt

# 1. HF 체크포인트(safetensors)를 GGUF로 변환
python llama.cpp/convert_hf_to_gguf.py ./Qwen3-8B --outtype bf16 --outfile qwen3-8b-bf16.gguf

# 2. 목표 크기로 양자화
llama-quantize qwen3-8b-bf16.gguf qwen3-8b-Q4_K_M.gguf Q4_K_M

실무에서는 직접 변환할 일이 거의 없습니다. bartowski와 mradermacher 같은 양자화자들이 주목할 만한 릴리스마다 모든 크기를 몇 시간 안에 공개합니다. 직접 변환하는 경우는 사내 파인튜닝이 있거나, imatrix 캘리브레이션된 I-quant를 원하거나, 비표준 비트 타깃이 필요할 때입니다 — 세부는 양자화에 있습니다.

임베딩 모델 — RAG의 검색 절반 — 도 같은 포맷으로 배포됩니다. llama.cpp 임베딩 엔드포인트용 GGUF, sentence-transformers용 safetensors. 위의 모든 것과 같은 규칙: 실제로 돌릴 엔진에 포맷을 맞추세요.

관련: 양자화 · 모델 패밀리 · 엔진 · RAG