GGUF 모델 포맷 완벽 이해

GGUF 모델 포맷 완벽 이해#

"Hugging Face에서 다운로드한 30GB짜리 모델, 어떻게 내 노트북에서 돌릴 수 있을까?"

AI, 특히 LLM(Large Language Model)에 입문한 개발자라면 누구나 한 번쯤 이런 고민을 해봤을 것입니다. Hugging Face는 수많은 최신 모델들의 보고이지만, 대부분은 PyTorch나 TensorFlow와 같은 대규모 프레임워크를 기반으로 하며, 여러 개의 파일(모델 가중치, 설정 파일, 토크나이저 등)로 흩어져 있습니다. 이를 그대로 가져와 로컬 환경, 특히 GPU가 없거나 VRAM이 부족한 환경에서 실행하는 것은 거의 불가능에 가깝습니다.

이때 혜성처럼 등장한 것이 바로 Llama.cpp와 그 심장부라 할 수 있는 GGUF(Georgi Gerganov Universal Format) 포맷입니다. GGUF는 복잡하고 분산된 모델 파일들을 단 하나의 실행 가능한 파일로 압축해주는, 마치 LLM계를 위한 'MP3'나 'ZIP' 파일과도 같은 존재입니다.

이번 챕터에서는 로컬 AI 생태계의 표준으로 자리 잡은 GGUF 포맷의 모든 것을 파헤쳐 봅니다. GGUF가 왜 중요한지, 그 내부 구조는 어떻게 생겼는지, 그리고 가장 중요한, Hugging Face에 있는 수많은 모델들을 어떻게 내 손으로 직접 GGUF로 변환할 수 있는지 실전 예제를 통해 완벽하게 마스터하게 될 것입니다. 이 챕터를 끝내고 나면, 여러분은 더 이상 다른 사람이 만들어둔 GGUF 파일에 의존하지 않고, 원하는 어떤 모델이든 Llama.cpp 환경에 맞게 직접 '요리'할 수 있는 능력을 갖추게 될 것입니다.

---

1. GGUF의 구조와 중요성: 왜 우리는 GGUF에 열광하는가?#

GGUF를 단순히 '파일 포맷'이라고만 생각하면 그 중요성을 놓치기 쉽습니다. GGUF는 Llama.cpp 프로젝트의 철학이 담긴 결과물이며, 로컬 AI가 실용적으로 사용될 수 있게 만든 핵심 기술입니다.

1.1 GGUF 이전의 시대: GGML, GGMF, GGJT의 혼돈#

GGUF는 하루아침에 탄생하지 않았습니다. Llama.cpp 프로젝트 초기에는 여러 버전의 포맷이 존재하며 약간의 혼란을 야기했습니다. 이 역사를 이해하면 GGUF가 해결하고자 했던 문제가 무엇인지 명확히 알 수 있습니다.

1. GGML (Georgi Gerganov Machine Learning library): Llama.cpp의 기반이 되는 C 라이브러리의 이름이자, 가장 원시적인 모델 포맷의 이름이었습니다. 이 시기에는 정해진 표준 없이, 모델 구조가 바뀔 때마다 포맷도 함께 바뀌어 호환성 문제가 심각했습니다.
2. GGMF (GGML Model File): 모델 파일에 '매직 넘버(Magic Number)'를 도입하여 최소한의 파일 식별이 가능하게 한 초기 버전입니다.
3. GGJT (GGML Just Tensors): 이후 등장한 포맷으로, 여러 버전의 모델을 지원하기 위한 나름의 체계를 갖추었지만, 치명적인 단점이 있었습니다. 바로 확장성 부족과 메타데이터 부재입니다. 모델에 새로운 정보(예: 새로운 RoPE 스케일링 방식)를 추가하려면 포맷 자체를 깨뜨리는 변경(Breaking Change)이 필요했습니다. 이는 구버전 Llama.cpp에서는 새 모델을, 신버전 Llama.cpp에서는 구 모델을 실행할 수 없는 '파편화' 문제를 낳았습니다. 또한, 토크나이저(Tokenizer) 파일(.model)을 항상 별도로 관리해야 하는 불편함도 있었습니다.

이러한 문제들을 해결하기 위해 완전히 새롭게 설계된 포맷이 바로 GGUF입니다.

