llama.cpp로 Qwen 로컬 실행하기

llama.cpp로 Qwen 로컬 실행하기

llama.cpp는 가벼운 풋프린트, 최소한의 외부 의존성, 멀티플랫폼, 그리고 광범위하고 유연한 하드웨어 지원을 지향하는, 서로 다른 설계 철학을 가진 생태계예요. 이 가이드에서는 llama.cpp의 예시 프로그램인 llama-cli와 llama-server를 사용해 로컬 머신에서 Qwen 모델을 실행하는 방법을 보여드려요.

출처: 문서

본문

C++ 라이브러리로서의 llama.cpp

시작하기 전에 llama.cpp가 무엇이고 무엇을 기대할 수 있는지, 그리고 왜 llama.cpp를 "사용한다"고 말하는지 먼저 이야기해 볼게요. llama.cpp는 근본적으로 가벼운 풋프린트, 최소한의 외부 의존성, 멀티플랫폼, 그리고 광범위하고 유연한 하드웨어 지원을 지향하는, 서로 다른 설계 철학을 가진 별개의 생태계예요:

  • 외부 의존성 없는 순수 C/C++ 구현
  • 다양한 하드웨어 지원:
    • x86_64 CPU를 위한 AVX, AVX2, AVX512 지원
    • Metal과 Accelerate를 통한 Apple Silicon (CPU 및 GPU)
    • NVIDIA GPU (CUDA), AMD GPU (hipBLAS), Intel GPU (SYCL), Ascend NPU (CANN), Moore Threads GPU (MUSA)
    • GPU를 위한 Vulkan 백엔드
  • 더 빠른 추론과 메모리 풋프린트 감소를 위한 다양한 양자화 기법
  • 총 VRAM 용량보다 큰 모델을 부분적으로 가속하는 CPU+GPU 하이브리드 추론

이것은 마치 Python 프레임워크인 torch+transformers나 torch+vllm을 C++로 만든 것과 같아요. 하지만 이 차이는 결정적이에요:

  • Python은 인터프리터 언어예요: 작성한 코드는 인터프리터가 한 줄씩 즉시 실행해요. 예시 코드나 스크립트를 인터프리터나 네이티브 대화형 인터프리터 셸로 실행할 수 있어요. 또한 Python은 학습자 친화적이라, 많이 몰라도 소스 코드를 여기저기 수정해 볼 수 있어요.
  • C++는 컴파일 언어예요: 작성한 소스 코드는 미리 컴파일돼야 하고, 컴파일러가 기계어와 실행 프로그램으로 번역해요. 언어 쪽 오버헤드는 최소예요. 라이브러리 사용법을 보여주는 예시 프로그램의 소스 코드가 있긴 하지만, C++나 C에 익숙하지 않다면 소스 코드를 수정하기가 쉽지 않아요.

llama.cpp를 "사용한다"는 것은 Ollama, LM Studio, GPT4ALL, llamafile 등의 소스 코드를 작성하는 것처럼 여러분의 프로그램에서 llama.cpp 라이브러리를 사용한다는 뜻이에요. 하지만 이 가이드는 그런 의도나 목적이 아니에요. 대신 여기서는 llama.cpp가 Qwen2.5 모델을 지원한다는 것과 llama.cpp 생태계가 일반적으로 어떻게 동작하는지 알 수 있도록 llama-cli 예시 프로그램 사용법을 소개할게요.

이 가이드에서는 llama.cpp로 로컬 머신에서 모델을 실행하는 방법, 특히 라이브러리와 함께 제공되는 llama-cli와 llama-server 예시 프로그램을 다룰게요.

주요 단계는 다음과 같아요:

  1. 프로그램 얻기
  2. GGUF[1] 형식의 Qwen3 모델 얻기
  3. 모델과 함께 프로그램 실행하기

📝 참고: llama.cpp는 버전 b5092부터 Qwen3와 Qwen3MoE를 지원해요.

프로그램 얻기

프로그램은 여러 방법으로 얻을 수 있어요. 최적의 효율을 위해 로컬에서 프로그램을 컴파일하는 것을 권장해요. 그러면 CPU 최적화를 자동으로 얻을 수 있거든요. 하지만 로컬에 C++ 컴파일러가 없다면 패키지 매니저를 사용하거나 미리 빌드된 바이너리를 다운로드해서 설치할 수도 있어요. 덜 효율적일 수 있지만 프로덕션이 아닌 예시 용도에는 충분해요.

로컬 컴파일

여기서는 macOS나 Linux에서 llama-cli를 로컬로 컴파일하는 기본 명령을 보여드려요. Windows나 GPU 사용자는 llama.cpp의 가이드를 참고하세요.

