llama.cpp로 모델을 GGUF로 변환하는 방법은 무엇입니까?

언어 선택:

🇺🇸en 🇩🇪de 🇫🇷fr 🇯🇵ja 🇨🇳zh 🇪🇸es 🇧🇷pt 🇸🇦ar 🇰🇷ko

빠른 답변

Hugging Face 형식의 모델 디렉터리에 대해 llama.cpp의 변환 스크립트를 실행하고, f16(완전 정밀도)이나 q4_k_m 같은 양자화 형식 등 출력 유형을 지정하십시오. 스크립트는 모델의 가중치와 설정을 읽어 단일 .gguf 파일로 기록하며, 이 파일은 llama.cpp, Ollama, LM Studio에서 직접 불러올 수 있습니다.

▸변환 전에 원본 모델은 Hugging Face 형식(safetensors 또는 PyTorch 체크포인트)이어야 합니다
▸출력 유형을 선택하십시오. 완전 정밀도에는 f16/f32를, 변환과 축소를 한 번에 하려면 양자화 유형을 선택하십시오
▸f16 변환 후 별도로 양자화하는 방식이 변환 중 양자화하는 것보다 더 세밀한 제어가 가능합니다

업데이트: 2026년 7월 15일

Technique & Concept Explainers기초 이해

핵심 요점

✓GGUF 변환은 Hugging Face 형식 모델의 가중치와 메타데이터를 읽어 이식성이 높은 단일 .gguf 파일로 기록하는 작업입니다
✓여러 양자화 수준을 시도할 계획이라면 먼저 f16/f32로 변환하십시오. 이미 양자화된 변환 결과에서 다시 양자화하면 완전 정밀도에서 양자화하는 것보다 품질 손실이 더 큽니다
✓변환 시 선택한 출력 유형이 파일 크기와 추론 품질을 동시에 결정합니다. 둘 다 얻을 수는 없습니다
✓대부분의 변환 오류는 변환 스크립트 자체보다는 호환되지 않거나 불완전한 원본 모델 디렉터리에서 비롯됩니다

변환 과정

변환은 실무적으로 세 단계로 이루어집니다. 원본 모델을 준비하고, 출력 유형을 지정해 변환 스크립트를 실행하고, 완전 정밀도로 변환했다면 이후 양자화를 진행합니다.

▸**1. 원본 모델 준비:** 변환 스크립트는 모델의 가중치 파일(레거시 PyTorch `.bin` 체크포인트보다 safetensors 형식이 선호됨)과 설정 및 토크나이저 파일이 포함된 Hugging Face 형식 디렉터리를 필요로 합니다. 부분적으로 다운로드되었거나 수동으로 구성한 디렉터리에 토크나이저 파일이 빠져 있는 경우가 변환 실패의 가장 흔한 원인입니다.
▸**2. 출력 유형을 지정해 변환 스크립트 실행:** `python convert_hf_to_gguf.py --outtype f16` 명령은 완전 정밀도 GGUF 파일을 생성합니다. 양자화된 `--outtype`(예: `q8_0`)을 전달하면 변환과 동시에 한 단계로 양자화되지만, 먼저 f16으로 변환한 뒤 전용 양자화 도구로 별도로 양자화하는 것보다는 제어 수준이 낮습니다.
▸**3. 더 세밀한 제어를 위해 별도로 양자화(선택 사항이지만 권장):** f16 GGUF 파일에서 시작하여 llama.cpp의 양자화 도구를 실행하면, 동일한 완전 정밀도 소스로부터 여러 양자화 버전(예: q4_k_m, q5_k_m)을 생성할 수 있습니다. 이를 통해 매번 변환을 다시 실행하지 않고도 품질과 크기의 트레이드오프를 비교할 수 있습니다.

자주 발생하는 변환 오류

대부분의 변환 실패는 몇 가지 범주로 나뉘며, 거의 항상 스크립트 자체가 아니라 원본 모델에서 원인을 찾을 수 있습니다.

▸**인식되지 않는 아키텍처:** 변환 스크립트는 지원되는 모델 아키텍처의 내부 목록을 유지합니다. 매우 새롭거나 흔치 않은 아키텍처는 아직 지원되지 않을 수 있습니다. 모델 파일이 손상되었다고 단정하기 전에 도구의 현재 아키텍처 목록을 먼저 확인하십시오.
▸**토크나이저 파일 누락:** 변환에는 가중치 외에 토크나이저 설정도 필요합니다. 가중치 파일만 있고 토크나이저 파일이 없는 모델 디렉터리는 변환 도중에 실패합니다.
▸**파일 형식 불일치:** 레거시 PyTorch `.bin` 체크포인트는 도구 버전에 따라 safetensors로 변환하는 추가 단계가 필요할 수 있습니다. 이를 완전히 피하려면 이미 safetensors 형식으로 제공되는 모델을 다운로드하는 것이 좋습니다.
▸**변환 중 디스크 공간 또는 메모리 부족:** 변환은 기록하기 전에 완전 정밀도 모델을 메모리에 로드하므로, 모델의 완전 정밀도 크기에 해당하는 메모리와 함께 원본 파일과 출력 GGUF 파일을 동시에 담을 디스크 공간이 필요합니다.

자주 묻는 질문

변환 중에 양자화해야 합니까, 아니면 먼저 완전 정밀도로 변환해야 합니까?▾

여러 양자화 수준을 비교할 계획이라면 먼저 완전 정밀도(f16)로 변환하십시오. 동일한 f16 소스에서 나중에 별도로 양자화하는 방식이 변환 중에 원본 모델에서 직접 양자화하는 것보다 더 정확한 결과를 제공하며, 변환 단계를 반복하지 않고도 여러 양자화 버전을 만들 수 있습니다.

변환은 성공했는데 변환된 GGUF 파일이 Ollama나 LM Studio에서 로드되지 않는 이유는 무엇입니까?▾

변환이 성공했다고 해서 로드 도구가 해당 아키텍처나 GGUF 버전을 지원한다는 보장은 없습니다. 로드 도구의 버전이 최신인지 확인하십시오. GGUF 형식과 아키텍처 지원은 계속 발전하므로, 오래된 버전의 도구는 더 최신 변환 스크립트로 생성된 파일을 인식하지 못할 수 있습니다.

변환에는 디스크 공간이 얼마나 필요합니까?▾

원본 모델의 전체 크기와 출력 GGUF 파일의 크기를 동시에 확보해야 합니다. 완전 정밀도 변환의 경우, 진행 중에는 모델이 차지하는 공간이 대략 두 배가 됩니다. 양자화된 출력 파일은 더 작지만, 변환이 끝날 때까지는 원본 파일도 유지되어야 합니다.

이미 파인튜닝된 모델도 변환할 수 있습니까?▾

가능합니다. 파인튜닝된 가중치가 Hugging Face와 호환되는 표준 형식으로 저장되어 있다면, 변환 과정은 베이스 모델과 동일하게 파인튜닝된 모델에도 적용됩니다. 파인튜닝에 LoRA와 같은 어댑터 가중치를 사용하고 전체 가중치를 사용하지 않았다면, 먼저 어댑터를 베이스 모델에 병합한 다음 병합된 결과를 변환하십시오.