1.2 GGUF의 핵심 철학 4가지#

GGUF는 다음과 같은 명확한 목표를 가지고 설계되었습니다.

1. 단일 파일 (Single File)의 완전성: GGUF의 가장 큰 특징은 모델 가중치, 모델 설정(하이퍼파라미터), 그리고 토크나이저 정보까지 모두 하나의 파일에 담는다는 것입니다. 더 이상 config.json, tokenizer.model, pytorch_model.bin 등 여러 파일을 신경 쓸 필요가 없습니다. GGUF 파일 하나만 있으면 어디서든 Llama.cpp를 통해 모델을 실행할 수 있습니다. 이는 배포와 관리를 극도로 단순화시켜 줍니다.
2. 확장성 (Extensibility)과 호환성 (Compatibility): GGUF는 유연한 Key-Value 형태의 메타데이터 저장 방식을 채택했습니다. 이는 마치 JSON처럼 새로운 정보를 얼마든지 추가할 수 있음을 의미합니다. 미래에 새로운 아키텍처나 기술이 등장하더라도, 포맷 자체를 변경할 필요 없이 새로운 메타데이터 키(Key)를 추가하기만 하면 됩니다. 덕분에 구버전 GGUF 파일도 최신 Llama.cpp에서 문제없이 실행되며, 하위 호환성이 보장됩니다.
3. 메모리 매핑 (mmap) 친화적 설계: Llama.cpp가 놀랍도록 빠른 로딩 속도와 낮은 RAM 사용량을 보여주는 비밀 중 하나는 바로 mmap입니다. mmap은 파일의 내용을 RAM에 전부 올리지 않고, 디스크에 있는 파일 자체를 메모리의 일부처럼 취급하는 운영체제 기술입니다. GGUF는 이 mmap을 효율적으로 사용할 수 있도록 데이터가 정렬(Alignment)되어 있어, 모델 로딩 시 필요한 부분만 즉시 메모리에 매핑하여 지연 시간을 최소화하고 RAM 사용을 최적화합니다. 예를 들어 70억(7B) 파라미터 모델을 로딩할 때, 수십 GB의 RAM이 필요 없이 단 몇 초 만에 로딩이 가능한 이유가 바로 이것입니다.
4. 사용자 편의성 (Ease of Use): GGUF는 모델에 대한 풍부한 정보를 담고 있습니다. 파일 이름만 보고는 알 수 없는 정보, 예를 들어 "이 모델은 어떤 아키텍처 기반이지?", "어떤 양자화 방식이 적용되었지?", "추천하는 프롬프트 템플릿은 무엇이지?" 와 같은 질문에 대한 답을 파일 내 메타데이터를 통해 확인할 수 있습니다.

1.3 GGUF 파일 구조 해부하기#

GGUF 파일의 내부를 개념적으로 들여다보면, 크게 네 부분으로 나눌 수 있습니다.

+-----------------------------------+
|            헤더 (Header)          |  <-- "GGUF" 매직 넘버, 버전 정보
+-----------------------------------+
|         메타데이터 (Metadata)     |  <-- Key-Value 저장소 (모델 정보, 토크나이저 등)
|           - 모델 아키텍처         |
|           - 하이퍼파라미터        |
|           - 토크나이저 어휘       |
|           - ... 등등              |
+-----------------------------------+
|         텐서 정보 (Tensor Info)   |  <-- 각 텐서의 이름, 모양, 타입, 위치 정보 목록
+-----------------------------------+
|          텐서 데이터 (Tensors)    |  <-- 실제 모델 가중치 (가장 큰 부분)
+-----------------------------------+

