Szybki start z llama.cpp: CLI i serwer

llama.cpp to silnik inferencji w językach C/C++ dla modeli GGUF: llama-cli do interaktywnego czatu, llama-completion do skryptowych promptów oraz llama-server dla kompatybilnego z OpenAI interfejsu API HTTP.

Jeśli nadal wahasz się między podejściami lokalnymi, self-hosted oraz chmurowymi, zacznij od przewodnika głównego LLM Hosting in 2026: Local, Self-Hosted & Cloud Infrastructure Compared.

Dlaczego llama.cpp w 2026

llama.cpp to lekki silnik inferencji z nastawieniem na:

• przenośność między CPU i wieloma backendami GPU,
• przewidywalną latencję na pojedynczej maszynie,
• elastyczność wdrożeń, od laptopów po węzły on-prem.

Wyróżnia się, gdy cenisz prywatność i działanie offline, gdy potrzebujesz deterministycznej kontroli nad flagami czasu uruchomienia, lub gdy chcesz osadzić inferencję w większym systemie bez uruchamiania pełnego, obciążonego Pythonem stosu.

Rozumienie llama.cpp jest przydatne nawet wtedy, gdy później wybierzesz serwer o wyższej przepustowości. Na przykład, jeśli Twoim celem jest maksymalna przepustowość obsługuwania zapytań na GPU, możesz chcieć porównać go z vLLM, używając: vLLM Quickstart: High-Performance LLM Serving oraz możesz przeprowadzić benchmarki wyborów narzędzi w: Ollama vs vLLM vs LM Studio: Best Way to Run LLMs Locally in 2026?.

Jeśli konkretnie Ollama jest alternatywą, którą rozważasz w porównaniu z llama-server, llama.cpp vs Ollama in 2026 to dedykowane porównanie parami, z konkretnymi wskazówkami, kiedy pozostać przy Ollamie, a kiedy przejść na bezpośrednie llama.cpp.

Instalacja llama.cpp na Windows, macOS i Linuxie

Polecenia poniżej odpowiadają wersji llama.cpp v0.6.0 (5 października 2026). Katalogowa pozycja dla tego samego runtime’u — inferencja GGUF na CPU i backendach przyspieszonych, wersjonowana przez commit budowy — znajduje się w referencji runtime llama.cpp na LLM Systems. Istnieje cztery praktyczne ścieżki instalacji, w zależności od tego, czy preferujesz wygodę, przenośność, czy maksymalną wydajność.

Instalacja za pomocą menedżerów pakietów

To najszybsza opcja „działania”.

# macOS lub Linux
brew install llama.cpp

# Windows
winget install llama.cpp

# macOS (MacPorts)
sudo port install llama.cpp

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

# Ubuntu (universe). Ten pakiet znacznie opóźnia się względem wersji górnej:
# 8681+dfsg w porównaniu z aktualnym buildem b11433 / v0.6.0, więc nowe flagi będą brakować.
sudo apt install llama.cpp-tools

Wskazówka: po instalacji sprawdź, czy narzędzia istnieją:

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

Instalacja z prezbudowanych binariów

Jeśli chcesz czystą instalację bez kompilatorów, użyj oficjalnych prezbudowanych binariów opublikowanych w release’ach GitHub llama.cpp. Zazwyczaj obejmują one wiele systemów operacyjnych i wiele backendów (warianty tylko CPU i z GPU).

Typowy workflow:

# 1) Pobierz odpowiedni archiwum dla swojego systemu i backendu
# 2) Rozpakuj je
# 3) Uruchom z rozpakowanego folderu

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

Uruchomienie oficjalnego kontenera

Projekt publikuje obrazy serwerowe w GitHub Container Registry. Obraz CPU to ghcr.io/ggml-org/llama.cpp:server; obraz CUDA to :server-cuda. Kontener musi nasłuchiwać na wszystkich interfejsach, ponieważ domyślne wiązanie nadal wynosi 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

Budowanie z kodu źródłowego pod Twój sprzęt

Jeśli zależy Ci na wyciśnięciu najlepszych wydajności z backendu CPU/GPU, zbuduj projekt z kodu źródłowego za pomocą CMake.

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

# Budowanie CPU
cmake -B build
cmake --build build --config Release

Po budowie binaria znajdują się zazwyczaj tutaj:

ls -la ./build/bin/

Budowanie GPU w jednym poleceniu

