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

로컬 추론을 위해 llama.cpp로 계속 돌아가게 됩니다. 이 도구는 Ollama 등 다른 도구들이 추상화해버리는 부분을 직접 제어할 수 있게 해주고, 단순히 잘 작동하기 때문입니다. llama-cli를 사용하여 GGUF 모델을 대화형으로 쉽게 실행하거나, llama-server를 통해 OpenAI 호환 HTTP API를 노출할 수 있습니다.

로컬, 자체 호스팅, 클라우드 방식 중 어디를 선택할지 고민 중이라면, 다음 핵심 가이드부터 시작해 보세요. 2026년 LLM 호스팅: 로컬, 자체 호스팅 및 클라우드 인프라 비교.

2026년, 왜 llama.cpp인가?

llama.cpp는 다음과 같은 편향을 가진 경량 추론 엔진입니다.

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

프라이버시와 오프라인 운영이 필요하거나, 런타임 플래그에 대해 결정론적 제어가 필요하거나, Python 기반의 무거운 스택을 실행하지 않고도 더 큰 시스템에 추론을 임베드하고 싶을 때 그 빛을 발합니다.

나중에 더 높은 처리량을 가진 서버 런타임을 선택하더라도 llama.cpp를 이해하는 것이 도움이 됩니다. 예를 들어, GPU에서 최대 서빙 처리량을 목표로 한다면 vLLM과 비교해 볼 수 있습니다: vLLM 빠른 시작: 고성능 LLM 서빙 또한 다음에서 도구 선택을 벤치마크할 수 있습니다: Ollama vs vLLM vs LM Studio: 2026년 로컬에서 LLM을 실행하는 최상의 방법?.

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: 전체 빌드 안내

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 빌드 (CUDA가 활성화된 llama.cpp 클론이 있는 디렉토리에서):

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
# GGUF를 models/my-model.gguf에 배치

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

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

옵션 B: Hugging Face에서 llama.cpp가 다운로드하도록 하기

현대적인 llama.cpp 빌드는 Hugging Face에서 다운로드하고 파일을 로컬 캐시에 유지할 수 있습니다. 이는 빠른 실험을 위해 가장 쉬운 워크플로우가 될 수 있습니다.

# HF에서 모델 다운로드 및 프롬프트 실행
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

모델이 특정 시퀀스를 인쇄할 때 생성을 종료하려면 역프롬프트(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를 시작 시 단일 모델에 바인딩합니다. 프로세스를 다시 시작하지 않고 요청마다 모델을 전환해야 한다면, 바로 라우터 모드를 위한 것입니다. llama-server 라우터 모드: 재시작 없이 동적 모델 전환. 라우터를 재시작하지 않고 VRAM을 해제하는 스크립트 가능한 언로드-모두 흐름에 대해서는 llama.cpp 라우터 모델 언로드: 재시작 없이.

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

FAQ 질문인 “llama.cpp 명령줄 옵션 중 속도와 메모리에 가장 중요한 것은 무엇인가"는 추론을 시스템으로 다룰 때 훨씬 쉬워집니다:

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

더 깊고 엔지니어링 중심의 관점을 보려면 다음을 참조하세요: 2026년 LLM 성능: 벤치마크, 병목 현상 및 최적화.

16 GB급 GPU에서 측정된 llama-cli 스타일의 결과(초당 토큰, VRAM, 밀집 및 MoE GGUF에 걸쳐 컨텍스트(19K / 32K / 64K)를 스윕할 때의 GPU 부하)를 원한다면 16 GB VRAM LLM 벤치마크 with llama.cpp (속도 및 컨텍스트).

Qwen 3.6의 경우, llama.cpp는 이제 생성 처리량을 현저히 높일 수 있는 빌트인 다중 토큰 예측(MTP) 추측 디코딩을 지원합니다. 측정된 생성 속도, VRAM 오버헤드 및 권장 --spec-draft-n-max 값을 보려면 Qwen 3.6 27B 및 35B MTP 대 표준 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. 더 광범위한 가이드: 가시성: 모니터링, 메트릭, Prometheus & Grafana 가이드 및 LLM 시스템용 가시성.

기본 경화 체크리스트

llama-server가 localhost 외부에서 접근 가능할 때:

• 요청이 인증되도록 --api-key(또는 --api-key-file) 사용,
• 필요하지 않으면 0.0.0.0에 바인딩하지 않기,
• 서버의 SSL 플래그를 통한 TLS 또는 리버스 프록시에서 TLS 종료 고려,
• 부하 하에서 지연 시간을 보호하기 위해 --parallel로 동시성 제한.

문제 해결 빠른 팁

모델은 로드되지만 채팅 답변이 이상함

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

• llama-cli --conversation 및 명시적 --system-prompt 사용,
• 모델이 인스트럭션 또는 채팅 튜닝된 변형인지 확인,
• 앱에 연결하기 전에 서버 Web UI로 테스트.

메모리 부족 발생

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

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

CPU에서 느림

다음으로 시작하세요:

• 물리적 코어와 동일한 --threads, -适中的 배치 크기,
• 머신(CPU 기능 및 백엔드)과 일치하는 빌드를 설치했는지 확인.

참고 자료

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