1. 헤더 (Header): 파일의 가장 앞부분에 위치하며, 이 파일이 GGUF 포맷임을 알리는 GGUF라는 고유한 '매직 넘버'와 GGUF 포맷의 버전 정보(v1, v2, v3...)를 담고 있습니다.
2. 메타데이터 (Metadata): GGUF의 핵심적인 유연성을 담당하는 부분입니다. 정해진 형식 없이 Key(문자열)와 Value(다양한 타입)의 쌍으로 수많은 정보를 저장합니다. Llama.cpp는 이 메타데이터를 읽어 모델을 어떻게 처리해야 할지 결정합니다.
   • 예시 메타데이터:
     • general.architecture: llama (이 모델은 Llama 아키텍처 기반임)
     • llama.context_length: 4096 (이 모델의 최대 컨텍스트 길이는 4096)
     • llama.embedding_length: 4096
     • llama.block_count: 32 (레이어 수)
     • tokenizer.ggml.model: llama
     • tokenizer.ggml.tokens: ["<unk>", "<s>", "</s>", ...] (토크나이저 어휘 목록)
     • tokenizer.ggml.scores: [-1000.0, -1000.0, ...] (각 토큰의 점수)
     • tokenizer.chat_template: {% for message in messages %}{% if message['role'] == 'user' %}{{ '### User:\n' + message['content'] + '\n\n' }}{% elif message['role'] == 'assistant' %}{{ '### Assistant:\n' + message['content'] + '\n\n' }}{% endif %}{% endfor %} (추천 채팅 템플릿)
3. 텐서 정보 (Tensor Info): 모델을 구성하는 모든 가중치 덩어리(텐서)들의 '목록' 또는 '색인'입니다. 각 텐서에 대해 다음과 같은 정보를 가집니다.
   • 이름: token_embd.weight, blk.0.attn_norm.weight, output.weight 등
   • 차원/모양 (Shape): [4096, 32000] 과 같은 형태
   • 타입 (Type): F32(32비트 부동소수점), F16(16비트), Q4_K_M(4비트 양자화) 등
   • 오프셋 (Offset): 파일 내에서 이 텐서의 실제 데이터가 시작되는 위치
4. 텐서 데이터 (Tensors): 파일의 대부분을 차지하는 실제 데이터 영역입니다. 모델의 '지능'이 담겨있는 수십억 개의 파라미터(가중치)가 바이너리 형태로 저장되어 있습니다. mmap을 위해 데이터 정렬(padding)이 적용되어 있습니다.

이처럼 GGUF는 단순한 파일 포맷을 넘어, 로컬 AI의 실행 환경을 단순화, 표준화, 최적화하는 핵심적인 역할을 수행합니다. 이제 이 강력한 GGUF 파일을 직접 만들어 볼 시간입니다.

---

2. 실전! convert.py로 나만의 GGUF 만들기#

이 섹션에서는 Hugging Face에 공개된 표준 모델을 GGUF 포맷으로 변환하는 전 과정을 단계별로 상세히 진행합니다. Llama.cpp 프로젝트에 포함된 convert.py 스크립트를 사용할 것입니다.

목표: 최근 좋은 성능으로 주목받고 있는 upstage/SOLAR-10.7B-Instruct-v1.0 모델을 GGUF로 변환하여 Llama.cpp에서 실행 가능한 상태로 만들기.

2.1 사전 준비: 환경 설정#

변환 작업을 위해서는 Llama.cpp 소스 코드와 Python 실행 환경이 필요합니다. Chapter 2에서 Llama.cpp 빌드를 완료했다면 대부분 준비가 되어있겠지만, 다시 한번 확인해 보겠습니다.

1. Llama.cpp 리포지토리 클론 (Clone)

아직 Llama.cpp 소스 코드가 없다면, Git을 사용해 클론합니다.

# 터미널 또는 Git Bash에서 실행
git clone https://github.com/ggerganov/llama.cpp.git
cd llama.cpp

이미 클론했다면, 최신 변경사항을 반영하기 위해 pull을 받아주는 것이 좋습니다.

cd llama.cpp
git pull

2. Python 가상 환경 생성 및 활성화

프로젝트별로 Python 라이브러리 의존성을 격리하는 것은 매우 좋은 습관입니다. venv를 사용해 가상 환경을 만듭니다.

# llama.cpp 디렉토리 안에서 실행
python -m venv venv  # 'venv'라는 이름의 가상 환경 생성

# Windows
.\venv\Scripts\activate

# macOS / Linux
source venv/bin/activate

이제 터미널 프롬프트 앞에 (venv)가 표시되며, 가상 환경이 활성화되었음을 의미합니다.

3. 필수 Python 라이브러리 설치

