# 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

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

Odpowiedź:

```json
{
  "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

```bash
# 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

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

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

### Znajdowanie podobnych wspomnień

```bash
# 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:

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

### Generowanie wsadowe

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

```bash
# 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ść

| 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ć `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

> [!TIP]
> - **Semantyczne do zapytań koncepcyjnych** — „jak obsługujemy X?"
> - **FTS5 dla konkretnych terminów** — „docker swarm"
> - **Regularnie wykonywać backfill osadzeń** — `POST /memory/embed-batch`
> - **Monitorować kondycję dostawcy** — wyszukiwanie semantyczne od niego zależy
> - **Łączyć z tagami** — semantyczne + filtr tagów zawęża wyniki

## Następne kroki

- [Wyszukiwanie FTS5](/docs/concepts/fts5-search)
- [Memory API](/docs/api/memory)
- [Architektura](/docs/concepts/architecture)