Spaces:
Sleeping
Sleeping
| 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 de la FAQ au format JSON | |
| ├── embeddings.py # Gestion ChromaDB + modèle transformers | |
| └── data/ | |
| └── faq.json # Exemple de base FAQ (intentions, formulations, réponses) | |
| ``` | |
| ## 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 faq-backend-api | |
| ``` | |
| 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": "Est-ce que c’est gratuit ?" | |
| } | |
| ``` | |
| **Réponse :** | |
| ```json | |
| { | |
| "question": "Est-ce que c’est gratuit ?", | |
| "formulation": "Est-ce que c’est gratuit ?", | |
| "answer": "Oui. L’adhésion et la participation aux projets de l'association sont gratuites. Il n’y a ni frais de formation ni cotisation obligatoire pour contribuer aux projets.", | |
| "theme": "est_ce_que_c_est_gratuit", | |
| "similarity_score": 0.95, | |
| "confidence": true | |
| } | |
| ``` | |
| **Champs de réponse :** | |
| - `question` : Question posée | |
| - `formulation` : Formulation de la FAQ qui correspond le mieux à la question | |
| - `answer` : Réponse trouvée dans la FAQ | |
| - `theme` : Intention de la FAQ (`intent_key`) | |
| - `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": 474 | |
| } | |
| ``` | |
| ### 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": "Est-ce que c’est gratuit ?"}' | |
| # 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": "Est-ce que c’est gratuit ?"}) | |
| 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 | |
| Le fichier d'exemple `data/faq.json` illustre le format attendu (chemin défini par `FAQ_JSON_PATH` dans `config.py`). Il contient une liste `intents` ; chaque intent activé (`enabled: true`) comporte : | |
| - `intent_key` : identifiant de l'intention (renvoyé comme `theme`) | |
| - `canonical_question` et `utterances` : formulations de la question | |
| - `response` : réponse associée | |
| Les FAQs sont chargées et indexées au démarrage de l'application. | |
| ## Hugging Face | |
| L'API est déployée sur Hugging Face Spaces (runtime Docker) : **https://loren-faq-backend-api.hf.space** | |
| | Ressource | URL | | |
| |---|---| | |
| | Swagger UI | https://loren-faq-backend-api.hf.space/docs | | |
| | Question (POST) | https://loren-faq-backend-api.hf.space/ask | | |
| | Santé | https://loren-faq-backend-api.hf.space/health | | |
| | Configuration | https://loren-faq-backend-api.hf.space/config | | |
| Exemple : | |
| ```bash | |
| curl -X POST "https://loren-faq-backend-api.hf.space/ask" -H "Content-Type: application/json" -d '{"question": "Comment je deviens membre ?"}' | |
| ``` | |
| ### Configuration | |
| Dans l'interface du Space, "Settings" → "Variables and secrets" permet de définir les variables d'environnement (ex : `SIMILARITY_THRESHOLD=0.6`). Les logs de build et d'exécution sont consultables depuis l'onglet "Logs". | |
| ### Démarrage | |
| Le démarrage (~30-60s) comprend : | |
| 1. Installation des dépendances | |
| 2. Téléchargement des modèles (embeddings et cross-encoder) | |
| 3. Chargement de la FAQ | |
| 4. Génération des embeddings | |
| Après une période d'inactivité, le Space peut être mis en veille : la première requête peut alors prendre quelques dizaines de secondes. | |
| ## 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** : 3 par défaut (`TOP_K` dans `config.py`) : nombre maximum de thèmes distincts retenus comme candidats (`list_candidates`). Peut être surchargé par requête via le champ `top_k` de `/ask` | |
| ## 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 | |