convert.py 스크립트는 torch, numpy, sentencepiece, huggingface-hub 등 여러 라이브러리를 필요로 합니다. requirements.txt 파일을 이용해 한 번에 설치할 수 있습니다.

# (venv)가 활성화된 상태에서 실행
pip install -r requirements.txt

설치 과정에서 수백 MB의 파일들이 다운로드될 수 있습니다. 시간이 다소 걸릴 수 있으니 잠시 기다려주세요.

2.2 1단계: Hugging Face 모델 다운로드#

GGUF로 변환할 원본 모델을 다운로드해야 합니다. 두 가지 방법이 있습니다.

방법 1: Git LFS (Large File Storage) 사용 (권장)

Git LFS는 대용량 파일을 Git으로 관리하기 위한 확장 기능입니다. 모델 저장소를 통째로 다운로드할 때 유용합니다.

먼저 Git LFS가 설치되어 있는지 확인하고, 설치되지 않았다면 설치합니다.

# git-lfs 설치 (대부분의 Linux 배포판)
sudo apt-get install git-lfs

# macOS (Homebrew 사용)
brew install git-lfs

# 설치 후 LFS 활성화
git lfs install

이제 모델 리포지토리를 클론합니다. upstage/SOLAR-10.7B-Instruct-v1.0 모델의 크기는 약 21GB이므로, 충분한 디스크 공간을 확보하세요.

# llama.cpp 와는 별도의 디렉토리에서 실행하는 것을 추천
# 예: D:\models 디렉토리
cd D:\models
git clone https://huggingface.co/upstage/SOLAR-10.7B-Instruct-v1.0

다운로드가 완료되면 SOLAR-10.7B-Instruct-v1.0 라는 디렉토리가 생성되고, 그 안에 모델 파일들이 위치하게 됩니다.

방법 2: Python 스크립트로 다운로드

Git LFS가 번거롭거나 특정 파일만 받고 싶을 때 유용한 방법입니다. huggingface-hub 라이브러리를 사용하면 간단한 스크립트로 모델을 다운로드할 수 있습니다.

# download_model.py 라는 이름으로 파일 저장
from huggingface_hub import snapshot_download

model_id = "upstage/SOLAR-10.7B-Instruct-v1.0"
local_dir = "./" + model_id.split('/')[-1] # ./SOLAR-10.7B-Instruct-v1.0 디렉토리 생성

print(f"Downloading model {model_id} to {local_dir}...")

snapshot_download(
    repo_id=model_id,
    local_dir=local_dir,
    local_dir_use_symlinks=False, # Windows 호환성을 위해 False로 설정
    resume_download=True
)

print("Download complete!")

이 스크립트를 실행하면 현재 디렉토리에 SOLAR-10.7B-Instruct-v1.0 폴더가 생기고 모델이 다운로드됩니다.

python download_model.py

다운로드가 완료된 디렉토리의 구조를 살펴보면 다음과 같은 파일들이 보일 것입니다.

SOLAR-10.7B-Instruct-v1.0/
├── config.json
├── generation_config.json
├── pytorch_model-00001-of-00005.bin
├── pytorch_model-00002-of-00005.bin
├── pytorch_model-00003-of-00005.bin
├── pytorch_model-00004-of-00005.bin
├── pytorch_model-00005-of-00005.bin
├── pytorch_model.bin.index.json
├── special_tokens_map.json
├── tokenizer.json
├── tokenizer_config.json
└── ...

이제 GGUF 변환을 위한 재료가 모두 준비되었습니다.

2.3 2단계: convert.py 스크립트 실행하기#

드디어 핵심 단계입니다. llama.cpp 디렉토리로 돌아가 convert.py 스크립트를 실행해 봅시다.

가장 기본적인 변환 명령어의 구조는 다음과 같습니다.

python convert.py [모델_경로] --outfile [출력_GGUF_파일명] --outtype [출력_타입]

• [모델_경로]: 방금 다운로드한 Hugging Face 모델 파일이 있는 디렉토리 경로입니다.
• --outfile [출력_GGUF_파일명]: 생성될 GGUF 파일의 이름과 경로를 지정합니다. 지정하지 않으면 기본값으로 생성됩니다.
• --outtype [출력_타입]: 출력할 GGUF 파일의 텐서 데이터 타입을 지정합니다. 이것이 매우 중요합니다.

