akadmin/Funk-lab
1
0
Fork 0
mirror of https://github.com/Alkatrazz24/Funk-lab.git synced 2026-07-08 17:04:42 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

docs: réorganisation complète de admin/ en 4 domaines thématiques

Browse source 
Structure avant : 20 fichiers à plat dans admin/ — difficile à naviguer.
Structure après : 4 sous-répertoires thématiques + index clair.

Réorganisation :
  admin/ops/    → cluster.md, ansible.md, systeme.md
  admin/infra/  → reseau.md, nfs.md, dnsmasq.md, ssh.md
  admin/k8s/    → talos.md, argocd.md, monitoring.md
  admin/ia/     → llama_server.md, rocm.md, litellm.md, hermes.md

Suppressions :
  - ask-agent.md : contenu fusionné dans ia/hermes.md (section ask-agent)
  - lm_studio.md : obsolète (LM Studio remplacé par llama-server)

Mises à jour contenu :
  - ia/hermes.md : fusion complète avec ask-agent.md (profils, skills,
    SOUL.md, ask-agent CLI, dépannage) — doc unifiée sans redondance
  - ops/cluster.md : section GitOps réduite à 2 lignes + lien argocd.md
  - incidents.md : tableau de résumé en tête + 4 nouveaux incidents
    (Grafana OOMKilled, AlertManager null receiver, llama-server 501,
    nftables règle après drop)
  - README.md : réécrit — navigation rapide + index par domaine

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
alkatrazz 2026-05-14 00:47:58 +02:00
parent d552abd2ef
commit 5bcf95b82e
19 changed files with 633 additions and 677 deletions
Download patch file Download diff file Expand all files Collapse all files

428
admin/ia/hermes.md Normal file
View file

