llama.cpp CLI 및 서버로 빠르게 시작하기

저는 로컬 추론을 위해 llama.cpp를 계속 사용합니다. 이는 Ollama 및 기타 도구가 추상화하는 것을 직접 제어할 수 있게 해주며, 작동이 매우 간단합니다. llama-cli를 사용하여 GGUF 모델을 간단하게 실행하거나 llama-server를 통해 OpenAI-compatible HTTP API를 노출시킬 수 있습니다.

아직 로컬, 자가호스팅, 클라우드 접근 방식을 결정하지 못했다면, 먼저 기초 가이드부터 시작하세요. LLM Hosting in 2026: Local, Self-Hosted & Cloud Infrastructure Compared.

2026년에 llama.cpp를 선택하는 이유

llama.cpp는 CPU와 여러 GPU 백엔드를 통해의 이동성을 중시하는 가벼운 추론 엔진입니다.

• 단일 머신에서 예측 가능한 지연 시간,
• 랩탑에서 온프레임 노드까지의 배포 유연성.

개인 정보 보호 및 오프라인 운영이 필요하거나 런타임 플래그에 대한 결정적 제어가 필요하거나, 전체 Python 중심 스택을 실행하지 않고도 큰 시스템에 추론을 내장하고 싶을 때 llama.cpp는 빛납니다.

심지어 나중에 고처리량 서버 런타임을 선택하더라도 llama.cpp를 이해하는 것은 도움이 됩니다. 예를 들어, GPU에서 최대 서빙 처리량을 목표로 한다면, 다음과 같이 vLLM과 비교할 수 있습니다. vLLM Quickstart: High-Performance LLM Serving 또한, 다음과 같은 도구 선택을 벤치마킹할 수 있습니다. Ollama vs vLLM vs LM Studio: Best Way to Run LLMs Locally in 2026?.

Windows, macOS, Linux에서 llama.cpp 설치

편의성, 이동성, 최대 성능에 따라 세 가지 실용적인 설치 경로가 있습니다.

패키지 관리자로 설치

이것은 가장 빠른 “실행” 옵션입니다.

# macOS 또는 Linux
brew install llama.cpp

# Windows
winget install llama.cpp

# macOS (MacPorts)
sudo port install llama.cpp

# macOS 또는 Linux (Nix)
nix profile install nixpkgs#llama-cpp

팁: 설치 후 도구가 존재하는지 확인하세요:

llama-cli --version
llama-server --version

사전 빌드된 바이너리로 설치

컴파일러 없이 깔끔한 설치를 원한다면, llama.cpp GitHub 릴리스에 게시된 공식 사전 빌드된 바이너리를 사용하세요. 일반적으로 여러 OS 타겟과 여러 백엔드(CPU 전용 및 GPU 활성화된 변형)를 포함합니다.

일반적인 워크플로우:

# 1) OS 및 백엔드에 맞는 아카이브 다운로드
# 2) 압축 해제
# 3) 압축 해제된 폴더에서 실행

./llama-cli --help
./llama-server --help

정확한 하드웨어에 맞는 소스에서 빌드

CPU/GPU 백엔드에서 최고 성능을 얻고자 한다면, CMake를 사용하여 소스에서 빌드하세요.

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

# CPU 빌드
cmake -B build
cmake --build build --config Release

빌드 후, 일반적으로 이곳에 바이너리가 있습니다:

ls -la ./build/bin/

GPU 빌드 한 줄 명령

하드웨어에 맞는 백엔드를 활성화하세요 (CUDA 및 Vulkan 예시):

# NVIDIA CUDA
cmake -B build -DGGML_CUDA=ON
cmake --build build --config Release

# Vulkan
cmake -B build -DGGML_VULKAN=ON
cmake --build build --config Release

Ubuntu 24.04 + NVIDIA GPU: 전체 빌드 가이드

Ubuntu 24.04에 NVIDIA GPU가 있다면, 빌드 전 CUDA 툴킷과 OpenSSL이 필요합니다. 다음은 테스트된 순서입니다:

1. CUDA 툴킷 13.1 설치