outtype의 선택: f32 vs f16 vs q8_0

• f32 (32-bit Float): 원본 모델의 정밀도를 그대로 유지합니다. 파일 크기가 가장 크고, 특별한 이유가 없다면 거의 사용하지 않습니다.
• f16 (16-bit Float / Half-precision): 정밀도를 절반으로 줄입니다. 파일 크기가 f32의 절반이 되며, 성능 손실은 거의 없습니다. 대부분의 양자화(Quantization) 작업은 f16 GGUF 파일을 기반으로 이루어지기 때문에, 변환의 첫 단계로는 f16을 선택하는 것이 표준입니다.
• q8_0 (8-bit Quantized): 8비트로 양자화합니다. 파일 크기가 f16의 절반이 됩니다. convert.py에서 바로 양자화까지 진행할 수 있지만, 보통은 quantize 도구를 따로 사용하는 것이 일반적입니다. (이는 Chapter 4에서 자세히 다룹니다.)

실행 명령어

이제 SOLAR 모델을 f16 타입의 GGUF로 변환해 보겠습니다.

# llama.cpp 디렉토리에서 실행
# (venv) 가상 환경이 활성화된 상태여야 함

# 모델 경로와 출력 파일 경로를 자신의 환경에 맞게 수정하세요.
# 예시: 모델이 D:\models\SOLAR-10.7B-Instruct-v1.0 에 있고,
#       출력 파일을 D:\models\gguf 에 저장하고 싶을 경우

python convert.py ^
    D:\models\SOLAR-10.7B-Instruct-v1.0 ^
    --outfile D:\models\gguf\SOLAR-10.7B-Instruct-v1.0.f16.gguf ^
    --outtype f16

# macOS / Linux 의 경우
python convert.py \
    /path/to/your/models/SOLAR-10.7B-Instruct-v1.0 \
    --outfile /path/to/your/models/gguf/SOLAR-10.7B-Instruct-v1.0.f16.gguf \
    --outtype f16

(Windows의 ^, macOS/Linux의 \는 긴 명령어를 여러 줄로 나눠 쓰기 위한 라인 연속 문자입니다.)

주의: 변환 과정은 상당한 양의 RAM을 사용합니다. 모델 파라미터 수에 비례하여 메모리가 필요하며, 10.7B 모델의 경우 최소 32GB 이상의 RAM을 권장합니다. RAM이 부족할 경우 시스템이 멈추거나 변환에 실패할 수 있습니다. (메모리가 부족한 경우를 위한 팁은 3.3 섹션에서 다룹니다.)

2.4 3단계: 변환 과정 로그 살펴보기#

명령어를 실행하면 터미널에 다양한 로그가 출력됩니다. 이 로그를 이해하면 변환 과정을 더 깊이 파악할 수 있습니다.

Loading model file D:\models\SOLAR-10.7B-Instruct-v1.0\pytorch_model-00001-of-00005.bin
Loading model file D:\models\SOLAR-10.7B-Instruct-v1.0\pytorch_model-00002-of-00005.bin
...
Loading model file D:\models\SOLAR-10.7B-Instruct-v1.0\pytorch_model-00005-of-00005.bin
...
params = Params(n_vocab=32000, n_embd=4096, n_layer=48, n_ctx=4096, n_ff=14336, n_head=32, n_head_kv=8, n_experts=None, n_experts_used=None, f_norm_eps=1e-05, rope_scaling_type=None, f_rope_freq_base=10000.0, f_rope_scale=None, n_orig_ctx=None, rope_finetuned=None, ftype=<GGMLFileType.MostlyF16: 1>, path_model=WindowsPath('D:/models/SOLAR-10.7B-Instruct-v1.0'))
...
gguf: This GGUF file is for Little Endian only
gguf: LLaMAv2Tokenizer
gguf: tokenizer.ggml.model: llama
...
gguf: writing 491 key-value pairs
gguf: writing 491 tensors
[ 1/491] Writing tensor token_embd.weight, shape (4096, 32000), type F16
[ 2/491] Writing tensor blk.0.attn_q.weight, shape (4096, 4096), type F16
[ 3/491] Writing tensor blk.0.attn_k.weight, shape (4096, 1024), type F16
...
[491/491] Writing tensor output.weight, shape (4096, 32000), type F16
gguf: model successfully exported to D:\models\gguf\SOLAR-10.7B-Instruct-v1.0.f16.gguf
gguf: model size =  20.03 GiB
gguf: total size =  20.03 GiB