Włącz backend odpowiadający Twojemu sprzętowi (przykłady pokazane dla CUDA i 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 + GPU NVIDIA: pełny przewodnik po budowaniu

Na Ubuntu 24.04 z GPU NVIDIA potrzebujesz narzędzia CUDA toolkit i OpenSSL przed budowaniem. Oto przetestowana sekwencja:

1. Zainstaluj CUDA toolkit 13.1. Ten przewodnik przypina lokalny instalator 13.1.1. Nowsze narzędzie z repozytorium Ubuntu 24.04 od NVIDIA stosuje te same kroki z plikiem pin i lokalnym deb, z zaktualizowanymi nazwami plików.

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. Dodaj CUDA do środowiska (dopisz do ~/.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

Następnie uruchom source ~/.bashrc lub otwórz nowy terminal.

3. Zainstaluj nagłówki deweloperskie OpenSSL (wymagane dla czystego budowania):

sudo apt update
sudo apt install libssl-dev

4. Zbuduj llama.cpp (z katalogu zawierającego Twój klony llama.cpp, z włączonym 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

Dzieło to generuje llama-cli, llama-mtmd-cli, llama-server, llama-embedding oraz llama-gguf-split w katalogu llama.cpp.

Możesz również skompilować wiele backendów i wybierać urządzenia w czasie działania. Jest to przydatne, jeśli wdrażasz ten sam build na jednorodnych maszynach.

Wybór modelu GGUF i kwantyzacji

Aby uruchomić inferencję, potrzebujesz pliku modelu GGUF (*.gguf). GGUF to format pojedynczego pliku, który wiąże wagi modelu wraz ze znormalizowanymi metadadanymi potrzebnymi silnikom takim jak llama.cpp.

Dwa sposoby uzyskania modelu

Opcja A: Użyj lokalnego pliku GGUF

Pobierz lub skopiuj GGUF do ./models/:

mkdir -p models
# Umieść Twój GGUF w models/my-model.gguf

Następnie uruchom go przez ścieżkę:

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

Opcja B: Pozwól llama.cpp pobierać z Hugging Face

Nowoczesne buildy llama.cpp mogą pobierać z Hugging Face i przechowywać pliki w lokalnej pamięci podręcznej. To często najłatwiejszy workflow do szybkich eksperymentów.

# Pobierz model z HF i uruchom prompt
llama-cli \
  --hf-repo ggml-org/tiny-llamas \
  --hf-file stories15M-q4_0.gguf \
  -p "Once upon a time," \
  -n 200 \
  -st

Możesz też określić kwantyzację w selektorze repozytorium i pozwolić narzędziu wybrać pasujący plik:

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

Jeśli później potrzebujesz w pełni offline’owego workflow, --offline wymusza użycie pamięci podręcznej i blokuje dostęp do sieci.

Wybór kwantyzacji do lokalnej inferencji

Kwantyzacja jest praktyczną odpowiedzią na pytanie „Która kwantyzacja GGUF powinnaś wybrać do lokalnej inferencji”, ponieważ bezpośrednio wymienia jakość, rozmiar modelu i szybkość.

Pragmatyczny punkt startowy:

• zacznij od wariantu Q4 lub Q5 dla maszyn opartych na CPU,
• przejdź do wyższej precyzji (lub mniej agresywnej kwantyzacji), gdy możesz sobie pozwolić na RAM lub VRAM,
• gdy model „działa głupio” w Twoim zadaniu, rozwiązaniem jest często lepszy model lub mniej agresywna kwantyzacja, a nie tylko dostosowanie próbkowania.

Pamiętaj również, że okno kontekstowe ma znaczenie: większe rozmiary kontekstu zwiększają zużycie pamięci (czasami dramatycznie), nawet jeśli sam plik GGUF się mieści.

Szybki start llama-cli i kluczowe parametry

llama-cli to najszybszy sposób, aby zweryfikować, że Twój model się ładuje, backend działa, a prompty zachowują się poprawnie.

llama-cli jest interaktywnym klientem czatu od przebudowania z grudnia 2025 r. Gdy model dostarcza szablon czatu, tryb konwersacji jest włączony domyślnie, a --no-conversation jest odrzucane z odniesieniem do llama-completion. Ten drugi binar to stary llama-cli: jeden prompt wejściowy, jeden wynik wyjściowy, odpowiedni do skryptów i potoków. Z nowego klienta, --single-turn (-st) generuje jedną odpowiedź i wychodzi.

Jedna odpowiedź, potem wyjście

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

Ten sam prompt przez binar nieliteraktywny:

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

Interaktywna sesja czatu

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

--conversation nie jest już wymagane. Aby zakończyć generowanie, gdy model wyświetli konkretną sekwencję, użyj promptu odwrotnego.

Główne flagi llama-cli, które mają znaczenie

Zamiast zapamiętywać 200 flag, skup się na tych, które dominują poprawność, latencję i pamięć.

Model i pobieranie

Kontekst i przepustowość

Offload GPU i wybór sprzętu

Próbkowanie i jakość wyjścia

Przykładowe obciążenia z llama-cli

Podsumowanie pliku, nie tylko promptu

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

Uczynienie wyników bardziej odtwarzalnymi

Gdy debugujesz prompty, ustabilizuj ziarno i zmniejsz losowość:

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

Szybki start llama-server z kompatybilnym z OpenAI API

llama-server to wbudowany serwer HTTP, który może udostępniać:

• kompatybilne z OpenAI punkty końcowe dla czatu, uzupełnień, embeddingów i odpowiedzi,
• interfejs webowy do testów interaktywnych,
• opcjonalne punkty końcowe monitorowania dla widoczności produkcyjnej.

Uruchomienie serwera z lokalnym modelem

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

Domyślnie nasłuchuje na 127.0.0.1:8080.

Aby powiązać zewnętrznie (np. w Dockerze lub LAN), określ host i port:

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

Opcjonalne, ale ważne flagi serwera

Jeśli uruchamiasz w kontenerach, wiele ustawień można również kontrolować przez zmienne środowiskowe LLAMA_ARG_*.

Przykładowe wywołania API

Uzupełnienia czatu z 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
  }'

Wskazówka dla rzeczywistych wdrożeń: jeśli ustawisz --api-key, możesz go wysłać przez nagłówek x-api-key (lub nadal używać nagłówków Authorization, w zależności od Twojej bramki).

Klient Pythona OpenAI kierujący na llama-server

Z kompatybilnym z OpenAI serwerem, wiele klientów może działać przez zmianę tylko base_url — tak też agenci badawczy tacy jak lukeswade/deep-research komunikują się bezpośrednio z llama-server, bez oddzielnej warstwy adaptera. Self-Hosted Deep Research Systems: 12 Tools Compared opisuje ten projekt i inne skierowane na kompatybilne lokalne punkty końcowe 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)

Embeddingi

Kompatybilne z OpenAI embeddingi są udostępnione w /v1/embeddings, ale model musi obsługiwać tryb poolingowania embeddingów, który nie jest 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"
  }'

