CLI와 서버를 사용한 llama.cpp 빠른 시작

지역 추론(local inference)을 위해 llama.cpp에 계속 돌아오고 있습니다. Ollama 등 다른 도구들이 추상화해 버리는 부분까지 직접 제어할 수 있고, 실제로도 잘 작동하기 때문입니다. llama-cli로 GGUF 모델을 인터랙티브하게 실행하거나, llama-server로 OpenAI 호환 HTTP API를 노출하는 것이 매우 쉽습니다.

아직 로컬, 셀프호스팅, 클라우드 접근 방식 중 어디를 선택할지 결정하고 있다면, 다음 pilar 가이드로 시작해 보세요. 2026년 LLM 호스팅: 로컬, 셀프호스팅 및 클라우드 인프라 비교

2026년 왜 llama.cpp인가

llama.cpp는 다음에 초점을 맞춘 경량 추론 엔진입니다:

• CPU 및 여러 GPU 백엔드 간 이식성,
• 단일 머신에서의 예측 가능한 지연 시간,
• 노트북부터 온프레미스 노드까지의 배포 유연성.

이는 프라이버시 및 오프라인 운영이 필요할 때, 런타임 플래그에 대한 결정론적 제어가 필요할 때, 또는 Python 중심의 전체 스택을 실행하지 않고 더 큰 시스템에 추론을 내장하고 싶을 때 빛을 발합니다.

또한 나중에 더 높은 처리량을 가진 서버 런타임을 선택하더라도 llama.cpp를 이해하는 것이 도움이 됩니다. 예를 들어, GPU에서 최대 서빙 처리량이 목표라면 vLLM과의 비교를 원할 수 있으며, 이 경우 다음 자료를 참고할 수 있습니다: vLLM 퀵스타트: 고성능 LLM 서빙 그리고 벤치마크 도구를 선택할 때 다음 자료를 활용할 수 있습니다: Ollama vs vLLM vs LM Studio: 2026년 로컬 LLM 실행의 최선의 방법?

특히 Ollama가 llama-server와 비교되는 대안이라면, 2026년 llama.cpp vs Ollama이 전념적인 1대1 비교 자료이며, Ollama를 유지해야 하는 구체적인 트리거와 직접적인 llama.cpp로 전환해야 하는 시점을 제공합니다.

Windows, macOS, Linux에 llama.cpp 설치

편리성, 이식성, 최대 성능 중 무엇을 원하느냐에 따라 세 가지 실용적인 설치 경로가 있습니다.

패키지 매니저를 통한 설치

이는 가장 빠른 “설치 후 실행” 옵션입니다.

# macOS or Linux
brew install llama.cpp

# Windows
winget install llama.cpp

# macOS (MacPorts)
sudo port install llama.cpp

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

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

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

미리 빌드된 바이너리를 통한 설치

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

공통 워크플로우:

# 1) Download the right archive for your OS and backend
# 2) Extract it
# 3) Run from the extracted folder

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

정확한 하드웨어를 위해 소스에서 빌드

CPU/GPU 백엔드에서 최적의 성능을 짜내야 한다거나 신경을 쓴다면, CMake를 사용하여 소스에서 빌드하세요.

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

# CPU build
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: 전체 빌드 워크스루

NVIDIA GPU가 있는 Ubuntu 24.04에서는 빌드 전에 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 llama-embedding
cp llama.cpp/build/bin/llama-* llama.cpp

이것은 llama.cpp 디렉터리에 llama-cli, llama-mtmd-cli, llama-server, llama-embedding, llama-gguf-split을 생성합니다.

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

GGUF 모델 및 양자화 선택

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

모델 얻는 두 가지 방법

옵션 A: 로컬 GGUF 파일 사용

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

mkdir -p models
# Place your GGUF at models/my-model.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에서 파일을 다운로드하고 로컬 캐시에 저장할 수 있습니다. 빠른 실험을 위한 워크플로우로 가장 쉬운 방법입니다.

# Download a model from HF and run a prompt
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

인터랙티브 챗 실행

대화 모드(conversation mode)는 챗 템플릿을 위해 설계되었습니다. 보통 인터랙티브 행동을 활성화하고 모델의 템플릿에 따라 프롬프트를 포맷팅합니다.

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

모델이 특정 시퀀스를 출력할 때 생성을 종료하려면 리버스 프롬프트(reverse prompt)를 사용하세요. 이는 인터랙티브 모드에서 특히 유용합니다.

