docs(admin): add ops documentation and fix hermes dashboard service

- Remove admin/ from .gitignore (repo is now private) - Add --tui flag to hermes-dashboard.service template - Document hermes-tui wrapper, dashboard access, TUI usage Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-07-09 18:54:42 +02:00 · 2026-05-12 18:50:43 +02:00 · 2026-05-12 18:50:43 +02:00 · dca71144d6
commit dca71144d6
parent 1544a2fc6d
17 changed files with 1979 additions and 4 deletions
--- a/admin/llama_server.md
+++ b/admin/llama_server.md
@ -0,0 +1,139 @@
+# llama-server — Inférence LLM (gpu-01)
+
+llama-server (llama.cpp compilé with ROCm 7.x) tourne en service systemd sur **gpu-01** (`192.168.10.20:1234`).
+API 100% compatible OpenAI — remplace LM Studio pour l'inférence.
+
+---
+
+## Service systemd
+
+```bash
+# Depuis gpu-01
+sudo systemctl status llama-server
+sudo systemctl restart llama-server
+sudo journalctl -u llama-server -f
+sudo journalctl -u llama-server -n 50
+```
+
+---
+
+## Modèle actuel
+
+| Paramètre | Valeur |
+|---|---|
+| Modèle | Qwen2.5-14B-Instruct Q4_K_M |
+| Alias API | `qwen2.5-14b-instruct` |
+| Chemin | `/mnt/models/bartowski/Qwen2.5-14B-Instruct-GGUF/Qwen2.5-14B-Instruct-Q4_K_M.gguf` |
+| Contexte | 16384 tokens (limité par VRAM — voir ci-dessous) |
+| GPU offload | 99 layers (tout sur GPU) |
+| Parallélisme | 1 slot (requis pour Hermes — voir bug parallel) |
+| Embeddings | activés (`--embeddings --pooling mean`) |
+
+### Contrainte VRAM (12 GB RX 6700XT)
+
+| Élément | VRAM |
+|---|---|
+| Modèle Q4_K_M 14B | ~8 GB |
+| KV cache à 16384 ctx | ~3 GB |
+| **Total** | **~11 GB** ✅ |
+
+À 32768 tokens de contexte, le KV cache monte à ~6 GB → total ~14 GB → segfault.
+**Ne pas augmenter `llama_ctx_size` au-delà de 16384 pour le 14B.**
+
+---
+
+## Embeddings
+
+llama-server expose `/v1/embeddings` avec `--embeddings --pooling mean`.
+Le flag `--pooling mean` est obligatoire pour les LLM causaux (sinon : erreur 400
+`Pooling type 'none' is not OAI compatible`).
+
+```bash
+# Test embeddings depuis storage-01
+curl -s -X POST http://192.168.10.20:1234/v1/embeddings \
+  -H "Content-Type: application/json" \
+  -d '{"model":"qwen2.5-14b-instruct","input":["test"]}' | jq '.data[0].embedding | length'
+# → 5120 (dimension Qwen2.5-14B)
+```
+
+---
+
+## Performances (RX 6700XT, ROCm 7.x)
+
+| Métrique | Qwen2.5-7B | Qwen2.5-14B |
+|---|---|---|
+| Prefill | ~400 tok/s | ~200 tok/s |
+| Génération | ~70 tok/s | ~35 tok/s |
+| TTFT Hermes (15k tokens) | ~35s | ~75s |
+| VRAM modèle | ~4 GB | ~8 GB |
+
+---
+
+## Validation API
+
+```bash
+# Depuis storage-01 ou n'importe quelle machine du LAN cluster
+curl -s http://192.168.10.20:1234/v1/models | jq '.data[].id'
+
+# Test inférence rapide
+curl http://192.168.10.20:1234/v1/chat/completions \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "qwen2.5-14b-instruct",
+    "messages": [{"role": "user", "content": "Dis bonjour"}],
+    "max_tokens": 50
+  }'
+```
+
+---
+
+## Changer de modèle
+
+1. Modifier `host_vars/gpu-01/vars.yml` :
+   ```yaml
+   llama_model_path: "/mnt/models/bartowski/NouveauModele.gguf"
+   llama_model_alias: "nouveau-alias"
+   llama_ctx_size: 16384   # ajuster selon VRAM disponible
+   ```
+
+2. Redéployer :
+   ```bash
+   ansible-playbook -i inventory.yml playbooks/gpu-01.yml --tags llama_server
+   ```
+
+3. Mettre à jour LiteLLM (alias `hermes-default`) :
+   ```bash
+   ansible-playbook -i inventory.yml playbooks/storage-01.yml --tags litellm
+   ```
+
+---
+
+## Build (source)
+
+```bash
+# Sur gpu-01 — rebuild si besoin
+cd /opt/llama.cpp
+git pull
+cmake -B build \
+  -DGGML_HIP=ON \
+  -DAMDGPU_TARGETS=gfx1030 \
+  -DCMAKE_BUILD_TYPE=Release \
+  -DCMAKE_HIP_COMPILER=/opt/rocm/llvm/bin/clang++ \
+  -DCMAKE_PREFIX_PATH=/opt/rocm
+cmake --build build --target llama-server -j$(nproc)
+sudo systemctl restart llama-server
+```
+
+---
+
+## Points d'attention
+
+| Sujet | Détail |
+|---|---|
+| GPU non officiel | RX 6700XT (gfx1031) — `HSA_OVERRIDE_GFX_VERSION=10.3.0` dans le service |
+| ROCm version | 7.2.3 — libs dans `/opt/rocm` |
+| VRAM limite | 14B + 16k ctx = ~11 GB — ne pas dépasser 16384 tokens |
+| parallel=1 obligatoire | `--parallel 4` divise le ctx en slots → contexte insuffisant pour Hermes |
+| pooling mean obligatoire | sans `--pooling mean` l'endpoint `/v1/embeddings` retourne erreur 400 |
+| Gemma 4 interdit | Crash ROCm sur prompts >800 tokens |
+| Modèles sur NFS | `/mnt/models` monté depuis storage-01 (NFS) |