GGUF 모델 로컬 실행법: Ollama, llama.cpp, vLLM

.gguf 파일을 내려받고 나서 실제로는 어떻게 실행하지, 궁금한가요? 가장 빠른 길은 ollama run hf.co/<repo>:Q4_K_M — Ollama가 Hugging Face에서 GGUF를 바로 받아 서빙합니다. GGUF는 llama.cpp가 도입했고 이제 모든 로컬 LLM 도구가 말하는 단일 파일 모델 포맷이라, 같은 파일이 Ollama, llama.cpp, LM Studio, Jan, 그리고 (단서 조항이 붙는) vLLM에서 돌아갑니다. 이 가이드는 각 러너를 복사해 쓸 수 있는 명령어와 함께 다루고, VRAM에 맞는 quantisation 고르는 법과 실제로 부딪히게 될 로드 에러를 정리합니다.

GGUF 파일이란?

GGUF(GGML Universal File)는 quantised 언어 모델의 컨테이너 포맷입니다. 파일 하나에 가중치, 토크나이저, 모델 메타데이터가 들어 있습니다 — 더 내려받을 것도, 설정 수프도 없습니다. 안의 가중치는 quantised 상태입니다: 16비트 부동소수점에서 4비트(또는 그 아래) 정수로 압축되어 있어, 풀 정밀도에서 ~18 GB가 필요한 9B 모델이 Q4 파일로는 ~5.5 GB에 들어가 게이밍 GPU나 심지어 CPU에서도 돌아가는 이유가 여기에 있습니다.

GGUF 파일 이름에서 중요한 것 두 가지:

1. 베이스 모델 — gemma-3-4b-it-GGUF는 Gemma 3 4B를 파인튜닝해 GGUF로 내보낸 것입니다.
2. quant 태그 — Q4_K_M, Q8_0, IQ4_XS 등이 가중치를 얼마나 공격적으로 압축했는지 말해 줍니다. 고르는 법은 아래에서.

Ollama로 GGUF 모델을 실행할 수 있을까?

네 — GGUF는 Ollama의 네이티브 포맷이고, 2024년부터 파일을 직접 건드릴 필요 없이 Hugging Face에서 바로 pull할 수 있습니다:

# Hugging Face에서 GGUF quant를 바로 pull해 대화하기
ollama run hf.co/bartowski/gemma-2-9b-it-GGUF:Q4_K_M

# 콜론 뒤 quant 태그가 저장소 안의 파일을 고른다
ollama run hf.co/ggml-org/gemma-3-4b-it-GGUF:Q8_0

이미 .gguf 파일을 내려받아 뒀나요? Modelfile로 그 파일을 가리키세요:

# Modelfile — 한 줄이면 충분
FROM ./gemma-2-9b-it-Q4_K_M.gguf

ollama create gemma9b -f Modelfile
ollama run gemma9b

Ollama는 GPU 오프로드를 자동으로 결정하고 11434 포트에 OpenAI 호환 API를 노출하므로, 그 API를 말하는 무엇이든 이 모델을 쓸 수 있습니다. 트레이드오프는 제어입니다: 몇 개의 레이어를 GPU로 보낼지는 고를 수 없습니다.

llama.cpp에서 GGUF 파일을 실행하는 방법은?

llama.cpp는 GGUF가 태어난 곳 — 포맷이 이것을 위해 존재합니다 — 이라 지원이 가장 깊고 가장 신선합니다. llama-server 바이너리는 채팅 UI와 OpenAI 호환 엔드포인트를 둘 다 줍니다:

# Hugging Face에서 바로 다운로드 (내 장비에 맞는 GGUF를 골라 준다)
llama-server -hf ggml-org/gemma-3-4b-it-GGUF --port 8080

# 또는 이미 갖고 있는 파일을 풀 GPU 오프로드로 실행
llama-server -m ./gemma-2-9b-it-Q4_K_M.gguf -ngl 99 --port 8080

-ngl 99는 99개 레이어를 GPU에 밀어 넣습니다; VRAM이 허락하는 것보다 낮추면 나머지는 CPU에 남습니다. 이 부분 오프로드 다이얼이 llama.cpp의 특기입니다 — 9B 모델도 48개 레이어 중 20개만 오프로드하면 6 GB 카드에서 돌아갑니다, 다만 느릴 뿐. 서버 대신 일회성 프롬프팅이라면 같은 -m 플래그로 llama-server를 llama-cli로 바꾸세요.

LM Studio는 같은 엔진에 데스크톱 GUI를 씌운 것입니다: .gguf 파일을 models 폴더에 넣거나(또는 앱 안에서 Hugging Face를 검색하거나) load를 클릭하면 됩니다. 도구 선택 자체는 Ollama vs LM Studio 비교가 다룹니다.

어떤 GGUF quantisation을 내려받아야 할까?