중요한 주요 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 호환 엔드포인트,
• 인터랙티브 테스트를 위한 Web 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/Qwen3-Embedding-0.6B-Q8_0.gguf \
  --embeddings \
  --host 127.0.0.1 \
  --pooling last \
  --port 8080

또는 CPU에서 llama-cpp 임베딩 모델을 실행하려면:

CUDA_VISIBLE_DEVICES="" llama-server \
  -m models/Qwen3-Embedding-0.6B-Q8_0.gguf \
  --embeddings \
  --host 127.0.0.1 \
  --pooling last \
  --port 8080

이렇게 시도해 보세요:

CUDA_VISIBLE_DEVICES="" llama-embedding \
  -m /path/to/Qwen3-Embedding-0.6B-Q8_0.gguf \
  -p "your text here" \
  --pooling last \
  --verbose-prompt

단일 프로세스에서 여러 모델 서빙

위의 예제들은 llama-server를 시작 시 단일 모델에 바인딩합니다. 프로세스를 재시작하지 않고 요청별로 모델을 전환해야 한다면, 이것이 바로 라우터 모드(router mode)의 용도입니다. 다음을 참조하세요. llama-server 라우터 모드: 재시작 없는 동적 모델 전환 라우터의 VRAM을 재시작 없이 해방하는 스크립터블한 언로드-모두(flow)를 보려면, 재시작 없이 llama.cpp 라우터 모델 모두 언로드

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

FAQ 질문 “속도와 메모리에 가장 중요한 llama.cpp 커맨드 라인 옵션은 무엇인가?“는 추론을 시스템으로 대할 때 훨씬 쉬워집니다:

• 메모리 한계는 보통 첫 번째 제약 조건입니다(CPU는 RAM, GPU는 VRAM).
• 컨텍스트 크기는 주요 메모리 증폭제입니다.
• GPU 레이어 오프로드는 보통 초당 더 높은 토큰 수로 가는 가장 빠른 경로입니다.
• 배치 크기와 스레드는 처리량을 개선할 수 있지만 메모리 압력을 증가시킬 수도 있습니다.

더 깊은, 엔지니어링 우선의 관점을 위해 다음을 참조하세요: 2026년 LLM 성능: 벤치마크, 병목 및 최적화

16 GB급 GPU에서 측정된 llama-cli 스타일의 결과(토큰/초, VRAM, 컨텍스트(19K / 32K / 64K)를 스윕하면서 dense 및 MoE GGUF에 걸친 GPU 부하)를 원한다면, 16 GB VRAM LLM 벤치마크 (llama.cpp 속도와 컨텍스트)를 참조하세요.

Qwen 3.6의 경우, llama.cpp는 이제 생성 처리량을 상당히 높일 수 있는 내장 Multi-Token Prediction (MTP) 스펙ুল레이티브 디코딩을 지원합니다. llama.cpp의 모든 스펙ulative 디코딩 방법을 다루는 포괄적인 가이드를 위해, 스펙ulative 디코딩을 참조하세요. Qwen 3.6 MTP 전용 벤치마크를 위해, Qwen 3.6 MTP vs Standard on 16GB GPU를 참조하세요.

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

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

llama.cpp(그리고 vLLM, TGI)에 특화된 대시보드와 알림: 프로덕션에서 LLM 추론 모니터링 (2026): vLLM, TGI, llama.cpp를 위한 Prometheus & Grafana. 더 넓은 가이드: 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로 동시성 제한.

트러블슈팅 퀵윈

모델은 로드되지만 챗에서 답변이 이상함

챗 엔드포인트는 모델이 지원되는 챗 템플릿을 가질 때 가장 좋습니다. 출력이 구조화되지 않은 것처럼 보이면 다음을 시도해 보세요:

• 명시적인 --system-prompt와 함께 llama-cli --conversation 사용,
• 모델이 지시(instruction) 또는 챗 튜닝된 변형인지 확인,
• 앱에 통합하기 전에 서버 Web UI로 테스트.

메모리 부족(OOM) 발생

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

• --ctx-size 낮추기,
• VRAM이 문제라면 --n-gpu-layers 줄이기,
• 더 작은 모델이나 더 압축된 양자화로 전환.

CPU에서 느림

다음부터 시작하세요:

• 물리적 코어 수와 동일한 --threads,
• 중간 정도의 배치 크기,
• 기계(CPU 기능 및 백엔드)에 맞는 빌드를 설치했는지 확인.

참고 자료

• 공식 llama.cpp 리포지토리 및 문서
• 공식 CLI 플래그 문서
• 공식 llama-server 문서 및 API 세부 사항