@ -0,0 +1,428 @@
# Hermes Agent
Hermes Agent tourne en deux services systemd sur **storage-01** :
- `hermes-agent` — gateway (messagerie, inférence, outils)
- `hermes-dashboard` — interface web (port 9119)
Il passe par **LiteLLM** (`:4000`) pour toute inférence — Qwen local ou Claude API.
Les données persistantes sont sur le RAID5 : `/srv/data/hermes`.
---
## Architecture
```
Profils Hermes → LiteLLM Proxy (:4000) → llama-server / API Anthropic
├── qwen3-8b → gpu-01:1234 (GPU RX 6700XT)
├── qwen3-1.7b-system → gpu-01:1236 (CPU 14 threads)
├── qwen3-1.7b-monitor → gpu-01:1237 (CPU 14 threads)
├── claude-sonnet-4-6 → api.anthropic.com
└── claude-opus-4-7 → api.anthropic.com
Depuis Hermes (TUI ou ask-agent) :
funk-ai (principal) ──┐
brain ├── LM_BASE_URL=http://127.0.0.1:4000/v1
system │
monitor ──┘
```
---
## Profils
| Profil | Alias CLI | Modèle | Usage |
|---|---|---|---|
| `funk-ai` ◆ | `funk-ai` | qwen3-8b (GPU, ~35 tok/s) | Principal — par défaut |
| `brain` | `brain` | claude-sonnet-4-6 (API) | Analyse complexe — facturé |
| `system` | `system` | qwen3-1.7b-system (CPU, ~21 tok/s) | Traitement texte rapide |
| `monitor` | `monitor` | qwen3-1.7b-monitor (CPU, ~21 tok/s) | Évaluation état services |
`◆` = profil actif par défaut
```bash
# Lancer un profil (nouvelle session TUI)
funk-ai # Qwen3-8B GPU
brain # Claude Sonnet
system # Qwen3-1.7B CPU
monitor # Qwen3-1.7B CPU
# Oneshot
sudo -i -u hermes bash -c 'HERMES_HOME=/srv/data/hermes hermes --profile system -z "ta question"'
# Changer le profil par défaut
sudo -i -u hermes bash -c 'HERMES_HOME=/srv/data/hermes hermes profile use funk-ai'
# Lister les profils
sudo -i -u hermes bash -c 'HERMES_HOME=/srv/data/hermes hermes profile list'
```
> Pas de changement de profil à chaud dans le TUI — ouvrir une nouvelle session.
---
## Service systemd
```bash
sudo systemctl status hermes-agent
sudo systemctl restart hermes-agent
sudo journalctl -u hermes-agent -f
sudo journalctl -u hermes-agent -n 50
```
---
## TUI (chat interactif)
Le TUI nécessite un TTY et doit tourner sous le compte `hermes` :
```bash
ssh storage-01
sudo -i -u hermes
cd /srv/data/hermes
hermes --tui
```
> Lancer depuis un autre compte génère des "gateway error" — toujours utiliser le compte hermes.
---
## Dashboard Web
Accessible depuis le poste admin uniquement (`192.168.1.10`) :
```
http://192.168.1.200:9119
```
```bash
sudo systemctl status hermes-dashboard
sudo systemctl restart hermes-dashboard
sudo journalctl -u hermes-dashboard -f
```
> L'onglet Chat (TUI via WebSocket) ne fonctionne pas dans le dashboard. Utiliser le TUI SSH.
---
## CLI
```bash
# Chat interactif (depuis storage-01, compte hermes)
cd /srv/data/hermes && hermes chat
# Question one-shot
cd /srv/data/hermes && hermes -z "ta question"
# Statut global
hermes status
# Diagnostics
hermes doctor
```
---
## Configuration
### config.yaml (`/srv/data/hermes/config.yaml`)
```yaml
model:
provider: lmstudio
base_url: "http://127.0.0.1:4000/v1"
default: "hermes-default"
context_length: 65536
gateway:
host: "0.0.0.0"
port: 8080
```
### .env (`/srv/data/hermes/.env`)
```bash
LM_BASE_URL=http://127.0.0.1:4000/v1
LM_API_KEY=lm-studio # valeur exacte obligatoire
```
### Variables d'environnement (service systemd)
| Variable | Valeur |
|---|---|
| `HOME` | `/opt/hermes` |
| `HERMES_HOME` | `/srv/data/hermes` |
| `LM_BASE_URL` | `http://127.0.0.1:4000/v1` |
| `LM_API_KEY` | `lm-studio` |
---
## SOUL.md — Identité des profils
Chaque profil peut avoir un fichier `SOUL.md` chargé en **slot #1** du system prompt.
Il définit l'identité de l'agent, son environnement, ses outils et son comportement.
Rechargé à chaque message sans redémarrage du service.
```
/srv/data/hermes/profiles/<profil>/SOUL.md
```
Sources versionnées dans le repo :
```
hermes-skills/souls/funk-ai.md → profil funk-ai
hermes-skills/souls/system.md → profil system
hermes-skills/souls/monitor.md → profil monitor
hermes-skills/souls/brain.md → profil brain
```
Le SOUL.md de `funk-ai` contient : environnement cluster (IPs, machines, services),
accès SSH gpu-01, règles `ask-agent`, routing system/monitor/brain, style de réponse.
```bash
# Déployer un SOUL.md depuis le repo
scp hermes-skills/souls/funk-ai.md storage-01:/tmp/soul.md
ssh storage-01 "sudo cp /tmp/soul.md /srv/data/hermes/profiles/funk-ai/SOUL.md"
# Pas de redémarrage nécessaire — rechargé automatiquement
```
---
## Skills
Les skills sont des fichiers `SKILL.md` chargés en contexte dans chaque session Hermes.
> **Règle critique** : un skill doit être présent dans **deux endroits** :
> - `$HERMES_HOME/skills/<cat>/<nom>/SKILL.md` — répertoire global (référence)
> - `$HERMES_HOME/profiles/<profil>/skills/<cat>/<nom>/SKILL.md` — chargé par le profil
>
> Placer un skill uniquement dans le global ne suffit pas.
```bash
# Lister les skills actifs du profil courant
sudo -u hermes env HERMES_HOME=/srv/data/hermes hermes skills list
# Vérifier qu'un skill est dans le profil funk-ai
sudo ls /srv/data/hermes/profiles/funk-ai/skills/funk/
```
### Skills custom Funk
| Skill | Catégorie | Usage |
|---|---|---|
| `agent-delegation` | `funk` | Déléguer des sous-tâches aux agents system/monitor/brain via `ask-agent` |
### Ajouter un skill custom
```bash
# 1. Créer dans le repo (versionné)
mkdir -p hermes-skills/funk/<nom-skill>
vim hermes-skills/funk/<nom-skill>/SKILL.md
# 2. Déployer dans le répertoire global
sudo mkdir -p /srv/data/hermes/skills/funk/<nom-skill>
sudo cp hermes-skills/funk/<nom-skill>/SKILL.md /srv/data/hermes/skills/funk/<nom-skill>/
# 3. Copier dans le profil cible
sudo mkdir -p /srv/data/hermes/profiles/funk-ai/skills/funk/<nom-skill>
sudo cp /srv/data/hermes/skills/funk/<nom-skill>/SKILL.md \
/srv/data/hermes/profiles/funk-ai/skills/funk/<nom-skill>/
sudo chown -R hermes:hermes /srv/data/hermes/profiles/funk-ai/skills/funk
# 4. Redémarrer + vérifier
sudo systemctl restart hermes-agent
sudo -u hermes env HERMES_HOME=/srv/data/hermes hermes skills list | grep funk
```
### Mettre à jour un skill existant
```bash
vim hermes-skills/funk/agent-delegation/SKILL.md
sudo cp hermes-skills/funk/agent-delegation/SKILL.md \
/srv/data/hermes/skills/funk/agent-delegation/SKILL.md
sudo cp hermes-skills/funk/agent-delegation/SKILL.md \
/srv/data/hermes/profiles/funk-ai/skills/funk/agent-delegation/SKILL.md
sudo chown hermes:hermes \
/srv/data/hermes/profiles/funk-ai/skills/funk/agent-delegation/SKILL.md
sudo systemctl restart hermes-agent
```
---
## ask-agent — Délégation inter-agents
`ask-agent` permet à Hermes (profil `funk-ai`) de déléguer des sous-tâches
aux agents spécialisés. Le skill `funk/agent-delegation` lui enseigne quand et comment.
```
funk-ai (Qwen3-8B GPU)
│
│ Terminal: ask-agent <agent> "question"
▼
ask-agent (/usr/local/bin/ask-agent)
│ POST http://127.0.0.1:4000/v1/chat/completions
▼
LiteLLM Proxy (:4000)
├── ask-agent system → qwen3-1.7b-system (CPU :1236)
├── ask-agent monitor → qwen3-1.7b-monitor (CPU :1237)
├── ask-agent brain → claude-sonnet-4-6 (API Anthropic)
└── ask-agent funk-ai → qwen3-8b (GPU :1234)
```
### Agents disponibles
| Agent | Modèle | Usage idéal |
|---|---|---|
| `system` | Qwen3-1.7B CPU (:1236) | Traitement texte : résumés, formatage, parsing, calculs Linux |
| `monitor` | Qwen3-1.7B CPU (:1237) | Évaluation santé : logs systemd, métriques, état des services |
| `brain` | Claude Sonnet 4.6 (API) | Raisonnement complexe, architecture — facturé |
| `funk-ai` | Qwen3-8B GPU (:1234) | Tâches générales (agent principal lui-même) |
### system vs monitor
| Critère | `system` | `monitor` |
|---|---|---|
| Type de question | "Qu'est-ce que ça signifie ?" / "Résume ça" | "Y a-t-il des erreurs ?" / "Ce service est-il sain ?" |
| Output | Réponse directe, liste de faits | Verdict OK/WARNING/ERROR + actions correctives |
### Utilisation
```bash
# system : traitement de texte
ask-agent system "que signifie cette sortie df -h : <texte>"
ask-agent system "convertis 8192 MiB en GiB"
# monitor : évaluation santé
ask-agent monitor "logs litellm : <texte> — erreurs ?"
ask-agent monitor "status llama-server : <texte> — service sain ?"
# brain : analyse complexe
ask-agent brain "architecture optimale pour ce schéma k8s : <contexte>" --max-tokens 3000
# Avec prompt système personnalisé
ask-agent monitor "est-ce normal ?" --system "Tu es expert Linux, réponds en 1 phrase max."
```
Pattern typique — Hermes collecte en local, délègue l'analyse :
```
Terminal: systemctl --state=failed --no-pager
Terminal: ask-agent monitor "voici les services en erreur : <résultat> — résume les problèmes"
```
### Paramètres du script
Déployé sur storage-01 : `/usr/local/bin/ask-agent`
Source versionnée : `ansible/roles/litellm/files/ask-agent`
| Paramètre | Valeur |
|---|---|
| LiteLLM URL | `http://127.0.0.1:4000/v1/chat/completions` |
| API key | `lm-studio` |
| Timeout | 120s (curl) |
| `/no_think` | Préfixé automatiquement pour system et monitor (évite la surconsommation de tokens) |
```bash
# Redéployer via Ansible
ansible-playbook -i inventory.yml playbooks/storage-01.yml --tags litellm
```
---
## Arborescence
Depuis l'incident 2026-05-13, le code est sur le SSD OS et les données sur le RAID5.
```
/opt/hermes/ → home utilisateur hermes (SSD OS)
├── .local/bin/hermes → wrapper bash → venv hermes-agent
└── .hermes/hermes-agent/ → code source + venv Python
├── venv/ → environnement Python (uv)
├── hermes_cli/ → source CLI
└── web/ → source frontend dashboard
/srv/data/hermes/ → HERMES_HOME (RAID5) — données persistantes
├── config.yaml → configuration profil par défaut (géré Ansible)
├── .env → LM_BASE_URL, LM_API_KEY (géré Ansible)
├── memories/ → mémoire persistante profil par défaut
├── sessions/ → historique sessions
├── logs/ → logs
├── skills/ → skills installées
├── state.db → base SQLite état agent
└── profiles/ → profils isolés
├── funk-ai/ → config.yaml, memories/, sessions/, state.db, SOUL.md
├── brain/
├── system/
└── monitor/
```
---
## Mise à jour de Hermes
```bash
sudo systemctl stop hermes-dashboard hermes-agent
sudo -i -u hermes bash -c 'HOME=/opt/hermes HERMES_HOME=/srv/data/hermes hermes update'
sudo systemctl start hermes-agent hermes-dashboard
sudo systemctl status hermes-agent hermes-dashboard --no-pager
```
Si rebuild frontend nécessaire après mise à jour majeure :
```bash
sudo -u hermes bash -c \
'HOME=/opt/hermes && cd /opt/hermes/.hermes/hermes-agent/web && npm install && npm run build'
sudo systemctl restart hermes-dashboard
```
---
## Dépannage
### ask-agent retourne du garbage
Modèle GGUF potentiellement corrompu (signe d'erreur disque).
```bash
ssh g01 "sudo systemctl status llama-server-system"
ssh g01 "md5sum /mnt/models/<chemin-gguf>"
```
### ask-agent timeout
LiteLLM ou llama-server ne répond pas.
```bash
ssh s01 "curl -s http://localhost:4000/health -H 'Authorization: Bearer lm-studio'"
ssh g01 "systemctl status llama-server-system llama-server-monitor"
```
### Le skill n'est pas chargé
```bash
sudo ls /srv/data/hermes/profiles/funk-ai/skills/funk/agent-delegation/
```
Si absent → copier depuis `/srv/data/hermes/skills/funk/agent-delegation/` et redémarrer.
### Hermes fait SSH vers storage-01
Le skill lui dit "tu es déjà sur storage-01". Une session déjà ouverte charge l'ancien skill.
Fermer le TUI et en ouvrir un nouveau après chaque modification.
---
## Points d'attention
| Sujet | Détail |
|---|---|
| Code vs données | Code + venv : `/opt/hermes/.hermes/hermes-agent/` (SSD OS) — Profils/données : `/srv/data/hermes/` (RAID5) |
| `HERMES_HOME` | Toujours préfixer les commandes hermes avec `HERMES_HOME=/srv/data/hermes` |
| `LM_API_KEY` | Doit valoir `lm-studio` exactement |
| `context_length` | Hermes exige 64k minimum — override via `model.context_length: 65536` dans config.yaml |
| `hermes -z` path | Toujours lancer depuis `/srv/data/hermes` (cherche .git en remontant) |
| LiteLLM requis | `litellm.service` doit tourner avant `hermes-agent` |
| Skills double emplacement | Tout skill custom doit être dans `skills/` ET dans `profiles/funk-ai/skills/` |
| Restart après skill | `systemctl restart hermes-agent` obligatoire après ajout ou modification d'un skill |
| brain coûteux | Claude Sonnet API — réserver aux analyses que system/monitor ne peuvent pas faire |
| Gemma 4 interdit | Crash ROCm sur prompts >800 tokens |
| Dashboard | Accessible uniquement depuis `192.168.1.10:9119` (restreint nftables) |
| TUI | `hermes --tui` nécessite un TTY — utiliser SSH interactif sous le compte hermes |
| `systemd-journal` | Le service inclut ce groupe — `journalctl` fonctionne sans sudo dans le Terminal de Hermes |