Szybki start z llama.cpp: CLI i serwer

Nieustannie wracam do llama.cpp do wnioskowania lokalnego – daje ono kontrolę, której Ollama i inne rozwiązania abstrahują, a po prostu działa. Łatwo uruchamiać modele GGUF interaktywnie za pomocą llama-cli lub narażać API HTTP zgodne z OpenAI za pomocą llama-server.

Jeśli nadal wahasz się między podejściami lokalnymi, self-hosted a chmurowymi, zacznij od przewodnika: Hosting LLM w 2026 roku: Infrastruktura Lokalna, Self-Hosted i Chmurowa w Porównaniu.

Dlaczego llama.cpp w 2026 roku?

llama.cpp to lekki silnik wnioskowania z naciskiem na:

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

Świeci się, gdy zależy Ci na prywatności i pracy offline, gdy potrzebujesz deterministycznej kontroli nad flagami czasu wykonania, lub gdy chcesz wkomponować wnioskowanie w większy system bez uruchamiania pełnego stosu opartego na Pythonie.

Zrozumienie llama.cpp jest przydatne nawet jeśli później wybierzesz silnik serwera o wyższej przepustowości. Na przykład, jeśli celem jest maksymalna przepustowość serwowania na GPU, możesz porównać go z vLLM korzystając z: vLLM Quickstart: Wysoka Wydajność Serwisowania LLM oraz możesz przetestować narzędzia w: Ollama vs vLLM vs LM Studio: Najlepszy Sposób Uruchamiania LLM Lokalnie w 2026 Roku?.

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 menadżerów pakietów

To najszybsza opcja „uruchom od razu”.

# 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 sprawdź, czy narzędzia istnieją:

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

Instalacja przez gotowe binaria

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 i włączone GPU).

Typowy przepływ pracy:

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

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

Kompilacja ze źródeł dla dokładnie Twojego sprzętu

Jeśli zależy Ci na wyciśnięciu najlepszej wydajności z backendu CPU/GPU, skompiluj ze źródeł używając CMake.

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

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

Po kompilacji binaria znajdują się zazwyczaj tutaj:

ls -la ./build/bin/

Budowanie dla 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 budowania

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

1. Instalacja zestawu narzędzi 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 swojego środowiska (dodaj do ~/.bashrc):

# zestaw narzędzi cuda
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 do czystego budowania):

sudo apt update
sudo apt install libssl-dev

4. Skompiluj 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

Tworzy to 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 wykonania. Jest to przydatne, jeśli wdrażasz tę samą kompilację na heterogenicznych maszynach.

Wybierz model GGUF i kwantyzację

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

Dwa sposoby uzyskania 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 poprzez ś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 kompilacje llama.cpp mogą pobierać z Hugging Face i przechowywać pliki w lokalnej pamięci podręcznej. Jest 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 "Było sobie czarną nocą," \
  -n 200

Możesz również 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 zapobiega dostępowi do sieci.

Wybór kwantyzacji do wnioskowania lokalnego

Kwantyzacja to praktyczna odpowiedź na pytanie „Jaki kwant GGUF wybrać do wnioskowania lokalnego”, ponieważ bezpośrednio wymienia jakość, rozmiar modelu i szybkość.

Pragmatyczny punkt wyjścia:

• 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 „wydaje się głupi” dla Twojego zadania, rozwiązaniem jest często lepszy model lub mniej agresywna kwantyzacja, a nie tylko ustawienia próbkowania.

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

Szybki start llama-cli i kluczowe parametry

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

Minimalne uruchomienie

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

Interaktywna rozmowa

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 wydrukuje określoną sekwencję, użyj odwrotnego promptu (reverse prompt). 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ą w poprawności, latencji i pamięci.

Model i pobieranie

Kontekst i przepustowość

Offloading 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

Podczas debugowania promptów, ustal seed i zmniejsz losowość:

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

Szybki start llama-server z API zgodnym z OpenAI

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

• punkty końcowe zgodne z OpenAI do czatu, ukończeń, embeddingów i odpowiedzi,
• interfejs Web UI do interaktywnego testowania,
• opcjonalne punkty końcowe monitoringu 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 związać zewnętrznie (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

Ukończenia 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 szybką checklistę llama.cpp." }
    ],
    "temperature": 0.7
  }'

