# 🤖 Effi - Assistant IA Personnel Self-Hosted

Effi est un assistant IA personnel **100% auto-hébergé**, avec mémoire persistante, discussion vocale, génération d'images/audio, et surveillance système.

---

## 🏗️ Architecture

### Infrastructure Multi-Machines

| Machine | IP | Rôle | Services |
|---------|-----|------|----------|
| **effi-server** | `192.168.1.27` | Serveur Docker principal | OpenWebUI, Qdrant, n8n, llm-proxy, TTS |
| **folzo-Corp** | `192.168.1.11` | Station GPU (LLM + STT) | llama.cpp, Ollama, ComfyUI, effi-stt, kreuzberg |
| **NAS Synology** | `192.168.1.25` | Monitoring | Beszel Hub |

### Schéma Global

```
┌─────────────────────────────────────────────────────────────────────────────┐
│                         NAS SYNOLOGY (192.168.1.25)                         │
│                            Beszel Hub :8090                                │
└─────────────────────────────────────────────────────────────────────────────┘
         │                              │                              │
         │ Monitoring                   │ Monitoring                    │ Monitoring
         ▼                              ▼                              ▼
┌───────────────────────────────────────┐  ┌─────────────────────────────────────────┐
│        EFFI SERVER (192.168.1.27)      │  │         FOLZO-CORP (192.168.1.11)       │
│                                       │  │                                          │
│  ┌──────────────┐  ┌────────────────┐ │  │  ┌──────────────┐  ┌──────────────┐   │
│  │ Open WebUI   │  │ llm-proxy      │ │  │  │ llama.cpp A  │  │ Ollama       │   │
│  │ Port 3000    │  │ :3011 Ollama   │ │  │  │ :8080        │  │ :11434       │   │
│  └──────────────┘  │ :3012 llama.cpp│ │  │  │ (Q4_K_M)     │  │ (vision,     │   │
│  ┌──────────────┐  │ :3015 STT      │ │  │  └──────────────┘  │ embeddings)  │   │
│  │ Qdrant       │  │ :3016 TTS      │ │  │  ┌──────────────┐  └──────────────┘   │
│  │ Port 6333    │  │ :3017 UI switch│ │  │  │ llama.cpp B  │                      │
│  └──────────────┘  │ + Wake-on-LAN  │ │  │  │ :8081        │                      │
│                     └────────────────┘ │  │  │ (IQ4_XS)     │                      │
│                                       │  │  └──────────────┘                      │
│                                       │  │  ┌──────────────┐  ┌──────────────┐   │
│                                       │  │  │ ComfyUI      │  │ effi-stt     │   │
│                                       │  │  │ :8188        │  │ :8200        │   │
│                                       │  │  └──────────────┘  └──────────────┘   │
└───────────────────────────────────────┘  └─────────────────────────────────────────┘
```

**Note :** `llm-proxy` est le point d'entrée unique vers la station GPU. Il fait du Wake-on-LAN : si le PC est éteint, il envoie un paquet magic avant d'attendre que le service cible soit prêt. Voir [WOL et démarrage auto](./docs/WOL-ET-DEMARRAGE-AUTO.md).

---

## 📦 Services

### FolzoCorp (192.168.1.11)

| Service | Port | Image | Rôle | RAM/VRAM | Auto-unload |
|---------|------|-------|------|----------|-------------|
| **llama.cpp A** | 8080 | Native | LLM principal — qwen3.8-27b **Q4_K_M** (17,5GB) | ~28GB | Démarré au boot |
| **llama.cpp B** | 8081 | Native | LLM alternatif — qwen3.8-27b **IQ4_XS** (14,2GB) | ~24GB | Démarré au boot |
| **Ollama** | 11434 | Native | LLM vision + embeddings | ~4-6GB | 5min après dernier usage |
| **ComfyUI** | 8188 | `yanwk/comfyui-boot:rocm` | Image + Audio generation | 18GB shm | ✅ après 10min idle |
| **effi-stt** | 8200 | Build local | Whisper STT | ~20MB | ✅ après 5min idle |
| **kreuzberg** | 8300 | `ghcr.io/kreuzberg-dev/kreuzberg:latest` | Document extraction | ~5MB | ✅ après 10min idle |
| **beszel-agent** | - | `henrygd/beszel-agent:latest` | Monitoring | ~5MB | Auto-start |

### EffiServer (192.168.1.27)

| Service | Port | Image | Rôle |
|---------|------|-------|------|
| **Open WebUI** | 3000 | `ghcr.io/open-webui/open-webui:main` | Interface IA |
| **Qdrant** | 6333 | `qdrant/qdrant:latest` | Vector DB (RAG) |
| **n8n** | 5678 | `docker.n8n.io/n8nio/n8n:latest` | Automatisation |
| **llm-proxy** | 3011/3012/3015/3016/3017 | Build local | Proxy unique + Wake-on-LAN + UI switch |
| **openedai-speech** | 8100 | `ghcr.io/matatonic/openedai-speech` | TTS |
| **beszel-agent** | - | `henrygd/beszel-agent:latest` | Monitoring |

