Szybki start z llama.cpp: CLI i serwer

Często powracam do llama.cpp do lokalnej inferencji – daje to kontrolę, którą Ollama i inne rozwiązania abstrahują, a po prostu to działa. Łatwo uruchamiać modele GGUF interaktywnie przy użyciu llama-cli lub wystawić kompatybilne z OpenAI HTTP API za pomocą llama-server.

Jeśli nadal wahasz się między podejściami lokalnymi, self-hosted a chmurowymi, zacznij od przewodnika filarowego LLM Hosting w 2026: Porównanie infrastruktury lokalnej, self-hosted i chmurowej.

Dlaczego llama.cpp w 2026 roku?

llama.cpp to lekki silnik inferencji z naciskiem na:

• przenośność między procesorami CPU i wieloma backendami GPU,
• przewidywalne opóźnienia na pojedynczym urządzeniu,
• elastyczność wdrożenia, od laptopów po węzły on-prem.

Szlachuje, gdy zależy Ci na prywatności i działaniu offline, gdy potrzebujesz deterministycznej kontroli nad flagami środowiska wykonawczego lub gdy chcesz zintegrować inferencję w większym systemie bez uruchamiania pełnego, opartego na Pythonie stosu.

Rozumienie llama.cpp jest również pomocne, nawet jeśli później wybierzesz środowisko wykonawcze o większej przepustowości. Na przykład, jeśli celem jest maksymalna przepustowość serwowania na kartach GPU, może warto porównać je z vLLM, używając: vLLM Quickstart: Wysokowydajne serwowanie LLM a wybory narzędziowe możesz przetestować w: Ollama vs vLLM vs LM Studio: Najlepszy sposób na uruchamianie LLM lokalnie w 2026?.

Instalacja llama.cpp na Windows, macOS i Linux

Istnieją trzy praktyczne ścieżki instalacji, w zależności od tego, czy zależy Ci na wygodzie, przenośności, czy maksymalnej wydajności.

Instalacja przez menedżery pakietów

To najszybsza opcja „uruchom i działaj".

# 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

Wskazówka: po instalacji zweryfikuj istnienie narzędzi:

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

Instalacja za pomocą gotowych binariów

Jeśli chcesz czystą instalację bez kompilatorów, użyj oficjalnych gotowych binariów opublikowanych w wydaniach llama.cpp na GitHubie. Zazwyczaj obejmują one wiele systemów operacyjnych i backendów (warianty tylko CPU oraz z obsługą GPU).

Typowy proces:

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

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

Budowa ze źródła dla Twojego dokładnego sprzętu

Jeśli zależy Ci na wydobywaniu maksymalnej wydajności z backendu CPU/GPU, zbuduj ze źródła przy użyciu CMake.

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

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

Po budowie binaria zazwyczaj znajdują się tutaj:

ls -la ./build/bin/

Budowa GPU w jednym poleceniu

