llama.cpp를 활용한 HuggingFace 모델 서빙 가이드

회사 프로젝트로 진행 중인 LLM을 팀원들과 함께 테스트하고 피드백을 받기 위해 llama.cpp를 도입하게 되었습니다. HuggingFace에서 파인튜닝한 모델을 GGUF 파일로 변환한 후 서버에 배포하는 과정에서 겪었던 시행착오를 정리해보았습니다.

1. 저장소 클론

가장 먼저 llama.cpp 저장소를 클론합니다.

git clone https://github.com/ggerganov/llama.cpp.git
cd llama.cpp

2. GGUF 파일 변환

2.1 변환 스크립트 위치 확인

클론한 레포지토리 내에서 convert_*.py 파일들이 있는 경로로 이동합니다. 총 4개의 변환 스크립트가 있는데, 각각 다른 용도로 사용됩니다.

2.2 HuggingFace 모델 변환

convert_hf_to_gguf.py를 사용하여 HuggingFace 모델을 GGUF 형식으로 변환합니다.

python convert_hf_to_gguf.py /path/to/merge_model \
  --outfile /save_path/to/gguf_model.gguf \
  --outtype f16

인자 설명:

• 첫 번째 인자: 변환할 HuggingFace 모델 경로
• --outfile: GGUF 파일 저장 경로
• --outtype: 출력 형식 (f32, f16, bf16, q8_0, q4_0, tq1_0, tq2_0, auto 지원)

2.3 LoRA 어댑터 처리

LoRA 어댑터만 있는 경우 두 가지 방법이 있습니다:

1. convert_lora_to_gguf.py 사용
2. merge_and_unload()로 어댑터를 원본 모델에 통합한 후 convert_hf_to_gguf.py을 사용해서 변환

3. Python 바인딩으로 사용하기

3.1 설치

pip install llama-cpp-python

3.2 사용 예제

from llama_cpp import Llama

llm = Llama(
    model_path="/path/to/gguf.gguf",
    chat_format="llama-2"
)

response = llm.create_chat_completion(
    messages=[
        {
            "role": "system", 
            "content": "You are an ai assistant who perfectly answer the question."
        },
        {
            "role": "user",
            "content": "What is the sum of the first 100 natural numbers? answer in a short form."
        }
    ]
)

print(response['choices'][0]['message']['content'])

⚠️ 주의사항: 현재 GPT-2와 Llama 토크나이저만 지원됩니다. Qwen 등 다른 토크나이저를 사용하는 모델은 Python 바인딩으로 사용할 수 없으므로 C++ 빌드 방식을 사용해야 합니다.

4. C++로 빌드하기

Python 바인딩이 지원되지 않는 경우, C++로 빌드하여 CLI 또는 서버 형태로 사용할 수 있습니다.

4.1 Visual Studio Build Tools 설치

1. Visual C++ Build Tools에서 설치 프로그램을 다운로드합니다.
2. 설치 시 “C++을 사용한 데스크탑 개발” 워크로드를 선택합니다.
3. 설치 세부정보에서 MSVC 버전을 선택합니다:
   • MSVC v143: CUDA 12용
   • MSVC v142: CUDA 11용

4.2 CPU 모드로 빌드

Visual Studio Build Tools 설치 후 생성되는 “x64 Native Tools Command Prompt for VS 2022”를 실행하여 다음 명령어를 입력합니다.

cd /path/to/llama.cpp
cmake -B build_cpu -S . -DGGML_CUDA=OFF -DLLAMA_CURL=OFF
cmake --build build_cpu --config Release

옵션 설명:

• -DGGML_CUDA=OFF: CPU 전용 빌드
• -DLLAMA_CURL=OFF: 로컬 모델 사용 시 CURL 비활성화 (모델 다운로드가 필요 없는 경우)

4.3 GPU 모드로 빌드

CUDA가 설치되어 있고 환경변수가 설정되어 있다는 가정 하에 진행합니다.

Step 1: CUDA 파일 복사

CUDA 설치 경로에서 MSBuild 확장 파일을 복사합니다.

From:

C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v11.8\extras\visual_studio_integration\MSBuildExtensions

To:

C:\Program Files (x86)\Microsoft Visual Studio\2022\BuildTools\MSBuild\Microsoft\VC\v170\BuildCustomizations

• 4개의 파일을 모두 복사합니다.
• v170, v160 등 여러 버전 폴더가 있다면 모두 복사합니다.

Step 2: GPU 빌드 실행

cmake -B build_gpu -S . -DGGML_CUDA=ON -DLLAMA_CURL=OFF -T v142 \
  -DCMAKE_CUDA_COMPILER="C:/Program Files/NVIDIA GPU Computing Toolkit/CUDA/v11.8/bin/nvcc.exe"

cmake --build build_gpu --config Release

옵션 설명:

• -DGGML_CUDA=ON: GPU 가속 활성화
• -T v142: MSVC 툴셋 버전 (CUDA 11: v142, CUDA 12: v143)
• -DCMAKE_CUDA_COMPILER: nvcc.exe 경로 명시

5. 서버 오픈

빌드가 완료되면 build경로/bin/Release 폴더에 llama-server.exe 파일이 생성됩니다.

5.1 로컬호스트 서버

llama-server.exe -m /path/to/gguf.gguf -c 2048 -t 8

5.2 외부 접속 가능한 서버

llama-server.exe -m /path/to/gguf.gguf --host 0.0.0.0 --port 8081 -c 2048 -t 8

옵션 설명:

• -m: GGUF 모델 파일 경로
• -c: 컨텍스트 크기 (토큰 수)
• -t: 사용할 스레드 수
• --host: 호스트 주소
• --port: 포트 번호

---