Effi/docs/SOLUTION-RECOMMANDEE-STT.md

# 🎙️ SOLUTION RECOMMANDÉE : Voix et Ouïe pour Effi

> **Date** : 05 Avril 2026
> **Statut** : Plan validé après recherche
> **Problème résolu** : Remplacement de speaches (v0.8+ incompatible) par une solution stable

---

## 📋 RÉCAPITULATIF DES ESSAIS

### ✅ Ce qui fonctionne déjà

**TTS (Text-to-Speech)** : 
- **Solution** : openedai-speech
- **Statut** : ✅ Opérationnel sur port 8100
- **Voix** : Piper (anglais) - fonctionne bien
- **GPU** : ROCm activé sur RX 7800 XT

### ❌ Problème rencontré

**STT (Speech-to-Text)** :
- **Solution testée** : speaches v0.8+
- **Problème** : Breaking change avec vérification "model card" (README.md obligatoire)
- **Erreur** : `The model repository does not contain a valid model card`
- **Conclusion** : speaches v0.8+ est incompatible avec les modèles faster-whisper standards

---

## 🎯 SOLUTION RECOMMANDÉE

### STT : whisper-asr-webservice (alternative à speaches)

**Pourquoi cette solution ?**
- ✅ **Stable et éprouvée** : 3.2k stars, maintenue activement
- ✅ **Compatible OpenAI API** : Fonctionne avec Open WebUI
- ✅ **Multi-engine** : Supporte OpenAI Whisper, faster-whisper, whisperX
- ✅ **Image Docker précompilée** : Pas besoin de builder
- ✅ **Pas de "model card" requise** : Contrairement à speaches v0.8+
- ✅ **Support CPU/GPU** : Fonctionne sur CPU (Intel J5040) ou GPU (ROCm)

**Caractéristiques :**
- Port : 8200 (comme prévu)
- Modèle recommandé : `large-v3` ou `faster-whisper-large-v3`
- Format : OpenAI API compatible
- Langue : Français supporté nativement

---

## 🚀 PLAN D'INSTALLATION

### Étape 1 : Arrêter et nettoyer speaches

```bash
# Sur folzo-Corp
cd ~/speaches
sudo docker compose down
sudo docker rm speaches-stt
# Garder le volume pour le cache si tu veux, ou supprimer :
# sudo docker volume rm speaches_speaches-models
```

### Étape 2 : Déployer whisper-asr-webservice

```bash
# Créer le dossier
mkdir -p ~/whisper-asr
cd ~/whisper-asr

# Docker Compose
cat > docker-compose.yml << 'EOF'
services:
  whisper-asr:
    image: onerahmet/openai-whisper-asr-webservice:latest
    container_name: whisper-asr
    restart: unless-stopped
    ports:
      - "8200:9000"
    environment:
      - ASR_ENGINE=faster_whisper
      - ASR_MODEL=large-v3
      - ASR_DEVICE=cpu
      - ASR_MODEL_PATH=/root/.cache/whisper
    volumes:
      - whisper-cache:/root/.cache
    # Optionnel : pour GPU ROCm (si supporté par l'image)
    # devices:
    #   - /dev/kfd
    #   - /dev/dri
    # group_add:
    #   - "44"
    #   - "991"

volumes:
  whisper-cache:
EOF

# Lancer
sudo docker compose up -d

# Attendre le téléchargement du modèle (2-3 min)
echo "⏳ Téléchargement du modèle Whisper..."
sleep 120
sudo docker logs whisper-asr --tail 20
```

### Étape 3 : Tester

```bash
# Test health
curl http://localhost:8200/health

# Test STT
curl -X POST http://localhost:8200/v1/audio/transcriptions \
  -F "file=@/tmp/test_tts.mp3" \
  -F "language=fr"
```

### Étape 4 : Configurer Open WebUI

```
Admin Panel → Settings → Audio

STT :
- Engine : OpenAI
- URL : http://192.168.1.11:8200/v1
- Model : large-v3
- Language : fr
```

---

## 🔧 ALTERNATIVES SI NECESSAIRE

### Option A : Utiliser l'engine "openai_whisper" (plus lent mais stable)

```yaml
environment:
  - ASR_ENGINE=openai_whisper
  - ASR_MODEL=base  # ou small, medium, large-v3
```

### Option B : Version GPU (si ROCm supporté)

```yaml
image: onerahmet/openai-whisper-asr-webservice:latest-gpu
```

**Note** : L'image GPU utilise CUDA par défaut. Pour ROCm (AMD), il faudra peut-être rester en CPU ou builder une image custom.

### Option C : Solution ultra-simple (Python direct)

Si l'image Docker pose problème, on peut créer un mini-serveur Python avec Flask/FastAPI qui wrap faster-whisper directement (3-4 lignes de code).

---

## 📊 COMPARAISON DES SOLUTIONS STT

| Solution | Stabilité | Complexité | ROCm | Commentaire |
|----------|-----------|------------|------|-------------|
| speaches v0.8+ | ❌ Mauvaise | Moyenne | ❌ | Model card requise, incompatible |
| **whisper-asr-webservice** | ✅ Excellente | Faible | ❓ | **RECOMMANDÉ** - Stable, simple |
| whisper.cpp | ✅ Bonne | Élevée | ✅ | Rapide mais complexe à compiler |
| Solution Python custom | ✅ Bonne | Faible | ❓ | Fallback si tout échoue |

---

## ✅ CHECKLIST DE VALIDATION

- [ ] whisper-asr-webservice déployé sur folzo-Corp:8200
- [ ] Modèle téléchargé et chargé
- [ ] Test `/health` OK
- [ ] Test STT avec fichier audio OK
- [ ] Configuration Open WebUI mise à jour
- [ ] Test micro dans Open WebUI OK
- [ ] TTS (openedai-speech) toujours fonctionnel
- [ ] Pipeline vocal complet testé (STT → LLM → TTS)

---

## 📝 NOTES IMPORTANTES

1. **Performance** : En CPU sur Intel J5040, attendre ~5-10s pour 5s d'audio
2. **GPU** : Si ROCm fonctionne un jour, on pourra passer à l'image GPU
3. **Cache** : Le modèle est conservé dans le volume Docker, pas besoin de re-télécharger
4. **Maintenance** : Solution stable, mises à jour via `docker compose pull`

---

**Prochaine étape** : Déployer whisper-asr-webservice et tester !