{"title":"Semantische Suche (Embeddings)","slug":"semantic-search","category":"concepts","summary":"Konzeptionelle Memory-Suche mit Vektor-Embeddings — nach Bedeutung finden, nicht nur nach Keywords.","audience":["human","llm"],"tags":["concept","semantic","embeddings","vector-search"],"difficulty":"advanced","updated":"2026-06-27","word_count":494,"read_minutes":2,"lang":"de","translated":true,"requested_lang":"de","content_markdown":"\n# Semantische Suche (Embeddings)\n\nSynapse unterstützt semantische Suche mittels Vektor-Embeddings. Anders als FTS5\n(Keyword-Matching) findet die semantische Suche Memories nach **Bedeutung** —\nselbst wenn keine Keywords übereinstimmen.\n\n## Funktionsweise\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### Was sind Embeddings?\n\nEmbeddings sind numerische Vektor-Repräsentationen von Text. Text mit ähnlicher\nBedeutung hat ähnliche Vektoren. Synapse generiert einen Vektor (z. B. 1536\nDimensionen) für den Inhalt jedes Memories.\n\n### Cosine-Ähnlichkeit\n\nUm semantisch ähnliche Memories zu finden, berechnet Synapse die\nCosine-Ähnlichkeit zwischen dem Query-Vektor und jedem Memory-Vektor. Höhere\nÄhnlichkeit = relevanter.\n\n## Wann semantische Suche verwenden?\n\n### Verwende semantische Suche, wenn:\n\n- Du „Memories über X\" suchst, wobei X anders beschrieben ist als gespeichert\n- FTS5 keine Ergebnisse liefert (kein Keyword-Match)\n- Du konzeptionelle Gruppierung willst (z. B. alle „Deployment\"-Memories, auch wenn manche „Release\" sagen)\n- Die Anfrage eine Frage ist: „wie gehen wir mit Authentifizierung um?\"\n\n### Verwende FTS5, wenn:\n\n- Du exakte Keywords kennst\n- Du boolesche Logik brauchst (AND, OR, NOT)\n- Du sub-millisecond-Antwort brauchst\n- Du Phrase-Matching willst\n\n## Endpunkt\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\nAntwort:\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## Beispiele\n\n### Deployment-Memories finden\n\n```bash\n# FTS5 might miss some — semantic catches all\ncurl .../memory/semantic-search?q=deployment+process\n```\n\nLiefert Memories über „Deployment\", „Release\", „Publishing\", „Rolling out\" etc.\n\n### Authentifizierungs-Pattern finden\n\n```bash\ncurl .../memory/semantic-search?q=how+do+users+log+in\n```\n\nLiefert Memories über Login, Auth, JWT, Session-Management, OAuth etc.\n\n### Ähnliche Memories finden\n\n```bash\n# Find memories similar to a specific one\ncurl .../memory/related/mem_001\n```\n\nVerwendet semantische Ähnlichkeit (über gemeinsame Tags UND Embedding-Vektoren).\n\n## Embedding-Generierung\n\n### Wann werden Embeddings generiert?\n\n- **Beim Speichern eines Memories** — wenn der Embeddings-Dienst konfiguriert ist, wird das Embedding synchron generiert\n- **Batch-Generierung** — `POST /memory/embed-batch` generiert Embeddings für Memories, die keine haben\n- **Async-Updates** — bei Inhaltsänderung wird das Embedding neu generiert\n\n### Embedding-Provider\n\nSynapse unterstützt konfigurierbare Embedding-Provider:\n\n- **OpenAI** (`text-embedding-3-small`, `text-embedding-3-large`)\n- **Lokale Modelle** (über Ollama oder ähnliches)\n- **Custom** (Embeddings-Interface implementieren)\n\nKonfiguriere via Environment-Variablen:\n\n```bash\nEMBEDDINGS_PROVIDER=openai\nEMBEDDINGS_API_KEY=sk-...\nEMBEDDINGS_MODEL=text-embedding-3-small\n```\n\n### Batch-Generierung\n\nFür Minds mit vielen Memories ohne Embeddings:\n\n```bash\n# Generate embeddings for up to 100 memories\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# Check progress\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n https://synapse.schaefer.zone/memory/embed-batch-status\n```\n\n## Performance\n\n| Operation | Latenz |\n|-----------|--------|\n| Embedding generieren (OpenAI) | 100-200ms |\n| Semantische Suche (1k Memories) | 50-100ms |\n| Semantische Suche (10k Memories) | 200-500ms |\n| Batch-Generierung (100 Memories) | 10-20s |\n\n> [!NOTE]\n> Semantische Suche ist langsamer als FTS5 wegen der Vektor-Berechnung.\n> Verwende FTS5 für bekannte Keywords, semantische für konzeptionelle Queries.\n\n## Einschränkungen\n\n### Embedding-Kosten\n\nBei Verwendung von OpenAI kostet die Embedding-Generierung Geld (~$0.02 pro 1M\nToken für text-embedding-3-small). Bei 10.000 Memories mit durchschnittlich 100\nToken sind das ~$0.02 — vernachlässigbar.\n\n### Cold Start\n\nMemories, die vor der Konfiguration der Embeddings gespeichert wurden, haben\nkeine Embeddings. Führe `POST /memory/embed-batch` zum Backfillen aus.\n\n### Provider-Abhängigkeit\n\nWenn der Embeddings-Provider down ist, schlägt die semantische Suche graceful\nfehl (leere Ergebnisse oder Fehler). FTS5 funktioniert weiterhin.\n\n## Wenn Embeddings nicht verfügbar sind\n\nWenn der Embeddings-Dienst nicht konfiguriert ist:\n\n- `GET /memory/semantic-search` liefert 503 Service Unavailable\n- `POST /memory` funktioniert weiterhin (nur kein Embedding generiert)\n- FTS5-Suche funktioniert weiterhin\n\n## Best Practices\n\n> [!TIP]\n> - **Semantisch für konzeptionelle Queries** — „wie gehen wir mit X um?\"\n> - **FTS5 für spezifische Begriffe** — „docker swarm\"\n> - **Embeddings regelmäßig backfillen** — `POST /memory/embed-batch`\n> - **Provider-Gesundheit überwachen** — semantische Suche hängt davon ab\n> - **Mit Tags kombinieren** — semantisch + Tag-Filter schränkt Ergebnisse ein\n\n## Nächste Schritte\n\n- [FTS5-Suche](/docs/concepts/fts5-search)\n- [Memory-API](/docs/api/memory)\n- [Architektur](/docs/concepts/architecture)\n","content_html":"

Semantische Suche (Embeddings)

\n

Synapse unterstützt semantische Suche mittels Vektor-Embeddings. Anders als FTS5\n(Keyword-Matching) findet die semantische Suche Memories nach Bedeutung —\nselbst wenn keine Keywords übereinstimmen.

\n

Funktionsweise

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

Was sind Embeddings?

\n

Embeddings sind numerische Vektor-Repräsentationen von Text. Text mit ähnlicher\nBedeutung hat ähnliche Vektoren. Synapse generiert einen Vektor (z. B. 1536\nDimensionen) für den Inhalt jedes Memories.

\n

Cosine-Ähnlichkeit

\n

Um semantisch ähnliche Memories zu finden, berechnet Synapse die\nCosine-Ähnlichkeit zwischen dem Query-Vektor und jedem Memory-Vektor. Höhere\nÄhnlichkeit = relevanter.

\n

Wann semantische Suche verwenden?

\n

Verwende semantische Suche, wenn:

\n\n

Verwende FTS5, wenn:

\n\n

Endpunkt

\n

GET /memory/semantic-search

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

Antwort:

\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}