빌드 도구 설치 — 로컬에서 빌드하려면 C++ 컴파일러와 빌드 시스템 도구가 필요해요. 이미 설치되어 있는지 확인하려면 터미널 창에서 cc --version이나 cmake --version을 입력하세요. 설치되어 있다면 도구의 빌드 구성이 터미널에 출력되고 바로 사용할 수 있어요! 오류가 발생하면 먼저 관련 도구를 설치해야 해요:

  • macOS에서는 xcode-select --install 명령으로 설치하세요.
  • Ubuntu에서는 sudo apt install build-essential 명령으로 설치하세요. 다른 Linux 배포판은 명령이 다를 수 있으며, 이 가이드에 필요한 핵심 패키지는 gcc와 cmake예요.

프로그램 컴파일 — 첫 단계로 저장소를 클론하고 디렉터리에 들어가세요:

git clone https://github.com/ggml-org/llama.cpp
cd llama.cpp

그 다음 CMake로 llama.cpp를 빌드하세요:

cmake -B build
cmake --build build --config Release

첫 번째 명령은 로컬 환경을 확인하고 어떤 백엔드와 기능을 포함할지 결정해요. 두 번째 명령은 실제로 프로그램을 빌드해요.

시간을 줄이려면 가진 CPU 코어에 맞춰 병렬 컴파일을 활성화할 수도 있어요. 예를 들어:

cmake --build build --config Release -j 8

이렇게 하면 8개의 병렬 컴파일 작업으로 프로그램을 빌드해요. 빌드된 프로그램은 ./build/bin/에 있어요.

패키지 매니저

macOS와 Linux 사용자는 Homebrew, Nix, Flox 등 패키지 매니저로 llama-cli와 llama-server를 설치할 수 있어요. 여기서는 Homebrew로 설치하는 방법을 보여드려요. 다른 패키지 매니저는 여기 지침을 확인하세요.

Homebrew로 설치는 아주 간단해요:

  1. 운영체제에 Homebrew가 있는지 확인하세요. 없으면 웹사이트에서 설치할 수 있어요.
  2. 그 다음 llama-cli와 llama-server가 포함된 미리 빌드된 바이너리를 한 번의 명령으로 설치하세요:
brew install llama.cpp

설치된 바이너리는 여러분의 하드웨어에 최적화된 컴파일 옵션으로 빌드되지 않았을 수 있어 성능이 좋지 않을 수 있다는 점을 참고하세요. 또한 Linux 시스템에서는 GPU를 지원하지 않아요.

바이너리 릴리스

GitHub Releases에서 미리 빌드된 바이너리를 다운로드할 수도 있어요. 이 미리 빌드된 바이너리는 아키텍처, 백엔드, OS별로 다르다는 점을 유의하세요. 이게 무엇을 뜻하는지 잘 모르겠다면 아마 사용하지 않는 편이 좋아요. 호환되지 않는 버전으로 실행하면 대부분 실패하거나 성능이 나빠질 거예요.

파일 이름은 llama-<version>-bin-<os>-<feature>-<arch>.zip과 같아요. 세 가지 단순한 부분이 있어요:

  • <version>: llama.cpp 버전. 최신이 선호되지만 llama.cpp는 자주 업데이트·릴리스되므로 최신 버전에 버그가 있을 수 있어요. 최신 버전이 동작하지 않으면 동작할 때까지 이전 릴리스를 사용해 보세요.
  • <os>: 운영체제. win은 Windows, macos는 macOS, linux는 Linux예요.
  • <arch>: 시스템 아키텍처. x64는 x86_64(대부분의 Intel·AMD 시스템, Intel Mac 포함), arm64는 arm64(Apple Silicon이나 Snapdragon 기반 시스템)예요.

<feature> 부분은 Windows에서 다소 복잡해요:

CPU 실행:

  • x86_64 CPU: 먼저 avx2를 시도해 보시길 권해요.
    • noavx: 하드웨어 가속이 전혀 없음
    • avx2, avx, avx512: SIMD 기반 가속. 대부분의 현대 데스크톱 CPU는 avx2를 지원하고, 일부 CPU는 avx512를 지원해요.
    • openblas: 프롬프트 처리에 OpenBLAS를 사용한 가속(생성은 아님)
  • arm64 CPU: 먼저 llvm을 시도해 보시길 권해요. llvm과 msvc는 서로 다른 컴파일러예요.