wget https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2404/x86_64/cuda-ubuntu2404.pin
sudo mv cuda-ubuntu2404.pin /etc/apt/preferences.d/cuda-repository-pin-600
wget https://developer.download.nvidia.com/compute/cuda/13.1.1/local_installers/cuda-repo-ubuntu2404-13-1-local_13.1.1-590.48.01-1_amd64.deb
sudo dpkg -i cuda-repo-ubuntu2404-13-1-local_13.1.1-590.48.01-1_amd64.deb
sudo cp /var/cuda-repo-ubuntu2404-13-1-local/cuda-*-keyring.gpg /usr/share/keyrings/
sudo apt-get update
sudo apt-get -y install cuda-toolkit-13-1

2. CUDA 환경에 추가 (~/.bashrc에 추가):

# cuda toolkit
export PATH=/usr/local/cuda-13.1/bin:$PATH
export LD_LIBRARY_PATH=/usr/local/cuda-13.1/lib64:$LD_LIBRARY_PATH

그런 다음 source ~/.bashrc 또는 새 터미널을 열어야 합니다.

3. OpenSSL 개발 헤더 설치 (깨끗한 빌드를 위해 필요):

sudo apt update
sudo apt install libssl-dev

4. llama.cpp 빌드 (llama.cpp 복사본이 있는 디렉토리에서 CUDA 활성화):

cmake llama.cpp -B llama.cpp/build -DBUILD_SHARED_LIBS=OFF -DGGML_CUDA=ON
cmake --build llama.cpp/build --config Release -j --clean-first --target llama-cli llama-mtmd-cli llama-server llama-gguf-split
cp llama.cpp/build/bin/llama-* llama.cpp

이 작업은 llama-cli, llama-mtmd-cli, llama-server, llama-gguf-split을 llama.cpp 디렉토리에 생성합니다.

다중 백엔드를 컴파일하고 런타임에 장치를 선택할 수도 있습니다. 이는 동질적인 머신에 동일한 빌드를 배포하는 데 유용합니다.

GGUF 모델과 양자화 선택

추론을 실행하려면 GGUF 모델 파일(*.gguf)이 필요합니다. GGUF는 모델 가중치와 엔진(예: llama.cpp)에 필요한 표준화된 메타데이터를 포함하는 단일 파일 형식입니다.

모델을 얻는 두 가지 방법

선택 A: 로컬 GGUF 파일 사용

GGUF을 ./models/에 다운로드하거나 복사하세요:

mkdir -p models
# models/my-model.gguf에 GGUF 파일을 배치하세요

그런 다음 경로로 실행하세요:

llama-cli -m models/my-model.gguf -p "Hello! Explain what llama.cpp is." -n 128

선택 B: llama.cpp가 Hugging Face에서 다운로드

현대적인 llama.cpp 빌드는 Hugging Face에서 다운로드하고 로컬 캐시에 파일을 보관할 수 있습니다. 이는 빠른 실험에 자주 사용되는 가장 간단한 워크플로우입니다.

# Hugging Face에서 모델 다운로드 및 프롬프트 실행
llama-cli \
  --hf-repo ggml-org/tiny-llamas \
  --hf-file stories15M-q4_0.gguf \
  -p "Once upon a time," \
  -n 200

리포지토리 선택기에서 양자화를 지정하고 도구가 일치하는 파일을 선택하도록 할 수도 있습니다:

llama-cli \
  --hf-repo unsloth/phi-4-GGUF:q4_k_m \
  -p "Summarize the concept of quantization in one paragraph." \
  -n 160

나중에 완전히 오프라인 워크플로우가 필요하다면, --offline 플래그로 캐시 사용을 강제하고 네트워크 액세스를 방지할 수 있습니다.

로컬 추론을 위한 양자화 선택

양자화는 “로컬 추론을 위해 어떤 GGUF 양자화를 선택해야 하나요?“라는 질문에 대한 실용적인 답이며, 품질, 모델 크기, 속도 사이에서 직접적인 트레이드오프를 제공합니다.

실용적인 시작점:

