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

1. Memory stored → embedding generated → vector stored
2. Search query → embedding generated → vector compared
3. Cosine similarity → top N results returned

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

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

Odpowiedź:

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

Przykłady

Znajdowanie wspomnień o wdrożeniu

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

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

Znajdowanie wzorców autoryzacji

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

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

Znajdowanie podobnych wspomnień

# Znalezienie wspomnień podobnych do konkretnego
curl .../memory/related/mem_001

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 — POST /memory/embed-batch 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 (text-embedding-3-small, text-embedding-3-large)
• Modele lokalne (przez Ollama lub podobne)
• Własne (implementacja interfejsu osadzeń)

Konfiguracja przez zmienne środowiskowe:

EMBEDDINGS_PROVIDER=openai
EMBEDDINGS_API_KEY=sk-...
EMBEDDINGS_MODEL=text-embedding-3-small

Generowanie wsadowe

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

# Generowanie osadzeń dla maksymalnie 100 wspomnień
curl -X POST https://synapse.schaefer.zone/memory/embed-batch \
  -H "Authorization: Bearer YOUR_MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{"limit": 100}'

# Sprawdzenie postępu
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/memory/embed-batch-status

Wydajność

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ć POST /memory/embed-batch, 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:

• GET /memory/semantic-search zwraca 503 Service Unavailable
• POST /memory nadal działa (tylko bez generowania osadzenia)
• Wyszukiwanie FTS5 nadal działa

Najlepsze praktyki

Następne kroki

• Wyszukiwanie FTS5
• Memory API
• Architektura