{"title":"Wyszukiwanie semantyczne (osadzenia)","slug":"semantic-search","category":"concepts","summary":"Koncepcyjne wyszukiwanie wspomnień z użyciem osadzeń wektorowych — znajdowanie po znaczeniu, nie tylko słowach kluczowych.","audience":["human","llm"],"tags":["concept","semantic","embeddings","vector-search"],"difficulty":"advanced","updated":"2026-06-27","word_count":528,"read_minutes":3,"lang":"pl","translated":true,"requested_lang":"pl","content_markdown":"\n# Wyszukiwanie semantyczne (osadzenia)\n\nSynapse obsługuje wyszukiwanie semantyczne z użyciem osadzeń wektorowych. W\nprzeciwieństwie do FTS5 (dopasowywanie słów kluczowych), wyszukiwanie semantyczne\nznajduje wspomnienia po **znaczeniu** — nawet gdy nie ma dopasowania słów\nkluczowych.\n\n## Jak to działa\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### Czym są osadzenia?\n\nOsadzenia to liczbowe reprezentacje wektorowe tekstu. Tekst o podobnym znaczeniu\nma podobne wektory. Synapse generuje wektor (np. 1536 wymiarów) dla treści\nkażdego wspomnienia.\n\n### Podobieństwo cosinusowe\n\nAby znaleźć semantycznie podobne wspomnienia, Synapse oblicza podobieństwo\ncosinusowe między wektorem zapytania a każdym wektorem wspomnienia. Wyższe\npodobieństwo = większa trafność.\n\n## Kiedy używać wyszukiwania semantycznego\n\n### Użyć wyszukiwania semantycznego, gdy:\n\n- Potrzebne są „wspomnienia o X\", gdzie X jest opisane inaczej niż zapisane\n- FTS5 nie zwraca wyników (brak dopasowania słów kluczowych)\n- Wymagane grupowanie koncepcyjne (np. wszystkie wspomnienia o „wdrożeniu\", nawet jeśli niektóre mówią „release\")\n- Zapytanie jest pytaniem: „jak obsługujemy autoryzację?\"\n\n### Użyć FTS5, gdy:\n\n- Znane są dokładne słowa kluczowe\n- Wymagana logika boolowska (AND, OR, NOT)\n- Wymagana odpowiedź poniżej milisekundy\n- Wymagane dopasowanie frazy\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\nOdpowiedź:\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## Przykłady\n\n### Znajdowanie wspomnień o wdrożeniu\n\n```bash\n# FTS5 może niektóre pominąć — semantyczne wyłapuje wszystkie\ncurl .../memory/semantic-search?q=deployment+process\n```\n\nZwraca wspomnienia o „deployment\", „release\", „publishing\", „rolling out\" itp.\n\n### Znajdowanie wzorców autoryzacji\n\n```bash\ncurl .../memory/semantic-search?q=how+do+users+log+in\n```\n\nZwraca wspomnienia o logowaniu, autoryzacji, JWT, zarządzaniu sesjami, OAuth itp.\n\n### Znajdowanie podobnych wspomnień\n\n```bash\n# Znalezienie wspomnień podobnych do konkretnego\ncurl .../memory/related/mem_001\n```\n\nUżywa podobieństwa semantycznego (przez współdzielone tagi i wektory osadzeń).\n\n## Generowanie osadzeń\n\n### Kiedy generowane są osadzenia?\n\n- **Przy zapisie wspomnienia** — jeśli skonfigurowano usługę osadzeń, są one generowane synchronicznie\n- **Generowanie wsadowe** — `POST /memory/embed-batch` generuje osadzenia dla wspomnień, które ich nie mają\n- **Aktualizacje asynchroniczne** — gdy treść jest aktualizowana, osadzenie jest regenerowane\n\n### Dostawcy osadzeń\n\nSynapse obsługuje konfigurowalnych dostawców osadzeń:\n\n- **OpenAI** (`text-embedding-3-small`, `text-embedding-3-large`)\n- **Modele lokalne** (przez Ollama lub podobne)\n- **Własne** (implementacja interfejsu osadzeń)\n\nKonfiguracja przez zmienne środowiskowe:\n\n```bash\nEMBEDDINGS_PROVIDER=openai\nEMBEDDINGS_API_KEY=sk-...\nEMBEDDINGS_MODEL=text-embedding-3-small\n```\n\n### Generowanie wsadowe\n\nDla umysłów z wieloma wspomnieniami bez osadzeń:\n\n```bash\n# Generowanie osadzeń dla maksymalnie 100 wspomnień\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# Sprawdzenie postępu\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n https://synapse.schaefer.zone/memory/embed-batch-status\n```\n\n## Wydajność\n\n| Operacja | Opóźnienie |\n|-----------|---------|\n| Generowanie osadzenia (OpenAI) | 100-200 ms |\n| Wyszukiwanie semantyczne (1k wspomnień) | 50-100 ms |\n| Wyszukiwanie semantyczne (10k wspomnień) | 200-500 ms |\n| Generowanie wsadowe (100 wspomnień) | 10-20 s |\n\n> [!NOTE]\n> Wyszukiwanie semantyczne jest wolniejsze niż FTS5 z powodu obliczeń wektorowych.\n> FTS5 należy stosować dla znanych słów kluczowych, semantyczne — do zapytań\n> koncepcyjnych.\n\n## Ograniczenia\n\n### Koszt osadzeń\n\nW przypadku użycia OpenAI generowanie osadzeń kosztuje (około 0,02 USD za 1M\ntokenów dla text-embedding-3-small). Dla 10 000 wspomnień średnio po 100 tokenów\nkażde — około 0,02 USD — zaniedbywalne.\n\n### Zimny start\n\nWspomnienia zapisane przed skonfigurowaniem osadzeń nie będą ich miały. Należy\nuruchomić `POST /memory/embed-batch`, aby wykonać backfill.\n\n### Zależność od dostawcy\n\nJeśli dostawca osadzeń jest niedostępny, wyszukiwanie semantyczne kończy się\nłagodnie (zwraca puste wyniki lub błąd). FTS5 nadal działa.\n\n## Gdy osadzenia nie są dostępne\n\nJeśli usługa osadzeń nie jest skonfigurowana:\n\n- `GET /memory/semantic-search` zwraca 503 Service Unavailable\n- `POST /memory` nadal działa (tylko bez generowania osadzenia)\n- Wyszukiwanie FTS5 nadal działa\n\n## Najlepsze praktyki\n\n> [!TIP]\n> - **Semantyczne do zapytań koncepcyjnych** — „jak obsługujemy X?\"\n> - **FTS5 dla konkretnych terminów** — „docker swarm\"\n> - **Regularnie wykonywać backfill osadzeń** — `POST /memory/embed-batch`\n> - **Monitorować kondycję dostawcy** — wyszukiwanie semantyczne od niego zależy\n> - **Łączyć z tagami** — semantyczne + filtr tagów zawęża wyniki\n\n## Następne kroki\n\n- [Wyszukiwanie FTS5](/docs/concepts/fts5-search)\n- [Memory API](/docs/api/memory)\n- [Architektura](/docs/concepts/architecture)\n","content_html":"

Wyszukiwanie semantyczne (osadzenia)

\n

Synapse obsługuje wyszukiwanie semantyczne z użyciem osadzeń wektorowych. W\nprzeciwieństwie do FTS5 (dopasowywanie słów kluczowych), wyszukiwanie semantyczne\nznajduje wspomnienia po znaczeniu — nawet gdy nie ma dopasowania słów\nkluczowych.

\n

Jak to działa

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

Czym są osadzenia?

\n

Osadzenia to liczbowe reprezentacje wektorowe tekstu. Tekst o podobnym znaczeniu\nma podobne wektory. Synapse generuje wektor (np. 1536 wymiarów) dla treści\nkażdego wspomnienia.

\n

Podobieństwo cosinusowe

\n

Aby znaleźć semantycznie podobne wspomnienia, Synapse oblicza podobieństwo\ncosinusowe między wektorem zapytania a każdym wektorem wspomnienia. Wyższe\npodobieństwo = większa trafność.

\n

Kiedy używać wyszukiwania semantycznego

\n

Użyć wyszukiwania semantycznego, gdy:

\n\n

Użyć FTS5, gdy:

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

Odpowiedź:

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

Przykłady

\n

Znajdowanie wspomnień o wdrożeniu

\n
# FTS5 może niektóre pominąć — semantyczne wyłapuje wszystkie\ncurl .../memory/semantic-search?q=deployment+process

Zwraca wspomnienia o „deployment", „release", „publishing", „rolling out" itp.

\n

Znajdowanie wzorców autoryzacji

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

Zwraca wspomnienia o logowaniu, autoryzacji, JWT, zarządzaniu sesjami, OAuth itp.

\n

Znajdowanie podobnych wspomnień

\n
# Znalezienie wspomnień podobnych do konkretnego\ncurl .../memory/related/mem_001

Używa podobieństwa semantycznego (przez współdzielone tagi i wektory osadzeń).

\n

Generowanie osadzeń

\n

Kiedy generowane są osadzenia?

\n\n

Dostawcy osadzeń

\n

Synapse obsługuje konfigurowalnych dostawców osadzeń:

\n\n

Konfiguracja przez zmienne środowiskowe:

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

Generowanie wsadowe

\n

Dla umysłów z wieloma wspomnieniami bez osadzeń:

\n
# Generowanie osadzeń dla maksymalnie 100 wspomnień\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# Sprawdzenie postępu\ncurl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     https://synapse.schaefer.zone/memory/embed-batch-status

Wydajność

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
OperacjaOpóźnienie
Generowanie osadzenia (OpenAI)100-200 ms
Wyszukiwanie semantyczne (1k wspomnień)50-100 ms
Wyszukiwanie semantyczne (10k wspomnień)200-500 ms
Generowanie wsadowe (100 wspomnień)10-20 s
\n
Wyszukiwanie semantyczne jest wolniejsze niż FTS5 z powodu obliczeń wektorowych.\nFTS5 należy stosować dla znanych słów kluczowych, semantyczne — do zapytań\nkoncepcyjnych.

Ograniczenia

\n

Koszt osadzeń

\n

W przypadku użycia OpenAI generowanie osadzeń kosztuje (około 0,02 USD za 1M\ntokenów dla text-embedding-3-small). Dla 10 000 wspomnień średnio po 100 tokenów\nkażde — około 0,02 USD — zaniedbywalne.

\n

Zimny start

\n

Wspomnienia zapisane przed skonfigurowaniem osadzeń nie będą ich miały. Należy\nuruchomić POST /memory/embed-batch, aby wykonać backfill.

\n

Zależność od dostawcy

\n

Jeśli dostawca osadzeń jest niedostępny, wyszukiwanie semantyczne kończy się\nłagodnie (zwraca puste wyniki lub błąd). FTS5 nadal działa.

\n

Gdy osadzenia nie są dostępne

\n

Jeśli usługa osadzeń nie jest skonfigurowana:

\n\n

Najlepsze praktyki

\n

Następne kroki

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