• Loading model file ...: 분할된 .bin 파일들을 순차적으로 읽어들입니다.
• params = Params(...): config.json 파일을 분석하여 모델의 주요 하이퍼파라미터(어휘 수, 임베딩 차원, 레이어 수 등)를 확인합니다.
• gguf: LLaMAv2Tokenizer: 사용된 토크나이저의 종류를 식별합니다.
• gguf: writing ... key-value pairs: GGUF의 메타데이터 부분을 기록합니다. 모델 아키텍처, 토크나이저 정보 등이 여기에 포함됩니다.
• gguf: writing ... tensors: 텐서 정보와 실제 텐서 데이터를 기록하는 과정입니다. 각 텐서의 이름, 모양, 타입이 표시됩니다. 이 과정이 가장 오래 걸립니다.
• gguf: model successfully exported ...: 변환이 성공적으로 완료되었음을 알립니다. 최종 파일 크기도 함께 보여줍니다.

원본 모델 파일 크기의 합이 약 21GB였는데, f16으로 변환된 GGUF 파일은 약 20GB로 약간 줄어든 것을 볼 수 있습니다. (정밀도가 절반이 되었는데 왜 파일 크기는 절반이 아닐까요? 원본 PyTorch 모델은 이미 bfloat16이나 float16으로 저장되어 있는 경우가 많기 때문입니다.)

2.5 4단계: 변환된 GGUF 모델 테스트하기#

이제 우리의 노동의 결실을 확인할 시간입니다. Chapter 2에서 빌드한 Llama.cpp의 main 프로그램을 사용하여 방금 생성한 GGUF 파일이 잘 작동하는지 테스트해 봅시다.

# llama.cpp 디렉토리에서 실행

# Windows (PowerShell)
.\main.exe -m D:\models\gguf\SOLAR-10.7B-Instruct-v1.0.f16.gguf -n 128 -p "### User:\nLlama.cpp에 대해 설명해주세요.\n\n### Assistant:\n" --color

# macOS / Linux
./main -m /path/to/your/models/gguf/SOLAR-10.7B-Instruct-v1.0.f16.gguf -n 128 -p "### User:\nLlama.cpp에 대해 설명해주세요.\n\n### Assistant:\n" --color

• -m [파일경로]: 사용할 GGUF 모델 파일을 지정합니다.
• -n 128: 생성할 최대 토큰 수를 128개로 제한합니다.
• -p "...": 모델에 전달할 초기 프롬프트입니다. SOLAR-Instruct 모델은 ### User: ... ### Assistant: 와 같은 템플릿을 사용하므로, 이에 맞춰 프롬프트를 제공했습니다.
• --color: 출력에 색상을 입혀 가독성을 높입니다.

명령어를 실행하면 모델이 로딩된 후, 프롬프트에 이어지는 답변을 생성하기 시작할 것입니다. CPU만으로 실행한다면 토큰 생성 속도가 다소 느릴 수 있지만, 에러 없이 텍스트가 출력된다면 성공적으로 GGUF 파일을 만든 것입니다!

---

3. 심화 과정: 다양한 변환 옵션과 트러블슈팅#

convert.py는 기본적인 변환 외에도 다양한 옵션을 제공합니다. 몇 가지 유용한 옵션들과 흔히 겪는 문제들의 해결책을 알아봅시다.

3.1 유용한 추가 옵션들#

• --vocab-type [TYPE]: 대부분의 최신 모델은 토크나이저 타입을 자동으로 감지하지만, 간혹 수동으로 지정해야 할 때가 있습니다. 예를 들어 SentencePiece 모델의 경우 --vocab-type spm을, BPE 토크나이저의 경우 --vocab-type bpe를 사용할 수 있습니다.
• --pad-vocab: 토크나이저의 어휘(vocabulary) 크기를 특정 숫자의 배수(보통 32 또는 64)로 맞추기 위해 더미(dummy) 토큰을 추가합니다. 일부 GPU 아키텍처에서 어휘 크기가 특정 값의 배수일 때 약간의 성능 향상을 가져올 수 있다고 알려져 있습니다. 큰 영향은 없지만, 시도해 볼 만한 옵션입니다.

