Szybki start z llama.cpp za pomocą CLI i serwera

Zawsze wracam do llama.cpp dla lokalnego wnioskowania – daje Ci kontrolę, którą Ollama i inni abstrahują, a po prostu działa. Łatwe uruchomienie modeli GGUF interaktywnie za pomocą llama-cli lub udostępnienie OpenAI-kompatybilnego HTTP API za pomocą llama-server.

Jeśli nadal decydujesz się między lokalnym, samowystarczalnym a chmurowym podejściem, zacznij od przewodnika podstawowego Hostowanie LLM w 2026: Porównanie lokalnego, samowystarczalnego i infrastruktury chmurowej.

Dlaczego llama.cpp w 2026

llama.cpp to lekki silnik wnioskowania z namiętnością do:

• przenośności między procesorami CPU i wieloma backendami GPU,
• przewidywalnej opóźnienia na jednym urządzeniu,
• elastyczności wdrażania, od laptopów do wewnętrznych węzłów.

Świetnie sprawdza się, gdy chcesz prywatność i działanie offline, gdy potrzebujesz deterministycznej kontroli nad flagami uruchomienia, lub gdy chcesz osadzić wnioskowanie w większym systemie bez uruchamiania pełnego stosu Pythona.

Jest również pomocne zrozumienie llama.cpp, nawet jeśli później wybierzesz bardziej wydajny serwerowy czas wykonywania. Na przykład, jeśli Twoim celem jest maksymalna wydajność serwowania na GPU, możesz również porównać ją z vLLM korzystając z: Przewodnika szybkiego startu vLLM: Wysokowydajne serwowanie LLM a możesz przeprowadzić testy narzędzi 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 instalacyjne, w zależności od tego, czy chcesz wygody, przenośności, czy maksymalnej wydajności.

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

To najszybszy sposób na „uruchomienie”.

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

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

Instalacja za pomocą gotowych binarnek

Jeśli chcesz czystą instalację bez kompilatorów, użyj oficjalnych gotowych binarnek opublikowanych w repozytorium llama.cpp GitHub. Zwykle obejmują one wiele celów systemowych i wielu backendów (wersje tylko z CPU i z włączonymi GPU).

Typowa praca:

# 1) Pobierz odpowiedni archiwum dla swojego systemu i backendu
# 2) Wyodrębnij je
# 3) Uruchom z wyodrębnionego folderu

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

Budowa z źródła dla Twojego sprzętu

Jeśli zależy Ci na wyciągnięciu maksymalnej wydajności z Twojego backendu CPU/GPU, zbuduj z źródła za pomocą CMake.

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

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

Po budowie, binarki są zazwyczaj 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

Pełny przewodnik budowy dla Ubuntu 24.04 + NVIDIA GPU

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

1. Zainstaluj CUDA Toolkit 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):

# 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 rozwojowe OpenSSL (wymagane do czystej budowy):

sudo apt update
sudo apt install libssl-dev

4. Buduj llama.cpp (z katalogu zawierającego Twoją klonowaną wersję 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
cp llama.cpp/build/bin/llama-* llama.cpp

To generuje llama-cli, llama-mtmd-cli, llama-server i llama-gguf-split w katalogu llama.cpp.

Możesz również kompilować wiele backendów i wybierać urządzenia w czasie wykonywania. Jest to przydatne, jeśli wdrażasz tę samą kompilację na maszynach heterogenicznych.

Wybierz model GGUF i kwantyzację

Aby uruchomić wnioskowanie, potrzebujesz pliku modelu GGUF (*.gguf). GGUF to jednoplikowy format, który łączy wagi modelu oraz standaryzowane metadane potrzebne silnikom takim jak llama.cpp.

Dwa sposoby na uzyskanie modelu

Opcja A: Użyj lokalnego pliku GGUF

Pobierz lub skopiuj plik GGUF do ./models/:

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

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

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

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

Nowoczesne kompilacje llama.cpp mogą pobrać z Hugging Face i przechowywać pliki w lokalnym katalogu cache. Jest to często najprostszy sposób 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 "Kiedyś, w pewnym miejscu," \
  -n 200

Możesz również określić kwantyzację w selektorze repozytorium i pozwolić narzędziu wybrać dopasowany plik:

llama-cli \
  --hf-repo unsloth/phi-4-GGUF:q4_k_m \
  -p "Streszczenie koncepcji kwantyzacji w jednym akapicie." \
  -n 160

Jeśli w przyszłości potrzebujesz pełnego działania offline, --offline wymusza użycie cache i uniemożliwia dostęp do sieci.

Wybór kwantyzacji dla wnioskowania lokalnego

Kwantyzacja to praktyczna odpowiedź na pytanie „Która kwantyzacja GGUF powinna być wybrana dla lokalnego wnioskowania”, ponieważ bezpośrednio wymienia jakość, rozmiar modelu i prędkość.

Praktyczny punkt wyjścia:

• zacznij od wersji Q4 lub Q5 dla maszyn zorientowanych na CPU,
• przechodź do wyższej precyzji (lub mniej agresywnej kwantyzacji), gdy możesz pozwolić sobie na RAM lub VRAM,
• gdy model „wydaje się głupi” dla Twojej pracy, naprawa często polega na lepszym modelu lub mniej agresywnej kwantyzacji, a nie tylko na ustawieniach próbkowania.

Pamiętaj również, że rozmiar kontekstu ma znaczenie: większe rozmiary kontekstu zwiększają użycie pamięci (czasem dramatycznie), nawet jeśli sam plik GGUF pasuje.

Szybki start llama-cli i kluczowe parametry

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

Minimalne uruchomienie

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

Uruchomienie rozmowy interaktywnej

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

llama-cli \
  -m models/my-model.gguf \
  --conversation \
  --system-prompt "Jestes pomocnym asystentem inżynierii systemowej." \
  --ctx-size 4096

Aby zakończyć generację, gdy model wypisuje określony ciąg, użyj odwrotnego promptu. 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ścią, opóźnieniem i pamięcią.

Model i pobieranie

Kontekst i przepustowość

Wydajność GPU i wybór sprzętu

Próbkowanie i jakość wyjścia

Przykładowe zadania z llama-cli

Streszczenie pliku, nie tylko promptu

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

Zrób wyniki bardziej powtarzalne

Kiedy debugujesz prompty, ustal seed i zmniejsz losowość:

llama-cli \
  -m models/my-model.gguf \
  -p "Wyodrębnij główne 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 udostępniać:

• kompatybilne z OpenAI punkty końcowe dla rozmów, uzupełnień, embeddingów i odpowiedzi,
• interaktywny interfejs WWW,
• 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ętrznie (np. wewnątrz Docker 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 rozmowy 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": "Jestes 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ć ją za pomocą nagłówka x-api-key (lub kontynuować użycie nagłówków Authorization w zależności od bramy).

Klient Pythona OpenAI wskazujący na llama-server

Z serwerem kompatybilnym 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": "Jestes skrótowym asystentem."},
        {"role": "user", "content": "Wyjaśnij wątki vs rozmiar batch w llama.cpp."}
    ],
)

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