Włącz backend pasujący do Twojego sprzętu (przykłady 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 budowy

Na Ubuntu 24.04 z kartą NVIDIA GPU potrzebujesz zestawu CUDA i OpenSSL przed budową. Oto przetestowana sekwencja:

1. Zainstaluj zestaw 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. 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 wykonaj source ~/.bashrc lub otwórz nowy terminal.

3. Zainstaluj nagłówki rozwijawcze OpenSSL (wymagane do czystej budowy):

sudo apt update
sudo apt install libssl-dev

4. Zbuduj llama.cpp (z katalogu zawierającego klon 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

W wyniku powstają llama-cli, llama-mtmd-cli, llama-server, llama-embedding oraz llama-gguf-split w katalogu llama.cpp.

Możesz też skompilować wiele backendów i wybierać urządzenia w czasie wykonania. Jest to przydatne, jeśli wdrażasz tę samą budowę na różnych maszynach.

Wybierz model GGUF i kwantyzację

Aby uruchomić inferencję, potrzebujesz pliku modelu GGUF (*.gguf). GGUF to format pojedynczego pliku, który łączy wagi modelu ze standaryzowanymi metadanymi wymaganymi przez silniki takie jak llama.cpp.

Dwa sposoby na uzyskanie modelu

Opcja A: Użyj lokalnego pliku GGUF

Pobierz lub skopiuj GGUF do ./models/:

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

Następnie uruchom go za ścieżką:

llama-cli -m models/my-model.gguf -p "Cześć! Wyjaśnij, czym jest llama.cpp." -n 128

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

Nowoczesne budowy llama.cpp mogą pobierać z Hugging Face i przechowywać pliki w lokalnej pamięci podręcznej. To często najłatwiejszy przepływ pracy dla 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 "Dawno, dawno temu," \
  -n 200

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 "Podsumuj koncepcję kwantyzacji w jednym akapicie." \
  -n 160

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

Wybór kwantyzacji dla lokalnej inferencji

Kwantyzacja to praktyczna odpowiedź na pytanie „Którą kwantyzację GGUF wybrać dla lokalnej inferencji", ponieważ bezpośrednio wymienia jakość, rozmiar modelu i szybkość.

Pragmatyczny punkt wyjścia:

• zacznij od wariantu Q4 lub Q5 dla maszyn z priorytetem CPU,
• przejdź do wyższej precyzji (lub mniej agresywnej kwantyzacji), gdy masz dostęp do RAM lub VRAM,
• gdy model „poczyna się głupio" dla Twojego zadania, rozwiązaniem jest często lepszy model lub mniej agresywna kwantyzacja, a nie tylko dostosowania próbkowania.

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

Szybki start llama-cli i kluczowe parametry

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

Minimalne uruchomienie

llama-cli \
  -m models/my-model.gguf \
  -p "Napisz krótkie porównanie TCP vs UDP." \
  -n 200

Interakcyjna sesja czatu

Tryb konwersacji jest zaprojektowany dla szablonów czatu. Zazwyczaj włącza zachowanie interaktywne i formatuje prompty zgodnie ze szablonem modelu.

llama-cli \
  -m models/my-model.gguf \
  --conversation \
  --system-prompt "Jesteś zwięzłym asystentem inżynierii systemowej." \
  --ctx-size 4096

Aby zakończyć generowanie, gdy model wyświetli określoną sekwencję, użyj promptu odwrotnego. Jest to szczególnie przydatne w trybie interaktywnym.

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

Zamiast zapamiętywać 200 flag, skup się na tych, które dominują poprawność, opóźnienia 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

Podsumuj plik, nie tylko prompt

llama-cli \
  -m models/my-model.gguf \
  --system-prompt "Podsumowujesz dokumenty techniczne. Wyjście maksymalnie pięć punktów." \
  --file ./docs/incident-report.txt \
  -n 300

Zrób wyniki bardziej powtarzalne

Gdy debugujesz prompty, ustal nasienie i zmniejsz losowość:

llama-cli \
  -m models/my-model.gguf \
  -p "Wyodrębnij kluczowe ryzyka z tej notatki projektowej." \
  -n 200 \
  --seed 42 \
  --temp 0.2

Szybki start llama-server z API kompatybilnym z OpenAI

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

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

Uruchom serwer 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ętrznym (np. wewnątrz Dockera lub w sieci 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": "Jesteś pomocnym asystentem." },
      { "role": "user", "content": "Daj mi szybki checklist llama.cpp." }
    ],
    "temperature": 0.7
  }'

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

Klient Python OpenAI celujący w llama-server

Z serwerem kompatybilnym z OpenAI, wiele klientów może działać poprzez zmianę tylko 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": "Jesteś zwięzłym asystentem."},
        {"role": "user", "content": "Wyjaśnij wątki vs rozmiar partii w llama.cpp."},
    ],
)

print(resp.choices[0].message.content)

Wektory (Embeddings)

Wektory kompatybilne z OpenAI są wystawione na /v1/embeddings, ale model musi obsługiwać tryb grupowania wektorów, który nie jest none.