• CPU 중심 머신에서는 Q4 또는 Q5 변형부터 시작하세요,
• RAM 또는 VRAM을 충분히 확보할 수 있다면, 더 높은 정밀도(또는 덜 공격적인 양자화)로 이동하세요,
• 모델이 작업에 대해 “아주 멍청해 보인다면”, 문제 해결 방법은 일반적으로 모델을 개선하거나 양자화를 덜 공격적으로 하거나, 샘플링 조정만이 아닙니다.

또한 컨텍스트 윈도우가 중요하다는 것을 기억하세요: 컨텍스트 크기가 클수록 메모리 사용량이 증가합니다(가끔은 극적으로), GGUF 파일 자체가 작더라도 그렇습니다.

llama-cli 빠른 시작 및 주요 파라미터

llama-cli는 모델이 로드되고 백엔드가 작동하며 프롬프트가 어떻게 동작하는지를 가장 빠르게 확인할 수 있는 방법입니다.

최소 실행

llama-cli \
  -m models/my-model.gguf \
  -p "Write a short TCP vs UDP comparison." \
  -n 200

대화 모드 실행

대화 모드는 대화 템플릿을 위해 설계되었습니다. 일반적으로 대화형 행동을 활성화하고 모델 템플릿에 따라 프롬프트를 포맷합니다.

llama-cli \
  -m models/my-model.gguf \
  --conversation \
  --system-prompt "You are a concise systems engineering assistant." \
  --ctx-size 4096

모델이 특정 시퀀스를 인쇄할 때 생성을 종료하려면 역 프롬프트를 사용하세요. 이는 대화형 모드에서 특히 유용합니다.

주요 llama-cli 플래그

200개의 플래그를 외우기보다는 정확성, 지연 시간, 메모리에 영향을 주는 것들에 집중하세요.

모델 및 다운로드

컨텍스트 및 처리량

GPU 오프로드 및 하드웨어 선택

샘플링 및 출력 품질

llama-cli 예제 작업

파일 요약, 단순히 프롬프트가 아닌

llama-cli \
  -m models/my-model.gguf \
  --system-prompt "You summarize technical documents. Output five bullets max." \
  --file ./docs/incident-report.txt \
  -n 300

결과를 더 재현 가능하게 만들기

프롬프트 디버깅 시 시드를 고정하고 무작위성을 줄이세요:

llama-cli \
  -m models/my-model.gguf \
  -p "Extract key risks from this design note." \
  -n 200 \
  --seed 42 \
  --temp 0.2

OpenAI 호환 API와 함께 llama-server 빠른 시작

llama-server는 다음과 같은 HTTP 서버를 내장하고 있습니다:

• OpenAI 호환 엔드포인트: 채팅, 완성, 임베딩, 응답,
• 대화형 테스트를 위한 웹 UI,
• 프로덕션 가시성을 위한 선택적 모니터링 엔드포인트.

로컬 모델과 함께 서버 시작

llama-server \
  -m models/my-model.gguf \
  -c 4096

기본적으로 127.0.0.1:8080에서 듣습니다.

외부에 바인딩하려면 (예: Docker 또는 LAN 내부), 호스트와 포트를 지정하세요:

llama-server \
  -m models/my-model.gguf \
  -c 4096 \
  --host 0.0.0.0 \
  --port 8080

서버 플래그 (선택 사항이지만 중요)

컨테이너에서 실행하는 경우, 많은 설정은 LLAMA_ARG_* 환경 변수를 통해 제어할 수 있습니다.

예제 API 호출

curl을 사용한 채팅 완성

curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer no-key" \
  -d '{
    "model": "gpt-3.5-turbo",
    "messages": [
      { "role": "system", "content": "You are a helpful assistant." },
      { "role": "user", "content": "Give me a quick llama.cpp checklist." }
    ],
    "temperature": 0.7
  }'

실제 배포 시 팁: --api-key를 설정하면 x-api-key 헤더를 통해 보낼 수 있습니다(게이트웨이에 따라 Authorization 헤더 사용도 가능합니다).

llama-server를 대상으로 하는 OpenAI Python 클라이언트

OpenAI 호환 서버가 실행 중이라면, 많은 클라이언트가 base_url만 변경하여 작동할 수 있습니다.

import openai

client = openai.OpenAI(
    base_url="http://localhost:8080/v1",
    api_key="sk-no-key-required",
)

