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

# 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

# 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

# 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)

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

Option B : Version GPU (si ROCm supporté)

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 !