로컬 LLM

지도 위치 : 2일차 · ②모델 파일 층(GGUF) × ③추론 엔진(llama.cpp) × ①하드웨어(VRAM ↔ RAM) | 이전: 11차시 8bit · 4bit 양자화 실습 | 다음: 13차시 LLM 추론 파라미터 최적화 키워드 : GGUF 구조, llama.cpp, GGUF 모델 실행, CPU · GPU 혼합 추론

이 차시를 다 읽으면

1. GGUF를 유와 종차로 정의하고, safetensors 묶음과 무엇이 다른지 말할 수 있다.
2. Q4_K_M, Q8_0 같은 양자화 이름을 읽고 대략의 크기와 품질 위치를 말할 수 있다.
3. llama.cpp의 -ngl과 -c가 각각 9차시 예산식의 어느 항 을 건드리는지 말할 수 있다.
4. CPU · GPU 혼합 추론이 왜 크게 느려지는지 디스크 ↔ 메모리 축으로 설명할 수 있다.
5. Ollama가 GGUF 위에 서 있다는 것과, 경량 LLM(1~4B) 이 문의봇의 어디에 쓰일 수 있는지 말할 수 있다.

---

0. 이 차시의 판별 축

앞에서 이어집니다 — 9차시 2.2에서 본 것처럼 Hugging Face 저장소의 모델은 여러 파일의 묶음 (가중치 파일 + config.json + 토크나이저 파일 …)입니다. 그런데 5차시에 ollama pull로 받은 모델은 따로 맞춰 줄 파일이 없었습니다. 그 모델이 사실 이번 차시의 형식(GGUF) 한 파일 이었습니다. 이번 차시는 그 형식과, 그 형식을 돌리는 엔진(llama.cpp), 그리고 VRAM이 모자랄 때 일어나는 일을 봅니다.

---

1. GGUF — 한 파일에 다 담은 형식

1.1 정의

GGUF — [모델 파일 형식]인데, [ 가중치뿐 아니라 모델 구조 · 토크나이저 · 채팅 템플릿 같은 메타데이터까지 한 파일에 담는다 ]는 점에서 가중치만 담고 나머지는 별도 파일로 두는 safetensors와 구별된다.

llama.cpp 프로젝트가 만든 형식이고(이전 형식 GGML의 후속), 처음부터 양자화된 가중치를 담는 것 을 전제로 설계되었습니다.

1.2 경계 — 모델 파일 확장자 세 가지

Hugging Face 저장소와 모델 배포 페이지에서 흔히 보는 가중치 파일 확장자는 세 가지입니다.

표의 낯선 단어 두 개만 짚습니다. 텐서 는 가중치 숫자들을 여러 차원의 표로 묶은 덩어리(행렬을 일반화한 것)입니다. pickle 은 Python 객체를 통째로 저장하는 방식인데, 파일을 여는 순간 그 안에 숨겨 둔 코드가 실행될 수 있어 출처를 모르는 파일은 위험합니다. 그래서 숫자(텐서)만 담고 코드는 담지 못하게 만든 형식이 safetensors ("안전한 텐서")입니다.

Hugging Face 저장소 (safetensors)          GGUF 한 파일
├─ config.json        ← 구조                ┌─────────────────────────┐
├─ tokenizer.json     ← 토크나이저           │ 헤더 · 메타데이터          │
├─ tokenizer_config.json ← 채팅 템플릿       │  - 구조(층 수, 헤드 수 …)  │
├─ generation_config.json                   │  - 토크나이저 어휘         │
└─ model-0000x-of-0000y.safetensors ← 가중치 │  - 채팅 템플릿             │
                                            │ 텐서(양자화된 가중치) …    │
                                            └─────────────────────────┘

⭐ 0절 축 2입니다. 여러 파일을 맞춰 옮기다가 하나를 빠뜨리는 실수가 사라지고, 폐쇄망 반입 단위가 파일 하나 가 됩니다(1차시 4.2).

1.3 반례 — 이건 아닙니다

---

2. 양자화 이름 읽는 법

2.1 이름의 구조

Q 4 _ K _ M
│ │   │   └ 크기 변형: S(작게) · M(중간) · L(크게) — 중요한 층을 얼마나 높은 비트로 남기는가
│ │   └ K-quant 방식 (그룹 단위 · 층별로 비트를 섞는 개선된 방식)
│ └ 대표 비트 수
└ 양자화(Quantized)

Q8_0처럼 _0이 붙은 것은 K-quant 이전의 단순한 방식(그룹마다 scale 하나)입니다.

2.2 자주 보는 이름들

⚠️ 크기는 파라미터 × 비트 ÷ 8에 그룹 scale과 "중요한 층은 높은 비트로" 몫이 더해진 어림 입니다(10차시 2.2). 정확한 값은 파일 크기 로 확인합니다. IQ4_XS 같은 IQ 계열 이름도 보이는데, 더 정교한 저비트 방식입니다(세부는 llama.cpp 문서 확인).