GPU 실행: NVIDIA GPU에는 cu<cuda_verison>을, AMD GPU에는 kompute를, Intel GPU에는 sycl을 먼저 시도해 보시길 권해요. 관련 드라이버가 설치되어 있는지 확인하세요.

  • vulcan: 특정 NVIDIA와 AMD GPU를 지원
  • kompute: 특정 NVIDIA와 AMD GPU를 지원
  • sycl: Intel GPU, oneAPI 런타임 포함
  • cu<cuda_verison>: NVIDIA GPU, CUDA 런타임 미포함. 해당 CUDA 툴킷이 없다면 cudart-llama-bin-win-cu<cuda_version>-x64.zip을 다운로드해 같은 디렉터리에 압축을 풀면 돼요.

macOS나 Linux에서는 선택지가 많지 않아요.

  • Linux: CPU를 지원하는 미리 빌드된 바이너리 하나, llama-<version>-bin-linux-x64.zip만 있어요.
  • macOS: Intel Mac용(무 GPU 지원) llama-<version>-bin-macos-x64.zip, Apple Silicon용(GPU 지원) llama-<version>-bin-macos-arm64.zip.

.zip 파일을 다운로드한 뒤 디렉터리에 압축을 풀고 그 디렉터리에서 터미널을 여세요.

GGUF 얻기

GGUF[1]는 모델 실행에 필요한 정보를 저장하는 파일 형식이에요. 모델 가중치, 모델 하이퍼파라미터, 기본 생성 설정, 토크나이저를 비롯해 (이에 국한되지 않고) 다양한 정보를 포함해요.

공식 Qwen GGUFs를 우리 Hugging Face Hub에서 사용하거나 나만의 GGUF 파일을 준비할 수 있어요.

공식 Qwen3 GGUFs 사용하기

우리는 Hugging Face 조직에서 다양한 GGUF 모델을 제공해요. 필요한 것을 찾으려면 저장소 이름에서 -GGUF를 검색하면 돼요.

원하는 GGUF 모델을 huggingface-cli로 다운로드하세요 (먼저 pip install huggingface_hub으로 설치 필요):

huggingface-cli download <model_repo> <gguf_file> --local-dir <local_dir>

예를 들어:

huggingface-cli download Qwen/Qwen3-8B-GGUF qwen3-8b-q4_k_m.gguf --local-dir .

이렇게 하면 Q4_K_M 방식으로 양자화된 GGUF 형식의 Qwen3-8B 모델을 다운로드해요.

나만의 GGUF 준비

Hugging Face Hub의 모델 파일은 convert-hf-to-gguf.py Python 스크립트를 사용해 GGUF로 변환할 수 있어요. 이 스크립트는 최소한 transformers가 설치된 동작하는 Python 환경이 필요해요.

아직 소스 파일이 없으면 얻으세요:

git clone https://github.com/ggml-org/llama.cpp
cd llama.cpp

Qwen3-8B를 사용하고 싶다면 fp16 모델의 GGUF 파일을 아래처럼 만들 수 있어요:

python convert-hf-to-gguf.py Qwen/Qwen3-8B --outfile qwen3-8b-f16.gguf

스크립트의 첫 번째 인자는 HF 모델 디렉터리 경로 또는 HF 모델 이름이고, 두 번째 인자는 출력 GGUF 파일 경로예요. 명령을 실행하기 전에 출력 디렉터리를 만들어 두는 것을 기억하세요.

fp16 모델은 로컬 실행에 다소 무거울 수 있으니 필요에 따라 모델을 양자화할 수 있어요. GGUF 파일을 만들고 양자화하는 방법은 이 가이드에서 소개할게요. 자세한 내용은 해당 문서를 참고하세요.

llama.cpp로 Qwen 실행하기

📝 참고: thinking 모드와 non-thinking 모드 전환과 관련해, 소프트 스위치는 항상 사용 가능하지만 채팅 템플릿에 구현된 하드 스위치는 llama.cpp에 노출되지 않아요. 빠른 해결책은 --chat-template-file을 통해 항상 enable_thinking=False와 동일한 커스텀 채팅 템플릿을 전달하는 거예요.

llama-cli

llama-cli는 LLM과 채팅할 수 있는 콘솔 프로그램이에요. llama.cpp 프로그램이 있는 위치에서 다음 명령을 실행하세요:

./llama-cli -hf Qwen/Qwen3-8B-GGUF:Q8_0 --jinja --color -ngl 99 -fa -sm row --temp 0.6 --top-k 20 --top-p 0.95 --min-p 0 -c 40960 -n 32768 --no-context-shift

위 명령에 대한 몇 가지 설명이에요:

