feat: anti-502 LLM — heartbeat (litellm) + watchdog auto-réparation (llama_server) (#23)

* feat(litellm): heartbeat anti-502 + request_timeout 20s

Cause racine du 502 « 1ʳᵉ demande après une pause » : la connexion keep-alive
LiteLLM↔llama-server devient inactive → llama-server la ferme → LiteLLM garde le
socket mort → la requête suivante part dans le vide → timeout → 502.

- llm-heartbeat : service systemd qui appelle hermes-default toutes les 15s
  (max_tokens:1, /no_think → ~10ms GPU) → la connexion n'est jamais inactive,
  jamais périmée. Logge les échecs → sert aussi de sonde (vraie génération).
- request_timeout 60→20s : un socket périmé échoue vite, dans la fenêtre où
  num_retries:2 peut rejouer sur une connexion neuve (sinon le client abandonnait
  avant le retry → 502 sec).
- Doc : admin/incidents-llm-gpu.md (fix racine) + README rôle.

⚠️ heartbeat appelle hermes-default en continu → si bascule sur Claude (facturé),
mettre llm_heartbeat_enabled: false. request_timeout global → remonter si Claude.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* feat(llama_server): watchdog auto-réparation du wedge ROCm

Service systemd local sur gpu-01 qui sonde une vraie génération sur :1234
(pas juste /health, qui ment quand le slot d'inférence est figé). Sur N
échecs consécutifs → systemctl restart llama-server en local (root, sans
SSH/sudo distant). Gère le 503 "Loading model" post-restart sans le compter
comme échec.

Complète le llm-heartbeat (rôle litellm) : le heartbeat empêche la péremption
par inactivité de la connexion ; le watchdog répare le figeage du serveur lui-même.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

ansible/roles/litellm/README.md

@@ -10,6 +10,10 @@ Proxy LLM multi-modèles sur storage-01 (`:4000`) — point d'entrée unique pou
   - `/usr/local/bin/ask-agent` — délégation inter-agents (texte → profil system/monitor/brain)
   - `/usr/local/bin/hermes-switch` — bascule l'alias `hermes-default` entre qwen (local) et claude (API), puis restart litellm
   - `/usr/local/bin/funk-cluster` — orchestration start/stop/status du homelab
+  - `/usr/local/bin/llm-heartbeat` (+ service `llm-heartbeat`) — garde chaud le tuyau
+    LiteLLM↔llama-server : petit appel à `hermes-default` toutes les `llm_heartbeat_interval` s.
+    Empêche la connexion keep-alive de devenir périmée → supprime le 502 « 1ʳᵉ demande après
+    une pause » (cf. `admin/incidents-llm-gpu.md`). Logge les échecs (`journalctl -u llm-heartbeat`).
 
 ## Variables principales
 
@@ -19,8 +23,19 @@ Proxy LLM multi-modèles sur storage-01 (`:4000`) — point d'entrée unique pou
 | `litellm_master_key` | `lm-studio` (clé API attendue par les clients) |
 | `litellm_local_llm_base_url` | `http://192.168.10.20:1234/v1` |
 | `litellm_anthropic_api_key` | `{{ vault_anthropic_api_key }}` |
+| `llm_heartbeat_enabled` | `true` |
+| `llm_heartbeat_interval` | `15` (s — doit rester < à l'idle keep-alive du llama-server) |
+| `llm_heartbeat_model` / `llm_heartbeat_timeout` | `hermes-default` / `20` |
+
+## Timeouts & résilience (anti-502 « connexion périmée »)
+
+`litellm_settings` : `request_timeout: 20` (court → un socket périmé échoue vite) + `num_retries: 2`
+(rejoue sur une connexion neuve). Combiné au **heartbeat** (connexion jamais inactive) et au
+retry côté STT-server : la chaîne tolère les blips et les redémarrages de llama-server.
+⚠️ `request_timeout` est global → si `hermes-default` passe sur **Claude** (raisonnement long), le remonter.
 
 ## Caveat
 
 - L'alias `hermes-default` est **ce que Hermes consomme** — changer le modèle derrière l'alias ne nécessite pas de reconfigurer Hermes
 - `hermes-switch` modifie `/etc/litellm/config.yaml` **en dehors d'Ansible** : un `--tags litellm` réécrit la config et peut écraser un switch manuel vers claude
+- Le **heartbeat** appelle `hermes-default` en continu : si tu bascules sur Claude (API facturée), pense à `llm_heartbeat_enabled: false` pour ne pas générer de coût en arrière-plan

ansible/roles/litellm/defaults/main.yml

@@ -13,3 +13,11 @@ litellm_anthropic_api_key: "{{ vault_anthropic_api_key }}"
 # Endpoint llama-server sur gpu-01
 litellm_local_llm_base_url: "http://192.168.10.20:1234/v1"
 litellm_local_llm_api_key: "lm-studio"
+
+# Heartbeat — garde chaud le tuyau LiteLLM↔llama-server (anti-502 « connexion périmée »).
+# Petit appel à hermes-default toutes les N s : la connexion ne devient jamais inactive →
+# la 1ʳᵉ vraie demande après une pause tombe toujours sur un tuyau vivant.
+llm_heartbeat_enabled: true
+llm_heartbeat_model: "hermes-default"   # l'alias que consomme le STT (même tuyau)
+llm_heartbeat_interval: 15              # secondes — doit être < à l'idle keep-alive du llama-server
+llm_heartbeat_timeout: 20               # = request_timeout LiteLLM

ansible/roles/litellm/handlers/main.yml

@@ -7,3 +7,8 @@
   ansible.builtin.systemd:
     name: litellm
     state: restarted
+
+- name: Restart llm-heartbeat
+  ansible.builtin.systemd:
+    name: llm-heartbeat
+    state: restarted

ansible/roles/litellm/tasks/main.yml

@@ -60,3 +60,27 @@
     enabled: true
     daemon_reload: true
     state: started
+
+# ── Heartbeat : garde chaud le tuyau LiteLLM↔llama-server (anti-502 connexion périmée) ──
+- name: Deploy llm-heartbeat script
+  ansible.builtin.template:
+    src: llm-heartbeat.sh.j2
+    dest: /usr/local/bin/llm-heartbeat
+    mode: '0755'
+  notify: Restart llm-heartbeat
+
+- name: Deploy llm-heartbeat service
+  ansible.builtin.template:
+    src: llm-heartbeat.service.j2
+    dest: /etc/systemd/system/llm-heartbeat.service
+    mode: '0644'
+  notify:
+    - Reload systemd
+    - Restart llm-heartbeat
+
+- name: Enable and start llm-heartbeat
+  ansible.builtin.systemd:
+    name: llm-heartbeat
+    enabled: "{{ llm_heartbeat_enabled }}"
+    state: "{{ 'started' if llm_heartbeat_enabled else 'stopped' }}"
+    daemon_reload: true

ansible/roles/litellm/templates/config.yaml.j2

@@ -30,12 +30,16 @@ model_list:
 
 litellm_settings:
   drop_params: true
-  # 600s = 10 min : une connexion keep-alive périmée vers llama-server (après un
-  # restart de ce dernier) fait alors hanger LiteLLM 10 min avant d'abandonner →
-  # 502 en cascade pour tous les consommateurs. 60s borne ce hang.
-  request_timeout: 60
-  # Rejoue une requête échouée (timeout/erreur réseau) : sur la 2ᵉ tentative la
-  # connexion morte du pool est évincée → la requête repart sur une connexion neuve.
+  # Timeout PAR tentative. Doit rester COURT : sur une connexion keep-alive périmée
+  # (llama-server ferme les sockets inactifs), la 1ʳᵉ tentative hang jusqu'à ce timeout.
+  # Il doit être < au budget total du STT-server (2×30s) pour que `num_retries`
+  # ci-dessous ait le temps de rejouer AVANT que le client abandonne (sinon 502 sec).
+  # qwen3-8b /no_think répond en <8s → 20s laisse une grosse marge.
+  # ⚠️ Si on bascule hermes-default sur Claude (raisonnement long), remonter cette valeur.
+  request_timeout: 20
+  # Rejoue une requête échouée (timeout/erreur réseau) : la 2ᵉ tentative évince la
+  # connexion morte du pool → repart sur une connexion neuve. Avec request_timeout=20,
+  # un blip « connexion périmée » se résorbe en ~20s au lieu d'un 502.
   num_retries: 2
 
 general_settings:

ansible/roles/litellm/templates/llm-heartbeat.service.j2

@@ -0,0 +1,16 @@
+[Unit]
+Description=LiteLLM heartbeat — garde chaud le tuyau LiteLLM↔llama-server (anti-502 connexion périmée)
+After=litellm.service network-online.target
+Wants=litellm.service
+
+[Service]
+Type=simple
+ExecStart=/usr/local/bin/llm-heartbeat
+Restart=always
+RestartSec=10
+StandardOutput=journal
+StandardError=journal
+SyslogIdentifier=llm-heartbeat
+
+[Install]
+WantedBy=multi-user.target

ansible/roles/litellm/templates/llm-heartbeat.sh.j2

@@ -0,0 +1,38 @@
+#!/usr/bin/env bash
+# llm-heartbeat — garde « chaud » le tuyau LiteLLM ↔ llama-server.
+#
+# Pourquoi : llama-server ferme les connexions keep-alive inactives, mais LiteLLM
+# garde le socket mort dans son pool → la 1ʳᵉ requête après une pause part dans le
+# vide → timeout → 502 (cf. admin/incidents-llm-gpu.md). Un petit appel régulier
+# maintient la connexion vivante (et la re-crée AVANT la vraie demande si elle est morte).
+#
+# Double rôle (watchdog d'observation) : logge un échec → visible dans
+# `journalctl -u llm-heartbeat`. Déployé/géré par le rôle Ansible `litellm`.
+set -u
+
+URL="http://127.0.0.1:{{ litellm_port }}/v1/chat/completions"
+KEY="{{ litellm_master_key }}"
+MODEL="{{ llm_heartbeat_model }}"
+TIMEOUT="{{ llm_heartbeat_timeout }}"
+INTERVAL="{{ llm_heartbeat_interval }}"
+
+# `/no_think` + max_tokens:1 → génération quasi instantanée (~10 ms GPU), coût négligeable.
+payload="{\"model\":\"${MODEL}\",\"messages\":[{\"role\":\"user\",\"content\":\"ping /no_think\"}],\"max_tokens\":1}"
+
+fails=0
+while true; do
+  code=$(curl -s -m "$TIMEOUT" -o /dev/null -w '%{http_code}' \
+    "$URL" \
+    -H "Authorization: Bearer ${KEY}" \
+    -H "Content-Type: application/json" \
+    -d "$payload" 2>/dev/null) || code="000"
+
+  if [ "$code" = "200" ]; then
+    fails=0
+  else
+    fails=$((fails + 1))
+    echo "heartbeat KO: HTTP ${code} (${MODEL}) — chaîne LLM non réactive (${fails} échec(s) consécutif(s))"
+  fi
+
+  sleep "$INTERVAL"
+done

ansible/roles/llama_server/README.md

@@ -12,6 +12,28 @@ Compile llama.cpp (backend HIP/ROCm) et déploie le service **llama-server GPU**
   `llama-embed` servant un modèle d'embedding spécialisé (ex. `nomic-embed-text`) sur
   `:1238`, GPU. Télécharge le GGUF depuis `llama_embed_model_url` si absent. Partage le
   binaire et le GPU avec `:1234` (modèle ~300 Mo VRAM).
+- **Watchdog** (optionnel, `llama_watchdog_enabled`, défaut `true`) : service systemd
+  `llama-watchdog` qui sonde une **vraie génération** sur `:1234` toutes les
+  `llama_watchdog_interval` s. Sur `llama_watchdog_failures` échecs consécutifs →
+  `systemctl restart llama-server` **en local** (tourne en root, pas de SSH). Répare
+  automatiquement le wedge ROCm où `/health` reste vert mais l'inférence est morte
+  (cf. `admin/incidents-llm-gpu.md`). Logs : `journalctl -u llama-watchdog`.
+
+## Watchdog — variables
+
+| Variable | Défaut |
+|---|---|
+| `llama_watchdog_enabled` | `true` |
+| `llama_watchdog_port` | `{{ llama_server_port }}` (1234) |
+| `llama_watchdog_model` | `{{ llama_model_alias }}` (`qwen3-8b`) |
+| `llama_watchdog_interval` | `20` (s entre deux sondes) |
+| `llama_watchdog_timeout` | `15` (s max par sonde) |
+| `llama_watchdog_failures` | `3` (échecs consécutifs avant restart) |
+
+> Complémentaire au `llm-heartbeat` du rôle `litellm` : le heartbeat empêche la
+> *péremption par inactivité* de la connexion LiteLLM↔llama-server ; le watchdog répare le
+> *figeage* du llama-server lui-même. Le watchdog gère le `503 "Loading model"` post-restart
+> (rechargement VRAM) sans le compter comme échec.
 
 ## Variables principales
 

ansible/roles/llama_server/defaults/main.yml

@@ -25,3 +25,15 @@ llama_embed_model_alias: "nomic-embed-text"
 llama_embed_ctx_size: 2048
 llama_embed_n_gpu_layers: 99
 llama_embed_pooling: "mean"
+
+# Watchdog — auto-réparation du llama-server figé (wedge ROCm gfx1031).
+# Sonde une VRAIE génération sur :1234 (pas seulement /health, qui ment quand le
+# slot d'inférence est bloqué — cf. admin/incidents-llm-gpu.md). Sur N échecs
+# consécutifs → `systemctl restart llama-server` en local (tourne en root).
+llama_watchdog_enabled: true
+llama_watchdog_port: "{{ llama_server_port }}"
+llama_watchdog_model: "{{ llama_model_alias }}"
+llama_watchdog_service: "llama-server"
+llama_watchdog_interval: 20         # s entre deux sondes
+llama_watchdog_timeout: 15          # s max par sonde (génération triviale)
+llama_watchdog_failures: 3          # échecs consécutifs avant restart

ansible/roles/llama_server/handlers/main.yml

@@ -12,3 +12,8 @@
   ansible.builtin.systemd:
     name: llama-embed
     state: restarted
+
+- name: Restart llama-watchdog
+  ansible.builtin.systemd:
+    name: llama-watchdog
+    state: restarted

ansible/roles/llama_server/tasks/main.yml

@@ -123,3 +123,31 @@
     state: enabled
     immediate: true
   when: llama_embed_enabled
+
+# --- Watchdog auto-réparation (wedge ROCm) — optionnel ------------------------
+
+- name: Deploy llama-watchdog script
+  ansible.builtin.template:
+    src: llama-watchdog.sh.j2
+    dest: /usr/local/bin/llama-watchdog
+    mode: '0755'
+  notify: Restart llama-watchdog
+  when: llama_watchdog_enabled
+
+- name: Deploy llama-watchdog service
+  ansible.builtin.template:
+    src: llama-watchdog.service.j2
+    dest: /etc/systemd/system/llama-watchdog.service
+    mode: '0644'
+  notify:
+    - Reload systemd
+    - Restart llama-watchdog
+  when: llama_watchdog_enabled
+
+- name: Enable llama-watchdog service
+  ansible.builtin.systemd:
+    name: llama-watchdog
+    enabled: true
+    daemon_reload: true
+    state: started
+  when: llama_watchdog_enabled

ansible/roles/llama_server/templates/llama-watchdog.service.j2

@@ -0,0 +1,15 @@
+[Unit]
+Description=llama-watchdog (auto-réparation du llama-server figé — ROCm gfx1031)
+After=llama-server.service
+Wants=llama-server.service
+
+[Service]
+Type=simple
+User=root
+ExecStart=/usr/local/bin/llama-watchdog
+Restart=always
+RestartSec=10
+SyslogIdentifier=llama-watchdog
+
+[Install]
+WantedBy=multi-user.target

ansible/roles/llama_server/templates/llama-watchdog.sh.j2

@@ -0,0 +1,52 @@
+#!/usr/bin/env bash
+# llama-watchdog — auto-réparation du llama-server figé (instabilité ROCm gfx1031).
+#
+# Le piège (cf. admin/incidents-llm-gpu.md) : un llama-server wedgé répond encore à
+# /health et /v1/models, mais la GÉNÉRATION est morte. On sonde donc par une VRAIE
+# génération (max_tokens:1, /no_think). Sur N échecs consécutifs → restart local.
+#
+# Tourne en root (service systemd) → peut `systemctl restart` en local, sans SSH ni sudo
+# distant. Déployé/géré par le rôle Ansible `llama_server`.
+set -u
+
+URL="http://127.0.0.1:{{ llama_watchdog_port }}/v1/chat/completions"
+MODEL="{{ llama_watchdog_model }}"
+SERVICE="{{ llama_watchdog_service }}"
+INTERVAL="{{ llama_watchdog_interval }}"
+TIMEOUT="{{ llama_watchdog_timeout }}"
+THRESHOLD="{{ llama_watchdog_failures }}"
+
+payload="{\"model\":\"${MODEL}\",\"messages\":[{\"role\":\"user\",\"content\":\"ping /no_think\"}],\"max_tokens\":1}"
+
+probe() {  # echo le code HTTP ; "000" si pas de réponse (timeout/refus)
+  curl -s -m "$TIMEOUT" -o /tmp/llama-watchdog.body -w '%{http_code}' \
+    "$URL" -H 'Content-Type: application/json' -d "$payload" 2>/dev/null || echo "000"
+}
+
+fails=0
+while true; do
+  code=$(probe)
+
+  if [ "$code" = "200" ]; then
+    fails=0
+  elif [ "$code" = "503" ] && grep -q "Loading model" /tmp/llama-watchdog.body 2>/dev/null; then
+    # Rechargement VRAM (juste après un restart) → ni échec ni succès : on patiente.
+    :
+  else
+    fails=$((fails + 1))
+    echo "watchdog: probe KO (HTTP ${code}) — ${fails}/${THRESHOLD}"
+    if [ "$fails" -ge "$THRESHOLD" ]; then
+      echo "watchdog: ${SERVICE} figé (${THRESHOLD} échecs consécutifs) → restart"
+      systemctl restart "$SERVICE"
+      echo "watchdog: restart émis ; attente du rechargement du modèle…"
+      # Cooldown : attendre que la génération remarche (couvre mort de l'instance + load VRAM).
+      for _ in $(seq 1 30); do
+        sleep 5
+        [ "$(probe)" = "200" ] && { echo "watchdog: ${SERVICE} de nouveau réactif"; break; }
+      done
+      fails=0
+    fi
+  fi
+
+  sleep "$INTERVAL"
+done