README_api.md

---
title: API FAQ - Embeddings Multilingues
description: API FastAPI pour répondre à des questions via recherche de similarité sur une base FAQ avec embeddings multilingues
sdk: docker
---

# API FAQ - Embeddings Multilingues

API FastAPI permettant de répondre à des questions en cherchant la réponse la plus similaire dans une base FAQ via recherche d'embeddings multilingues.

## Caractéristiques

- 🌍 **Multilingue** : Utilise le modèle `intfloat/multilingual-e5-small` pour supporter plusieurs langues
- 🚀 **Rapide** : Recherche par similarité cosinus via ChromaDB
- 📊 **Seuil configurable** : Filtrage des réponses selon un seuil de confiance
- 📝 **Type-safe** : Utilise Pydantic pour la validation des données
- 📚 **Documentation interactive** : Swagger UI intégrée via `/docs`

## Architecture

```
app.py                  # Point d'entrée FastAPI
├── models.py           # Modèles Pydantic (QuestionInput, AnswerOutput)
├── config.py           # Configuration centralisée
├── faq_loader.py       # Chargement des fichiers CSV
├── embeddings.py       # Gestion ChromaDB + modèle transformers
└── data/
    ├── faq_formulations.csv    # Questions FAQ
    └── faq_responses.csv       # Réponses FAQ
```

## Installation locale

### Prérequis
- Python 3.8+
- pip ou conda

### Étapes

1. **Cloner le repository** (ou télécharger les fichiers)
```bash
git clone <url>
cd choupidou
```

2. **Créer un environnement virtuel** (recommandé)
```bash
python -m venv venv
# Windows
venv\Scripts\activate
# Linux/Mac
source venv/bin/activate
```

3. **Installer les dépendances**
```bash
pip install -r requirements.txt
```

4. **Configurer les variables d'environnement** (optionnel)
```bash
cp .env.example .env
# Éditer .env si nécessaire
```

5. **Lancer l'application**
```bash
uvicorn app:app --reload
```

L'API sera accessible à `http://localhost:8000`

## Utilisation

### Endpoint principal : POST `/ask`

Poser une question et obtenir la réponse la plus similaire

**Requête :**
```json
{
  "question": "Les parents ont-ils besoin de télécharger une application ?"
}
```

**Réponse :**
```json
{
  "question": "Les parents ont-ils besoin de télécharger une application ?",
  "answer": "Non. Les parents accèdent aux médias via un lien web reçu par e-mail, sans installation requise.",
  "theme": "need_download_family_app",
  "similarity_score": 0.95,
  "confidence": true
}
```

**Champs de réponse :**
- `question` : Question posée
- `answer` : Réponse trouvée dans la FAQ
- `theme` : Catégorie/thème de la FAQ
- `similarity_score` : Score de similarité cosinus [0, 1]
- `confidence` : `true` si le score ≥ seuil de confiance, `false` sinon

### Endpoint santé : GET `/health`

Vérifier l'état du service et le nombre de FAQs indexées

**Réponse :**
```json
{
  "status": "ok",
  "faq_count": 3
}
```

### Documentation interactive : GET `/docs`

Accéder à la documentation Swagger UI interactive :
```
http://localhost:8000/docs
```

## Tests

### Avec curl

```bash
# Test question connue
curl -X POST "http://localhost:8000/ask" \
  -H "Content-Type: application/json" \
  -d '{"question": "Les parents ont-ils besoin de télécharger une application ?"}'

# Test question inconnue
curl -X POST "http://localhost:8000/ask" \
  -H "Content-Type: application/json" \
  -d '{"question": "Comment faire des crêpes ?"}'

# Health check
curl "http://localhost:8000/health"
```

### Avec Python

```python
import requests

url = "http://localhost:8000/ask"
response = requests.post(url, json={"question": "Les parents ont-ils besoin de télécharger une application ?"})
print(response.json())
```

