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

llama.cpp는 GGUF 모델용 C/C++ 추론 엔진입니다: 대화형 챗에는 llama-cli, 스크립트된 프롬프트에는 llama-completion, OpenAI 호환 HTTP API에는 llama-server를 제공합니다.

로컬, 셀프 호스팅, 클라우드 방식 중 어디를 선택해야 할지 고민 중이라면 LLM 호스팅 2026: 로컬, 셀프 호스팅 및 클라우드 인프라 비교라는 pilar 가이드부터 시작하는 것이 좋습니다.

2026년, 왜 llama.cpp인가

llama.cpp는 다음과 같은 방향으로 편향된 경량 추론 엔진입니다:

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

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

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

만약 llama-server와 비교 고려 중인 대안이 Ollama라면, llama.cpp vs Ollama (2026년)는 Ollama를 유지할 때와 직접 llama.cpp로 전환할 때의 구체적 트리거를 포함한 전용 페어비즈 비교입니다.

Windows, macOS, Linux에 llama.cpp 설치

아래 명령어들은 llama.cpp v0.6.0 (2026년 10월 5일)에 적합합니다. 동일한 런타임에 대한 카탈로그 항목 — 빌드 커밋으로 버전 관리되는 CPU 및 가속기 백엔드용 GGUF 추론 — 은 LLM Systems의 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

# Ubuntu (universe). This package lags upstream by a long way:
# 8681+dfsg against current build b11433 / v0.6.0, so newer flags will be missing.
sudo apt install llama.cpp-tools

팁: 설치 후 도구가 존재하는지 확인하십시오:

llama-cli --version
llama-completion --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

공식 컨테이너 실행

该项目是发布在 GitHub Container Registry 上的服务器镜像. CPU 镜像是 ghcr.io/ggml-org/llama.cpp:server, CUDA 镜像是 :server-cuda. 容器必须监听所有接口,因为默认绑定仍然是 127.0.0.1:

docker run --gpus all -p 8080:8080 \
  -v /path/to/models:/models \
  ghcr.io/ggml-org/llama.cpp:server-cuda \
  -m models/my-model.gguf -c 4096 --host 0.0.0.0 -ngl all

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

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

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

1. CUDA 툴킷 13.1 설치. 이 walkthrough는 13.1.1 로컬 설치기를 고정합니다. NVIDIA의 Ubuntu 24.04 저장소에서 더 새로운 툴킷을 사용할 경우, 업데이트된 파일명을 가지고 동일한 pin 파일 및 로컬 deb 단계를 따릅니다.

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 -st

옵션 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 \
  -st

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

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

나중에 완전한 오프라인 워크플로를 필요로 한다면, --offline은 캐시 사용을 강제하고 네트워크 접근을 방지합니다.

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

양자화는 “로컬 추론에 어떤 GGUF 양자화를 선택해야 하는가"라는 질문에 대한 실용적인 답으로, 품질, 모델 크기, 속도를 직접 트레이드오프합니다.

실용적인 시작점:

• CPU 우선 머신에는 Q4 또는 Q5 변형으로 시작,
• RAM 또는 VRAM을 감당할 수 있을 때 더 높은 정밀도로 (또는 덜 공격적인 양자화로) 이동,
• 모델이 작업에 대해 “멍청하게 느껴질” 때, 해결책은 종종 더 나은 모델이거나 덜 공격적인 양자화이며, 샘플링 조정만으로는 부족합니다.

또한 컨텍스트 윈도우가 중요하다는 점을 기억하십시오: GGUF 파일 자체가 들어맞더라도 더 큰 컨텍스트 크기는 메모리 사용량(때로는 극적으로)을 증가시킵니다.

llama-cli 퀵스타트 및 주요 파라미터

llama-cli는 모델이 로드되고, 백엔드가 작동하며, 프롬프트가 의도대로 작동하는지 확인하는 가장 빠른 방법입니다.

2025년 12월 재작성 이후, llama-cli는 대화형 챗 클라이언트였습니다. 모델이 챗 템플릿을 함께 제공하면, 대화 모드가 기본으로 켜지고, --no-conversation은 llama-completion을 가리키는 포인터와 함께 거부됩니다. 그 두 번째 바이너리는 구버전의 llama-cli로, 하나의 프롬프트를 입력하고 하나의 보전을 출력하여, 스크립트 및 파이프에 적합합니다. 새 클라이언트에서, --single-turn (-st)은 한 번의 응답을 생성하고 종료합니다.

한 번의 응답, 그리고 종료

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

비대화형 바이너리를 통한 동일한 프롬프트:

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

대화형 챗 실행

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

--conversation은 더 이상 필요하지 않습니다. 모델이 특정 시퀀스를 출력할 때 생성을 종료하려면, 리버스 프롬프트를 사용하십시오.

중요한 주요 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 \
  -st

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

