tomasz-syn-grzegorza/ubuntu-bare-metal
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial import: bare-metal stacks, Server UI, GPU fan, tutorials.

Browse Source 
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>
This commit is contained in:
tomasz-syn-grzegorza
2026-07-05 12:02:04 +00:00
commit 359afb3a59
153 changed files with 18169 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
stacks/localai/coding-agent/BACKLOG.md
+28
View File
@@ -0,0 +1,28 @@
# BACKLOG — LocalAI stack
## P0 — KV cache (bieżąca sesja)
- [x] Audyt konfiguracji KV (compose, YAML, backendy)
- [x] Szablon `profiles/gemma-4-12b-q4-kv-q8.yaml.example`
- [x] Skrypt `scripts/apply-kv-profile.sh`
- [x] Aktualizacja YAML Gemma na `/data` (via `docker exec` — plik root-owned)
- [x] Restart `localai` — health OK
- [ ] **Test VRAM po załadowaniu Gemma GGUF** — uzupełnić STATE.md
## P1 — po pierwszym modelu chat
- [ ] Dostroić `context_size` (8192 → 16384 jeśli VRAM pozwala)
- [ ] Porównanie jakości odpowiedzi f16 vs q8_0 KV (krótki prompt)
- [ ] Profil KV dla Qwen3.6-27B GGUF (gdy dodany do LocalAI)
- [ ] Przekazać `LOCALAI_API_KEY` do `docker-compose.yml` (zsynchronizować z root BACKLOG)
## P2 — opcjonalnie
- [ ] Backend `turboquant` + `turbo3`/`turbo4` (~3–4× kompresja KV)
- [ ] Skrypt sync GGUF z `stacks/vllm/models.catalog.yaml`
- [ ] Reverse proxy + firewall (root tutorial 07)
## P3 — dokumentacja
- [ ] Zsynchronizować port 8070 vs 8080 w całym repo (root BACKLOG)
- [ ] Przykład `curl /v1/chat/completions` z auth w tutorialu
stacks/localai/coding-agent/CONVENTIONS.md
+41
View File
@@ -0,0 +1,41 @@
# Konwencje — stack LocalAI
Skrót reguł specyficznych dla tego stacku. Pełne konwencje repo: [`../../coding-agent/CONVENTIONS.md`](../../coding-agent/CONVENTIONS.md).
## Ścieżki
| Warstwa | Ścieżka |
|---------|---------|
| Repo stack | `ubuntu-bare-metal/stacks/localai/` |
| `.env` (sekrety) | `stacks/localai/.env` — **gitignore** |
| Modele runtime | `/data/apps/localai/models/` |
| YAML modeli | `/data/apps/localai/models/*.yaml` — **poza git** |
| Szablony KV | `stacks/localai/profiles/*.yaml.example` |
| Notatki agenta | `stacks/localai/coding-agent/` |
## KV cache
- Ustawienia **tylko** w sekcji `parameters:` pliku YAML modelu.
- Skwantyzowany `cache_type_v` wymaga `flash_attention: true`.
- Dozwolone na `llama-cpp`: `f16`, `f32`, `q8_0`, `q4_0`, `q4_1`, `q5_0`, `q5_1`.
- Startowa rekomendacja: `cache_type_k: q8_0`, `cache_type_v: q8_0`, `context_size: 8192`.
- Modele embedding (np. bge-m3) — **nie** dodawać KV cache.
## Docker
```bash
cd stacks/localai
docker compose --profile localai up -d
docker compose --profile localai restart localai
```
Port wewnątrz kontenera zawsze **8080**; host mapuje `LOCALAI_PORT` (użytkownik: **8070**).
## VRAM
- Jeden duży model chat na GPU naraz.
- Przed loadem dużego modelu: `cd ../vllm && docker compose --profile vllm down`.
## Sekrety
- `LOCALAI_API_KEY` — tylko w `.env` na serwerze, nie w `coding-agent/`.
stacks/localai/coding-agent/EMBEDDING-STATUS-REPORT.md
+147
View File
@@ -0,0 +1,147 @@
# RTX1 — raport naprawy embeddingu (odpowiedź dla ai-lawyer-srvr)
**Typ dokumentu:** raport po stronie **RTX1** (LocalAI na `gmktec-k11`) — odpowiedź na żądanie z hosta dev.
**Data:** 2026-06-30
**Status:** **NAPRAWIONE** — `POST /v1/embeddings` zwraca HTTP 200, wektor **1024** wymiarów.
**Adresat:** agent kodujący na hoście dev (`ai-lawyer-srvr`).
---
## 1. Podsumowanie wykonawcze
| Obszar | Stan |
|--------|------|
| Connectivity (`llm.rtx1.mobile.agency-ai.dev`) | OK (wcześniej potwierdzone przez dev) |
| Graph LLM (`gemma-4-12b-it-qat-q4_0`) | OK |
| Embedding (`bge-m3-FP16.gguf`) | **OK** po poprawce YAML |
| Zmiana `.env` dev | **Nie wymagana** |
---
## 2. Root cause
Model `bge-m3-FP16.gguf` został zaimportowany z galerii LocalAI z konfiguracją **chat**, bez flagi embedding:
```yaml
# PRZED (błędne)
known_usecases:
- chat
# brak: embeddings: true
```
Skutek: worker llama-cpp padał przy `POST /v1/embeddings` z błędem:
```
rpc error: code = Unavailable desc = error reading from server: EOF
```
**Nie było to:** zły URL, API key, brak pliku GGUF (1.1 GB OK), ani brak VRAM w stanie idle.
---
## 3. Zastosowana poprawka
Zaktualizowano `/data/apps/localai/models/bge-m3-FP16.gguf.yaml`:
```yaml
name: bge-m3-FP16.gguf
backend: llama-cpp
embeddings: true
description: BGE-M3 embedding model (1024 dims)
known_usecases:
- embedding
parameters:
model: bge-m3-FP16.gguf
context_size: 8192
```
Szablon w repo (na przyszłe reimporty): [`../profiles/bge-m3-FP16-embedding.yaml.example`](../profiles/bge-m3-FP16-embedding.yaml.example)
Restart: `docker compose --profile localai restart localai`
---
## 4. Wyniki testów akceptacyjnych (RTX1)
| Test | Endpoint | HTTP | Wynik |
|------|----------|------|-------|
| Embeddings lokalnie | `POST http://127.0.0.1:8070/v1/embeddings` | **200** | wektor **1024** dims |
| Chat → embed (swap) | gemma chat, potem bge embed | **200** / **200** | `SINGLE_ACTIVE_BACKEND` OK |
| Embeddings przez domenę z RTX1 | `POST https://llm.rtx1.mobile.agency-ai.dev/v1/embeddings` | timeout (000) | hairpin NAT z wnętrza LAN — **nie blokuje dev** |
Test lokalny (na RTX1):
```bash
curl -s http://127.0.0.1:8070/v1/embeddings \
-H "Authorization: Bearer $LOCALAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"input":"test prawny","model":"bge-m3-FP16.gguf"}' \
| python3 -c "import sys,json; d=json.load(sys.stdin); print(len(d['data'][0]['embedding']))"
# Wynik: 1024
```
---
## 5. Wartości dla `.env` dev — bez zmian
```bash
EMBEDDING_URL=https://llm.rtx1.mobile.agency-ai.dev/v1
GRAPH_LLM_URL=https://llm.rtx1.mobile.agency-ai.dev/v1
EMBEDDING_MODEL=bge-m3-FP16.gguf
GRAPH_LLM_MODEL=gemma-4-12b-it-qat-q4_0
EMBEDDING_DIMS=1024
```
`EMBEDDING_API_KEY` / `GRAPH_LLM_API_KEY` — bez zmian (ten sam token co `LOCALAI_API_KEY` na RTX1).
---
## 6. Checklist dla agenta dev (wykonaj teraz)
1. [ ] `docker compose -f docker-compose.dev.yml exec api python scripts/discover_rtx1_models.py`
Oczekiwane: embed test **OK**, chat test **OK**
2. [ ] `docker compose -f docker-compose.dev.yml up -d api` (jeśli zmieniano `.env`)
3. [ ] Smoke hybrid chat — SSE z `"route": "hybrid"` i semantycznym retrieval
4. [ ] Jeśli ES był indeksowany bez wektorów: `python scripts/reindex_embeddings.py`
Test z hosta dev:
```bash
curl -s https://llm.rtx1.mobile.agency-ai.dev/v1/embeddings \
-H "Authorization: Bearer $EMBEDDING_API_KEY" \
-H "Content-Type: application/json" \
-d '{"input":"test prawny","model":"bge-m3-FP16.gguf"}' \
| python3 -c "import sys,json; d=json.load(sys.stdin); print('dims:', len(d['data'][0]['embedding']))"
```
Oczekiwane: `dims: 1024`
---
## 7. Architektura (bez zmian)
- Publiczny URL: `https://llm.rtx1.mobile.agency-ai.dev/v1`
- LocalAI LAN: `http://192.168.100.5:8070` (bind `0.0.0.0`)
- `SINGLE_ACTIVE_BACKEND=true` — gemma i bge przełączają się sekwencyjnie (OK dla hybrid RAG: embed RTX1 → chat RTX2)
---
## 8. Mapa dokumentacji
| Plik | Opis |
|------|------|
| Ten dokument | Status naprawy embeddingu |
| [`STATE.md`](STATE.md) | Runtime LocalAI na RTX1 |
| [`../profiles/bge-m3-FP16-embedding.yaml.example`](../profiles/bge-m3-FP16-embedding.yaml.example) | Szablon YAML embedding |
---
## 9. Odpowiedź na żądanie (tabela)
| Punkt | Odpowiedź |
|-------|-----------|
| 1. Root cause | Błędny YAML — `chat` zamiast `embedding`, brak `embeddings: true` |
| 2. Poprawka | YAML + restart LocalAI |
| 3. curl embed | HTTP **200**, **1024** dims (lokalnie na RTX1) |
| 4. Zmiana `id` / dims | **Nie** — `bge-m3-FP16.gguf`, `1024` |
stacks/localai/coding-agent/HANDOFF.md
+46
View File
@@ -0,0 +1,46 @@
# HANDOFF — LocalAI KV cache
## Cel sesji
Przeanalizować konfigurację KV cache w LocalAI i włączyć **skwantyzowany KV** (`q8_0`), aby zmieścić większe modele / dłuższy kontekst na RTX 3090 Ti (24 GB).
## Wynik audytu
1. W [`docker-compose.yml`](../docker-compose.yml) i [`.env`](../.env) **brak** ustawień KV — to prawidłowe; LocalAI konfiguruje KV w YAML modelu.
2. YAML `gemma-4-12b-it-qat-q4_0` na `/data` nie miał `cache_type_k`, `cache_type_v`, `flash_attention`, `context_size` → domyślnie **f16** KV (więcej VRAM).
3. Backend: tylko `cuda13-llama-cpp`. TurboQuant **nie** instalowany.
4. Plik GGUF Gemma **jeszcze nie pobrany** — YAML gotowy przed pierwszym loadem.
## Decyzja
| Opcja | Wybór |
|-------|-------|
| Standard `q8_0` + `flash_attention` na `llama-cpp` | **TAK** |
| Backend `turboquant` (turbo3/4) | **NIE** (odłożone) |
Uzasadnienie: ~2× mniej pamięci KV vs f16, bez nowego backendu, minimalny wpływ na jakość.
## Co zrobiono w repo
- Katalog `coding-agent/` (ten handoff + STATE, BACKLOG, KV-CACHE, CONVENTIONS)
- [`profiles/gemma-4-12b-q4-kv-q8.yaml.example`](../profiles/gemma-4-12b-q4-kv-q8.yaml.example)
- [`scripts/apply-kv-profile.sh`](../scripts/apply-kv-profile.sh)
- Sekcja KV w README stacku i tutorialu 05
## Co zrobiono na serwerze
- Zaktualizowano `/data/apps/localai/models/gemma-4-12b-it-qat-q4_0.yaml` (parametry KV)
- Restart kontenera `localai`
## Następne kroki (dla agenta / użytkownika)
1. Dokończyć pobieranie GGUF Gemma 4 12B (galeria UI lub URI z `._gallery_*.yaml`).
2. Po loadzie: `nvidia-smi` + krótki chat — zapisać VRAM w [STATE.md](STATE.md).
3. Jeśli zapas VRAM: podnieść `context_size` do 16384 w YAML.
4. Dla przyszłego Qwen3.6-27B GGUF: skopiować wzorzec KV z `profiles/`.
5. BACKLOG P0 root repo: przekazać `LOCALAI_API_KEY` do compose (osobne zadanie).
## Dokumentacja zewnętrzna
- [LocalAI model configuration — cache_type_k/v](https://localai.io/advanced/model-configuration/)
- [Text generation — llama-cpp backend](https://localai.io/features/text-generation/)
stacks/localai/coding-agent/KV-CACHE.md
+84
View File
@@ -0,0 +1,84 @@
# KV cache w LocalAI (llama-cpp)
## Problem
Przy inference LLM pamięć KV rośnie z długością kontekstu. Domyślnie LocalAI/llama.cpp używa **f16** dla K i V — pełna precyzja, najwięcej VRAM.
Na RTX 3090 Ti (24 GB) przy modelu Q4 + mmproj (Gemma 4 12B) kwantyzacja KV zwalnia miejsce na dłuższy `context_size` lub większy model.
## Gdzie konfigurować
| Miejsce | KV cache? |
|---------|-----------|
| `docker-compose.yml` | nie |
| `.env` stacku | nie |
| `models/<nazwa>.yaml` → `parameters:` | **tak** |
## Pola YAML (llama-cpp)
| Pole | Typ | Domyślnie | Opis |
|------|-----|-----------|------|
| `cache_type_k` | string | `f16` | Kwantyzacja cache kluczy (`-ctk` w llama.cpp) |
| `cache_type_v` | string | `f16` | Kwantyzacja cache wartości (`-ctv`) |
| `flash_attention` | bool/string | off | **Wymagane** przy skwantyzowanym `cache_type_v` |
| `context_size` | int | niski / auto | Maks. tokenów kontekstu (wpływa na rozmiar KV) |
### Dozwolone typy (`cuda13-llama-cpp`)
`f16`, `f32`, `q8_0`, `q4_0`, `q4_1`, `q5_0`, `q5_1`
### Rekomendacja dla tego serwera (q8_0)
```yaml
parameters:
cache_type_k: q8_0
cache_type_v: q8_0
flash_attention: true
context_size: 8192
```
Po teście VRAM można podnieść `context_size` do `16384`.
## Szacunek VRAM (Gemma 4 12B Q4_0 + mmproj)
| Składnik | Orientacyjnie |
|----------|---------------|
| Wagi + mmproj | ~8–10 GB |
| KV @ f16, ctx 8k | ~2–4 GB |
| KV @ q8_0, ctx 8k | ~1–2 GB |
## TurboQuant (odłożone)
Backend `turboquant` + typy `turbo2`/`turbo3`/`turbo4` dają większą kompresję (~3–4×), ale wymagają:
```bash
docker exec localai /local-ai backends install turboquant
```
oraz `backend: turboquant` w YAML. Nie wdrożone w bieżącej sesji.
## Zastosowanie profilu
```bash
cd stacks/localai
./scripts/apply-kv-profile.sh gemma-4-12b-it-qat-q4_0
docker compose --profile localai restart localai
```
## Weryfikacja
```bash
# modele
curl -s http://localhost:8070/v1/models -H "Authorization: Bearer $KEY"
# VRAM
nvidia-smi
# logi backendu
docker compose --profile localai logs localai 2>&1 | grep -iE 'cache|ctk|ctv|flash' | tail -20
```
## Źródła
- https://localai.io/advanced/model-configuration/
- https://localai.io/features/text-generation/
stacks/localai/coding-agent/README.md
+25
View File
@@ -0,0 +1,25 @@
# coding-agent — notatki dla agenta (stack LocalAI)
Katalog handoff dla sesji Cursor pracujących nad [`stacks/localai/`](../) na serwerze GMKtec K11.
## Kolejność czytania
1. **[HANDOFF.md](HANDOFF.md)** — decyzje (KV q8_0), audyt, następne kroki
2. **[STATE.md](STATE.md)** — stan runtime: kontener, modele, backendy, VRAM
3. **[KV-CACHE.md](KV-CACHE.md)** — referencja techniczna KV cache w YAML
4. **[BACKLOG.md](BACKLOG.md)** — priorytetyzowane zadania
5. **[CONVENTIONS.md](CONVENTIONS.md)** — ścieżki, sekrety, konwencje stacku
Wspólne konwencje repo: [`../../coding-agent/CONVENTIONS.md`](../../coding-agent/CONVENTIONS.md)
## Zasady
- Instrukcje dla użytkownika: **po polsku**. Komendy: **po angielsku**.
- **Nie commituj** ani nie zapisuj tutaj wartości `LOCALAI_API_KEY`, tokenów HF itd.
- YAML modeli na `/data/apps/localai/models/` **nie są w git** — szablony trzymaj w [`../profiles/`](../profiles/).
- Commity i push **tylko na prośbę** użytkownika.
- Nie edytuj plików planu w `.cursor/plans/`.
## Ostatnia aktualizacja
Sesja: audyt KV cache → wdrożenie `cache_type_k/v: q8_0` + `flash_attention` dla modeli chat (llama-cpp).
stacks/localai/coding-agent/STATE.md
+62
View File
@@ -0,0 +1,62 @@
# STATE — LocalAI runtime
Ostatnia aktualizacja: po wdrożeniu BGE-Reranker-v2-m3 (2026-07-01).
## Kontener
| Element | Wartość |
|---------|---------|
| Nazwa | `localai` |
| Obraz | `localai/localai:v4.4.3-gpu-nvidia-cuda-13` |
| Status | running (healthy) |
| Port hosta | **8070** → 8080 w kontenerze (`0.0.0.0` — LAN) |
| GPU | `CUDA_VISIBLE_DEVICES=0` (RTX 3090 Ti) |
| API auth | `LOCALAI_API_KEY` w compose — 401 bez Bearer |
## Publiczny endpoint (NPMPlus)
| Element | Wartość |
|---------|---------|
| Domena | `https://llm.rtx1.mobile.agency-ai.dev/v1` |
| Upstream | `http://127.0.0.1:8070` (lub LAN `192.168.100.5:8070`) |
## Backendy
| Backend | Zainstalowany |
|---------|---------------|
| `cuda13-llama-cpp` (alias `llama-cpp`) | tak |
| `turboquant` | **nie** (odłożone) |
## Modele (`/data/apps/localai/models/`)
| Model | GGUF | YAML | Status API |
|-------|------|------|------------|
| `gemma-4-12b-it-qat-q4_0` | tak (~6.5 GB) | KV `q8_0`, `flash_attention`, `context_size: 8192` | chat **OK** |
| `bge-m3-FP16.gguf` | tak (1.1 GB) | `embeddings: true`, `known_usecases: [embedding]` | embed **OK**, 1024 dims |
| `bge-reranker-v2-m3-FP16.gguf` | tak (1.1 GB) | `reranking: true`, `known_usecases: [rerank]`, `backend: llama-cpp` | rerank **OK** |
Szablony w repo:
- Gemma KV: [`../profiles/gemma-4-12b-q4-kv-q8.yaml.example`](../profiles/gemma-4-12b-q4-kv-q8.yaml.example)
- BGE embed: [`../profiles/bge-m3-FP16-embedding.yaml.example`](../profiles/bge-m3-FP16-embedding.yaml.example)
- BGE rerank: [`../profiles/bge-reranker-v2-m3-FP16-rerank.yaml.example`](../profiles/bge-reranker-v2-m3-FP16-rerank.yaml.example)
## Weryfikacja (2026-06-30)
| Test | Wynik |
|------|-------|
| `GET /readyz` | 200 |
| `GET /v1/models` (auth) | 200 — 2 modele |
| `POST /v1/chat/completions` (gemma) | 200 |
| `POST /v1/embeddings` (bge-m3) | **200**, wektor **1024** |
| `POST /v1/rerank` (bge-reranker) | **200**, indeks 2 (panda) na top |
| Chat → embed (SINGLE_ACTIVE_BACKEND) | 200 / 200 |
| Embeddings z RTX1 przez publiczną domenę | timeout (hairpin NAT) — dev powinien testować z zewnątrz |
## Ścieżki
| Co | Gdzie |
|----|-------|
| Repo stack | `/home/tomasz-syn-grzegorza/cursor/ubuntu-bare-metal/stacks/localai` |
| Modele runtime | `/data/apps/localai/models` |
| Raport dla dev | [`EMBEDDING-STATUS-REPORT.md`](EMBEDDING-STATUS-REPORT.md) |