tomasz-syn-grzegorza/ubuntu-bare-metal
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
359afb3a59588ca6757bdafcde8746dda55f2c59
ubuntu-bare-metal/manual-tutorial/05-localai-stack.md
T
tomasz-syn-grzegorza 359afb3a59 Initial import: bare-metal stacks, Server UI, GPU fan, tutorials. 
Infrastructure configs for GMKtec K11 (Docker, vLLM, LocalAI, ComfyUI,
control-plane, gpu-fan agent, Server UI with CLI/file explorer/GPU fan curve).

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-07-05 12:02:04 +00:00

7.4 KiB
Raw Blame History

05 — LocalAI stack

Cel rozdziału: uruchomić LocalAI w Dockerze z GPU (CUDA 13), wbudowanym UI na porcie 8070 i pustym katalogiem modeli. Modele dodasz później (GGUF, galeria).

Szacowany czas:

  • Pobranie obrazu Docker: 10–30 minut
  • Start bez modelu: 1–2 minuty

Wymagania: ukończone rozdziały 01–04 (część A — dysk /data zamontowany)

Spis treści

  1. LocalAI vs vLLM
  2. Porty i architektura
  3. Struktura plików stacku
  4. Przygotowanie .env
  5. Clone upstream (opcjonalnie)
  6. Instalacja obrazu (bez modelu)
  7. Start stacku
  8. Weryfikacja UI i API
  9. Zarządzanie stackiem
  10. Troubleshooting
  11. Następny krok

1. LocalAI vs vLLM

vLLM (stacks/vllm/) LocalAI (stacks/localai/)
UI Brak (tylko API) Wbudowany chat w przeglądarce
Port 8000 8070 (host) → 8080 (kontener)
Modele skwantyzowane AWQ / HF (nie GGUF) GGUF, AWQ, wiele backendów
Ten krok Obraz pobrany, bez modelu OK Start bez modelu — pusty /models

Oba stacki mogą współistnieć na dysku, ale nie ładuj dużych modeli na GPU równocześnie (24 GB VRAM).

2. Porty i architektura

flowchart LR
    browser["Przeglądarka :8070"]
    curl["curl / OpenAI SDK"]
    localai["Kontener localai"]
    gpu["RTX 3090 Ti"]
    disk["/data/apps/localai/models"]

    browser --> localai
    curl --> localai
    localai --> gpu
    localai --> disk
Element Wartość
Obraz localai/localai:v4.4.3-gpu-nvidia-cuda-13
UI + API (LAN / tunel) http://127.0.0.1:8070 lub publicznie przez NPMPlus (rozdział 07)
Modele /data/apps/localai/models
Docker data /data/docker

3. Struktura plików stacku

stacks/localai/
├── README.md
├── docker-compose.yml
├── .env.example
├── .gitignore
├── upstream/              # opcjonalny shallow clone (gitignored)
└── scripts/
    ├── clone-upstream.sh
    ├── pull.sh
    └── start.sh

Katalogi na dysku 1 TB (tworzone przez skrypty):

/data/apps/localai/
├── models/
├── backends/
├── configuration/
├── images/
└── data/

4. Przygotowanie .env

cd /home/tomasz-syn-grzegorza/cursor/ubuntu-bare-metal/stacks/localai
cp .env.example .env
cat .env

Oczekiwane:

DATA_ROOT=/data
LOCALAI_PORT=8070
LOCALAI_API_KEY=your-secret-key
LOCALAI_IMAGE=localai/localai:v4.4.3-gpu-nvidia-cuda-13
CUDA_VISIBLE_DEVICES=0
DEBUG=false

5. Clone upstream (opcjonalnie)

Shallow clone repozytorium GitHub — tylko referencja (przykładowe YAML modeli). Runtime idzie z oficjalnego obrazu Docker, nie z buildu lokalnego.

./scripts/clone-upstream.sh

Powstaje stacks/localai/upstream/ (ignorowane przez git).

6. Instalacja obrazu (bez modelu)

Pobiera wyłącznie obraz Docker — nie startuje kontenera, nie pobiera modeli LLM.

./scripts/pull.sh

Alternatywa ręczna:

docker compose --profile localai pull

Weryfikacja:

docker images | grep localai
docker compose --profile localai ps

Oczekiwane: obraz widoczny, kontener nie działa.

7. Start stacku

