CLI 및 서버를 활용한 llama.cpp 빠른 시작

로컬 추론을 위해 llama.cpp 로 계속 돌아오게 됩니다. 이 도구는 Ollama 와 다른 도구들이 추상화하는 제어를 제공하며, 실제로 작동합니다. llama-cli 를 통해 GGUF 모델을 대화식으로 쉽게 실행하거나, llama-server 를 통해 OpenAI 호환 HTTP API 를 노출할 수 있습니다.

로컬, 자체 호스팅, 클라우드 접근 방식 중 어떤 것을 선택할지 아직 결정 중이시라면, 다음 가이드에서 시작해 보세요. LLM 호스팅 2026: 로컬, 자체 호스팅 및 클라우드 인프라 비교.

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

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
# GGUF 를 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 에서 다운로드하여 파일을 로컬 캐시에 유지할 수 있습니다. 이는 빠른 실험을 위한 가장 쉬운 워크플로우입니다.

# 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 호환 엔드포인트,
• 대화형 테스트를 위한 웹 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 라우터 모드: 재시작 없이 동적 모델 전환.

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

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

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

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

16 GB 등급 GPU 에서 측정된 llama-cli 스타일의 결과 (초당 토큰 수, VRAM, GPU 부하) 를 얻고 싶다면, 밀집 및 MoE GGUF 를 통해 컨텍스트 (19K / 32K / 64K) 를 스윕하는 경우를 확인하세요: 16 GB VRAM LLM 벤치마크 with llama.cpp (속도 및 컨텍스트).

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

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

llama.cpp (및 vLLM, TGI) 에 대한 대시보드 및 경고: 프로덕션 LLM 추론 모니터링 (2026): vLLM, TGI, llama.cpp 를 위한 Prometheus & Grafana. 더 넓은 가이드: 가시성: 모니터링, 메트릭, Prometheus & Grafana 가이드 및 LLM 시스템의 가시성.

기본 강화 체크리스트

llama-server 가 로컬호스트를 넘어 도달할 수 있을 때:

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

문제 해결 빠른 해결책

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

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

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

메모리 부족 발생

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

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

CPU 에서 느림

다음으로 시작하세요:

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

참고 자료

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