ubuntu-bare-metal/stacks/localai

LocalAI stack

LocalAI — silnik inference z wbudowanym UI (chat) i API kompatybilnym z OpenAI. Obsługuje modele skwantyzowane (GGUF, AWQ, …) przez backendy (llama.cpp, vLLM, …).

Porty

Serwis	Port	URL
LocalAI UI + API	8080	http://HOST:8080
vLLM (osobny stack)	8000	tylko API, bez UI

Jeden port — UI i API na tym samym endpoincie.

Jak to działa

flowchart LR
    browser["Przeglądarka"]
    api["curl / OpenAI SDK"]
    localai["LocalAI :8080"]
    gpu["RTX 3090 Ti"]
    models["/data/apps/localai/models"]

    browser --> localai
    api --> localai
    localai --> gpu
    localai --> models

Element	Opis
Obraz	localai/localai:v4.4.3-gpu-nvidia-cuda-13
Konfiguracja	.env + docker-compose.yml
Modele	/data/apps/localai/models (puste na start)
Upstream repo	opcjonalnie upstream/ przez clone-upstream.sh

Struktura

stacks/localai/
├── README.md
├── docker-compose.yml
├── .env.example
├── .gitignore
├── coding-agent/          # notatki dla agenta (KV cache, STATE)
├── profiles/              # szablony YAML (KV q8_0)
├── upstream/              # shallow clone (gitignored)
└── scripts/
    ├── clone-upstream.sh
    ├── pull.sh
    ├── start.sh
    └── apply-kv-profile.sh

Na dysku /data:

/data/apps/localai/
├── models/           # GGUF, YAML model configs
├── backends/         # custom backends
├── configuration/    # api_keys.json, runtime settings
├── images/           # generated images
└── data/             # agents, skills, persistent app data

Workflow (bez modelu)

cd stacks/localai
cp .env.example .env

# opcjonalnie — referencja YAML z GitHub
./scripts/clone-upstream.sh

# tylko obraz Docker
./scripts/pull.sh

# uruchom (pusty katalog models/)
./scripts/start.sh

Weryfikacja:

curl -s http://localhost:8080/readyz
# UI: http://<IP-serwera>:8080

Zmienne .env

Zmienna	Opis	Domyślnie
DATA_ROOT	Mount dysku danych	/data
LOCALAI_PORT	Port na hoście	8080
LOCALAI_IMAGE	Obraz Docker (CUDA 13)	localai/localai:v4.4.3-gpu-nvidia-cuda-13
CUDA_VISIBLE_DEVICES	GPU	0
DEBUG	Verbose logs	false

VRAM (24 GB)

Compose ustawia SINGLE_ACTIVE_BACKEND=true i PARALLEL_REQUESTS=false — jeden aktywny backend/model naraz.

Nie uruchamiaj dużego modelu w vLLM i LocalAI równocześnie na tej samej karcie:

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

Modele (później)

• UI → Model Gallery w przeglądarce
• CLI w kontenerze: docker exec -it localai local-ai models install ...
• Ręcznie: GGUF + YAML w /data/apps/localai/models/

GGUF z stacks/vllm/models.catalog.yaml można skopiować lub podlinkować do models/.

KV cache (skwantyzowany q8_0)

Domyślnie llama.cpp trzyma KV cache w f16 — dużo VRAM przy długim kontekście. Ustawienia są per model w YAML na /data, nie w compose.

Pole	Rekomendacja
cache_type_k	q8_0
cache_type_v	q8_0
flash_attention	true (wymagane przy q8_0 V)
context_size	8192 (start; zwiększ po teście VRAM)

Szablon: profiles/gemma-4-12b-q4-kv-q8.yaml.example

Zastosowanie na istniejącym modelu:

./scripts/apply-kv-profile.sh gemma-4-12b-it-qat-q4_0
docker compose --profile localai restart localai

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

Zarządzanie

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

Dokumentacja

Tutorial: manual-tutorial/05-localai-stack.md

Upstream: github.com/mudler/LocalAI