# Wyszukiwanie semantyczne (osadzenia)
SUMMARY: Koncepcyjne wyszukiwanie wspomnień z użyciem osadzeń wektorowych — znajdowanie po znaczeniu, nie tylko słowach kluczowych.

Wyszukiwanie semantyczne (osadzenia)
Synapse obsługuje wyszukiwanie semantyczne z użyciem osadzeń wektorowych. W
przeciwieństwie do FTS5 (dopasowywanie słów kluczowych), wyszukiwanie semantyczne
znajduje wspomnienia po znaczeniu — nawet gdy nie ma dopasowania słów
kluczowych.
Jak to działa
[CODE BLOCK]
Czym są osadzenia?
Osadzenia to liczbowe reprezentacje wektorowe tekstu. Tekst o podobnym znaczeniu
ma podobne wektory. Synapse generuje wektor (np. 1536 wymiarów) dla treści
każdego wspomnienia.
Podobieństwo cosinusowe
Aby znaleźć semantycznie podobne wspomnienia, Synapse oblicza podobieństwo
cosinusowe między wektorem zapytania a każdym wektorem wspomnienia. Wyższe
podobieństwo = większa trafność.
Kiedy używać wyszukiwania semantycznego
Użyć wyszukiwania semantycznego, gdy:
- Potrzebne są „wspomnienia o X", gdzie X jest opisane inaczej niż zapisane
- FTS5 nie zwraca wyników (brak dopasowania słów kluczowych)
- Wymagane grupowanie koncepcyjne (np. wszystkie wspomnienia o „wdrożeniu", nawet jeśli niektóre mówią „release")
- Zapytanie jest pytaniem: „jak obsługujemy autoryzację?"
Użyć FTS5, gdy:
- Znane są dokładne słowa kluczowe
- Wymagana logika boolowska (AND, OR, NOT)
- Wymagana odpowiedź poniżej milisekundy
- Wymagane dopasowanie frazy
Endpoint
GET /memory/semantic-search
[CODE BLOCK]
Odpowiedź:
[CODE BLOCK]
Przykłady
Znajdowanie wspomnień o wdrożeniu
[CODE BLOCK]
Zwraca wspomnienia o „deployment", „release", „publishing", „rolling out" itp.
Znajdowanie wzorców autoryzacji
[CODE BLOCK]
Zwraca wspomnienia o logowaniu, autoryzacji, JWT, zarządzaniu sesjami, OAuth itp.
Znajdowanie podobnych wspomnień
[CODE BLOCK]
Używa podobieństwa semantycznego (przez współdzielone tagi i wektory osadzeń).
Generowanie osadzeń
Kiedy generowane są osadzenia?
- Przy zapisie wspomnienia — jeśli skonfigurowano usługę osadzeń, są one generowane synchronicznie
- Generowanie wsadowe —  generuje osadzenia dla wspomnień, które ich nie mają
- Aktualizacje asynchroniczne — gdy treść jest aktualizowana, osadzenie jest regenerowane
Dostawcy osadzeń
Synapse obsługuje konfigurowalnych dostawców osadzeń:
- OpenAI (, )
- Modele lokalne (przez Ollama lub podobne)
- Własne (implementacja interfejsu osadzeń)
Konfiguracja przez zmienne środowiskowe:
[CODE BLOCK]
Generowanie wsadowe
Dla umysłów z wieloma wspomnieniami bez osadzeń:
[CODE BLOCK]
Wydajność
| Operacja | Opóź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 |
> [!NOTE]
> Wyszukiwanie semantyczne jest wolniejsze niż FTS5 z powodu obliczeń wektorowych.
> FTS5 należy stosować dla znanych słów kluczowych, semantyczne — do zapytań
> koncepcyjnych.
Ograniczenia
Koszt osadzeń
W przypadku użycia OpenAI generowanie osadzeń kosztuje (około 0,02 USD za 1M
tokenów dla text-embedding-3-small). Dla 10 000 wspomnień średnio po 100 tokenów
każde — około 0,02 USD — zaniedbywalne.
Zimny start
Wspomnienia zapisane przed skonfigurowaniem osadzeń nie będą ich miały. Należy
uruchomić , aby wykonać backfill.
Zależność od dostawcy
Jeśli dostawca osadzeń jest niedostępny, wyszukiwanie semantyczne kończy się
łagodnie (zwraca puste wyniki lub błąd). FTS5 nadal działa.
Gdy osadzenia nie są dostępne
Jeśli usługa osadzeń nie jest skonfigurowana:
-  zwraca 503 Service Unavailable
-  nadal działa (tylko bez generowania osadzenia)
- Wyszukiwanie FTS5 nadal działa
Najlepsze praktyki
> [!TIP]
> - Semantyczne do zapytań koncepcyjnych — „jak obsługujemy X?"
> - FTS5 dla konkretnych terminów — „docker swarm"
> - Regularnie wykonywać backfill osadzeń — 
> - Monitorować kondycję dostawcy — wyszukiwanie semantyczne od niego zależy
> - Łączyć z tagami — semantyczne + filtr tagów zawęża wyniki
Następne kroki
- Wyszukiwanie FTS5
- Memory API
- Architektura