156 lines
5.2 KiB
Plaintext
156 lines
5.2 KiB
Plaintext
# Llama.Cpp — Router Mode (preset) & Watchdog
|
|
|
|
Path di riferimento per i flag CLI di `llama-server`: vedi `llamacpp-serve.README`.
|
|
|
|
## Indice
|
|
|
|
- [Router mode & preset (piu' modelli)](#router-mode--preset-piu-modelli)
|
|
- [Aggiungere un modello](#aggiungere-un-modello)
|
|
- [Watchdog (livelock su /slots)](#watchdog-livelock-su-slots)
|
|
|
|
---
|
|
|
|
## Router mode & preset (piu' modelli)
|
|
|
|
Il container `llamacpp.container` gira in **router mode**: `llama-server` non
|
|
carica un modello fisso ma fa da router, caricando/scaricando i modelli al
|
|
volo e selezionandoli per richiesta tramite il campo `"model"` dell'API.
|
|
|
|
I preset sono definiti nel file **`/config/preset.ini`** (montato da host in
|
|
`/srv/containers/llamacpp/config/preset.ini`), impostato con l'env var
|
|
`LLAMA_ARG_MODELS_PRESET`.
|
|
|
|
Struttura del `preset.ini`:
|
|
|
|
```ini
|
|
version = 1
|
|
|
|
[*]
|
|
; tuning globale, condiviso da tutti i modelli
|
|
ctx-size = 131072
|
|
batch-size = 4096
|
|
ubatch-size = 1024
|
|
cache-type-k = q4_1
|
|
cache-type-v = q4_1
|
|
cache-reuse = 256
|
|
|
|
[qwen36-mtp]
|
|
hf = unsloth/Qwen3.6-35B-A3B-MTP-GGUF:UD-IQ4_NL
|
|
spec-type = draft-mtp
|
|
spec-draft-n-max = 2
|
|
|
|
[gemma4]
|
|
hf = unsloth/gemma-4-26B-A4B-it-GGUF:UD-IQ4_NL
|
|
|
|
[deepseek]
|
|
hf = unsloth/DeepSeek-V4-Flash-0731-GGUF:UD-IQ3_XXS
|
|
hf-repo-draft = unsloth/DeepSeek-V4-Flash-0731-GGUF:Q8_0
|
|
spec-type = draft-dspark
|
|
spec-draft-n-max = 3
|
|
n-gpu-layers-draft = 99
|
|
|
|
[embedding]
|
|
hf = Qwen/Qwen3-Embedding-0.6B-GGUF:Q8_0
|
|
embeddings = true
|
|
pooling = last
|
|
ctx-size = 8192
|
|
```
|
|
|
|
- Ogni sezione `[nome]` e' un preset/modello; il **nome della sezione** e' il
|
|
valore da passare nel campo `"model"` dell'API.
|
|
- La chiave `hf` punta a un modello Hugging Face (repo:quant); usa il quant
|
|
**esatto** del repo (prefisso `UD-` incluso). In alternativa `model` punta
|
|
a un file `.gguf` locale gia' scaricato.
|
|
- La sezione `[*]` contiene il tuning globale condiviso (batch, ubatch,
|
|
cache-type, cache-reuse).
|
|
- I parametri **per-modello** (tipo MTP, ctx dedicato) vanno nella sezione
|
|
del modello, NON in `[*]`. `spec-type=draft-mtp` e' valido solo sui modelli
|
|
con MTP nativo (qwen36-mtp). DeepSeek usa **DSpark**
|
|
(`spec-type=draft-dspark` + `hf-repo-draft` per il draft module separato,
|
|
che si scarica da solo da HF), mentre gemma usa un file draft separato da
|
|
configurare esplicitamente.
|
|
- `ctx-size` e' gestito nel preset: 131072 in `[*]` (default), con override
|
|
per-modello dove serve (es. `[embedding]` usa 8192).
|
|
- L'embedding e' servito dallo stesso router (sezione `[embedding]` con
|
|
`embeddings=true` e `pooling=last`); il container dedicato
|
|
`llamacpp-embedding.container` (porta 8091) e' stato rimosso e caddy/nginx
|
|
inoltrano `/v1/embeddings` alla porta 8090.
|
|
|
|
### Uso
|
|
|
|
```bash
|
|
# Elenca i modelli disponibili nel router
|
|
curl -s localhost:8090/v1/models
|
|
|
|
# Chat selezionando il modello tramite il campo "model"
|
|
curl -s localhost:8090/v1/chat/completions \
|
|
-H 'Content-Type: application/json' \
|
|
-d '{"model":"qwen36-mtp","messages":[{"role":"user","content":"ciao"}]}'
|
|
```
|
|
|
|
### Aggiungere un modello
|
|
|
|
1. Aggiungi una sezione a `preset.ini` — sia in git
|
|
(`containers/llamacpp/preset.ini`) sia in
|
|
`/srv/containers/aitools/config/preset.ini` (la copia montata).
|
|
Esempio con override per-modello:
|
|
|
|
```ini
|
|
[chat]
|
|
hf = unsloth/altro-modello-GGUF:Q4_K_M
|
|
ctx-size = 65536
|
|
```
|
|
|
|
2. Riavvia il servizio:
|
|
|
|
```bash
|
|
systemctl --user daemon-reload
|
|
systemctl --user restart llamacpp.service
|
|
```
|
|
|
|
> **Nota**: il Model ID cambiato. Prima era il nome del file `.gguf`; ora e'
|
|
> il nome della sezione nel preset (es. `qwen36-mtp` per chat, `embedding` per
|
|
> gli embedding). Aggiorna il campo "model" nelle integrazioni (es. Odoo > AI).
|
|
|
|
---
|
|
|
|
## Watchdog (livelock su /slots)
|
|
|
|
`llama-server` puo' restare "livelocked" dopo la cancellazione di una
|
|
richiesta a meta' prompt-processing su uno slot senza cache riusabile,
|
|
specialmente con speculative decoding attivo su contesti molto lunghi: il
|
|
thread principale gira in loop su CPU senza mai liberare lo slot, la GPU
|
|
resta a 0% e nessuna nuova richiesta viene piu' processata. `/health`
|
|
continua pero' a rispondere "ok", quindi non e' un check affidabile;
|
|
`/slots` invece si blocca (probabilmente condivide un lock col loop
|
|
principale) ed e' il segnale usato dal watchdog qui incluso.
|
|
|
|
I file sono in `containers/llamacpp/`:
|
|
`llamacpp-watchdog.sh`, `llamacpp-watchdog.service`, `llamacpp-watchdog.timer`.
|
|
|
|
Installazione su host (utente non-root, stesso utente che gestisce i
|
|
quadlet):
|
|
|
|
```bash
|
|
mkdir -p ~/scripts/llamacpp-watchdog
|
|
cp containers/llamacpp/llamacpp-watchdog.sh ~/scripts/llamacpp-watchdog/
|
|
chmod +x ~/scripts/llamacpp-watchdog/llamacpp-watchdog.sh
|
|
|
|
cp containers/llamacpp/llamacpp-watchdog.service ~/.config/systemd/user/
|
|
cp containers/llamacpp/llamacpp-watchdog.timer ~/.config/systemd/user/
|
|
|
|
systemctl --user daemon-reload
|
|
systemctl --user enable --now llamacpp-watchdog.timer
|
|
```
|
|
|
|
Verifica:
|
|
|
|
```bash
|
|
systemctl --user status llamacpp-watchdog.timer
|
|
journalctl --user -u llamacpp-watchdog.service -f
|
|
```
|
|
|
|
Il watchdog riavvia `llamacpp.service` dopo 3 controlli `/slots` falliti di
|
|
fila (~3 minuti), e si ferma da solo (senza piu' riavviare) se in un'ora
|
|
scatta piu' di 3 volte, per non nascondere un bug persistente dietro un
|
|
restart-loop infinito - in quel caso va guardato a mano. |