fix(litellm): request_timeout 600→60s + num_retries 2 (anti-connexion périmée) (#22)

Cause du burst de 502 « cold-start » : après un restart de llama-server, LiteLLM
garde des connexions keep-alive mortes dans son pool → la requête suivante hang
jusqu'au timeout. Or request_timeout valait 600s → hang jusqu'à 10 min, sans log
(LiteLLM attendait encore). Fix :
- request_timeout 60s : borne le hang d'une connexion morte
- num_retries 2 : rejoue → évince le socket périmé, repart sur une connexion neuve

Doc : section dédiée dans admin/incidents-llm-gpu.md (mécanisme + application +
reste à faire = watchdog qui bounce llama-server ET litellm).

Application : ansible-playbook -i inventory.yml playbooks/storage-01.yml --tags litellm
(redémarre LiteLLM → applique le fix ET purge le pool d'un coup).

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

admin/incidents-llm-gpu.md

@@ -85,3 +85,47 @@ ssh gpu-01 'sudo systemctl restart llama-server'
 - **Watchdog** : si LiteLLM accumule des `Timeout` sur `hermes-default`, redémarrer
   automatiquement `llama-server` sur gpu-01.
 - Réduire le `request_timeout` LiteLLM (600 s est très long → un 502 tardif et opaque).
+
+---
+
+## 2026-06-19 (suite) — burst de 502 « cold-start » : connexions keep-alive périmées (LiteLLM)
+
+### Symptôme
+
+Après le déploiement du STT-server résilient (latence ramenée à ~340 ms en régime), un
+**nouveau pod** STT (ou une reprise de trafic après inactivité) voyait ses **1-2 premières
+requêtes hanger ~60 s puis 502**, ensuite tout repartait. Reproductible à chaque rollout.
+
+### Cause
+
+**Connexions keep-alive périmées dans le pool LiteLLM → llama-server.** Les redémarrages de
+`llama-server` (cf. incident ci-dessus) tuent ses connexions, mais LiteLLM garde les
+sockets morts dans son pool. La requête suivante part sur un socket mort → attend dans le
+vide jusqu'au timeout. Or `litellm_settings.request_timeout` valait **600 s** → LiteLLM
+pouvait hanger **10 min** sans rien logguer (d'où « LiteLLM ne logge aucune erreur » pendant
+la fenêtre de 502 : il *attendait* encore). Le STT, lui, abandonne avant (timeout par
+tentative) et renvoie 502.
+
+> Diagnostic clé : llama-server **direct** est stable (10/10 à 0,32 s) ; le hang est dans la
+> couche LiteLLM↔llama-server, pas dans llama-server ni le code STT.
+
+### Correctifs
+
+1. **Côté STT-server** (déployé, v0.2.1) : 2 tentatives avec fermeture du client httpx entre
+   les essais (connexion neuve) + timeout 30 s/tentative. Tolère un blip, mais ne couvre pas
+   un hang > 60 s.
+2. **Côté LiteLLM** (`ansible/roles/litellm/templates/config.yaml.j2`) :
+   ```yaml
+   litellm_settings:
+     request_timeout: 60   # était 600 — borne le hang d'une connexion morte
+     num_retries: 2        # rejoue → évince le socket périmé, repart sur une connexion neuve
+   ```
+   Appliquer : `ansible-playbook -i inventory.yml playbooks/storage-01.yml --tags litellm`
+   (⚠️ redémarre LiteLLM — service partagé Hermes/n8n/Open WebUI/Ghostfolio).
+3. **Purge immédiate** (sans attendre l'IaC) : `sudo systemctl restart litellm` vide le pool.
+
+### Reste à faire (cause racine)
+
+Tant que `llama-server` se fige et nécessite des redémarrages, le pool LiteLLM se re-périme.
+La vraie prévention = **watchdog de génération réelle** qui détecte le freeze et, idéalement,
+bounce **à la fois** llama-server **et** litellm pour repartir sur des connexions saines.

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

@@ -30,7 +30,13 @@ model_list:
 
 litellm_settings:
   drop_params: true
-  request_timeout: 600
+  # 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.
+  num_retries: 2
 
 general_settings:
   master_key: {{ litellm_master_key }}