python convert.py [모델_경로] --outfile [출력_파일] --outtype f16 --pad-vocab

• --use-temp-cache: RAM이 부족할 때 매우 유용한 옵션입니다. 이 옵션을 사용하면 변환 과정에서 텐서들을 RAM에 모두 올리는 대신, 임시 파일(cache)에 기록했다가 최종 GGUF 파일을 만들 때 사용합니다. 속도는 훨씬 느려지지만, 16GB RAM과 같은 저사양 환경에서도 대용량 모델 변환을 시도해 볼 수 있게 해줍니다.

python convert.py [모델_경로] --outfile [출력_파일] --outtype f16 --use-temp-cache

• --vocab-dir [경로]: 드물지만, tokenizer.model이나 vocab.json 파일이 모델 가중치와 다른 디렉토리에 있는 경우, 해당 파일이 위치한 경로를 직접 지정해 줄 수 있습니다.

3.2 흔히 발생하는 문제와 해결 방법 (Q&A)#

Q1: ModuleNotFoundError: No module named 'torch' 와 같은 에러가 발생합니다.

A1: Python 가상 환경이 제대로 활성화되지 않았거나, 필수 라이브러리가 설치되지 않은 경우입니다.

1. source venv/bin/activate (macOS/Linux) 또는 .\venv\Scripts\activate (Windows) 명령으로 가상 환경을 활성화했는지 확인하세요.
2. pip install -r requirements.txt 명령을 다시 실행하여 모든 라이브러리가 정상적으로 설치되었는지 확인하세요.

Q2: 변환 도중 컴퓨터가 멈추거나 'Killed' 메시지가 표시되며 프로세스가 종료됩니다.

A2: 전형적인 메모리 부족(Out of Memory) 문제입니다. 시스템의 RAM이 모델을 변환하기에 부족한 경우입니다.

1. 가장 간단한 해결책은 위에서 설명한 --use-temp-cache 옵션을 추가하는 것입니다. 변환 속도는 현저히 느려지지만, RAM 사용량을 크게 줄일 수 있습니다.
2. 실행 중인 다른 프로그램(웹 브라우저, Docker 등)을 모두 종료하여 최대한의 RAM을 확보하세요.
3. Linux 시스템의 경우, SWAP 공간을 늘리는 것도 임시적인 해결책이 될 수 있습니다.

Q3: NotImplementedError: Architecture '[모델 아키텍처]' not supported! 에러가 발생합니다.

A3: convert.py 스크립트가 해당 모델의 아키텍처를 아직 지원하지 않는다는 의미입니다.

1. 먼저 git pull을 통해 Llama.cpp 리포지토리를 최신 버전으로 업데이트하세요. Llama.cpp 커뮤니티는 매우 활발하여 새로운 아키텍처 지원이 빠르게 추가됩니다.
2. 만약 최신 버전에서도 지원하지 않는다면, 해당 모델은 아직 Llama.cpp에서 사용할 수 없는 것입니다. Llama.cpp의 GitHub 이슈(Issues)나 풀 리퀘스트(Pull Requests)를 확인하여 지원 계획이 있는지 찾아볼 수 있습니다.

Q4: GGUF로 변환은 성공했는데, main 프로그램으로 실행하니 이상한 글자(gibberish)만 나옵니다.

A4: 여러 원인이 있을 수 있지만, 가장 흔한 경우는 토크나이저 변환 문제입니다.

1. 변환 시 사용한 convert.py 스크립트와 모델을 실행하는 main 프로그램의 Llama.cpp 버전이 너무 크게 차이 나지 않는지 확인하세요. 가급적 같은 시점의 버전을 사용하는 것이 안전합니다.
2. --vocab-type 옵션을 명시적으로 지정하여 다시 변환을 시도해 보세요.
3. 모델의 Hugging Face 페이지에서 특별한 프롬프트 템플릿을 요구하는지 확인하고, -p 옵션에 정확한 템플릿을 적용하여 테스트해 보세요.