Jeśli uruchamiasz dedykowany model embeddingowy, rozważ uruchomienie serwera w trybie tylko embeddingów:

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

lub jeśli chcesz uruchomić llama-cpp z modelem embeddingowym na CPU:

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

spróbuj w ten sposób:

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

Serwowanie wielu modeli z jednego procesu

Powyższe przykłady wiążą llama-server z pojedynczym modelem przy starcie. Jeśli potrzebujesz przełączania między modelami per zapytanie — bez restartu procesu — to do tego służy tryb routera. Zobacz llama-server router mode: dynamic model switching without restarts. Dla skryptowalnego przepływu odładowywania wszystkich modeli, który zwalnia VRAM bez restartu routera, zobacz Unload All llama.cpp Router Models Without Restarting.

Wydajność, monitorowanie i wzmacnianie produkcyjne

Pytanie FAQ „Które opcje linii komend llama.cpp mają największe znaczenie dla szybkości i pamięci” staje się znacznie łatwiejsze, gdy traktujesz inferencję jak system:

• Limit pamięci to zwykle pierwsze ograniczenie (RAM na CPU, VRAM na GPU).
• Rozmiar kontekstu to duży mnożnik pamięci.
• Offload warstw GPU to często najszybsza droga do wyższej liczby tokenów na sekundę.
• Rozmiary batchy i wątki mogą poprawić przepustowość, ale mogą też zwiększyć presję na pamięć.

Dla głębszego, inżynierskiego punktu widzenia, zobacz: LLM Performance in 2026: Benchmarks, Bottlenecks & Optimization.

Jeśli chcesz zmierzonych wyników w stylu llama-cli na GPU klasy 16 GB — tokeny na sekundę, VRAM i obciążenie GPU podczas zmieniania kontekstu (19K / 32K / 64K) dla gęstych i MoE GGUF — zobacz 16 GB VRAM LLM benchmarks with llama.cpp (speed and context).

