01
📖 Qu'est-ce que la recherche vectorielle ?
La recherche vectorielle (ou recherche sémantique) permet de trouver des documents par similarité de sens, et non par correspondance exacte de mots-clés. Notre API expose cette fonctionnalité via un endpoint REST simple d'utilisation.
💡 À retenir : Contrairement à une recherche classique, "discours sur la liberté" trouvera l'Appel du 18 juin même si le mot "liberté" n'apparaît pas textuellement.
🌐 Endpoint public :
https://lemondesemantique.fr/api/v2/search/vector
Caractéristiques :
- ✅ Recherche par texte libre (automatiquement converti en embedding)
- ✅ Recherche par embedding direct (pour les utilisateurs avancés)
- ✅ Top-k : nombre de résultats souhaités
- ✅ Filtrage par métadonnées (date, type, auteur)
- ✅ Scores de similarité (cosinus, euclidien)
02
🧠 Principe de la recherche vectorielle
🔢 Visualisation simplifiée :
"Appel du 18 juin" → [0.12, 0.45, 0.78, 0.03, ...]
"Discours de Bayeux" → [0.14, 0.42, 0.75, 0.05, ...] (proche)
"Recette de cuisine" → [0.89, 0.12, 0.23, 0.91, ...] (éloigné)
Le processus :
- 🔤 Votre requête texte est convertie en embedding (vecteur de 384 dimensions)
- 🔍 L'API compare ce vecteur à tous les vecteurs de discours pré-calculés
- 📊 Calcul de la similarité cosinus (plus le score est proche de 1, plus c'est similaire)
- 📋 Retour des k résultats les plus similaires
📝 Exemple :
Requête : "discours sur la résistance"
Résultat #1 : "Appel du 18 juin" (score: 0.89)
Résultat #2 : "Appel du 22 juin" (score: 0.85)
Résultat #3 : "Discours de Bayeux" (score: 0.62)
03
🔌 Endpoints
POST /api/v2/search/vector - Recherche par texte
curl -X POST https://lemondesemantique.fr/api/v2/search/vector \
-H "Authorization: Bearer votre_clé_api" \
-H "Content-Type: application/json" \
-d '{
"query": "discours sur la liberté",
"top_k": 5,
"min_score": 0.6,
"filter": {
"type": "discours",
"date_after": "1940-01-01"
}
}'
POST /api/v2/search/vector/embed - Recherche par embedding
curl -X POST https://lemondesemantique.fr/api/v2/search/vector/embed \
-H "Authorization: Bearer votre_clé_api" \
-H "Content-Type: application/json" \
-d '{
"embedding": [0.12, 0.45, 0.78, ...],
"top_k": 5
}'
POST /api/v2/embed - Générer un embedding
curl -X POST https://lemondesemantique.fr/api/v2/embed \
-H "Authorization: Bearer votre_clé_api" \
-H "Content-Type: application/json" \
-d '{
"text": "Charles de Gaulle appelle les français à résister"
}'
GET /api/v2/search/vector/stats - Statistiques
curl -X GET https://lemondesemantique.fr/api/v2/search/vector/stats \
-H "Authorization: Bearer votre_clé_api"
04
🎯 Exemples de requêtes
Recherche simple
curl -X POST https://lemondesemantique.fr/api/v2/search/vector \
-H "Authorization: Bearer kg_live_xxxxx" \
-H "Content-Type: application/json" \
-d '{
"query": "appel à la résistance",
"top_k": 3
}'
Avec filtre par auteur
curl -X POST https://lemondesemantique.fr/api/v2/search/vector \
-H "Authorization: Bearer kg_live_xxxxx" \
-H "Content-Type: application/json" \
-d '{
"query": "discours sur l'Europe",
"top_k": 5,
"filter": {
"speaker_id": "emmanuel_macron"
}
}'
Avec seuil de score minimum
curl -X POST https://lemondesemantique.fr/api/v2/search/vector \
-H "Authorization: Bearer kg_live_xxxxx" \
-H "Content-Type: application/json" \
-d '{
"query": "liberté égalité fraternité",
"top_k": 10,
"min_score": 0.7
}'
Génération d'embedding seul
curl -X POST https://lemondesemantique.fr/api/v2/embed \
-H "Authorization: Bearer kg_live_xxxxx" \
-H "Content-Type: application/json" \
-d '{
"text": "Votre texte à vectoriser"
}'
05
📄 Structure de la réponse
{
"query": "appel à la résistance",
"total_results": 3,
"results": [
{
"id": "appel_18_juin",
"title": "Appel du 18 juin",
"speaker": "Charles de Gaulle",
"date": "1940-06-18",
"score": 0.8923,
"snippet": "Le gouvernement français a capitulé...",
"url": "/speeches/appel_18_juin"
},
{
"id": "appel_22_juin",
"title": "Appel du 22 juin",
"speaker": "Charles de Gaulle",
"date": "1940-06-22",
"score": 0.8456,
"snippet": "La lutte doit continuer...",
"url": "/speeches/appel_22_juin"
}
],
"metadata": {
"latency_ms": 12,
"index_size": 124
}
}
| Champ | Description |
|---|
| score | Similarité cosinus (0 à 1, plus haut = plus similaire) |
| snippet | Extrait du document autour de la requête |
| metadata.latency_ms | Temps de réponse en millisecondes |
06
🔗 Intégration dans vos applications
Python
import requests
API_KEY = "kg_live_xxxxx"
url = "https://lemondesemantique.fr/api/v2/search/vector"
response = requests.post(
url,
headers={
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json"
},
json={
"query": "discours sur la liberté",
"top_k": 5
}
)
results = response.json()
for item in results["results"]:
print(f"{item['title']} (score: {item['score']:.3f})")
JavaScript / Node.js
const API_KEY = "kg_live_xxxxx";
const response = await fetch(
"https://lemondesemantique.fr/api/v2/search/vector",
{
method: "POST",
headers: {
"Authorization": `Bearer ${API_KEY}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
query: "discours sur la liberté",
top_k: 5
})
}
);
const data = await response.json();
data.results.forEach(item => {
console.log(`${item.title} (score: ${item.score})`);
});
PHP
$apiKey = "kg_live_xxxxx";
$url = "https://lemondesemantique.fr/api/v2/search/vector";
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
"Authorization: Bearer $apiKey",
"Content-Type: application/json"
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
"query" => "discours sur la liberté",
"top_k" => 5
]));
$response = curl_exec($ch);
$data = json_decode($response, true);
🚀 Chez Le Monde Sémantique
Notre API vectorielle interroge plus de 100 discours en moins de 10ms. Testez-la gratuitement !
🎯 Tester la démo interactive →