# 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/