Dla Qwen 3.6, llama.cpp obsługuje wbudowane spekulatoryczne dekodowanie Multi-Token Prediction. Włącz je za pomocą --spec-type draft-mtp; --spec-draft-n-max ustawia, ile tokenów głowa draft proponuje (domyślnie 3). Wersja v0.6.0 rozszerza tę samą ścieżkę MTP na Qwen4Exp. Dla porównania metod, zobacz Speculative Decoding. Dla zmierzonych wyników Qwen 3.6 na 16 GB, zobacz Qwen 3.6 MTP vs Standard on 16GB GPU.

Monitorowanie llama-server z Prometheus i Grafana

llama-server udostępnia kompatybilne z Prometheus metryki w /metrics tylko wtedy, gdy włączony jest --metrics. Skieruj zadanie scrapingu Prometheus na tę ścieżkę. Pulpity i progi alertów dla llama.cpp, vLLM i TGI znajdują się w Monitor LLM Inference in Production (2026): Prometheus & Grafana for vLLM, TGI, llama.cpp.

Podstawowa lista kontrolna wzmacniania

Gdy Twój llama-server jest dostępny poza localhostem:

• użyj --api-key (lub --api-key-file), aby zapytania były uwierzytelnione,
• unikaj wiązania z 0.0.0.0, chyba że tego potrzebujesz,
• rozważ TLS przez flagi SSL serwera lub kończenie TLS w proxy odwrotnym,
• ogranicz równoległość za pomocą --parallel, aby chronić latencję pod obciążeniem,
• zostaw --tools i --agent wyłączone. Oba są eksperymentalne i ujawniają operacje plików i powłoki przez API; włączenie któregokolwiek ogranicza również CORS do localhostu.

Szybkie rozwiązania problemów

Model się ładuje, ale odpowiedzi w czacie są dziwne

Punkty końcowe czatu działają najlepiej, gdy model ma wspierany szablon czatu. Jeśli wyjścia wyglądają na nieustrukturyzowane, spróbuj:

• przekazać jawny --system-prompt (tryb konwersacji jest już domyślny w llama-cli),
• zweryfikować, że Twój model to wariant dostrojony do instrukcji lub czatu,
• przetestować za pomocą interfejsu webowego serwera, zanim podłączysz go do aplikacji. Wersja v0.6.0 przebudowała ten interfejs z przeglądarką Hugging Face Hub, więc model można pobrać ze strony, a nie tylko z CLI.

Modele myślowe owijają odpowiedź w ślady rozumowania. --reasoning off tłumi to, a --reasoning-format deepseek przenosi ślad do reasoning_content zamiast content.

Uderzyłeś w limit pamięci

Zmniejsz kontekst lub wybierz mniejszą kwantyzację:

• obniż --ctx-size,
• zmniejsz --n-gpu-layers, jeśli problemem jest VRAM, lub ustaw --cpu-moe, aby wagi ekspertów modelu MoE pozostały w RAM,
• przejdź na mniejszy model lub bardziej skompresowaną kwantyzację,
• skwantyzuj pamięć podręczną KV za pomocą --cache-type-k q8_0 --cache-type-v q8_0.

Kontekst lub podział GPU nie jest taki, o który prosiłeś

--fit jest domyślnie włączony i przepisuje ustawienia pamięci, które nie ustawiłeś, dążąc do pozostawienia 1024 MiB wolnego na każdym urządzeniu (--fit-target). Zmniejszy kontekst, ale nigdy poniżej --fit-ctx (4096) i tylko wtedy, gdy nie przekazałeś -c. Nie dotknie rozmieszczenia warstw, gdy przekazesz jakikolwiek -ngl. --fit off dezaktywuje mechanizm. Jeśli logi mówią n_gpu_layers already set by user, to Twój jawny -ngl się załadował, a fit nie uratuje przed brakiem pamięci z niego.

To wolne na CPU

Zacznij od:

• --threads równych Twoim fizycznym rdzeniom,
• umiarkowanych rozmiarów batchy,
• zweryfikowania, że zainstalowałeś build odpowiadający Twojej maszynie (cechy CPU i backend).

Referencje

• Oficjalne repozytorium i dokumentacja llama.cpp
• Oficjalna dokumentacja flag CLI
• Oficjalna dokumentacja llama-server i szczegóły API