File size: 7,244 Bytes
2d887e1
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
ac5e637
2d887e1
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
---

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/

    └── 260817_FAQ_Miss_Terry.json    # FAQ Guild Open Tech (intents, 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 got-faq-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": "C'est quoi Guild Open Tech ?"

}

```

**Réponse :**
```json

{

  "question": "C'est quoi Guild Open Tech ?",

  "formulation": "Qu’est-ce que Guild Open Tech ?",

  "answer": "Guild Open Tech est une association qui permet de développer et de partager des compétences utilisables dans le milieu informatique, en développement, gestion de projet, ou RH. [...]",

  "theme": "qu_est_ce_que_guild_open_tech",

  "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": 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": "Comment je deviens membre de Guild Open Tech ?"}'



# 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": "Comment je deviens membre de Guild Open Tech ?"})

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

La FAQ de Guild Open Tech est un fichier JSON situé dans `data/` (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-got-api-faq.hf.space**

| Ressource | URL |
|---|---|
| Swagger UI | https://loren-got-api-faq.hf.space/docs |
| Question (POST) | https://loren-got-api-faq.hf.space/ask |
| Santé | https://loren-got-api-faq.hf.space/health |
| Configuration | https://loren-got-api-faq.hf.space/config |

Exemple :

```bash

curl -X POST "https://loren-got-api-faq.hf.space/ask"   -H "Content-Type: application/json"   -d '{"question": "Comment je deviens membre de Guild Open Tech ?"}'

```

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