### Avec Postman ou Insomnia

Importer la collection depuis `/docs` ou créer manuellement une requête POST vers `/ask`

## Configuration

### Variables d'environnement

Créer un fichier `.env` (voir `.env.example`) pour configurer :

```env
# Modèle d'embedding
MODEL_NAME=intfloat/multilingual-e5-small

# Seuil de confiance [0.0, 1.0]
# 0.5 par défaut
SIMILARITY_THRESHOLD=0.5
```

### Fichiers de données

Les fichiers FAQ doivent être dans `data/` :
- `faq_formulations.csv` : colonnes `formulation;theme`
- `faq_responses.csv` : colonnes `theme;response`

Les FAQs sont chargées et indexées au démarrage de l'application.

## Déploiement sur Hugging Face Spaces

### Étapes

1. **Créer un Hugging Face Space**
   - Aller sur https://huggingface.co/spaces
   - Cliquer sur "Create new Space"
   - Choisir "Docker" comme runtime (ou "Python 3" + Dockerfile)

2. **Configurer le repository**
   - Cloner le Space : `git clone https://huggingface.co/spaces/<username>/<space-name>`
   - Copier les fichiers du projet

3. **Pousser le code**
   ```bash
   git add .
   git commit -m "Initial commit: FAQ API"
   git push
   ```

4. **HF Spaces va automatiquement**
   - Déployer l'application
   - Générer les embeddings au démarrage
   - Rendre l'API publique avec HTTPS

5. **Accéder à l'API**
   - Swagger UI : `https://<username>-<space-name>.hf.space/docs`
   - Endpoint `/ask` : `https://<username>-<space-name>.hf.space/ask`
   - Health : `https://<username>-<space-name>.hf.space/health`

### Configuration HF Spaces

Dans l'interface web du Space, vous pouvez configurer :

- **Secrets** : Ajouter des variables d'env sensibles via "Settings" → "Repository Secrets"
  - Ex: `SIMILARITY_THRESHOLD=0.6`

- **Resources** : Allouer CPU/RAM (par défaut: CPU standard)

- **Logs** : Consulter les logs de déploiement et runtime

### Démarrage prévu

Le démarrage (~30-60s) comprend :
1. Installation des dépendances
2. Téléchargement du modèle d'embedding (~500MB)
3. Chargement des FAQ
4. Génération des embeddings

## Architecture ChromaDB

### EphemeralClient (Option utilisée)

Les embeddings sont chargés en mémoire au démarrage et recalculés à chaque redémarrage :

**Avantages :**
- ✓ Plus rapide (pas d'I/O disque)
- ✓ Pas de dépendance de persistance
- ✓ Idéal pour HF Spaces (ressources limitées)

**Inconvénients :**
- Les embeddings sont recalculés à chaque déploiement (~30s)

### PersistentClient (Alternative)

Si vous préférez persister les embeddings sur disque, remplacer `EphemeralClient` par `PersistentClient` dans `embeddings.py`.

## Considérations de performance

- **Modèle** : `multilingual-e5-small` (~50MB)
- **Threshold** : Augmenter pour être plus strict, réduire pour plus de matches
- **Top-k** : Actuellement set à 1 (retourne le meilleur match) - modifier dans `embeddings.py` pour en retourner plusieurs

## Troubleshooting

### "ModuleNotFoundError: No module named 'chromadb'"

→ Installer les dépendances : `pip install -r requirements.txt`


### Pas de réponses trouvées

→ Vérifier le seuil : `SIMILARITY_THRESHOLD` trop élevé ?

→ Augmenter : `SIMILARITY_THRESHOLD=0.3` ou vérifier que les FAQs sont bien chargées via `/health`

## Logs

Les logs sont affichés au démarrage et en temps réel :
- 🚀 Démarrage
- 📚 Chargement FAQ
- ✓ Application prête
- 📝 Questions reçues
- ✓/❌ Réponses trouvées