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

```bash
# 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

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

### 3. Copier les fichiers du projet

```bash
# 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:

```yaml
---
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

```bash
# 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

```bash
# 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`:

```yaml
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:

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

### Ajouter de l'authentification

Pour limiter l'accès:

```python
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/<username>/<space-name>/logs

### Métriques

Ajoute à `app.py`:

```python
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/<username>/<space-name>/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.)