./scripts/start.sh

Skrypt sprawdza: /data zamontowany, Docker działa, tworzy katalogi w /data/apps/localai/.

Logi:

docker compose --profile localai logs -f localai

8. Weryfikacja UI i API

8.1 Health check

curl -s http://localhost:8070/readyz

Oczekiwane: odpowiedź HTTP 200 (tekst potwierdzający gotowość).

8.2 UI w przeglądarce

Otwórz na swoim PC (z sieci LAN):

http://127.0.0.1:8070

Adres IP serwera:

hostname -I | awk '{print $1}'

UI powinno się załadować — lista modeli będzie pusta (to OK na tym etapie).

8.3 API (opcjonalnie)

curl -s http://localhost:8070/v1/models -H "Authorization: Bearer $LOCALAI_API_KEY" | jq .

Pusta lista modeli — normalne bez pobranego modelu.

9. Zarządzanie stackiem

cd /home/tomasz-syn-grzegorza/cursor/ubuntu-bare-metal/stacks/localai

docker compose --profile localai ps
docker compose --profile localai logs -f localai
docker compose --profile localai restart localai
docker compose --profile localai down

Przed testem modelu w LocalAI — zatrzymaj vLLM jeśli działa:

cd ../vllm
docker compose --profile vllm down

10. Troubleshooting

10.1 /data is not mounted

Wróć do 04-vllm-stack.md — część A i dokończ setup dysku.

10.2 GPU niewidoczne w kontenerze

docker run --rm --gpus all nvidia/cuda:12.6.0-base-ubuntu24.04 nvidia-smi

Upewnij się, że używasz obrazu -cuda-13, nie -cuda-12.

10.3 Healthcheck failing / restarting

docker compose --profile localai logs --tail 100 localai

Pierwszy start może trwać 1–2 minuty. Healthcheck ma start_period: 2m.

10.4 UI niedostępne z innego komputera

LocalAI nasłuchuje na 127.0.0.1:8070. Dostęp z LAN/internetu — przez NPMPlus (rozdział 07) lub SSH tunnel:

# na swoim PC:
ssh -L 8070:127.0.0.1:8070 tomasz-syn-grzegorza@<IP-serwera>
# potem: http://localhost:8070

10.5 Brak modeli w UI

Zamierzone na tym kroku. Modele dodasz w kolejnym etapie (Model Gallery, GGUF, CLI).

11. KV cache (po dodaniu modelu chat)

Domyślnie KV cache w llama.cpp jest w f16 — zajmuje dużo VRAM przy długim kontekście. Na RTX 3090 Ti (24 GB) rekomendujemy q8_0 dla K i V.

Ustawienia są w YAML modelu na /data/apps/localai/models/<nazwa>.yaml, sekcja parameters::

Pole Wartość startowa
cache_type_k q8_0
cache_type_v q8_0
flash_attention true
context_size 8192

Zastosowanie z repo:

cd /home/tomasz-syn-grzegorza/cursor/ubuntu-bare-metal/stacks/localai
./scripts/apply-kv-profile.sh gemma-4-12b-it-qat-q4_0
docker compose --profile localai restart localai

Skrypt tworzy backup YAML. Pliki w /data/apps/localai/models/ są często root-owned — skrypt używa wtedy docker exec localai (volume /models).

Szczegóły: stacks/localai/coding-agent/KV-CACHE.md

Po załadowaniu modelu sprawdź VRAM:

nvidia-smi
docker compose --profile localai logs localai 2>&1 | tail -50

12. Następny krok

Po przejściu weryfikacji:

  1. Zgłoś w rozmowie z Cursorem, że krok 05 jest gotowy.
  2. Pobierz model (np. GGUF Qwen z katalogu vLLM) — osobny krok.
  3. Później: rozdział 06 — sterowanie wentylatorami GPU lub 07 — ComfyUI stack.

Checklist

  • .env utworzony z .env.example
  • docker compose --profile localai pull — obraz pobrany
  • ./scripts/start.sh — kontener localai running
  • curl http://localhost:8070/readyz — OK
  • UI otwiera się w przeglądarce na :8070 (lub przez tunel SSH)
  • Katalogi istnieją pod /data/apps/localai/
  • (Po modelu chat) KV cache q8_0 w YAML + restart
Reference in New Issue View Git Blame Copy Permalink