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-08 13:54:41 +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/litellm.md
+++ b/admin/litellm.md
@ -0,0 +1,128 @@
+# LiteLLM — Proxy LLM unifié (storage-01)
+
+LiteLLM tourne en service systemd sur **storage-01** (`127.0.0.1:4000`).
+Il route les requêtes OpenAI-compatibles vers le bon backend selon le modèle demandé.
+
+---
+
+## Flux
+
+```
+Hermes / Open WebUI / n8n
+        │
+        ▼  http://127.0.0.1:4000/v1  (Authorization: Bearer lm-studio)
+   LiteLLM Proxy
+        ├── hermes-default        →  qwen2.5-14b-instruct  (défaut Hermes)
+        ├── qwen2.5-14b-instruct  →  llama-server gpu-01 :1234  (local, gratuit)
+        ├── claude-sonnet-4-6     →  api.anthropic.com           (cloud, payant)
+        └── claude-opus-4-7       →  api.anthropic.com           (cloud, payant)
+```
+
+---
+
+## Service systemd
+
+```bash
+# Depuis storage-01
+sudo systemctl status litellm
+sudo systemctl restart litellm
+sudo journalctl -u litellm -f
+sudo journalctl -u litellm -n 50
+```
+
+---
+
+## Modèles disponibles
+
+| Nom dans l'API | Backend | Coût |
+|---|---|---|
+| `hermes-default` | Alias switchable (Qwen par défaut) | Selon backend actif |
+| `qwen2.5-14b-instruct` | llama-server gpu-01 (ROCm 7.x) | Gratuit |
+| `claude-sonnet-4-6` | Anthropic API | ~$3/$15 par million tokens in/out |
+| `claude-opus-4-7` | Anthropic API | Plus cher, meilleur raisonnement |
+
+---
+
+## Switch rapide avec hermes-switch
+
+Script déployé sur storage-01 :
+
+```bash
+sudo hermes-switch status    # voir le modèle actuel de hermes-default
+sudo hermes-switch qwen      # Qwen2.5-14B local (gratuit, ~35 tok/s)
+sudo hermes-switch claude    # Claude Sonnet 4.6 (payant, ~1-2$ par session debug)
+```
+
+Le script modifie `/etc/litellm/config.yaml` et redémarre litellm automatiquement.
+Source : `roles/litellm/files/hermes-switch`.
+
+### Coût Claude
+
+| Session type | Tokens input | Coût estimé |
+|---|---|---|
+| Debug simple (5 échanges) | ~80k | ~$0.24 |
+| Debug complexe (10 échanges) | ~375k | ~$1.12 |
+| Utilisation courante | — | Utiliser Qwen |
+
+---
+
+## Validation API
+
+```bash
+# Depuis storage-01 — master_key = lm-studio
+curl http://127.0.0.1:4000/v1/models \
+  -H "Authorization: Bearer lm-studio" | python3 -m json.tool
+
+# Test inférence Qwen (local)
+curl http://127.0.0.1:4000/v1/chat/completions \
+  -H "Authorization: Bearer lm-studio" \
+  -H "Content-Type: application/json" \
+  -d '{"model": "qwen2.5-14b-instruct", "messages": [{"role": "user", "content": "Dis bonjour"}], "max_tokens": 30}'
+
+# Test inférence Claude
+curl http://127.0.0.1:4000/v1/chat/completions \
+  -H "Authorization: Bearer lm-studio" \
+  -H "Content-Type: application/json" \
+  -d '{"model": "claude-sonnet-4-6", "messages": [{"role": "user", "content": "Dis bonjour"}], "max_tokens": 30}'
+```
+
+---
+
+## Configuration
+
+Fichier : `/etc/litellm/config.yaml` (géré par Ansible, propriété `litellm:litellm`, mode `0640`)
+
+La clé API Anthropic est injectée via `ANTHROPIC_API_KEY` dans l'unit systemd —
+elle vient du vault Ansible (`vault_anthropic_api_key`). Jamais en clair dans config.yaml.
+
+**master_key** : `lm-studio` — doit correspondre à `LM_API_KEY` dans le `.env` Hermes.
+
+---
+
+## Ajouter un modèle
+
+1. Modifier `roles/litellm/templates/config.yaml.j2` :
+   ```yaml
+   - model_name: claude-haiku-4-5
+     litellm_params:
+       model: anthropic/claude-haiku-4-5-20251001
+       api_key: os.environ/ANTHROPIC_API_KEY
+   ```
+
+2. Redéployer :
+   ```bash
+   ansible-playbook -i inventory.yml playbooks/storage-01.yml --tags litellm
+   ```
+
+---
+
+## Points d'attention
+
+| Sujet | Détail |
+|---|---|
+| Accès réseau | `127.0.0.1` uniquement — pour exposer au cluster, changer `litellm_host: 0.0.0.0` + ouvrir firewall |
+| master_key | `lm-studio` — doit correspondre exactement à `LM_API_KEY` dans le `.env` Hermes |
+| Clé Anthropic | `ANTHROPIC_API_KEY` dans l'env systemd — vault Ansible |
+| Coût Claude | Surveiller la consommation sur console.anthropic.com |
+| 404 /api/v1/models | Hermes appelle `/api/v1/models` à l'init (retourne 404) — normal, ne bloque pas |
+| hermes-switch status | Utilise `grep -A3` — si le bloc hermes-default a une structure différente, ajuster |