# 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).