curl http://localhost:8080/v1/embeddings \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer no-key" \
  -d '{
    "input": ["cześć", "świat"],
    "model": "GPT-4",
    "encoding_format": "float"
  }'

Jeśli uruchamiasz dedykowany model wektorowy, rozważ uruchomienie serwera w trybie tylko wektoró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 wektorowym 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 tak:

CUDA_VISIBLE_DEVICES="" llama-embedding \
  -m /path/to/Qwen3-Embedding-0.6B-Q8_0.gguf \
  -p "Twój tekst tutaj" \
  --pooling last \
  --verbose-prompt

Serwowanie wielu modeli z jednego procesu

Powyższe przykłady wiążą llama-server z pojedynczym modelem na starcie. Jeśli potrzebujesz przełączać między modelami w oparciu o żądanie – bez restartu procesu – do tego służy tryb routera. Zobacz llama-server router mode: dynamiczne przełączanie modeli bez restartów.

Wydajność, monitorowanie i hartowanie produkcyjne

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

• Limit pamięci jest zazwyczaj pierwszym ograniczeniem (RAM na CPU, VRAM na GPU).
• Rozmiar kontekstu to główny mnożnik zużycia pamięci.
• Offload warstw GPU to często najszybsza droga do wyższej liczby tokenów na sekundę.
• Rozmiary partii i wątki mogą poprawić przepustowość, ale też zwiększyć presję na pamięć.

Dla głębszego, inżynierskiego spojrzenia zobacz: Wydajność LLM w 2026: Testy, wąskie gardła i optymalizacja.

Jeśli chcesz zmierzone wyniki w stylu llama-cli dla GPU klasy 16 GB – tokeny na sekundę, VRAM i obciążenie GPU podczas przesuwanie kontekstu (19K / 32K / 64K) dla gęstych i MoE GGUF – zobacz Testy wydajności LLM z llama.cpp (prędkość i kontekst) na 16 GB VRAM.

Monitorowanie llama-server z Prometheus i Grafana

llama-server może wystawić metryki kompatybilne z Prometheus na /metrics, gdy --metrics jest włączone. To naturalnie pasuje do konfiguracji skanowania Prometheus i paneli Grafana.

Dla paneli i alertów specyficznych dla llama.cpp (i vLLM, TGI): Monitoruj inferencję LLM w produkcji (2026): Prometheus & Grafana dla vLLM, TGI, llama.cpp. Szersze przewodniki: Obserwowalność: Monitorowanie, metryki, Prometheus & Grafana Przewodnik i Obserwowalność dla systemów LLM.

Podstawowa lista kontroli hartowania

Gdy Twój llama-server jest osiągalny poza localhost:

• użyj --api-key (lub --api-key-file), aby żądania były autoryzowane,
• unikaj wiązania z 0.0.0.0, jeśli tego nie potrzebujesz,
• rozważ TLS przez flagi SSL serwera lub zakończ TLS na proxy odwróconym,
• ogranicz równoległość z --parallel, aby chronić opóźnienia pod obciążeniem.

Szybkie zwycięstwa przy rozwiązywaniu problemów

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

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

• użyć llama-cli --conversation plus jawnego --system-prompt,
• zweryfikować, czy Twój model to wariant instrukcyjny lub dostrojony do czatu,
• przetestować używając Web UI serwera przed podpięciem do aplikacji.

Zderzyłeś się z brakiem pamięci

Zmniejsz kontekst lub wybierz mniejszą kwantyzację:

• obniż --ctx-size,
• zmniejsz --n-gpu-layers, jeśli problemem jest VRAM,
• przełącz na mniejszy model lub bardziej skompresowaną kwantyzację.

Jest wolne na CPU

Zacznij od:

• --threads równej liczbie fizycznych rdzeni,
• umiarkowanych rozmiarów partii,
• zweryfikowania, czy zainstalowałeś budowę pasującą do Twojej maszyny (cechy CPU i backend).

Referencje

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