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/03-guides/installation.md
+335
View File
@@ -0,0 +1,335 @@
# 📦 Guide d'Installation
## Vue d'ensemble
Ce guide décrit l'installation complète de l'infrastructure Effi, du serveur Ubuntu au premier démarrage des services.
**Temps estimé** : 2-3 heures
**Difficulté** : Intermédiaire
---
## Prérequis
### Matériel
**effi-server (serveur principal)** :
- CPU : Intel J5040 ou équivalent (4 cœurs)
- RAM : 8 GB minimum
- Stockage : 50 GB SSD minimum
- OS : Ubuntu Server 22.04 LTS
**folzo-Corp (PC Gaming)** :
- CPU : AMD Ryzen 5 ou supérieur
- RAM : 32 GB recommandé
- GPU : AMD RX 7800 XT (16 GB VRAM)
- OS : Bazzite (Fedora) ou Ubuntu 22.04
### Logiciels requis
**Sur effi-server** :
- Docker Engine 24.x+
- Docker Compose v2+
- curl, git
**Sur folzo-Corp** :
- Ollama
- ROCm 6.3.4 (pour AMD GPU)
- Docker Engine
---
## Étape 1 : Préparation du serveur (effi-server)
### 1.1 Installation de Docker
```bash
# Mettre à jour le système
sudo apt update && sudo apt upgrade -y
# Installer les dépendances
sudo apt install -y ca-certificates curl gnupg lsb-release
# Ajouter la clé GPG officielle de Docker
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
# Ajouter le repository Docker
echo \
"deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
$(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
# Installer Docker
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin
# Vérifier l'installation
sudo docker --version
sudo docker compose version
# Ajouter l'utilisateur au groupe docker (déconnexion/reconnexion nécessaire)
sudo usermod -aG docker $USER
```
### 1.2 Création de la structure de dossiers
```bash
# Créer le dossier principal
mkdir -p ~/effi
cd ~/effi
# Créer les sous-dossiers
mkdir -p mcpo-config
mkdir -p qdrant-storage
mkdir -p couchdb-data
mkdir -p n8n-data
mkdir -p wol-proxy
mkdir -p tts-voices
mkdir -p tts-config
mkdir -p obsidian-vault
```
---
## Étape 2 : Configuration du PC Gaming (folzo-Corp)
### 2.1 Installation d'Ollama
```bash
# Installer Ollama
curl -fsSL https://ollama.com/install.sh | sh
# Vérifier l'installation
ollama --version
# Télécharger les modèles nécessaires
ollama pull qwen2.5:14b
ollama pull qwen2.5:3b
ollama pull bge-m3
# Vérifier les modèles installés
ollama list
```
### 2.2 Configuration de Ollama pour le réseau
```bash
# Créer le fichier de service systemd
sudo systemctl edit ollama.service
```
Ajouter :
```ini
[Service]
Environment="OLLAMA_HOST=0.0.0.0:11434"
```
```bash
# Redémarrer Ollama
sudo systemctl daemon-reload
sudo systemctl restart ollama
# Vérifier que Ollama écoute sur toutes les interfaces
sudo ss -tlnp | grep 11434
```
### 2.3 Installation de ROCm (pour AMD GPU)
```bash
# Sur Bazzite/Fedora
sudo dnf install -y rocm-dev rocm-smi
# Vérifier l'installation
rocm-smi --showproductname
rocminfo | grep gfx
```
### 2.4 Configuration des services Docker sur folzo-Corp
Créer les dossiers :
```bash
mkdir -p ~/speaches
mkdir -p ~/openedai-speech/tts-voices
mkdir -p ~/openedai-speech/tts-config
```
---
## Étape 3 : Configuration de la mémoire persistante
Voir le guide détaillé dans [Configuration Mémoire](./memoire.md).
---
## Étape 4 : Premier démarrage
### 4.1 Configuration du fichier .env
```bash
cd ~/effi
cp .env.example .env
nano .env
```
Remplir toutes les variables :
- `WEBUI_SECRET_KEY` : Générer une clé aléatoire
- `OLLAMA_HOST` : IP de folzo-Corp
- `PC_GAMING_MAC` : Adresse MAC de folzo-Corp
- `COUCHDB_USER/PASSWORD` : Identifiants CouchDB
- `N8N_USER/PASSWORD` : Identifiants n8n
### 4.2 Initialisation de CouchDB
```bash
# Démarrer uniquement CouchDB
docker compose up -d couchdb
# Attendre 10 secondes
sleep 10
# Créer les bases nécessaires
curl -X PUT http://master:VOTRE_MOT_DE_PASSE@192.168.1.27:5984/_users
curl -X PUT http://master:VOTRE_MOT_DE_PASSE@192.168.1.27:5984/_replicator
curl -X PUT http://master:VOTRE_MOT_DE_PASSE@192.168.1.27:5984/obsidian-livesync
```
### 4.3 Démarrage complet
```bash
# Démarrer tous les services
docker compose up -d
# Vérifier l'état
docker compose ps
# Voir les logs
docker compose logs -f
```
---
## Étape 5 : Configuration STT/TTS sur folzo-Corp
### 5.1 Build de speaches (ROCm)
```bash
cd ~
git clone https://github.com/speaches-ai/speaches.git
cd speaches/src
# Modifier pour gfx1100
sed -i 's/gfx1101/gfx1100/g' Dockerfile.rocm-ct2
# Build (prend ~50 min)
docker build -f Dockerfile.rocm-ct2 -t speaches:rocm-ct2 .
```
### 5.2 Téléchargement des voix TTS
```bash
cd ~/openedai-speech/tts-voices
# Voix française Piper
wget https://huggingface.co/rhasspy/piper-voices/resolve/main/fr/fr_FR/upmc/medium/fr_FR-upmc-medium.onnx
wget https://huggingface.co/rhasspy/piper-voices/resolve/main/fr/fr_FR/upmc/medium/fr_FR-upmc-medium.onnx.json
# Configuration
mkdir -p ../tts-config
cat > ../tts-config/config.yaml << 'EOF'
tts-1:
alloy:
model: voices/fr_FR-upmc-medium.onnx
speaker: 0
EOF
```
### 5.3 Démarrage des services audio
```bash
cd ~/speaches
docker compose up -d
cd ~/openedai-speech
docker compose up -d
```
---
## Étape 6 : Vérification finale
### 6.1 Test des services
```bash
# Test OpenWebUI
curl http://192.168.1.27:3000
# Test Ollama
curl http://192.168.1.11:11434/api/tags
# Test STT
curl http://192.168.1.11:8200/v1/models
# Test TTS
curl http://192.168.1.11:8100/v1/models
# Test CouchDB
curl http://192.168.1.27:5984
# Test n8n
curl http://192.168.1.27:5678
```
### 6.2 Accès aux interfaces
| Service | URL |
|---------|-----|
| Open WebUI | http://192.168.1.27:3000 |
| n8n | http://192.168.1.27:5678 |
| CouchDB | http://192.168.1.27:5984/_utils |
| Qdrant | http://192.168.1.27:6333 |
---
## Prochaines étapes
Après l'installation, suivre le guide de [Première Configuration](./premiere-config.md) pour :
- Créer le compte admin
- Configurer les connexions
- Installer les filtres de mémoire
- Tester le pipeline vocal
---
## Dépannage initial
### Les conteneurs ne démarrent pas
```bash
# Voir les logs d'erreur
docker compose logs [nom-du-service]
# Vérifier les ports utilisés
sudo ss -tlnp
# Vérifier les variables d'environnement
docker compose config
```
### Erreur de permissions
```bash
# Fixer les permissions des volumes
sudo chown -R $USER:$USER ~/effi/*-data
sudo chown -R $USER:$USER ~/effi/*-storage
```
### Wake-on-LAN ne fonctionne pas
```bash
# Vérifier que wol-proxy est configuré
docker logs wol-proxy
# Tester le WoL manuellement
sudo apt install wakeonlan
wakeonlan XX:XX:XX:XX:XX:XX # MAC de folzo-Corp
```
docs/03-guides/premiere-config.md
+323
View File
@@ -0,0 +1,323 @@
# ⚙️ Guide de Première Configuration
## Vue d'ensemble
Ce guide couvre la configuration initiale d'OpenWebUI après l'installation, de la création du compte à la mise en place de la mémoire persistante.
---
## Étape 1 : Premier accès à OpenWebUI
### 1.1 Créer le compte administrateur
1. Ouvrir `http://192.168.1.27:3000` dans un navigateur
2. Cliquer sur "Sign up"
3. Créer un compte avec :
- **Nom** : Folzo (ou votre nom)
- **Email** : votre email
- **Mot de passe** : mot de passe fort
**Note** : Le premier compte créé devient automatiquement administrateur.
---
## Étape 2 : Configuration des connexions
### 2.1 Connexion Ollama
**Admin Panel → Settings → Connections**
| Paramètre | Valeur |
|-----------|--------|
| Ollama API URL | `http://192.168.1.27:3011` |
| Verify Ollama API | ✅ Cocher |
Cliquer sur **Save** puis **Verify**.
### 2.2 Configuration Audio
**Admin Panel → Settings → Audio**
#### Paramètres STT (Speech-to-Text)
| Paramètre | Valeur |
|-----------|--------|
| STT Engine | `OpenAI` |
| STT OpenAI API URL | `http://192.168.1.11:8200/v1` |
| STT Model | `deepdml/faster-whisper-large-v3-turbo-ct2` |
| STT API Key | `anything` |
#### Paramètres TTS (Text-to-Speech)
| Paramètre | Valeur |
|-----------|--------|
| TTS Engine | `OpenAI` |
| TTS OpenAI API URL | `http://192.168.1.11:8100/v1` |
| TTS Model | `tts-1` (Piper) ou `tts-1-hd` (XTTS) |
| TTS Voice | `alloy` |
Cliquer sur **Save**.
### 2.3 Configuration RAG (Documents)
**Admin Panel → Settings → Documents**
| Paramètre | Valeur |
|-----------|--------|
| Embedding Model Engine | `Ollama` |
| Ollama Base URL | `http://192.168.1.27:3011` |
| Embedding Model | `bge-m3:latest` |
| Vector Database | `qdrant` |
| Qdrant URL | `http://qdrant:6333` |
Cliquer sur **Save**.
---
## Étape 3 : Création du modèle Effi
### 3.1 Créer le modèle personnalisé
**Admin Panel → Models → + New Model**
| Paramètre | Valeur |
|-----------|--------|
| Model Name | `Effi` |
| Base Model | `qwen2.5:14b` |
Dans le champ **System Prompt**, coller :
```
Tu es Effi, l'assistante IA locale de Folzo (Open WebUI + Ollama).
## Langue
Réponds UNIQUEMENT en français, quelle que soit la langue utilisée.
## Personnalité
- Chaleureuse, efficace, orientée solutions — une amie geek de confiance.
- Humour fin : 0 à 1 vanne max par réponse, jamais forcée.
- Ton conversationnel IRL, phrases courtes, pas de pavés.
## Priorités
1. Répondre à la demande directement et clairement.
2. Ajouter un conseil ou alternative si pertinent.
3. Si ambigu → 1 à 3 questions courtes avant de proposer une solution.
## Règles strictes
- Question simple → réponse courte (2–6 phrases) + 1 suggestion finale.
- Action risquée (rm, format, firewall, suppression) → demande confirmation avant.
- Ne sur-parle pas, pas de répétitions inutiles.
## Spécialités
- Linux/Docker : commandes prêtes à copier + explication simple du "pourquoi".
- Débogage : étape par étape, checks rapides d'abord.
- Écriture : corrige en gardant le style de Folzo.
## Prise de notes
Folzo utilise Obsidian. Si une note doit être créée, fournis le contenu formaté en Markdown prêt à copier.
## Mémoire
N'invente pas de souvenirs. Les infos sur Folzo sont injectées automatiquement ci-dessous.
<memory_user_context></memory_user_context>
```
Cliquer sur **Save**.
---
## Étape 4 : Installation des filtres de mémoire
### 4.1 Installation d'Auto Memory
**Admin Panel → Functions → Discover**
1. Rechercher **"Auto Memory"** par **nokodo**
2. Cliquer sur **Install**
### 4.2 Configuration d'Auto Memory
**Admin Panel → Functions → Auto Memory → ⚙️ (Settings)**
| Paramètre | Valeur |
|-----------|--------|
| OpenAI API URL | `http://192.168.1.27:3011/v1` |
| Model | `qwen2.5:3b` |
| API Key | `toto` |
| Messages To Consider | `10` |
| Related Memories N | `5` |
| Minimum Memory Similarity | `0.7` |
| Override Memory Context | `OFF` |
| Debug Mode | `OFF` |
**Activation** : Admin Panel → Functions → Auto Memory → ⋯ → Toggle Global → **ON**
### 4.3 Patch du code Auto Memory
Le filtre a besoin d'un patch pour gérer correctement les réponses JSON.
**Admin Panel → Functions → Auto Memory → ⋯ → Edit**
1. Chercher : `text_response = response.choices[0].message.content`
2. Remplacer le bloc `if response_model:` par :
```python
if response_model:
try:
cleaned = re.sub(r'```(?:json)?\s*', '', text_response)
cleaned = re.sub(r'```\s*', '', cleaned).strip()
match = re.search(r'\{.*\}', cleaned, re.DOTALL)
if match:
cleaned = match.group(0)
return response_model.model_validate_json(cleaned)
except ValidationError as e:
self.log(f"response model validation error: {e}", level="warning")
raise
return text_response
```
3. Chercher `UNIFIED_SYSTEM_PROMPT` et ajouter au début :
```python
UNIFIED_SYSTEM_PROMPT = """IMPORTANT: Respond with ONLY valid JSON. No markdown formatting, no code blocks, no explanation text. Start your response directly with { and end with }. """ + UNIFIED_SYSTEM_PROMPT
```
4. Cliquer sur **Save**
### 4.4 Installation de Memory Injection Filter
**Admin Panel → Functions → Discover**
1. Rechercher **"Memory Injection Filter"** par **Raphael**
2. Cliquer sur **Install**
### 4.5 Configuration de Memory Injection
**Admin Panel → Functions → Memory Injection Filter → ⚙️**
| Paramètre | Valeur |
|-----------|--------|
| PREPENDING_TEXT | `Voici les souvenirs à long terme de l'utilisateur :` |
| SHOW_MEMORY_COUNT_EMITTER | `ON` |
**Activation** : Admin Panel → Functions → Memory Injection Filter → ⋯ → Toggle Global → **ON**
---
## Étape 5 : Tests de fonctionnement
### 5.1 Test de conversation basique
1. Créer un nouveau chat
2. Sélectionner le modèle **Effi**
3. Envoyer : `Bonjour Effi, comment vas-tu ?`
→ Effi devrait répondre en français avec sa personnalité configurée.
### 5.2 Test de mémoire
**Test d'enregistrement :**
```
Je collectionne les vinyles des années 80
```
Vérifier dans la base SQLite :
```bash
docker cp open-webui:/app/backend/data/webui.db /tmp/webui.db
sqlite3 /tmp/webui.db "SELECT content FROM memory ORDER BY created_at DESC LIMIT 3;"
```
→ Le souvenir devrait apparaître.
**Test de restitution :**
1. Créer un **nouveau chat** (important !)
2. Demander : `Qu'est-ce que tu sais sur mes hobbies ?`
→ Effi devrait mentionner les vinyles sans que vous l'ayez redit.
### 5.3 Test audio (si configuré)
**Test STT :**
- Cliquer sur l'icône micro dans OpenWebUI
- Parler : "Bonjour Effi"
- Vérifier que le texte est transcrit
**Test TTS :**
- Activer la lecture vocale dans les paramètres du chat
- Envoyer un message
- Vérifier que la réponse est lue à voix haute
---
## Étape 6 : Configuration Obsidian LiveSync
### 6.1 Préparer CouchDB
```bash
# Vérifier que CouchDB fonctionne
curl http://192.168.1.27:5984
# Les bases devraient déjà être créées lors de l'installation
# Si ce n'est pas le cas :
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
```
### 6.2 Configurer Obsidian
Dans l'application Obsidian :
1. **Paramètres → Communauté → Parcourir**
2. Installer le plugin **Self-hosted LiveSync**
3. Ouvrir les paramètres du plugin
4. Configurer :
- **URI** : `http://192.168.1.27:5984`
- **Database** : `obsidian-livesync`
- **Username** : `master`
- **Password** : [votre mot de passe CouchDB]
5. Cliquer sur **Test**
6. Si OK, cliquer sur **Apply**
7. Activer la synchronisation
---
## Étape 7 : Optimisations
### 7.1 Activer les mémoires globales
**Admin Panel → Settings → General**
- **Memories** : ✅ ON
- **Memory Mode** : `User` ou `Global`
### 7.2 Configuration des modèles par défaut
**Admin Panel → Settings → Interface**
- **Default Model** : `Effi`
- **Default Language** : `fr-FR`
### 7.3 Personnalisation de l'interface
**Admin Panel → Settings → Interface**
- Changer le thème (clair/sombre)
- Configurer les raccourcis
- Personnaliser le logo et les couleurs
---
## Félicitations !
Effi est maintenant complètement configuré et prêt à l'emploi !
### Prochaines étapes suggérées :
1. **Explorer n8n** : Créer des workflows d'automatisation
2. **Configurer le RAG** : Uploader des documents pour enrichir les réponses
3. **Personnaliser davantage** : Ajuster le system prompt selon vos préférences
4. **Documentation** : Noter vos configurations dans Obsidian
### En cas de problème :
Consulter la section [Dépannage](../04-depannage/) pour les erreurs courantes et leurs solutions.