DEPLOYMENT.md

Guide de déploiement sur Hugging Face Spaces

Prérequis

• Compte Hugging Face: https://huggingface.co
• Git installé localement
• Token HF avec permissions write (https://huggingface.co/settings/tokens)

Étapes de déploiement

1. Créer un Space sur Hugging Face

# Visite https://huggingface.co/new-space
# - Remplis le formulaire:
#   - Name: mms-asr-tts (ou autre nom)
#   - License: OpenRAIL (ou CC-BY-NC-4.0 pour correspondre à Meta)
#   - Space SDK: Docker
# - Clique "Create Space"

2. Cloner le Space

git clone https://huggingface.co/spaces/<username>/<space-name>
cd <space-name>

3. Copier les fichiers du projet

# Depuis le répertoire du projet
cp app_v2.py app.py
cp requirements.txt .
cp Dockerfile .
cp README.md .
cp .gitignore .
cp examples.py .
cp client.py .

4. Configurer le fichier de révision de Hugging Face

Crée README_SPACE.md avec les métadonnées:

---
title: Meta MMS ASR/TTS
description: API multilingue pour reconnaissance vocale et synthèse vocale
sdk: docker
pinned: false
app_port: 7860
models:
  - facebook/mms-1b-all
  - facebook/mms-tts-eng
  - facebook/mms-tts-yor
  - facebook/mms-tts-beh
  - facebook/mms-tts-ddn
  - facebook/mms-tts-ewe
  - facebook/mms-tts-gej
  - facebook/mms-tts-tbz
  - facebook/mms-tts-bba
tags:
  - ASR
  - TTS
  - Speech
  - Audio
  - Multilingual
  - MMS
---

5. Pousser vers Hugging Face

# Configure Git si nécessaire
git config user.email "email@example.com"
git config user.name "Your Name"

# Ajoute et pousse
git add .
git commit -m "Initial commit: Meta MMS ASR/TTS API"
git push

6. Attendre le déploiement

Le Space se construira automatiquement (5-15 minutes). Pendant ce temps:

• Les dépendances seront installées
• Les modèles seront téléchargés (peut prendre du temps)
• L'application sera lancée

7. Tester le Space

# Accède à: https://huggingface.co/spaces/<username>/<space-name>
# Teste les endpoints:
# - GET / → Documentation
# - GET /health → État
# - POST /tts → Teste avec du texte en Yoruba/autres langues

Troubleshooting

Erreur: "Model not found"

Solution: Les modèles peuvent prendre du temps à télécharger. Attends 5-10 minutes et réessaie.

Erreur: "CUDA out of memory"

Solution:

• Réduis MAX_AUDIO_LENGTH ou MAX_TEXT_LENGTH
• Utilise CPU au lieu du GPU
• Ajoute à requirements.txt: transformers[deepspeed]

Erreur: "Port already in use"

Solution: Le port 7860 est utilisé par défaut sur HF Spaces. Vérifier app_port dans README.md

Optimisation pour Production

Augmenter les ressources

Modifie le docker-compose.yml:

deploy:
  resources:
    limits:
      memory: 8G
    reservations:
      memory: 4G
      devices:
        - driver: nvidia
          count: 1  # GPU
          capabilities: [gpu]

Ajouter du caching

Modifie le Dockerfile pour persister les modèles:

ENV HF_HOME=/app/hf_cache
ENV TORCH_HOME=/app/torch_cache

Ajouter de l'authentification

Pour limiter l'accès:

from functools import wraps
from flask import request

def require_token(f):
    @wraps(f)
    def decorated(*args, **kwargs):
        token = request.headers.get('Authorization', '').replace('Bearer ', '')
        if token != os.getenv('API_TOKEN'):
            return {'error': 'Unauthorized'}, 401
        return f(*args, **kwargs)
    return decorated

@app.route('/tts', methods=['POST'])
@require_token
def tts():
    # ...

Monitoring

Logs

Accède aux logs du Space:

• https://huggingface.co/spaces///logs

Métriques

Ajoute à app.py:

from prometheus_client import Counter, Histogram

requests_total = Counter('requests_total', 'Total requests', ['method', 'endpoint'])
request_duration = Histogram('request_duration_seconds', 'Request duration', ['endpoint'])

Coûts

• Gratuit: Un Space gratuit avec ressources limitées (2-4GB RAM, pas de GPU)
• Libre (avec GPU): Nécessite un Space payant (~$5-20/mois selon GPU)

Support

Pour les problèmes:

1. Vérifie les logs: https://huggingface.co/spaces///logs
2. Consulte la doc: https://huggingface.co/docs/hub/spaces
3. Pose une question: https://discuss.huggingface.co

Prochaines étapes

1. ✅ Déploie d'abord sur HF Spaces
2. Teste tous les endpoints
3. Collecte du feedback
4. Ajoute des fonctionnalités (streaming, batch processing, etc.)