---

3. llama.cpp — GGUF를 실행하는 엔진

llama.cpp — [추론 엔진]인데, [ C/C++로 작성되어 GPU 없이 CPU만으로도, 또는 GPU와 CPU를 섞어서도 GGUF 모델을 실행한다 ]는 점에서 GPU · Python 환경을 전제로 하는 Transformers · vLLM과 구별된다.

설치는 공식 저장소의 README(미리 빌드된 파일 또는 CUDA 옵션으로 직접 빌드)를 따릅니다. 시스템 전체에 영향을 주는 CUDA 설치가 필요하면 실행 전 설명을 받고 승인 합니다(README 9장).

3.1 두 개의 명령

# 대화형으로 한 번 실행
llama-cli -m ./Qwen3-8B-Q4_K_M.gguf -ngl 99 -c 8192

# 서버로 띄우기 (OpenAI 호환 API 제공)
llama-server -m ./Qwen3-8B-Q4_K_M.gguf -ngl 99 -c 8192 --port 8080

🔍 읽는 포인트

llama-server를 띄우면 http://localhost:8080/v1/chat/completions가 열립니다. 7차시의 Ollama(11434), 19차시의 vLLM(8000)과 같은 OpenAI 호환 형식 입니다.

앞으로 다시 만납니다 — 20차시에서 같은 클라이언트 코드로 base_url만 바꿔 셋을 갈아 끼웁니다. README 5.1의 축 ② 추상 ↔ 구상 입니다. "OpenAI 호환 API"라는 약속(포트) 하나에 llama.cpp · Ollama · vLLM이라는 구현(어댑터) 이 각각 꽂힙니다. 약속만 지키면 구현은 갈아 끼울 수 있습니다(README 7장 문장 3).

---

4. ⭐ CPU · GPU 혼합 추론 — VRAM ↔ RAM

4.1 정의와 위치

CPU · GPU 혼합 추론 (부분 오프로드) — [추론 실행 방식]인데, [ 모델의 일부 층만 VRAM에 올리고 나머지 층은 RAM에 두어 CPU가 계산한다 ]는 점에서 전부 GPU에서 계산하는 방식, 전부 CPU에서 계산하는 방식과 구별된다.

-ngl 36 (전부)         -ngl 20 (일부)                      -ngl 0 (없음)
┌──────────┐          ┌──────────┐ ┌──────────┐          ┌──────────┐
│ VRAM     │          │ VRAM     │ │ RAM      │          │ RAM      │
│ 층 1~36  │          │ 층 1~20  │→│ 층 21~36 │          │ 층 1~36  │
│ GPU 계산 │          │ GPU 계산 │ │ CPU 계산 │          │ CPU 계산 │
└──────────┘          └──────────┘ └──────────┘          └──────────┘
 가장 빠름              토큰마다 이 경계를 건넘                가장 느림

(층 수 36은 Qwen3-8B 예시. 모델마다 다름)

4.2 왜 크게 느려지는가

15차시에서 자세히 보지만, Decode(2차시 4절)는 토큰 하나마다 가중치 전체를 메모리에서 읽는 메모리 병목 작업입니다. 그러면 속도는 가장 느린 메모리 가 정합니다.

⭐ RAM 쪽이 열 배 이상 좁은 길 입니다. 층의 1/3만 RAM에 있어도, 토큰마다 그 1/3을 좁은 길로 읽느라 전체 속도가 RAM 쪽에 끌려갑니다. "조금 넘쳤으니 조금 느리겠지"가 아니라 크게 느려지는 이유입니다.

컴퓨터의 스왑 과 같은 구조입니다.

스왑 (swap) — [운영체제의 메모리 관리 방식]인데, [ RAM이 모자랄 때 디스크의 일부를 메모리인 것처럼 빌려 쓴다 ]는 점에서 RAM만 쓰는 정상 상태와 구별된다. 디스크는 RAM보다 훨씬 느리므로, 스왑을 많이 쓰기 시작하면 컴퓨터 전체가 멈춘 것처럼 느려집니다.

오프로드는 VRAM이 모자라 RAM을 쓰는 것이고, 스왑은 RAM이 모자라 디스크를 쓰는 것입니다. 축 ①(빠르지만 작은 쪽 ↔ 크지만 느린 쪽)이 한 칸씩 자리를 옮겨 반복 됩니다.

4.3 그래도 쓰는 경우

4.4 Ollama에서 보이는 모습

Ollama도 내부적으로 GGUF와 llama.cpp 계열 엔진을 씁니다. Ollama는 -ngl을 자동으로 정하고, 결과를 ollama ps의 PROCESSOR 열에 보여줍니다.

