llama.cpp 를 이용해 huggingface 모델을 GGUF 형태로 변환하기

개요

LM Studio 는 LLM 챗봇 모델들을 로컬 머신에서 inference 할수 있게 해주는 유용한 프로그램으로, 원하는 모델을 다운 받아 ChatGPT 와 비슷한 형태로 채팅을 할수 있도록 하는 프로그램이다. 이 프로그램은 llama.cpp 기반으로 만들어졌으며, 따라서 inference 할 모델이 GGUF 확장자를 가진 파일이어야 하는 제약조건이 있다. 본 글에서는 huggingface 에 올라온 모델들 중 아직 GGUF 변환이 되지 않은 모델을 llama.cpp 를 사용해 GGUF 형식으로 바꿔서 LM Studio 에서 사용할수 있도록 만든다.

0. llama.cpp setup 하기

0-1. 공식 깃허브에서 로컬로 clone 해오기

git clone https://github.com/ggerganov/llama.cpp.git
cd llama.cpp # clone 한 디렉토리로 이동하기

0-1.a. 이미 clone 및 build 가 완료된 경우, pull 땡겨서 최신 버전으로 만들어준다. (새로운 모델 구조 지원)

git pull -p

0-1.b. 그러면 git pull 할때 마다 매번 build (make) 를 새로 해줘야 하는가?

아니다. quantize.cpp 또는 convert-pth-to-ggml.py 파일이 수정된 경우가 아니라면 새로 할 필요는 없다고 한다. 자세한 답변은 공식 discussion 에 나와있다.

$\rightarrow$ a 를 진행한 경우 1. 로 건너뛴다.

0-2. 필요 패키지 설치하기

pip install -r requirements.txt

• 여느때와 같이 필수패키지를 설치한다.

0-3. 빌드 하기

llama.cpp 를 사용하기 위해서는 필수적으로 build 를 먼저 해주어야 한다. 여기서는 Linux 계열 OS (WSL 포함) 를 사용하고, 머신에 Nvidia GPU (Cuda 지원) 이 장착되있다는 가정 하에 진행한다.

make LLAMA_CUBLAS=1

• Cuda 의 cuBLAS 기반 빌드이며 make 를 사용한다.
• GPU 유무, OS 등의 요인에 따라 서로 다른 명령어를 사용해야하므로, 자세한 정보는 공식 깃허브의 readme 를 참고하면 된다.

1. Huggingface 모델 스냅샷을 로컬 컴퓨터로 다운로드 하기

1-1. 필요한 패키지 import 하기

import os
from huggingface_hub import snapshot_download

1-2. 모델명 및 저장 디렉토리 이름 선언하기

여기서는 한국어를 가장 잘하는 모델중 하나로 알려진 Orion-14B-Chat 모델을 가지고 설명한다.

MODEL_ID = "OrionStarAI/Orion-14B-Chat"
MODEL_NAME = MODEL_ID.split('/')[-1] # Orion-14B-Chat

1-3. 스냅샷 다운로드 하기

snapshot_download(repo_id=MODEL_ID, local_dir=MODEL_NAME, local_dir_use_symlinks=False, revision="main")

• 여기서 모델 스냅샷 (config.json, tokenizer.model 등 huggingface 모델 페이지의 Files and versions 에 있는 파일들) 은 현재 디렉토리 . 산하의 Orion-14B-Chat 폴더에 저장된다.

2. 저장된 모델을 GGUF 형태로 변환하기

2-1. 변환하는 명령어 실행하기

# python llama.cpp/convert-hf-to-gguf.py {스냅샷 저장한 폴더 위치} --outfile {내보낼 gguf 모델 위치}.gguf

python llama.cpp/convert-hf-to-gguf.py ./Orion-14B-Chat --outfile ./Orion-14B-Chat.gguf

• 빌드된 llama.cpp 폴더 내부의 convert-hf-to-gguf.py 파일을 파이썬으로 실행한다.
• 만약 에러가 뜨는 경우 현재 변환하고자 하는 모델 아키텍쳐 (LlamaForCausalLM 같은 huggingface transformers 에 구현된 모델 구조) 가 아직 llama.cpp 에서는 지원되지 않을 가능성이 높은데, 이때는 지원될때까지 기다리거나 코드 직접 손봐서 공식 깃허브에 직접 contribution 해야한다.

3. GGUF 로 변환된 모델을 양자화(Quantization 하기)

변환한 모델의 크기가 너무 커서 본인 하드웨어의 RAM or VRAM 에 올라가지 못할것 같다면, 양자화를 시도해서 크기를 줄여보자.

3-1. 양자화 명령 실행하기

# ./llama.cpp/quantize {GGUF 파일 위치} {양자화된 GGUF 파일 위치} {양자화 방식}
./llama.cpp/quantize ./Orion-14B-Chat.gguf ./orion-14b-chat.Q5_K_S.gguf q5_k_s

• 앞에서 변환했던 현재 디렉토리 . 내의 Orion-14B-Chat.gguf 모델 파일을 5bit int 로 양자화해서 orion-14b-chat.Q5_K_S.gguf 라는 이름으로 저장하는 명령어
• 실제로 Orion-14B-Chat 의 기존 GGUF 파일 크기는 29GB 인데, 5bit 양자화하면 10GB 수준으로 크기가 33% 수준 까지 감소한다.
• 양자화 방식은 (int) 2bit 부터 6bit 까지 총 9 개의 옵션으로 존재한다.
  • Q2_K
  • Q3_K_S
  • Q3_K_M
  • Q3_K_L
  • Q4_K_S
  • Q4_K_M
  • Q5_K_S
  • Q5_K_M
  • Q6_K
• bit 를 많이 잘라낼수록 모델 크기가 감소하고 추론 속도가 빨라지지만, 모델이 제 성능을 발휘하기 힘들다.
• 한 블로그글에 따르면 Q5_K_M 이 가장 적절하며, 그 이유는 기존 모델의 성능을 가장 잘 지켜냈기 때문이라고 한다.
• 옵션 별 비교는 공식 깃허브의 k-quants PR 에 자세히 설명되어있다.

이제 모델크기를 줄였으니 LM Studio 에서 사용해볼수 있게되었다.

Appendix

출처

• ggerganov/llama.cpp
• Quantize Llama models with GGUF and llama.cpp
• OrionStartAI/Orion