### NAS Synology (192.168.1.25)

| Service | Port | Image | Rôle |
|---------|------|-------|------|
| **Beszel Hub** | 8090 | `henrygd/beszel:latest` | Monitoring central |

---

## 🎯 Fonctionnalités

### 💬 Chat IA
- **Interface**: Open WebUI
- **LLM principal**: llama.cpp (`qwen3.8-27b`) via `llm-proxy:3012`
- **Switch d'instance** : 2 instances llama.cpp (8080 Q4_K_M, 8081 IQ4_XS), bascule via l'UI du proxy sans toucher aux configs
- **LLM vision / embeddings**: Ollama via `llm-proxy:3011`
- **Wake-on-LAN automatique**: le proxy réveille la station GPU si elle est éteinte

### 🔌 llm-proxy — Proxy unique + Wake-on-LAN + UI switch
- **5 routes** : Ollama (`:3011`), llama.cpp (`:3012`), STT (`:3015`), TTS (`:3016`), UI de gestion (`:3017`)
- **Route virtuelle `:3012`** : pointe vers l'instance llama.cpp active (8080 ou 8081), choix persisté dans `llm-proxy/state/active.json`
- **Alias modèle** : les harnais envoient toujours `qwen3.8-27b` ; le proxy réécrit l'id réel dans les 2 sens (requêtes, `/v1/models`, streaming SSE) → le switch est invisible pour OpenWebUI/OpenFox/Hermes
- **Wake-on-LAN** : si le PC est éteint, envoie 3 paquets magic (MAC `04:D9:F5:D1:EC:DF`) puis attend le service
- **Anti-spam WOL** : un seul réveil en cours à la fois, pas de re-envoi pendant l'attente
- **Fail-fast** : PC up mais instance cible éteinte → 503 après 20s (pas de WOL)
- **API OpenAI-compatible** : `/v1/models` et `/v1/chat/completions` sur les routes LLM
- **Streaming** : passthrough des réponses SSE (alias réécrit par ligne)
- **UI `:3017`** : statut des 2 instances, bouton *Activer* (persisté), bouton *Tester* (latence + réponse)

#### Switcher entre les 2 versions de qwen3.8

1. Sur le PC : démarrer l'instance voulue (et arrêter l'autre — une seule tient dans la VRAM)
2. Ouvrir http://192.168.1.27:3017 → *Tester* pour vérifier que l'instance répond → *Activer*
3. Terminé : `:3012` sert désormais la nouvelle instance, zéro changement de config côté harnais

```bash
# Alternative sans UI
curl -X POST http://192.168.1.27:3017/api/activate -d '{"real":"qwen3.8-27b"}'          # instance A (8080)
curl -X POST http://192.168.1.27:3017/api/activate -d '{"real":"qwen3.8-27b-iq4xs"}'    # instance B (8081)
curl http://192.168.1.27:3017/api/status
```

### 🎤 Pipeline Vocal
- **STT**: Whisper large-v3 via effi-stt (CPU, déchargement auto)
- **TTS**: openedai-speech (serveur, voix Piper + XTTS)

### 🖼️ Génération Images/Audio
- **ComfyUI**: Workflows pour image et audio
- **Modèle audio**: ACE-Step (génération musicale)
- **Modèles image**: Multiples checkpoints disponibles

### 📄 Extraction Documents
- **Kreuzberg**: Extraction 90+ formats (PDF, DOCX, images, etc.)
- Intégré à OpenWebUI via CONTENT_EXTRACTION_ENGINE=docling

### 🧠 Mémoire
- **Type**: Mémoire manuelle via OpenWebUI (snippets)
- **RAG**: Qdrant pour embeddings sémantiques

### 📊 Monitoring

- **URL Beszel**: http://192.168.1.25:8090
- **Agents actifs**:
  - FolzoCorp (192.168.1.11) - GPU AMD RX 7800 XT
  - EffiServer (192.168.1.27) - Intel J5040

### 🛠️ Tool OpenWebUI - Beszel

Outil custom pour interroger Beszel depuis OpenWebUI via Effi.

**Fonctionnalités actuelles**:
- `get_system_stats` → retourne CPU, RAM, GPU (%)
- Données temps réel depuis `info` (cpu, mp=gpu, g=gpu, dt=timestamp)

**Documentation**: [Tool Beszel OpenWebUI](./docs/TOOL-BESZEL-OPENWEBUI.md)

### Scripts Memory

| Script | Condition | Action |
|--------|-----------|--------|
| comfyui-memory-manager.py | 10min idle + VRAM<1% + RAM>5GB | Restart container |
| kreuzberg-memory-manager.py | 10min idle + RAM>2GB | Restart container |
| effi-stt | 5min idle | Déchargement modèle Whisper |

### Commandes Utiles

```bash
# Statut services
docker ps
docker logs -f llm-proxy

# Tester le proxy (PC allumé)
curl http://192.168.1.27:3012/health
curl http://192.168.1.27:3011/api/version

# Métriques Beszel
python3 scripts/beszel_client.py --system folzocorp --check stats
```

---

## 📚 Documentation

