Własne API LLM z Qwen3 i llama.cpp — od plików do tunelu SSH

Własny model nie musi oznaczać od razu rozbudowanej platformy kontenerowej. Pierwszy krok może być prostszy: pobrać określone pliki, sprawdzić ich integralność, uruchomić proces na GPU i połączyć się z nim przez SSH. Poniżej pokazujemy taki układ dla Qwen3-8B w formacie Q4_K_M oraz llama.cpp.

To poradnik uruchomieniowy oparty na artefaktach i ustawieniach użytych w naszych testach. Nie jest porównaniem jakości modeli, testem odporności aplikacji ani gotową konfiguracją publicznej usługi dla wielu użytkowników. API pozostaje dostępne wyłącznie lokalnie na serwerze; z własnego komputera docieramy do niego tunelem.

Sprawdziliśmy poniższą konfigurację jednego slotu: lokalne /health i /completion zwróciły HTTP 200, a strumień zakończył generowanie 32 tokenów. Potwierdziliśmy proces na właściwym GPU i przeniesienie 37/37 warstw do GPU. To kontrola uruchomienia, nie pomiar wydajności ani test połączenia internetowego klienta.

Środowisko i zakres poradnika

Szczegóły wykonywania pomiarów opisuje metodyka testów.

Przypinamy llama.cpp do commitu 7fe450e19305b828c199d602c23a8337aaa1f03b. Wydanie b11146 jest oznaczone przez projekt jako pre-release. Wybraliśmy je do odtwarzania tej konkretnej serii, nie jako deklarację najnowszej stabilnej wersji produkcyjnej. Archiwa mają w nazwie Ubuntu, ale te konkretne binaria i biblioteki uruchomiliśmy na wskazanym Rocky. Nie oznacza to zgodności każdej paczki Ubuntu z każdym systemem.

Zanim pobierzesz model

Potrzebne są działający sterownik GPU, konto bez uprawnień roota, Bash, curl, tar, sha256sum i dostęp SSH. Komendy przygotowawcze wykonuj w tej samej sesji Bash na serwerze. Zostaw miejsce zarówno na pobrane archiwa, jak i ich rozpakowaną zawartość oraz model.

Najpierw sprawdź GPU:

nvidia-smi --query-gpu=name,driver_version,memory.total,power.limit --format=csv

Jeżeli polecenie nie działa albo nie pokazuje właściwej karty, najpierw trzeba naprawić instalację sterownika. Pobranie bibliotek CUDA nie zastąpi sterownika jądra. Pole „CUDA Version” w nvidia-smi również nie jest dowodem, że zainstalowano dokładnie tę wersję toolkitu — dotyczy możliwości sterownika. Zobacz opis NVIDIA-SMI i zasady zgodności CUDA.

Poniższe kroki nie instalują pakietów systemowych, nie zmieniają sterownika, firmware ani konfiguracji SSH. Biblioteki będą widoczne tylko dla uruchamianego procesu przez LD_LIBRARY_PATH.

Pobierz konkretne wersje i sprawdź sumy

Tworzymy nowy, prywatny katalog roboczy. Kolejne wykonanie tej komendy utworzy osobny katalog — nie nadpisze poprzedniego środowiska.

set -euo pipefail
umask 077
llm_dir="$(mktemp -d "$HOME/qwen3-api.XXXXXX")"
cd "$llm_dir"
mkdir downloads engine cuda models

Pobierz dwa oficjalne archiwa wydania: program oraz biblioteki CUDA. Flagi --proto ograniczają transfer i przekierowania do HTTPS.

llm_release='https://github.com/ggml-org/llama.cpp/releases/download/b11146'
curl --fail --location --proto '=https' --proto-redir '=https' \
  "$llm_release/llama-b11146-bin-ubuntu-cuda-12.8-x64.tar.gz" \
  --output downloads/llama.tar.gz
curl --fail --location --proto '=https' --proto-redir '=https' \
  "$llm_release/cudart-llama-b11146-bin-ubuntu-cuda-12.8-x64.tar.gz" \
  --output downloads/cudart.tar.gz