Wskazówka dla rzeczywistych wdrożeń: jeśli ustawisz --api-key, możesz wysłać go przez nagłówek 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

Ze serwerem zgodnym z OpenAI, wiele klientów może działać, zmieniając 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)

Embeddingi

Embeddingi zgodne z OpenAI są narażone na /v1/embeddings, ale model musi obsługiwać tryb poolingu embeddingów różny od 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 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

Serwisowanie wielu modeli z jednego procesu

Przykłady powyżej wiążą llama-server z jednym modelem przy starcie. Jeśli musisz przełączać się między modelami na żądanie — bez restartowania procesu — oto po co służy tryb routera. Zobacz llama-server router mode: dynamiczne przełączanie modeli bez restartów. Dla skryptowalnego przepływu odładowania wszystkich modeli, który zwalnia VRAM bez restartowania routera, zobacz Odładuj Wszystkie Modele Routerowe llama.cpp Bez Restartowania.

Wydajność, monitoring i utwardzanie produkcyjne

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

• Sufit pamięci jest zazwyczaj pierwszym ograniczeniem (RAM na CPU, VRAM na GPU).
• Rozmiar kontekstu jest głównym mnożnikiem pamięci.
• Offloading warstw GPU to często najszybsza droga do wyższych tokenów na sekundę.
• Rozmiary partii i wątki mogą poprawić przepustowość, ale mogą również zwiększyć presję na pamięć.

Dla głębszej, inżynieryjnej perspektywy zobacz: Wydajność LLM w 2026 Roku: Benchmarki, Butelki i Optymalizacja.

Jeśli chcesz zmierzone wyniki w stylu llama-cli na GPU klasy 16 GB – tokeny na sekundę, VRAM i obciążenie GPU podczas skanowania kontekstu (19K / 32K / 64K) przez gęste i MoE GGUF-y – zobacz Benchmarki LLM 16 GB VRAM z llama.cpp (szybkość i kontekst).

Dla Qwen 3.6 specyficznie, llama.cpp teraz obsługuje wbudowane wielotokenowe przewidywanie (MTP) dekodowania spekulacyjnego, które może znacząco podnieść przepustowość generowania. Zobacz Qwen 3.6 27B i 35B MTP vs Standard na 16GB GPU dla zmierzonych szybkości generowania, narzutu VRAM i zalecanych wartości --spec-draft-n-max.

Monitorowanie llama-server z Prometheus i Grafana

llama-server może narażać metryki zgodne z Prometheus na /metrics, gdy --metrics jest włączone. To naturalnie łączy się z konfiguracjami skanowania Prometheus i dashboardami Grafana.

Dla dashboardów i alertów specyficznych dla llama.cpp (i vLLM, TGI): Monitoruj Wnioskowanie LLM w Produkcji (2026): Prometheus & Grafana dla vLLM, TGI, llama.cpp. Szersze przewodniki: Obserwowalność: Monitoring, Metryki, Prometheus & Grafana Guide i Obserwowalność dla Systemów LLM.

Podstawowa lista utwardzania

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

• użyj --api-key (lub --api-key-file), aby żądania były autoryzowane,
• unikaj wiązania z 0.0.0.0, chyba że jest to konieczne,
• rozważ TLS przez flagi SSL serwera lub terminację TLS na proxy odwrotnym,
• ogranicz równoległość z --parallel, aby chronić latencję pod obciążeniem.

Szybkie zwycięstwa w rozwiązywaniu problemów

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

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

• użyć llama-cli --conversation plus jawne --system-prompt,
• zweryfikować, czy Twój model to wariant instrukcyjny lub chat-tuned,
• przetestować używając interfejsu Web UI serwera przed podłączeniem go do aplikacji.

Trafiasz na błąd braku pamięci (out of memory)

Zmniejsz kontekst lub wybierz mniejszy kwant:

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

Wolno na CPU

Zacznij od:

• --threads równych Twoim fizycznym rdzeniom,
• umiarkowanych rozmiarów partii,
• weryfikacji, czy zainstalowałeś kompilację pasującą do Twojej maszyny (cechy CPU i backend).

Referencje

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