- [WOL et démarrage auto](./docs/WOL-ET-DEMARRAGE-AUTO.md)
- [Installation Beszel](./docs/BESZEL-INSTALLATION.md)
- [Gestion Mémoire](./docs/MEMOIRE-GESTION.md)
- [Session 2026-04-12](./docs/SESSION-2026-04-12-RAM-BESZEL.md)
- [Guide ACE-Step](./docs/guide-ace-step.md)
- [Guide ComfyUI](./comfyui/README.md)

---

## 🔗 Technologies

| Domaine | Technologies |
|---------|-------------|
| **LLM** | llama.cpp (principal), Ollama (vision + embeddings) |
| **Proxy / WOL** | llm-proxy (Flask, proxy multi-cibles + Wake-on-LAN) |
| **Interface** | Open WebUI |
| **STT** | Faster Whisper (CPU) |
| **TTS** | openedai-speech (Piper + XTTS) |
| **Image/Audio** | ComfyUI + ACE-Step |
| **Vector DB** | Qdrant |
| **Document** | Kreuzberg (docling) |
| **Automatisation** | n8n |
| **GPU** | AMD RX 7800 XT (ROCm) |
| **Monitoring** | Beszel |

---

## 📁 Structure du Projet

```
effi/
├── llm-proxy/                # Proxy unique + Wake-on-LAN + UI switch
│   ├── app.py
│   ├── Dockerfile
│   └── state/                # Persistance instance active (active.json)
│
├── beszel/                    # Configuration Beszel
│   ├── docker-compose-hub.yml          # Hub (Synology)
│   ├── docker-compose-agent-folzocorp.yml  # Agent FolzoCorp
│   └── docker-compose-agent-effiserver.yml # Agent EffiServer
│
├── comfyui/                  # ComfyUI (Image/Audio)
│   ├── docker-compose.yml
│   ├── custom_nodes/          # Nodes personnalisés
│   ├── models/               # Modèles checkpoints, VAE, LoRA
│   └── workflows/            # Workflows JSON
│
├── effi-stt/                 # STT Whisper
│   ├── docker-compose.yml
│   ├── Dockerfile
│   └── main.py               # API avec timeout auto-unload
│
├── effi-kreuzberg/           # Documentation Kreuzberg
│   ├── README.md
│   └── MIGRATION.md
│
├── scripts/                  # Scripts utilitaires
│   ├── beszel_client.py      # Client API Beszel
│   ├── comfyui-memory-manager.py    # Restart ComfyUI après idle
│   ├── kreuzberg-memory-manager.py   # Restart Kreuzberg si >2GB
│   └── start-memory-monitors.sh
│
├── systemd/                  # Services systemd
│   ├── comfyui-memory-manager.service
│   ├── kreuzberg-memory-manager.service
│   └── beszel-agent-wake.service
│
├── docs/                     # Documentation
│   ├── WOL-ET-DEMARRAGE-AUTO.md
│   ├── BESZEL-INSTALLATION.md
│   ├── MEMOIRE-GESTION.md
│   └── TOOL-BESZEL-OPENWEBUI.md
│
└── docker-compose.yml        # Stack principale (effi-server)
```

---

## 📝 Historique

**Septembre 2026** - Switch d'instance llama.cpp
- 2 instances llama.cpp sur folzo-Corp (8080 Q4_K_M, 8081 IQ4_XS)
- Route virtuelle `:3012` + alias modèle `qwen3.8-27b` : switch transparent, zéro re-config harnais
- UI de gestion `:3017` (statut, Activer, Tester)
- Fail-fast 503 (20s) quand l'instance active est éteinte, sans spam WOL

**Août 2026** - Simplification : proxy unique + Wake-on-LAN

### llm-proxy ✅
- Un seul service remplace jean-router, jean-proxy, jean-proxy-moe, wol-proxy
- 4 routes : Ollama (`:3011`), llama.cpp (`:3012`), STT (`:3015`), TTS (`:3016`)
- Wake-on-LAN intégré avec anti-spam (un seul réveil en cours)
- Suppression de tout le code Jean (plus besoin de routing dynamique)
- OpenWebUI pointe vers `llm-proxy:3011` (Ollama) et `llm-proxy:3012` (llama.cpp)

**Juillet 2026** - Routing dynamique (abandonné)
- jean-router : routing dynamique Jean/Ollama + gestion VRAM (supprimé)

**Avril 2026** - Optimisation RAM + Monitoring + Tool OpenWebUI
- Scripts déchargement mémoire avec restart container (ComfyUI, Kreuzberg)
- Timeout inactivité 300s pour effi-stt avec déchargement Whisper
- Beszel Monitoring (Hub NAS + agents FolzoCorp/EffiServer)
- Tool OpenWebUI Beszel

**Février 2026** - Stack Vocale
- effi-stt avec Whisper large-v3
- openedai-speech avec XTTS v2
- Kreuzberg pour extraction documents

---

## 🙋 Auteur

**Folzo** - [gitea.folzocorp.fr/Folzo](https://gitea.folzocorp.fr/Folzo)

---

*Dernière mise à jour : Août 2026*