printf '%s  %s\n' \
  'c2ab9e19838513ff69d1af8d999ad717dd3c7ee4714ac04c7ed5ab9077c50e4e' downloads/llama.tar.gz \
  '1466daea60aad1144819e151b2bae19d54556cf1da6c129c4f55a5ded2637c25' downloads/cudart.tar.gz \
  | sha256sum --check

Obie pozycje muszą otrzymać wynik OK. Przy błędzie pobierania lub sumy nie rozpakowuj pliku i nie przechodź dalej. Suma kontrolna potwierdza zgodność z przypiętym artefaktem; sama nie zastępuje zaufania do jego wydawcy.

Model pobieramy z repozytorium autora i konkretnej rewizji 7c41481f57cb95916b40956ab2f0b139b296d974, a nie ze zmiennej gałęzi main:

llm_model_source='https://huggingface.co/Qwen/Qwen3-8B-GGUF/resolve/7c41481f57cb95916b40956ab2f0b139b296d974'
curl --fail --location --proto '=https' --proto-redir '=https' \
  "$llm_model_source/Qwen3-8B-Q4_K_M.gguf" \
  --output models/Qwen3-8B-Q4_K_M.gguf
printf '%s  %s\n' \
  'd98cdcbd03e17ce47681435b5150e34c1417f50b5c0019dd560e4882c5745785' \
  models/Qwen3-8B-Q4_K_M.gguf | sha256sum --check
curl --fail --location --proto '=https' --proto-redir '=https' \
  "$llm_model_source/LICENSE" --output models/LICENSE
curl --fail --location --proto '=https' --proto-redir '=https' \
  "$llm_model_source/README.md" --output models/README.md

Tutaj również wymagany jest wynik OK przed uruchomieniem modelu. Zachowaj plik licencji i kartę modelu. Nazwa Q4_K_M określa wybrany wariant wag; nie oznacza tej samej jakości ani rozmiaru jak inne kwantyzacje.

Rozpakuj runtime i potwierdź dostęp do CUDA

Rozpakowujemy wyłącznie sprawdzone archiwa do wcześniej utworzonych, pustych katalogów:

tar --extract --gzip --file downloads/llama.tar.gz \
  --directory engine --no-same-owner --no-same-permissions
tar --extract --gzip --file downloads/cudart.tar.gz \
  --directory cuda --no-same-owner --no-same-permissions
llm_server="$llm_dir/engine/llama-b11146/llama-server"
llm_libraries="$llm_dir/engine/llama-b11146:$llm_dir/cuda/cudart-llama-b11146-bin-ubuntu-cuda-12.8-x64"
env LD_LIBRARY_PATH="$llm_libraries" CUDA_VISIBLE_DEVICES=0 \
  "$llm_server" --list-devices

Wynik powinien wskazać urządzenie CUDA i właściwy GPU. Samo uruchomienie procesu na CPU nie potwierdza poprawnej konfiguracji GPU. Jeżeli brakuje biblioteki, sprawdź oba archiwa i ścieżki, zamiast kopiować przypadkowe pliki .so do katalogów systemowych.

Uruchom API tylko na serwerowym localhost

W tej samej sesji uruchom proces na pierwszym GPU. Wybieramy jeden slot i kontekst 8704 tokenów, bez automatycznego dopasowywania parametrów. To konfiguracja startowa do sprawdzenia integracji, nie ustawienie dobrane do każdej aplikacji.

env LD_LIBRARY_PATH="$llm_libraries" CUDA_VISIBLE_DEVICES=0 \
  "$llm_server" \
  -m "$llm_dir/models/Qwen3-8B-Q4_K_M.gguf" \
  --host 127.0.0.1 --port 8080 \
  -ngl 999 --fit off -fa on \
  -t 16 -b 2048 -ub 512 -ctk f16 -ctv f16 \
  -np 1 -c 8704 \
  --cache-ram 0 --no-cache-idle-slots --no-context-shift