Beispiele

\n

Deployment-Memories finden

\n
# FTS5 might miss some — semantic catches all\ncurl .../memory/semantic-search?q=deployment+process

Liefert Memories über „Deployment", „Release", „Publishing", „Rolling out" etc.

\n

Authentifizierungs-Pattern finden

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

Liefert Memories über Login, Auth, JWT, Session-Management, OAuth etc.

\n

Ähnliche Memories finden

\n
# Find memories similar to a specific one\ncurl .../memory/related/mem_001

Verwendet semantische Ähnlichkeit (über gemeinsame Tags UND Embedding-Vektoren).

\n

Embedding-Generierung

\n

Wann werden Embeddings generiert?

\n\n

Embedding-Provider

\n

Synapse unterstützt konfigurierbare Embedding-Provider:

\n\n

Konfiguriere via Environment-Variablen:

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

Batch-Generierung

\n

Für Minds mit vielen Memories ohne Embeddings:

\n
# Generate embeddings for up to 100 memories\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# Check progress\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
OperationLatenz
Embedding generieren (OpenAI)100-200ms
Semantische Suche (1k Memories)50-100ms
Semantische Suche (10k Memories)200-500ms
Batch-Generierung (100 Memories)10-20s
\n
Semantische Suche ist langsamer als FTS5 wegen der Vektor-Berechnung.\nVerwende FTS5 für bekannte Keywords, semantische für konzeptionelle Queries.

Einschränkungen

\n

Embedding-Kosten

\n

Bei Verwendung von OpenAI kostet die Embedding-Generierung Geld (~$0.02 pro 1M\nToken für text-embedding-3-small). Bei 10.000 Memories mit durchschnittlich 100\nToken sind das ~$0.02 — vernachlässigbar.

\n

Cold Start

\n

Memories, die vor der Konfiguration der Embeddings gespeichert wurden, haben\nkeine Embeddings. Führe POST /memory/embed-batch zum Backfillen aus.

\n

Provider-Abhängigkeit

\n

Wenn der Embeddings-Provider down ist, schlägt die semantische Suche graceful\nfehl (leere Ergebnisse oder Fehler). FTS5 funktioniert weiterhin.

\n

Wenn Embeddings nicht verfügbar sind

\n

Wenn der Embeddings-Dienst nicht konfiguriert ist:

\n\n

Best Practices

\n

Nächste Schritte

\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"]}