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
commit 359afb3a59
153 changed files with 18169 additions and 0 deletions
@@ -0,0 +1,102 @@
+# Wdrożenie BGE-Reranker-v2-m3 w LocalAI
+
+Data: 2026-07-01  
+Host: `gmktec-k11` (RTX 3090 Ti, LocalAI `v4.4.3-gpu-nvidia-cuda-13`, port **8070**)
+
+## Podsumowanie
+
+| Element | Wartość |
+|---------|---------|
+| Model GGUF | `bge-reranker-v2-m3-FP16.gguf` (~1.1 GB) |
+| Źródło | [gpustack/bge-reranker-v2-m3-GGUF](https://huggingface.co/gpustack/bge-reranker-v2-m3-GGUF/resolve/main/bge-reranker-v2-m3-FP16.gguf) |
+| Backend | **`llama-cpp`** → automatycznie `cuda13-llama-cpp` na obrazie cuda-13 |
+| API id | `bge-reranker-v2-m3-FP16.gguf` |
+| Endpoint | `POST /v1/rerank` (format Jina/Cohere-compatible) |
+| Status | **OK** — HTTP 200, dokument o pandzie na indeksie 2 ma najwyższy `relevance_score` |
+
+## Problem z importem z galerii (naprawiony)
+
+Wcześniejsza próba importu przez UI LocalAI utworzyła błędny YAML:
+
+```yaml
+backend: rerankers   # źle dla GGUF
+parameters:
+  model: gpustack/bge-reranker-v2-m3-GGUF/resolve/main/bge-reranker-v2-m3-FP16.gguf  # URL zamiast pliku lokalnego
+```
+
+Backend `rerankers` służy modelom HuggingFace (transformers), **nie** plikom GGUF. Dla GGUF wymagany jest `llama-cpp` z:
+
+- `reranking: true`
+- `known_usecases: [rerank]`
+- `parameters.model` = lokalna nazwa pliku `.gguf`
+
+Dodatkowy backend **nie był potrzebny** — `cuda13-llama-cpp` był już zainstalowany (ten sam co Gemma chat i BGE-M3 embed).
+
+## Co zrobiono
+
+1. Pobrano GGUF do `/data/apps/localai/models/bge-reranker-v2-m3-FP16.gguf`
+2. Zastosowano poprawny YAML (szablon w repo)
+3. Dodano skrypt `stacks/localai/scripts/download-reranker.sh`
+4. Restart kontenera `localai`
+5. Smoke test `/v1/rerank` — **200 OK**
+
+## Pliki w repo
+
+| Plik | Rola |
+|------|------|
+| [`stacks/localai/profiles/bge-reranker-v2-m3-FP16-rerank.yaml.example`](../stacks/localai/profiles/bge-reranker-v2-m3-FP16-rerank.yaml.example) | Szablon YAML |
+| [`stacks/localai/scripts/download-reranker.sh`](../stacks/localai/scripts/download-reranker.sh) | Pobieranie GGUF + aplikacja profilu |
+
+## Pliki na hoście (runtime)
+
+```
+/data/apps/localai/models/
+├── bge-reranker-v2-m3-FP16.gguf       # ~1.1 GB
+└── bge-reranker-v2-m3-FP16.gguf.yaml  # backend llama-cpp, reranking: true
+```
+
+## Weryfikacja
+
+```bash
+API_KEY=$(grep '^LOCALAI_API_KEY=' stacks/localai/.env | cut -d= -f2)
+
+curl -s http://127.0.0.1:8070/v1/models \
+  -H "Authorization: Bearer $API_KEY"
+# powinien zawierać bge-reranker-v2-m3-FP16.gguf
+
+curl -s http://127.0.0.1:8070/v1/rerank \
+  -H "Authorization: Bearer $API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "bge-reranker-v2-m3-FP16.gguf",
+    "query": "What is a panda?",
+    "top_n": 3,
+    "documents": [
+      "hi",
+      "it is a bear",
+      "The giant panda (Ailuropoda melanoleuca) is a bear species endemic to China."
+    ]
+  }'
+```
+
+Oczekiwany wynik: `results[0].index == 2` (dokument o pandzie), `relevance_score` najwyższy dla tego indeksu.
+
+## VRAM i SINGLE_ACTIVE_BACKEND
+
+Compose ma `SINGLE_ACTIVE_BACKEND=true` — przy przełączaniu chat → embed → rerank model jest przeładowywany (jak przy embed). Reranker (~1.1 GB) + Gemma (~6.5 GB) **nie mieszczą się naraz** w sensie aktywnego backendu; kolejne wywołania API przełączają model.
+
+Dla pipeline RAG (embed → rerank → chat) klient musi liczyć się z latencją przeładowania (~kilka sekund między typami modeli).
+
+## Integracja z klientem (ai-lawyer / dev)
+
+| Zmienna | Wartość |
+|---------|---------|
+| `RERANK_MODEL` | `bge-reranker-v2-m3-FP16.gguf` |
+| `RERANK_URL` | `https://llm.rtx1.mobile.agency-ai.dev/v1/rerank` (lub LAN `http://192.168.100.5:8070/v1/rerank`) |
+| Auth | `Authorization: Bearer <LOCALAI_API_KEY>` |
+
+Payload zgodny z OpenAI/Jina rerank API — pole `documents` to tablica stringów, `query` to zapytanie, `top_n` opcjonalne.
+
+## Uwaga: uprawnienia plików
+
+Pliki YAML utworzone przez kontener/UI mogą być owned by `root`. Skrypt `download-reranker.sh` przy błędzie `cp` zapisuje YAML przez `docker exec localai` (bez sudo na hoście).