Zostaw ten terminal otwarty. Po wcześniejszym sprawdzeniu urządzenia CUDA użyj nvidia-smi w osobnej sesji SSH: powinien być widoczny proces llama-server i zajęta pamięć GPU, a podczas zapytania także aktywność GPU. Domyślny poziom logowania tej wersji nie musi wypisywać liczby warstw przeniesionych na GPU; brak takiego wiersza sam w sobie nie oznacza pracy na CPU. --host 127.0.0.1 jest tutaj istotny: nie zastępuj go 0.0.0.0 i nie otwieraj portu 8080 na routerze. Opcje i endpointy opisuje dokumentacja tej rewizji llama-server.

Połącz się ze swojego komputera

W drugim terminalu, na własnym komputerze, uruchom tunel. Zastąp gpu-server.example, login, ścieżkę klucza i port 22 danymi własnego serwera. Użyj portu wybranego przy instalacji, także jeśli jest to 3414 albo port losowy. Nie kopiuj klucza prywatnego na serwer.

ssh -N -T -a \
  -i "$HOME/.ssh/gpu-server" -p 22 \
  -o ExitOnForwardFailure=yes \
  -o ServerAliveInterval=30 -o ServerAliveCountMax=3 \
  -L 127.0.0.1:18080:127.0.0.1:8080 \
  gpu@gpu-server.example

Przy pierwszym połączeniu zweryfikuj klucz hosta znanym, zaufanym kanałem. Nie wyłączaj sprawdzania jego tożsamości. Tunel wiąże lokalny port 18080 tylko z localhost Twojego komputera i prowadzi do portu 8080 widzianego przez serwer. Znaczenie -L i -N opisuje dokumentacja OpenSSH.

W trzecim terminalu, również na własnym komputerze, sprawdź gotowość:

curl --fail --show-error http://127.0.0.1:18080/health

Oczekiwana gotowość to HTTP 200 i {"status":"ok"}. Podczas ładowania modelu endpoint może odpowiadać HTTP 503. Następnie wykonaj krótkie zapytanie strumieniowe:

curl --fail --show-error --no-buffer \
  http://127.0.0.1:18080/completion \
  -H 'Content-Type: application/json' \
  --data '{"prompt":"Write one sentence about GPU memory.","n_predict":32,"stream":true,"cache_prompt":false,"temperature":0}'

/completion służy tu do sprawdzenia lokalnego generowania i przesyłania odpowiedzi. To nie jest gotowy szablon czatu ani ocena jakości modelu. Nie należy traktować parametrów tego krótkiego sprawdzenia jako zalecanej konfiguracji Qwen dla wszystkich rozmów. Integrację czatową, szablon i ustawienia generowania dobierz do aplikacji, korzystając z karty modelu Qwen oraz dokumentacji serwera.

Co sprawdzić, kiedy coś nie działa

Aby zakończyć próbę, naciśnij Ctrl+C w terminalu serwera, a potem w terminalu tunelu. Nie wymaga to restartu maszyny. Pobrane pliki pozostają w oddzielnym katalogu do kolejnego uruchomienia.

Granice bezpieczeństwa i licencji

Loopback z tunelem ogranicza dostęp sieciowy, ale nie uwierzytelnia innych procesów lokalnych ani osób mających dostęp do konta. Na tym etapie korzystaj wyłącznie z danych testowych. Stała usługa potrzebuje osobnego projektu uwierzytelniania, limitów zapytań, aktualizacji i zasad przechowywania logów; udostępnienie API klientom jest kolejnym etapem, nie zmianą jednej flagi adresu.

Qwen3-8B-GGUF ma licencję Apache-2.0 w przypiętej rewizji, a llama.cpp licencję MIT. Biblioteki NVIDIA mają odrębne warunki CUDA. Nie przenoś automatycznie licencji tego modelu na inne warianty Qwen ani na pozostałe składniki środowiska. Wagi pobierasz bezpośrednio od ich wydawcy; GPU Server Hub nie rozpowszechnia ich w tym poradniku.

Jeżeli chcesz przejść od próby do własnej aplikacji, sprawdź konfigurację serwera albo opisz model, kontekst i przewidywany ruch. Testy i poradniki pomagają oddzielić działającą instalację od pomiaru jej wydajności.