README_api.md

metadata

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)

git clone <url>
cd choupidou

2. Créer un environnement virtuel (recommandé)

python -m venv venv
# Windows
venv\Scripts\activate
# Linux/Mac
source venv/bin/activate

3. Installer les dépendances

pip install -r requirements.txt

4. Configurer les variables d'environnement (optionnel)

cp .env.example .env
# Éditer .env si nécessaire

5. Lancer l'application

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 :

{
  "question": "Les parents ont-ils besoin de télécharger une application ?"
}

Réponse :

{
  "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 :

{
  "status": "ok",
  "faq_count": 3
}

Documentation interactive : GET /docs

Accéder à la documentation Swagger UI interactive :

http://localhost:8000/docs

Tests

Avec curl

# 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

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 :

# 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

   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