Effi/docs/MEMOIRE-GESTION.md

# Gestion Mémoire - FolzoCorp

## Vue d'ensemble

Ce document décrit les mécanismes de gestion mémoire implementés sur **FolzoCorp** (192.168.1.11) pour optimiser l'utilisation RAM.

## Problème initial

- **RAM Totale**: 32 GB
- **RAM Utilisée**: ~29 GB (93%)
- **Swap utilisé**: 8 GB (100%)
- **Cause principale**: ComfyUI (15.2 GB) + services permanentents

## Solutions implémentées

### 1. effi-stt (Whisper STT)

**Fichier**: `effi-stt/main.py`

**Mécanisme**: Déchargement automatique après inactivité

**Fonctionnement**:
- Le modèle Whisper (`large-v3`) est chargé à la première utilisation
- Après chaque requête, un timer de 300s (5 minutes) est démarré
- Si aucune requête n'est reçue pendant ce délai, le modèle est déchargé
- La mémoire est libérée via `gc.collect()`

**Nouveaux endpoints**:
| Endpoint | Méthode | Description |
|----------|---------|-------------|
| `/unload` | POST | Déchargement manuel du modèle |
| `/reload` | POST | Rechargement manuel du modèle |
| `/stats` | GET | Statistiques (model_loaded, last_request_age) |

**Variables d'environnement**:
| Variable | Défaut | Description |
|----------|--------|-------------|
| `INACTIVITY_TIMEOUT` | 300 | Timeout en secondes avant déchargement |

**Commandes**:
```bash
# Redémarrer avec les nouvelles variables
cd effi-stt
docker compose down
docker compose up -d --build

# Vérifier le statut
curl http://localhost:8200/stats
```

---

### 2. ComfyUI (Image + Audio Generation)

**Fichier**: `scripts/comfyui-unload-monitor.py`

**Mécanisme**: Monitoring externe + déchargement via API

**Fonctionnement**:
- Script Python qui tourne en arrière-plan
- Vérifie l'utilisation VRAM toutes les 60s
- Après 300s (5 minutes) d'inactivité + VRAM utilisée:
  - Exécute un workflow pour décharger tous les modèles
  - Appelle `gc.collect()` et `torch.cuda.empty_cache()`

**Utilisation**:
```bash
# Lancer le monitor
python3 scripts/comfyui-unload-monitor.py

# Avec paramètres personnalisés
python3 scripts/comfyui-unload-monitor.py --timeout 600 --interval 30

# Mode debug
python3 scripts/comfyui-unload-monitor.py --debug

# En arrière-plan (systemd)
nohup python3 scripts/comfyui-unload-monitor.py > /var/log/comfyui-unload.log 2>&1 &
```

**Démarrage automatique (systemd)**:
```bash
# Créer le service
sudo tee /etc/systemd/system/comfyui-unload.service << EOF
[Unit]
Description=ComfyUI Model Unload Monitor
After=network.target docker.service

[Service]
Type=simple
User=folzo
WorkingDirectory=/home/folzo/Documents/OpenCode/Projets/Effi
ExecStart=/usr/bin/python3 scripts/comfyui-unload-monitor.py
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
EOF

# Activer le service
sudo systemctl daemon-reload
sudo systemctl enable comfyui-unload
sudo systemctl start comfyui-unload

# Vérifier le statut
sudo systemctl status comfyui-unload
```

---

### 3. Kreuzberg (Document Extraction)

**Fichier**: `scripts/kreuzberg-memory-manager.py`

**Mécanisme**: Restart automatique après inactivité + seuil mémoire

**Fonctionnement**:
- Vérifie la mémoire du container toutes les 60s
- Si mémoire > 2GB pendant > 10 minutes d'inactivité:
  - Redémarre le container kreuzberg
  - Libère toute la mémoire accumulée

**Note**: Kreuzberg est un service pre-built (image Rust), donc le déchargement interne n'est pas possible. Le restart container est la seule option pour libérer la mémoire.

**Utilisation**:
```bash
# Lancer le manager
python3 scripts/kreuzberg-memory-manager.py

# Avec paramètres personnalisés
python3 scripts/kreuzberg-memory-manager.py --timeout 600 --max-memory 1.5

# En arrière-plan (systemd)
nohup python3 scripts/kreuzberg-memory-manager.py > /var/log/kreuzberg-mem.log 2>&1 &
```

---

## Impact mémoire attendu

| Service | Avant | Après (inactif) |
|---------|-------|-----------------|
| ComfyUI | 15.2 GB | ~500 MB (VRAM libérée) |
| effi-stt | ~3 GB | ~100 MB (modèle déchargé) |
| kreuzberg | 1 GB | ~100 MB (container redémarré) |
| **Total** | **~20 GB** | **< 1 GB** |

---

## Surveillance

### Commandes utiles

```bash
# Vérifier mémoire containers
docker stats --no-stream

# Vérifier VRAM GPU
rocm-smi --showmeminfo vram

# Statuts effi-stt
curl http://localhost:8200/stats

# Logs du monitor ComfyUI
tail -f /var/log/comfyui-unload.log

# Logs du manager Kreuzberg
tail -f /var/log/kreuzberg-mem.log
```

---

## Fichiers modifiés/créés

### Modifiés
- `effi-stt/main.py` - Ajout timeout + déchargement
- `effi-stt/Dockerfile` - Variable INACTIVITY_TIMEOUT
- `effi-stt/docker-compose.yml` - Variable INACTIVITY_TIMEOUT

### Créés
- `scripts/comfyui-unload-monitor.py` - Monitor déchargement ComfyUI
- `scripts/kreuzberg-memory-manager.py` - Manager mémoire Kreuzberg
- `docs/MEMOIRE-GESTION.md` - Cette documentation

---

## Limitations connues

1. **ComfyUI**: Le monitor utilise l'API ComfyUI. Si ComfyUI est complètement bloqué, le monitor pourrait ne pas fonctionner.

2. **Kreuzberg**: Le restart du container interrompt brièvement le service (~5-10s).

3. **effi-stt**: Le premier appel après déchargement sera plus lent (rechargement du modèle).

---

## Améliorations futures possibles

1. Intégrer les monitors dans Docker Compose avec des sidecars
2. Ajouter des métriques Prometheus pour le monitoring
3. Implémenter un agente Effi qui surveille et actionne selon les besoins