모델: llama-cli는 로컬 경로, 원격 URL, 또는 Hugging Face 허브의 모델 파일을 지원해요.

  • 위의 -hf Qwen/Qwen3-8B-GGUF:Q8_0은 Hugging Face 허브의 모델 파일을 사용한다는 뜻이에요
  • 로컬 경로를 사용하려면 대신 -m qwen3-8b-q8_0.gguf를 전달하세요
  • 원격 URL을 사용하려면 대신 -mu https://hf.co/Qwen/Qwen3-8B-GGUF/resolve/main/qwen3-8b-Q8_0.gguf?download=true를 전달하세요

속도 최적화:

  • CPU: llama-cli는 기본적으로 CPU를 사용하며 -t로 사용할 스레드 수를 지정할 수 있어요. 예: -t 8은 8개 스레드 사용.
  • GPU: 프로그램이 GPU 지원으로 빌드되었다면 -ngl을 사용해 일부 레이어를 GPU에 오프로드해 계산할 수 있어요. GPU가 여러 개면 모든 GPU로 오프로드해요. -dev로 사용할 디바이스를, -sm으로 사용할 병렬 처리 종류를 제어할 수 있어요. 예: -ngl 99 -dev cuda0,cuda1 -sm row는 모든 레이어를 GPU 0과 GPU1에 row 분할 모드로 오프로드한다는 뜻이에요. -fa를 추가하면 생성이 더 빨라질 수도 있어요.

샘플링 파라미터: llama.cpp는 다양한 샘플링 방법을 지원하고 많은 방법에 대해 기본 구성을 갖추고 있어요. 실제 상황에 맞게 파라미터를 조정하는 것이 권장되며, Qwen3 모델카드의 권장 파라미터를 참고할 수 있어요. 반복(repetition)과 끝없는 생성 문제가 발생한다면 추가로 --presence-penalty를 최대 2.0까지 전달하는 것을 권장해요.

컨텍스트 관리: llama.cpp는 기본적으로 "회전(rotating)" 컨텍스트 관리를 채택해요. -c는 최대 컨텍스트 길이(기본 4096, 0은 모델에서 로드)를 제어하고, -n은 매번의 최대 생성 길이(기본 -1은 끝날 때까지 무한, -2는 컨텍스트가 찰 때까지)를 제어해요. 컨텍스트가 가득 찼는데 생성이 끝나지 않으면 초기 프롬프트의 첫 --keep 토큰(기본 0, -1은 전부)이 유지되고 나머지의 앞부분 절반이 버려져요. 그 다음 모델은 새 컨텍스트 토큰을 바탕으로 계속 생성해요. --no-context-shift를 설정하면 이 회전 동작을 막고 -c에 도달하면 생성이 멈춰요.

llama.cpp는 YaRN을 지원해서 -c 131072 --rope-scaling yarn --rope-scale 4 --yarn-orig-ctx 32768로 활성화할 수 있어요.

채팅: --jinja는 GGUF에 내장된 채팅 템플릿(선호되는 방식)을 사용한다는 뜻이고, --color는 텍스트에 색을 입혀 사용자 입력과 모델 출력을 더 잘 구분하게 해줘요. Qwen3 모델처럼 채팅 템플릿이 있다면 llama-cli는 자동으로 채팅 모드로 진입해요. 생성을 멈추거나 종료하려면 "Ctrl+C"를 누르세요. -sys로 시스템 프롬프트를 추가할 수 있어요.

llama-server

llama-server는 LLM REST API 세트와 llama.cpp로 LLM과 상호작용하는 간단한 웹 프런트엔드를 포함하는 간단한 HTTP 서버예요.

핵심 명령은 llama-cli와 유사해요. 추가로 thinking 콘텐츠 파싱과 도구 호출 파싱을 지원해요.

./llama-server -hf Qwen/Qwen3-8B-GGUF:Q8_0 --jinja --reasoning-format deepseek -ngl 99 -fa -sm row --temp 0.6 --top-k 20 --top-p 0.95 --min-p 0 -c 40960 -n 32768 --no-context-shift

기본적으로 서버는 http://localhost:8080에서 수신하며 --host와 --port로 바꿀 수 있어요. 웹 프런트엔드는 브라우저에서 http://localhost:8080/으로 접근할 수 있어요. OpenAI 호환 API는 http://localhost:8080/v1/에 있어요.

더 많은 것

여전히 llama.cpp가 어렵게 느껴진다면 걱정하지 마세요. 다른 llama.cpp 기반 애플리케이션을 확인해 보세요. 예를 들어 Qwen3는 이미 Ollama와 LM Studio의 공식 일부로 포함되어 있고, 이들은 로컬 LLM을 검색·실행하는 플랫폼이에요.

즐거운 사용 되세요!

[1] (1,2) GGUF = GPT-Generated Unified Format

더 알아보기 (Learn more)