💡 Ollama에도 GPU 층 수를 직접 정하는 옵션(num_gpu)이 있으나 동작은 버전에 따라 다르니 공식 문서를 확인하세요. 대개는 자동 결정에 맡기고 PROCESSOR 열만 감시 하는 편이 안전합니다.

---

5. Ollama와 GGUF, 그리고 경량 LLM

5.1 GGUF 파일을 Ollama로 가져오기

Hugging Face에서 받은 GGUF 파일을 Ollama 모델로 등록할 수 있습니다. 8차시의 Modelfile과 같은 모양입니다.

# Modelfile
FROM ./Qwen3-8B-Q4_K_M.gguf
PARAMETER num_ctx 8192
PARAMETER temperature 0.2

ollama create munuibot-q4 -f Modelfile
ollama show munuibot-q4 --modelfile    # 템플릿 · 파라미터가 제대로 들어갔는지 확인

🔍 읽는 포인트 : FROM 뒤가 태그 이름(qwen3:8b)이 아니라 파일 경로 입니다. 폐쇄망에서는 이 방식이 ollama pull 대신 쓰는 반입 경로가 됩니다.

⚠️ 채팅 템플릿이 제대로 안 들어가면 모델이 대화 형식을 못 알아듣고 이상한 말을 이어 붙입니다. ollama show --modelfile로 TEMPLATE 부분을 확인하게 하세요.

5.2 경량 LLM — 작은 모델이 맡는 자리

경량 LLM — [언어 모델]인데, [ 1~4B 정도로 작아 저사양 GPU나 CPU에서도 돌아간다 ]는 점에서 8B 이상 중형 모델과 구별된다. ⚠️ 크기(파라미터 수)는 "얼마나 무거운가"의 축이지 "우리 업무를 얼마나 잘하는가"의 축이 아닙니다. 큰 모델이 대체로 더 많은 일을 잘하지만, 업무가 좁고 정해져 있으면 작은 모델로 충분할 수 있습니다. 어느 쪽인지는 평가셋이 정합니다.

⭐ 흔히 쓰는 실전 조합 은 작은 모델이 쉬운 일을 먼저 처리하고, 무거운 일만 큰 모델에 넘기는 구조입니다. 문의봇으로 옮기면 "경량 모델이 분류 · 추출 → 8B 모델이 답변 초안" 이라는 두 단 구조를 후보로 둘 수 있습니다. 경량 모델은 CPU에서 돌려 GPU의 KV 캐시 자리를 아끼는 선택도 가능합니다. 채택 여부는 16차시 결정 절차에서 정합니다.

---

6. 실습 — 맡기고 검수하기

지시

목표: 같은 GGUF 모델을 -ngl 값만 바꿔 실행하며 속도와 메모리 변화를 관찰한다.
맥락: llama.cpp 공식 저장소 README의 설치 방법을 따르고, 설치 방법(미리 빌드/직접 빌드)과 버전을 먼저 보고해.
      CUDA나 드라이버를 새로 설치해야 하면 실행하지 말고 계획만 보고해(내가 승인).
모델: Hugging Face에서 Qwen3-8B의 Q4_K_M GGUF 파일(저장소 주소를 보고에 포함).
작업:
 1. GGUF 메타데이터에서 층 수, 컨텍스트 길이, 채팅 템플릿 존재 여부를 출력.
 2. -c 4096 고정, 같은 프롬프트, 출력 200토큰 고정으로 -ngl 0, 12, 24, 99 각각 실행.
    (llama.cpp에 포함된 벤치마크 도구가 있으면 써도 됨. 옵션은 --help로 확인)
 3. 각 실행마다 nvidia-smi memory.used와 생성 속도(토큰/초)를 기록. 워밍업 1회 버리고 3회 중앙값.
보고 형식:
| -ngl | GPU 층/전체 층 | nvidia-smi used(GB) | 프롬프트 처리 토큰/초 | 생성 토큰/초 |
추측하지 말고 실행 명령과 출력 원문을 붙여.

받을 증거

• 설치 방법 · 버전 출력, GGUF 저장소 주소
• 메타데이터 출력 (층 수가 보이는 부분)
• -ngl별 실행 명령과 출력 원문, nvidia-smi 출력

내가 직접 볼 것

---

부록 A. 스스로 확인하기

부록 B. 자주 하는 실수

부록 C. NotebookLM 복습 프롬프트

이 12차시 노트만 근거로 6문제를 내줘. 비전공자 기준으로.
"GGUF와 safetensors의 차이", "Q4_K_M 이름 읽기", "-ngl과 CPU·GPU 혼합 추론이 느린 이유", "경량 LLM의 쓰임새"는 반드시 포함해줘.
답은 내가 답한 다음에 채점하고, 틀린 이유를 노트의 절 번호를 근거로 설명해줘.