Folzo/Effi
Public Access
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit: Documentation Effi v1.0

Browse Source 
- Structure complète du projet
- Docker compose de production
- Documentation organisée par thèmes
- Guides d'installation et configuration
- Section dépannage détaillée
- Journal historique
This commit is contained in:
Folzo
2026-04-04 08:45:59 +02:00
commit d1e12cff60
35 changed files with 4656 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/01-architecture/infrastructure.md
+185
View File
@@ -0,0 +1,185 @@
# 🏗️ Architecture Infrastructure
## Vue d'ensemble
Effi fonctionne sur une architecture **multi-machines** avec une séparation claire entre le serveur principal (services Docker) et la station de travail puissante (calcul GPU).
---
## Machines
### effi-server (192.168.1.27)
**Rôle** : Serveur Docker principal, héberge tous les services de l'interface et de la logique
| Caractéristique | Valeur |
|-----------------|--------|
| **OS** | Ubuntu Server 22.04 LTS |
| **CPU** | Intel J5040 (4 cœurs) |
| **RAM** | ~7.6 GB |
| **Stockage** | SSD |
| **GPU** | Aucun (tout est fait en CPU) |
**Services hébergés :**
- Open WebUI (interface utilisateur)
- Qdrant (base vectorielle)
- CouchDB (synchronisation Obsidian)
- n8n (automatisation)
- mcpo (proxy MCP)
- wol-proxy (Wake-on-LAN)
- pipelines (middleware mémoire)
- Watchtower (mises à jour auto)
- Obsidian Server (interface web)
---
### folzo-Corp (192.168.1.11)
**Rôle** : Station de calcul GPU pour LLM et traitement audio
| Caractéristique | Valeur |
|-----------------|--------|
| **OS** | Bazzite (Fedora-based) |
| **CPU** | AMD Ryzen 5800X3D |
| **RAM** | 32 GB+ |
| **GPU** | AMD RX 7800 XT 16 GB VRAM |
| **ROCm** | Version 6.3.4 |
| **Architecture GPU** | gfx1100 |
**Services hébergés :**
- Ollama (LLM qwen2.5:14b)
- speaches (STT Whisper)
- openedai-speech (TTS Piper/XTTS)
---
## Schéma Réseau
```
Internet
│
▼
┌────────────────────────────────────────────────────────────┐
│ Routeur (Box) │
│ DHCP 192.168.1.0/24 │
└────────────────────────────────────────────────────────────┘
│ │
│ │
▼ ▼
┌──────────────┐ ┌──────────────────┐
│ effi-server │◄────────►│ folzo-Corp │
│ 192.168.1.27 │ LAN │ 192.168.1.11 │
│ │ │ │
│ • Docker │ │ • Ollama │
│ • WebUI │ WoL │ • Whisper │
│ • Qdrant │◄─────────│ • TTS │
│ • n8n │ │ • ROCm/GPU │
└──────────────┘ └──────────────────┘
```
---
## Flux de Données
### Pipeline Conversationnelle
```
┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ Micro │────►│ speaches │────►│ Open WebUI │────►│ Ollama │
│ (Client) │ STT │ (folzo-Corp) │ │(effi-server) │ │ (folzo-Corp) │
└──────────────┘ └──────────────┘ └──────┬───────┘ └──────┬───────┘
│ │
│◄───────────────────┘
│ Réponse LLM
│
▼
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ Haut- │◄────│ openedai- │◄────│ Open WebUI │
│ parleurs │ TTS │ speech │ │(traite la │
│ │ │(folzo-Corp) │ │ réponse) │
└──────────────┘ └──────────────┘ └──────────────┘
```
### Wake-on-LAN
Quand OpenWebUI sur effi-server veut appeler Ollama sur folzo-Corp :
1. Requête vers `192.168.1.27:3011` (wol-proxy)
2. wol-proxy vérifie si Ollama répond sur `192.168.1.11:11434`
3. Si non → envoie un Magic Packet WoL à l'adresse MAC configurée
4. Attend que le PC démarre (timeout configurable)
5. Une fois démarré, fait le proxy vers Ollama
---
## Sécurité Réseau
### Ports ouverts sur effi-server
| Port | Service | Exposition |
|------|---------|------------|
| 3000 | Open WebUI | LAN uniquement |
| 5678 | n8n | LAN uniquement |
| 5984 | CouchDB | LAN uniquement |
| 6333 | Qdrant | LAN uniquement |
| 8000 | mcpo | LAN uniquement |
### Ports ouverts sur folzo-Corp
| Port | Service | Exposition |
|------|---------|------------|
| 8100 | openedai-speech | LAN uniquement |
| 8200 | speaches | LAN uniquement |
| 11434 | Ollama | LAN uniquement |
### Recommandations
- Utiliser un VPN (WireGuard, Tailscale) pour l'accès externe
- Jamais exposer les ports directement sur Internet
- Configurer le pare-feu UFW (Ubuntu) ou firewall-cmd (Fedora)
---
## Sauvegardes
### Données critiques à sauvegarder
**Sur effi-server :**
```
~/effi/
├── docker-compose.yml # Configuration
├── .env # Variables (chiffrer)
├── open-webui-data/ # Mémoire, config
├── qdrant-storage/ # Vecteurs RAG
├── couchdb-data/ # Sync Obsidian
└── n8n-data/ # Workflows
```
**Sur folzo-Corp :**
```
~/ollama/ # Modèles téléchargés
~/speaches/models/ # Modèles Whisper
~/openedai-speech/tts-voices/ # Voix TTS
```
### Commande de backup
```bash
# Sur effi-server
tar -czvf effi-backup-$(date +%Y%m%d).tar.gz \
~/effi/docker-compose.yml \
~/effi/.env \
~/effi/open-webui-data/ \
~/effi/qdrant-storage/ \
~/effi/couchdb-data/ \
~/effi/n8n-data/
```
---
## Évolution Future
- **Réservation DHCP** : Fixer les IPs via le routeur
- **DNS local** : Utiliser des noms comme `effi.local` et `folzo-corp.local`
- **Reverse Proxy** : Traefik ou Nginx Proxy Manager pour HTTPS
- **Monitoring** : Prometheus + Grafana pour les métriques
docs/01-architecture/services.md
+230
View File
@@ -0,0 +1,230 @@
# 🐳 Services et Ports
## Tableau récapitulatif
| Service | Hôte | Port | Image | Description |
|---------|------|------|-------|-------------|
| **Open WebUI** | effi-server | 3000 | `ghcr.io/open-webui/open-webui:main` | Interface IA principale |
| **Qdrant** | effi-server | 6333 | `qdrant/qdrant:latest` | Base de données vectorielle |
| **CouchDB** | effi-server | 5984 | `couchdb:3.3` | Backend Obsidian LiveSync |
| **n8n** | effi-server | 5678 | `docker.n8n.io/n8nio/n8n:latest` | Automatisation workflows |
| **mcpo** | effi-server | 8000 | `ghcr.io/open-webui/mcpo:main` | Proxy MCP pour outils |
| **wol-proxy** | effi-server | 3011 | Build local | Wake-on-LAN + Proxy Ollama |
| **pipelines** | effi-server | 9099 | `ghcr.io/open-webui/pipelines:main` | Middleware mémoire mem0 |
| **speaches** | folzo-Corp | 8200 | `speaches:rocm-ct2` (build local) | STT Whisper avec ROCm |
| **openedai-speech** | folzo-Corp | 8100 | `ghcr.io/matatonic/openedai-speech` | TTS Piper/XTTS |
| **Ollama** | folzo-Corp | 11434 | Installation native | LLM (qwen2.5:14b) |
| **Obsidian** | effi-server | 3100 | `lscr.io/linuxserver/obsidian:latest` | Interface Obsidian web |
---
## Description détaillée
### Open WebUI (Port 3000)
**Rôle** : Interface utilisateur principale pour interagir avec l'IA
**Fonctionnalités :**
- Chat textuel avec le LLM
- Support vocal (STT/TTS)
- Gestion des conversations
- Upload de documents (RAG)
- Administration système
**Configuration clé :**
```yaml
environment:
- OLLAMA_BASE_URL=http://host.docker.internal:3011
- VECTOR_DB=qdrant
- QDRANT_URI=http://qdrant:6333
- ENABLE_MEMORIES=true
```
---
### Qdrant (Port 6333)
**Rôle** : Stockage vectoriel pour le RAG (Retrieval Augmented Generation)
**Utilisation :**
- Indexation des documents uploadés
- Recherche sémantique
- Embeddings via `bge-m3:latest`
**Endpoints :**
- API REST : `http://192.168.1.27:6333`
- gRPC : `http://192.168.1.27:6334`
---
### CouchDB (Port 5984)
**Rôle** : Base de données NoSQL pour Obsidian LiveSync
**Fonctionnalités :**
- Synchronisation temps réel des notes Obsidian
- Multi-device (mobile, desktop, web)
- Résolution de conflits intégrée
**Initialisation (premier démarrage) :**
```bash
curl -X PUT http://master:MOT_DE_PASSE@192.168.1.27:5984/_users
curl -X PUT http://master:MOT_DE_PASSE@192.168.1.27:5984/_replicator
curl -X PUT http://master:MOT_DE_PASSE@192.168.1.27:5984/obsidian-livesync
```
---
### n8n (Port 5678)
**Rôle** : Plateforme d'automatisation de workflows
**Cas d'usage :**
- Workflows d'intégration avec Home Assistant
- Automatisations basées sur le calendrier
- Webhooks pour notifications
- Traitement de données
**Authentification :** Basic Auth configurée via variables d'environnement
---
### mcpo (Port 8000)
**Rôle** : Proxy pour le protocole MCP (Model Context Protocol)
**Fonctionnalités :**
- Interface entre OpenWebUI et outils externes
- Exécution de commandes système
- Intégration avec Obsidian MCP
**Configuration :**
Fichier `~/effi/mcpo-config/config.json` :
```json
{
"mcpServers": {}
}
```
---
### wol-proxy (Port 3011)
**Rôle** : Wake-on-LAN + Proxy vers Ollama
**Fonctionnement :**
1. Intercepte les requêtes vers Ollama
2. Envoie un Magic Packet si le PC est éteint
3. Attend le démarrage (timeout: 60s)
4. Proxy la requête vers Ollama
**Variables d'environnement :**
- `TARGET_HOST` : IP du PC Gaming
- `TARGET_MAC` : Adresse MAC pour WoL
- `BROADCAST_IP` : IP de broadcast
---
### pipelines (Port 9099)
**Rôle** : Middleware pour les filtres OpenWebUI
**Utilisation actuelle :**
- Intégration mem0 pour mémoire avancée
- Traitement des messages entrants/sortants
---
### speaches (Port 8200)
**Rôle** : Service STT (Speech-to-Text)
**Caractéristiques :**
- Modèle : `deepdml/faster-whisper-large-v3-turbo-ct2`
- Accélération : ROCm (GPU AMD)
- Langue : Français forcé
- Format : Compatible API OpenAI
**Build personnalisé :**
- Nécessite CTranslate2 compilé pour gfx1100
- Voir guide dépannage ROCm
---
### openedai-speech (Port 8100)
**Rôle** : Service TTS (Text-to-Speech)
**Voix disponibles :**
- `tts-1` : Piper (CPU, rapide) - Voix FR : `fr_FR-upmc-medium`
- `tts-1-hd` : XTTS (GPU, qualité) - Voix clones
**Configuration :**
Fichier `~/openedai-speech/tts-config/config.yaml`
---
### Ollama (Port 11434)
**Rôle** : Serveur LLM
**Modèles installés :**
- `qwen2.5:14b` : LLM principal d'Effi
- `bge-m3:latest` : Modèle d'embeddings pour RAG
- `qwen2.5:3b` : LLM léger pour filtres mémoire
**Commandes utiles :**
```bash
# Lister les modèols
ollama list
# Télécharger un modèle
ollama pull qwen2.5:14b
# Vérifier le statut
curl http://localhost:11434/api/tags
```
---
### Obsidian Server (Port 3100)
**Rôle** : Interface web Obsidian 24/7
**Utilisation :**
- Accès aux notes depuis n'importe où
- Intégration MCP pour modification automatique
- Interface graphique complète
**Note :** Nécessite `shm_size: 1gb` pour la stabilité
---
## Dépendances entre services
```
open-webui
├──► qdrant (pour RAG)
├──► wol-proxy (pour Ollama)
└──► mcpo (pour outils externes)
n8n
└──► Peut appeler tous les services via API
Obsidian (mobile/desktop)
└──► CouchDB (synchronisation)
```
---
## Ressources système
| Service | CPU | RAM | Stockage |
|---------|-----|-----|----------|
| Open WebUI | Faible | ~500 MB | ~1 GB (DB SQLite) |
| Qdrant | Moyen | ~1 GB | Variable (vecteurs) |
| CouchDB | Faible | ~200 MB | Taille des notes |
| n8n | Variable | ~500 MB | Workflows |
| speaches | Élevé (GPU) | ~4 GB VRAM | ~3 GB (modèles) |
| openedai-speech | Moyen | ~2 GB VRAM | ~2 GB (voix) |
| Ollama | Élevé (GPU) | ~10 GB VRAM | ~9 GB (qwen2.5:14b) |