llama.cpp에서 GGUF 사용하기

llama.cpp에서 GGUF 사용하기

llama.cpp는 Hugging Face 저장소 경로와 파일명만 지정하면 GGUF 모델을 내려받아 바로 추론(inference)을 실행할 수 있게 해 줍니다. 이 페이지에서는 llama.cpp를 설치하고 GGUF 모델을 실행하는 방법을 차근차근 설명해 드릴게요.

출처: 문서

본문

[!TIP] 이제 Inference Endpoints에서도 llama.cpp 호환 GGUF를 배포할 수 있어요. 자세한 내용은 여기에서 확인하세요.

llama.cpp는 Hugging Face 저장소 경로와 파일명만 제공하면 GGUF를 내려받아 추론을 실행할 수 있어요. llama.cpp는 모델 체크포인트를 다운로드하고 자동으로 캐시합니다. 캐시 위치는 LLAMA_CACHE 환경 변수로 정의되며, 자세한 내용은 여기에서 확인할 수 있어요.

llama.cpp는 brew(Mac과 Linux에서 동작)로 설치하거나 소스에서 직접 빌드할 수 있어요. 미리 빌드된 바이너리와 Docker 이미지도 있으니 공식 문서에서 확인해 보세요.

방법 1: brew / winget으로 설치

brew install llama.cpp

Windows에서는 winget을 이용할 수 있어요.

winget install llama.cpp

방법 2: 소스에서 빌드

1단계: GitHub에서 llama.cpp를 클론합니다.

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

2단계: llama.cpp 폴더로 이동해 빌드합니다. 하드웨어별 플래그(예: Nvidia GPU용 -DGGML_CUDA=1)를 추가할 수도 있어요.

cd llama.cpp
cmake -B build   # 선택적으로 CUDA 활성화를 위해 -DGGML_CUDA=ON 추가
cmake --build build --config Release

참고: 다른 하드웨어 지원(예: AMD ROCm, Intel SYCL)은 llama.cpp의 빌드 가이드를 참고하세요.

설치가 끝나면 llama-cli 또는 llama-server를 다음과 같이 사용할 수 있어요.

llama-cli -hf bartowski/Llama-3.2-3B-Instruct-GGUF:Q8_0

참고: -no-cnv를 명시적으로 추가하면 CLI를 raw 완성(비챗) 모드로 실행할 수 있어요.

또한 llama.cpp 서버를 이용하면 OpenAI 스펙의 chat completions 엔드포인트를 직접 호출할 수 있어요.

llama-server -hf bartowski/Llama-3.2-3B-Instruct-GGUF:Q8_0

서버를 실행한 뒤에는 아래처럼 엔드포인트를 사용하면 됩니다.

curl http://localhost:8080/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ***" \
-d '{
"messages": [
    {
        "role": "system",
        "content": "You are an AI assistant. Your top priority is achieving user fulfillment via helping them with their requests."
    },
    {
        "role": "user",
        "content": "Write a limerick about Python exceptions"
    }
  ]
}'

-hf 뒤에 유효한 Hugging Face 허브 저장소 이름을 넣으면 됩니다. 이제 시작해 보세요! 🦙

더 알아보기 (Learn more)