Embeddingi

Kompatybilne z OpenAI embeddingi są udostępniane na /v1/embeddings, ale model musi obsługiwać tryb pooling 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 model embeddingów, rozważ uruchomienie serwera w trybie tylko embeddingów:

llama-server \
  -m models/my-embedding-model.gguf \
  --embeddings \
  --host 127.0.0.1 \
  --port 8080

Wydajność, monitorowanie i wzmocnienie produkcyjne

Pytanie FAQ „Które opcje wiersza poleceń llama.cpp mają największy wpływ na prędkość i pamięć” staje się znacznie łatwiejsze, gdy traktujesz wnioskowanie jak system:

• Ściana pamięci jest zazwyczaj pierwszym ograniczeniem (RAM na CPU, VRAM na GPU).
• Rozmiar kontekstu to główny mnożnik pamięci.
• Przeniesienie warstw GPU jest często najszybszą drogą do większej liczby tokenów na sekundę.
• Rozmiary batch i wątki mogą poprawić przepustowość, ale mogą również zwiększyć presję na pamięć.

Dla głębszego, inżynierskiego spojrzenia, zobacz: Wydajność LLM w 2026: Testy, Bottlenecks & Optymalizacja.

Monitorowanie llama-server z Prometheus i Grafana

llama-server może udostępniać metryki kompatybilne z Prometheus na /metrics, gdy jest włączona opcja --metrics. To naturalnie współgra z konfiguracjami scrapowania Prometheus i pulpitami Grafana.

Dla pulpitów i alertów specyficznych dla llama.cpp (i vLLM, TGI): Monitorowanie wnioskowania LLM w produkcji (2026): Prometheus & Grafana dla vLLM, TGI, llama.cpp. Szersze przewodniki: Obserwacja: Przewodnik po monitorowaniu, metrykach, Prometheus & Grafana i Obserwacja dla systemów LLM.

Podstawowy checklist wzmocnienia

Kiedy Twój llama-server jest dostępny poza localhost:

• użyj --api-key (lub --api-key-file), aby żądania były autoryzowane,
• unikaj wiązania do 0.0.0.0, chyba że jest to konieczne,
• rozważ TLS za pomocą flag SSL serwera lub zakończenie TLS na odwrotnym proxy,
• ogranicz wątkowość za pomocą --parallel, aby chronić opóźnienie przy obciążeniu.

Szybkie rozwiązania problemów

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

Punkty końcowe rozmowy są najlepsze, gdy model ma obsługiwany szablon rozmowy. Jeśli wyniki wyglądają bezstrukturalnie, spróbuj:

• użyć llama-cli --conversation plus jawnego --system-prompt,
• zweryfikować, czy Twój model to wersja instrukcji lub rozmowy,
• przetestować za pomocą interfejsu WWW serwera przed podłączeniem do aplikacji.

Zostałeś zakończony z brakiem pamięci

Zmniejsz kontekst lub wybierz mniejszą kwantyzację:

• obniż --ctx-size,
• zmniejsz --n-gpu-layers, jeśli problemem jest VRAM,
• przejdź do mniejszego modelu lub bardziej skompresowanej kwantyzacji.

Jest wolny na CPU

Zacznij od:

• --threads równe ilości Twoich rdzeni fizycznych,
• umiarkowane rozmiary batch,
• weryfikacji, czy zainstalowałeś kompilację dopasowaną do Twojego sprzętu (cechy CPU i backend).

Źródła

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