기본 답: Q4_K_M. 커뮤니티의 스위트 스팟입니다 — 크기는 대략 1/4인데 풀 정밀도 품질의 1–2% 이내입니다. 큰 것부터 작은 것 순서의 사다리:

• Q8_0 — 거의 무손실; VRAM이 8.5비트/가중치를 아무렇지 않게 소화한다면 이걸 쓰세요.
• Q6_K / Q5_K_M — 크기는 한 단계 아래, 30B+ 모델에는 여전히 훌륭합니다.
• Q4_K_M — 기본값. 7–14B 모델에서 GB당 품질이 정점을 찍는 지점입니다.
• IQ4_XS / Q3_K_M — 큰 모델을 작은 카드에 우겨 넣을 때; 품질 손실이 체감되기 시작합니다.
• Q2_K 이하 — 최후의 수단; 모델이 문장 중간에 헛소리로 무너지기 시작합니다.

수용량 경험칙: 파일 크기(GB) + 컨텍스트 오버헤드 ~1–2 GB가 VRAM에 들어가면 됩니다. 9B 모델의 4.7 GB Q4_K_M은 8 GB 카드에서 여유롭습니다. 끔찍한 quant의 큰 모델보다 높은 quant의 작은 모델을 선호하세요 — Q8 4B가 보통 Q2 9B를 이깁니다.

GGUF vs Safetensors: 어느 포맷이 필요할까?

Safetensors는 quantise하지 않은 아카이브 포맷입니다 — 훈련, 파인튜닝, transformers와 ComfyUI 같은 도구를 위한 풀 정밀도 가중치. GGUF는 자신의 하드웨어에서 추론하기 위한 quantised, 실행 가능한 포맷입니다. GGUF는 파인튜닝할 수 없고, safetensors 파일은 변환 없이는 Ollama나 llama.cpp에서 실행할 수 없습니다(llama.cpp의 convert_hf_to_gguf.py 스크립트가 하는 일이 그것입니다). 규칙: 훈련이나 이미지 파이프라인 → safetensors; 로컬 채팅과 서빙 → GGUF. 검색이 “gguf vs safetensors”로 시작했다면, 이 구분이 답의 전부입니다.

GGUF 러너는 무엇을 써야 할까?

러너	적합한 용도	설치	GPU 오프로드	OpenAI 호환 API
Ollama	설치 후 잊는 서비스	curl 한 줄	자동	예 (:11434/v1)
llama.cpp	최대 제어, 최신 기능	빌드 또는 패키지 매니저	수동 -ngl 다이얼	예 (llama-server)
LM Studio	데스크톱 GUI, 모델 탐색	앱 다운로드	자동	예 (로컬 서버)
vLLM	다중 사용자 배치 서빙	pip install vllm	자동	예 (네이티브)

부팅 시 뜨고 보이지 않는 곳에서 돌기를 원하면 Ollama — 제가 homelab에서 네트워크의 모든 것에 모델을 서빙하는 데 쓰는 것도 이것입니다. 기능이 배포된 당일에 필요하거나(새 아키텍처가 가장 먼저 도착하는 곳입니다) 레이어 단위 메모리 제어가 필요하면 llama.cpp. GUI라면 LM Studio. 모델 하나가 많은 동시 사용자를 서빙해야 할 때만 vLLM — GGUF 지원이 동작하긴 하지만 네이티브 포맷에 비하면 이등 시민입니다.

GGUF 모델이 로드되지 않는 이유는?

대부분의 경우를 커버하는 네 가지 에러:

1. unknown model architecture — 런타임보다 나중에 나온 아키텍처를 GGUF가 씁니다(새 MoE와 비전 모델은 끊임없이 등장합니다). Ollama를 업데이트하거나 llama.cpp를 다시 빌드하세요; 다른 해결책은 없습니다.
2. 로드 시 메모리 부족 — quant가 VRAM + 컨텍스트보다 큽니다. 한 단계 아래로(Q4_K_M → Q3_K_M), -ngl을 낮추거나, -c 4096으로 컨텍스트를 줄이세요.
3. 다운로드 잘림 / 손상 — magic number나 메타데이터 에러로 GGUF 로드가 실패합니다. 다시 내려받고 Hugging Face 페이지에 표시된 SHA256과 비교하세요.
4. ollama run ./model.gguf가 거부함 — 정상입니다: Ollama의 run은 파일 경로가 아니라 모델 이름을 받습니다. 위에 보여 준 Modelfile 경로를 쓰세요.

마지막으로 알아둘 각도 하나: 로컬 GGUF 엔드포인트는 에이전틱 코딩 도구와 잘 어울립니다 — OpenAI 호환 클라이언트를 그 주소로 향하게 하면 completions의 비용은 전기요금뿐입니다. 이 가이드의 배관이 돌아가게 된 뒤 어떤 모델이 그 슬롯에 값어치가 있는지는 코딩용 최강 로컬 LLM이 테스트했습니다.