프롬프트 디버깅 중에는 시드를 고정하고 무작위성을 줄이십시오:

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

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만 변경하여 작동할 수 있으며 — 이것은 lukeswade/deep-research와 같은 연구 에이전트들이 별도의 어댑터 레이어 없이 llama-server와 직접 대화하는 방식이기도 합니다. 셀프 호스팅 딥 리서치 시스템: 12가지 도구 비교는 OpenAI 호환 로컬 엔드포인트를 가리키는 그 프로젝트 및 다른 프로젝트들을 다룹니다.

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 성능: 벤치마크, 병목 및 최적화.

측정된 llama-cli 스타일 결과, 16 GB 클래스 GPU에서 — 초당 토큰, VRAM, 컨텍스트(19K / 32K / 64K)를 스윕하면서 밀집 및 MoE GGUF를 가로지르는 GPU 로드 — 에 대한 내용은 16 GB VRAM LLM 벤치마크 (llama.cpp로) (속도와 컨텍스트)를 참조하십시오.

Qwen 3.6에 대해, llama.cpp은 내장된 Multi-Token Prediction 스펙ュ레이티브 디코딩을 지원합니다. --spec-type draft-mtp로 켜십시오; --spec-draft-n-max는 드래프트 헤드가 제안하는 토큰 수를 설정합니다 (기본 3). v0.6.0은 동일한 MTP 경로를 Qwen4Exp로 확장합니다. 메서드 비교에 대해서는 스펙ュ레이티브 디코딩을, 16 GB에서 측정된 Qwen 3.6 숫자에 대해서는 Qwen 3.6 MTP vs Standard (16GB GPU)를 참조하십시오.

Prometheus와 Grafana로 llama-server 모니터링

--metrics가 활성화되어 있을 때만, llama-server는 /metrics에 Prometheus 호환 메트릭을 노출합니다. Prometheus 스크레프 잡을 해당 경로로 지정하십시오. llama.cpp, vLLM, TGI에 대한 대시보드 및 얼럿 임계값은 프로덕션에서 LLM 추론 모니터링 (2026): Prometheus & Grafana for vLLM, TGI, llama.cpp에 있습니다.

기본 하드닝 체크리스트

llama-server가 localhost 이상에서 도달 가능할 때:

• --api-key (또는 --api-key-file)를 사용하여 요청이 인증되도록 하십시오,
• 필요하지 않다면 0.0.0.0에 바인딩하지 마십시오,
• 서버의 SSL 플래그를 통해 또는 리버스 프록시에서 TLS 종료를 고려하십시오,
• --parallel로 동시성을 제한하여 하중에서 레이턴시를 보호하십시오,
• --tools와 --agent를 꺼두십시오. 둘 다 실험적이며 API를 통해 파일 및 셸 작업을 노출합니다; 어느 것을 활성화하든 CORS를 localhost로 제한합니다.

트러블슈팅 퀵 윈

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

챗 엔드포인트는 모델이 지원되는 챗 템플릿을 가질 때 최적입니다. 출력이 구조화되지 않아 보이면, 다음을 시도하십시오:

• 명시적인 --system-prompt 전달 (llama-cli에서 대화 모드는 이미 기본입니다),
• 모델이 인스트럭션 또는 챗 튜닝 변형인지 확인,
• 앱에 연결하기 전에 서버 웹 UI로 테스트. v0.6.0은 Hugging Face Hub 브라우저로 그 UI를 재구축했기 때문에, 모델은 CLI에서만이 아닌 페이지에서 다운로드될 수 있습니다.

사고 모델은 답변을 추론 트레이스에 감싸서 제공합니다. --reasoning off는 그것을 억제하고, --reasoning-format deepseek는 트레이스를 content 대신 reasoning_content으로 이동시킵니다.

메모리 부족에 도달함

컨텍스트를 줄이거나 더 작은 양자화를 선택하십시오:

• --ctx-size를 낮추기,
• VRAM이 문제라면 --n-gpu-layers를 줄이거나, MoE 모델의 전문가 가중치가 RAM에 남도록 --cpu-moe를 설정하기,
• 더 작은 모델 또는 더 압축된 양자로 전환하기,
• --cache-type-k q8_0 --cache-type-v q8_0로 KV 캐시를 양자화하기.

컨텍스트 또는 GPU 분할이 요청한 것과 다름

--fit은 기본적으로 켜져 있으며, 사용자가 설정하지 않은 메모리 설정을 재작성하여, 각 장치에서 1024 MiB를 비우기를 목표로 합니다 (--fit-target). 이는 컨텍스트를 축소할 수 있지만, --fit-ctx (4096) 아래로는 절대 내려가지 않으며, -c를 전달하지 않은 경우에만 그렇습니다. -ngl을 전달하면 레이어 배치에 건드리지 않습니다. --fit off는 메커니즘을 비활성화합니다. 로그가 n_gpu_layers already set by user라고 말하면, 명시적인 -ngl이 로드되었고, fit은 메모리 부족을 구제하지 못할 것입니다.

CPU에서 느림

다음으로 시작하십시오:

• 물리적 코어와 동일한 --threads,
• 중간 배치 크기,
• 기계와 일치하는 빌드(CPU 기능 및 백엔드)를 설치했는지 검증.

레퍼런스

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