{"title":"Recherche sémantique (embeddings)","slug":"semantic-search","category":"concepts","summary":"Recherche de mémoire conceptuelle utilisant des embeddings vectoriels — trouver par signification, pas seulement par mots-clés.","audience":["human","llm"],"tags":["concept","semantic","embeddings","vector-search"],"difficulty":"advanced","updated":"2026-06-27","word_count":648,"read_minutes":3,"lang":"fr","translated":true,"requested_lang":"fr","content_markdown":"\n# Recherche sémantique (embeddings)\n\nSynapse prend en charge la recherche sémantique utilisant des embeddings vectoriels.\nContrairement à FTS5 (correspondance par mots-clés), la recherche sémantique trouve\nles mémoires par **signification** — même si aucun mot-clé ne correspond.\n\n## Comment ça marche\n\n```\n1. Memory stored → embedding generated → vector stored\n2. Search query → embedding generated → vector compared\n3. Cosine similarity → top N results returned\n```\n\n### Que sont les embeddings ?\n\nLes embeddings sont des représentations vectorielles numériques du texte. Le texte\navec une signification similaire a des vecteurs similaires. Synapse génère un vecteur\n(ex. 1536 dimensions) pour le contenu de chaque mémoire.\n\n### Similarité cosinus\n\nPour trouver les mémoires sémantiquement similaires, Synapse calcule la similarité\ncosinus entre le vecteur de requête et chaque vecteur de mémoire. Similarité plus\nélevée = plus pertinent.\n\n## Quand utiliser la recherche sémantique\n\n### Utilisez la recherche sémantique quand :\n\n- Vous voulez « des mémoires sur X » où X est décrit différemment que stocké\n- FTS5 ne renvoie aucun résultat (aucune correspondance de mot-clé)\n- Vous voulez un regroupement conceptuel (ex. toutes les mémoires « deployment », même si certaines disent « release »)\n- La requête est une question : « comment gérons-nous l'authentification ? »\n\n### Utilisez FTS5 quand :\n\n- Vous connaissez les mots-clés exacts\n- Vous avez besoin de logique booléenne (AND, OR, NOT)\n- Vous avez besoin d'une réponse sub-milliseconde\n- Vous voulez la correspondance de phrase\n\n## Endpoint\n\n### GET /memory/semantic-search\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/memory/semantic-search?q=container+orchestration\"\n```\n\nRéponse :\n\n```json\n{\n \"results\": [\n {\n \"id\": \"mem_001\",\n \"category\": \"project\",\n \"key\": \"project_synapse_deployment\",\n \"content\": \"Synapse deployed using Docker Swarm on vps1...\",\n \"tags\": [\"docker\", \"swarm\", \"deployment\"],\n \"similarity\": 0.89\n },\n {\n \"id\": \"mem_042\",\n \"category\": \"fact\",\n \"key\": \"kubernetes_cluster\",\n \"content\": \"We use Kubernetes for production orchestration...\",\n \"tags\": [\"kubernetes\", \"orchestration\"],\n \"similarity\": 0.84\n }\n ]\n}\n```\n\n## Exemples\n\n### Trouver les mémoires de déploiement\n\n```bash\n# FTS5 peut en manquer — la sémantique les attrape toutes\ncurl .../memory/semantic-search?q=deployment+process\n```\n\nRenvoie les mémoires sur « deployment », « release », « publishing », « rolling out »,\netc.\n\n### Trouver les schémas d'authentification\n\n```bash\ncurl .../memory/semantic-search?q=how+do+users+log+in\n```\n\nRenvoie les mémoires sur le login, l'auth, le JWT, la gestion de session, OAuth, etc.\n\n### Trouver des mémoires similaires\n\n```bash\n# Trouver les mémoires similaires à une spécifique\ncurl .../memory/related/mem_001\n```\n\nUtilise la similarité sémantique (via tags partagés ET vecteurs d'embedding).\n\n## Génération d'embeddings\n\n### Quand les embeddings sont-ils générés ?\n\n- **Au stockage de mémoire** — si le service d'embeddings est configuré, l'embedding est généré de manière synchrone\n- **Génération par lot** — `POST /memory/embed-batch` génère des embeddings pour les mémoires qui en manquent\n- **Mises à jour asynchrones** — quand le contenu est mis à jour, l'embedding est régénéré\n\n### Fournisseurs d'embeddings\n\nSynapse prend en charge des fournisseurs d'embeddings configurables :\n\n- **OpenAI** (`text-embedding-3-small`, `text-embedding-3-large`)\n- **Modèles locaux** (via Ollama ou similaire)\n- **Personnalisé** (implémentez l'interface embeddings)\n\nConfigurez via des variables d'environnement :\n\n```bash\nEMBEDDINGS_PROVIDER=openai\nEMBEDDINGS_API_KEY=sk-...\nEMBEDDINGS_MODEL=text-embedding-3-small\n```\n\n### Génération par lot\n\nPour les minds avec beaucoup de mémoires sans embeddings :\n\n```bash\n# Générer des embeddings pour jusqu'à 100 mémoires\ncurl -X POST https://synapse.schaefer.zone/memory/embed-batch \\\n -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"limit\": 100}'\n\n# Vérifier la progression\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n https://synapse.schaefer.zone/memory/embed-batch-status\n```\n\n## Performance\n\n| Opération | Latence |\n|-----------|---------|\n| Génération d'embedding (OpenAI) | 100-200 ms |\n| Recherche sémantique (1k mémoires) | 50-100 ms |\n| Recherche sémantique (10k mémoires) | 200-500 ms |\n| Génération par lot (100 mémoires) | 10-20 s |\n\n> [!NOTE]\n> La recherche sémantique est plus lente que FTS5 en raison du calcul vectoriel.\n> Utilisez FTS5 pour les mots-clés connus, sémantique pour les requêtes conceptuelles.\n\n## Limites\n\n### Coût des embeddings\n\nSi vous utilisez OpenAI, générer des embeddings coûte de l'argent (~0,02 $ par 1M\ntokens pour text-embedding-3-small). Pour 10 000 mémoires de 100 tokens en moyenne,\ncela représente ~0,02 $ — négligeable.\n\n### Démarrage à froid\n\nLes mémoires stockées avant la configuration des embeddings n'en auront pas. Exécutez\n`POST /memory/embed-batch` pour les rétroalimenter.\n\n### Dépendance au fournisseur\n\nSi le fournisseur d'embeddings est en panne, la recherche sémantique échoue\ngracieusement (renvoie des résultats vides ou une erreur). FTS5 fonctionne toujours.\n\n## Quand les embeddings ne sont pas disponibles\n\nSi le service d'embeddings n'est pas configuré :\n\n- `GET /memory/semantic-search` renvoie 503 Service Unavailable\n- `POST /memory` fonctionne toujours (simplement aucun embedding généré)\n- La recherche FTS5 fonctionne toujours\n\n## Bonnes pratiques\n\n> [!TIP]\n> - **Utilisez sémantique pour les requêtes conceptuelles** — « comment gérons-nous X ? »\n> - **Utilisez FTS5 pour les termes spécifiques** — « docker swarm »\n> - **Rétroalimentez les embeddings régulièrement** — `POST /memory/embed-batch`\n> - **Surveillez la santé du fournisseur** — la recherche sémantique en dépend\n> - **Combinez avec les tags** — sémantique + filtre de tag affine les résultats\n\n## Prochaines étapes\n\n- [Recherche FTS5](/docs/concepts/fts5-search)\n- [API Memory](/docs/api/memory)\n- [Architecture](/docs/concepts/architecture)\n","content_html":"

Recherche sémantique (embeddings)

\n

Synapse prend en charge la recherche sémantique utilisant des embeddings vectoriels.\nContrairement à FTS5 (correspondance par mots-clés), la recherche sémantique trouve\nles mémoires par signification — même si aucun mot-clé ne correspond.

\n

Comment ça marche

\n
1. Memory stored → embedding generated → vector stored\n2. Search query → embedding generated → vector compared\n3. Cosine similarity → top N results returned

Que sont les embeddings ?

\n

Les embeddings sont des représentations vectorielles numériques du texte. Le texte\navec une signification similaire a des vecteurs similaires. Synapse génère un vecteur\n(ex. 1536 dimensions) pour le contenu de chaque mémoire.

\n

Similarité cosinus

\n

Pour trouver les mémoires sémantiquement similaires, Synapse calcule la similarité\ncosinus entre le vecteur de requête et chaque vecteur de mémoire. Similarité plus\nélevée = plus pertinent.

\n

Quand utiliser la recherche sémantique

\n

Utilisez la recherche sémantique quand :

\n\n

Utilisez FTS5 quand :

\n\n

Endpoint

\n

GET /memory/semantic-search

\n
curl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     "https://synapse.schaefer.zone/memory/semantic-search?q=container+orchestration"

Réponse :

\n
{\n  "results": [\n    {\n      "id": "mem_001",\n      "category": "project",\n      "key": "project_synapse_deployment",\n      "content": "Synapse deployed using Docker Swarm on vps1...",\n      "tags": ["docker", "swarm", "deployment"],\n      "similarity": 0.89\n    },\n    {\n      "id": "mem_042",\n      "category": "fact",\n      "key": "kubernetes_cluster",\n      "content": "We use Kubernetes for production orchestration...",\n      "tags": ["kubernetes", "orchestration"],\n      "similarity": 0.84\n    }\n  ]\n}

Exemples

\n

Trouver les mémoires de déploiement

\n
# FTS5 peut en manquer — la sémantique les attrape toutes\ncurl .../memory/semantic-search?q=deployment+process

Renvoie les mémoires sur « deployment », « release », « publishing », « rolling out »,\netc.

\n

Trouver les schémas d'authentification

\n
curl .../memory/semantic-search?q=how+do+users+log+in

Renvoie les mémoires sur le login, l'auth, le JWT, la gestion de session, OAuth, etc.

\n

Trouver des mémoires similaires

\n
# Trouver les mémoires similaires à une spécifique\ncurl .../memory/related/mem_001

Utilise la similarité sémantique (via tags partagés ET vecteurs d'embedding).

\n

Génération d'embeddings

\n

Quand les embeddings sont-ils générés ?

\n\n

Fournisseurs d'embeddings

\n

Synapse prend en charge des fournisseurs d'embeddings configurables :

\n\n

Configurez via des variables d'environnement :

\n
EMBEDDINGS_PROVIDER=openai\nEMBEDDINGS_API_KEY=sk-...\nEMBEDDINGS_MODEL=text-embedding-3-small

Génération par lot

\n

Pour les minds avec beaucoup de mémoires sans embeddings :

\n
# Générer des embeddings pour jusqu'à 100 mémoires\ncurl -X POST https://synapse.schaefer.zone/memory/embed-batch \\\n  -H "Authorization: Bearer YOUR_MIND_KEY" \\\n  -H "Content-Type: application/json" \\\n  -d '{"limit": 100}'\n\n# Vérifier la progression\ncurl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     https://synapse.schaefer.zone/memory/embed-batch-status

Performance

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
OpérationLatence
Génération d'embedding (OpenAI)100-200 ms
Recherche sémantique (1k mémoires)50-100 ms
Recherche sémantique (10k mémoires)200-500 ms
Génération par lot (100 mémoires)10-20 s
\n
La recherche sémantique est plus lente que FTS5 en raison du calcul vectoriel.\nUtilisez FTS5 pour les mots-clés connus, sémantique pour les requêtes conceptuelles.

Limites

\n

Coût des embeddings

\n

Si vous utilisez OpenAI, générer des embeddings coûte de l'argent (~0,02 $ par 1M\ntokens pour text-embedding-3-small). Pour 10 000 mémoires de 100 tokens en moyenne,\ncela représente ~0,02 $ — négligeable.

\n

Démarrage à froid

\n

Les mémoires stockées avant la configuration des embeddings n'en auront pas. Exécutez\nPOST /memory/embed-batch pour les rétroalimenter.

\n

Dépendance au fournisseur

\n

Si le fournisseur d'embeddings est en panne, la recherche sémantique échoue\ngracieusement (renvoie des résultats vides ou une erreur). FTS5 fonctionne toujours.

\n

Quand les embeddings ne sont pas disponibles

\n

Si le service d'embeddings n'est pas configuré :

\n\n

Bonnes pratiques

\n

Prochaines étapes

\n\n","urls":{"html":"/docs/concepts/semantic-search","text":"/docs/concepts/semantic-search?format=text","json":"/docs/concepts/semantic-search?format=json","llm":"/docs/concepts/semantic-search?format=llm"},"translations_available":["en","zh","hi","es","fr","ar","pt","ru","ja","de","it","ko","nl","pl","tr","sv","vi","th","id","uk"]}