resp = client.chat.completions.create(
    model="gpt-3.5-turbo",
    messages=[
        {"role": "system", "content": "You are a concise assistant."},
        {"role": "user", "content": "Explain threads vs batch size in llama.cpp."}
    ],
)

print(resp.choices[0].message.content)

임베딩

OpenAI 호환 임베딩은 /v1/embeddings에서 노출되지만, 모델이 none이 아닌 임베딩 풀링 모드를 지원해야 합니다.

curl http://localhost:8080/v1/embeddings \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer no-key" \
  -d '{
    "input": ["hello", "world"],
    "model": "GPT-4",
    "encoding_format": "float"
  }'

특정 임베딩 모델을 실행하는 경우, 서버를 임베딩 전용 모드로 시작하세요:

llama-server \
  -m models/my-embedding-model.gguf \
  --embeddings \
  --host 127.0.0.1 \
  --port 8080

성능, 모니터링, 프로덕션 강화

“llama.cpp 명령줄 옵션 중에서 속도와 메모리에 가장 영향을 주는 것은 무엇인가?“라는 FAQ 질문은 추론을 시스템처럼 다루는 경우 훨씬 쉬워집니다:

• 메모리 제한은 일반적으로 첫 번째 제약 조건입니다(RAM은 CPU, VRAM은 GPU).
• 컨텍스트 크기는 메모리의 주요 곱셈자입니다.
• GPU 레이어 오프로드는 토큰당 초당 처리량을 높이는 가장 빠른 방법입니다.
• 배치 크기 및 스레드는 처리량을 향상시킬 수 있지만, 메모리 압력을 증가시킬 수도 있습니다.

더 깊고, 엔지니어링 중심의 시각을 원한다면: LLM Performance in 2026: Benchmarks, Bottlenecks & Optimization.

Prometheus 및 Grafana를 사용한 llama-server 모니터링

llama-server는 --metrics가 활성화되면 /metrics에서 Prometheus 호환 메트릭을 노출할 수 있습니다. 이는 Prometheus 스크레이프 구성 및 Grafana 대시보드와 자연스럽게 결합됩니다.

llama.cpp(및 vLLM, TGI)에 특화된 대시보드 및 경고: Monitor LLM Inference in Production (2026): Prometheus & Grafana for vLLM, TGI, llama.cpp. 더 넓은 가이드: Observability: Monitoring, Metrics, Prometheus & Grafana Guide 및 Observability for LLM Systems.

기본 강화 체크리스트

llama-server가 로컬 호스트 외부에 도달 가능한 경우:

• --api-key (또는 --api-key-file)를 사용하여 요청이 인증되도록 하세요,
• 0.0.0.0에 바인딩하는 것을 피하세요(필요할 경우만 사용),
• 서버의 SSL 플래그를 통해 TLS를 활성화하거나 역방향 프록시에서 TLS를 종료하세요,
• --parallel을 사용하여 동시성을 제한하여 로드 시 지연 시간을 보호하세요.

문제 해결 빠른 승리

모델이 로드되지만 채팅에서 답변이 이상하다

채팅 엔드포인트는 모델이 지원하는 채팅 템플릿을 가지고 있을 때 가장 잘 작동합니다. 출력이 비구조화된 경우 다음을 시도하세요:

• llama-cli --conversation과 명시적인 --system-prompt 사용,
• 모델이 지시문 또는 채팅 최적화 변형인지 확인,
• 앱에 연결하기 전에 서버 웹 UI에서 테스트.

메모리 부족

컨텍스트를 줄이거나 더 작은 양자화를 선택하세요:

• --ctx-size를 낮추세요,
• VRAM 문제가 있다면 --n-gpu-layers를 줄이세요,
• 더 작은 모델 또는 더 압축된 양자화로 전환하세요.

CPU에서 느리다

다음부터 시작하세요:

• --threads를 물리적 코어 수와 같게 설정,
• 중간 배치 크기,
• 설치한 빌드가 기계(예: CPU 기능 및 백엔드)와 일치하는지 확인.

참고 자료

• 공식 llama.cpp 저장소 및 문서
• 공식 CLI 플래그 문서
• 공식 llama-server 문서 및 API 세부 정보