# Семантический поиск (эмбеддинги)

Synapse поддерживает семантический поиск с использованием векторных эмбеддингов.
В отличие от FTS5 (совпадение по ключевым словам), семантический поиск находит
воспоминания по **смыслу** — даже если ни одно ключевое слово не совпадает.

## Как это работает

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

### Что такое эмбеддинги?

Эмбеддинги — это числовые векторные представления текста. Текст с похожим смыслом
имеет похожие векторы. Synapse генерирует вектор (например, 1536 измерений) для
содержимого каждого воспоминания.

### Косинусное сходство

Для поиска семантически похожих воспоминаний Synapse вычисляет косинусное сходство
между вектором запроса и вектором каждого воспоминания. Чем выше сходство,
тем выше релевантность.

## Когда использовать семантический поиск

### Используйте семантический поиск, когда:

- Вы хотите «воспоминания о X», где X описан иначе, чем хранится
- FTS5 возвращает ноль результатов (нет совпадений по ключевым словам)
- Нужна концептуальная группировка (например, все воспоминания о «deployment», даже если в некоторых написано «release»)
- Запрос — это вопрос: «как мы обрабатываем аутентификацию?»

### Используйте FTS5, когда:

- Вы знаете точные ключевые слова
- Нужна булева логика (AND, OR, NOT)
- Нужен ответ быстрее миллисекунды
- Нужно совпадение по фразе

## Эндпоинт

### GET /memory/semantic-search

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

Ответ:

```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
    }
  ]
}
```

## Примеры

### Найти воспоминания о развёртывании

```bash
# FTS5 might miss some — semantic catches all
curl .../memory/semantic-search?q=deployment+process
```

Возвращает воспоминания о «deployment», «release», «publishing», «rolling out» и т. д.

### Найти паттерны аутентификации

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

Возвращает воспоминания о login, auth, JWT, управлении сессиями, OAuth и т. д.

### Найти похожие воспоминания

```bash
# Find memories similar to a specific one
curl .../memory/related/mem_001
```

Использует семантическое сходство (через общие теги И векторы эмбеддингов).

## Генерация эмбеддингов

### Когда генерируются эмбеддинги?

- **При сохранении памяти** — если сервис эмбеддингов настроен, эмбеддинг генерируется синхронно
- **Пакетная генерация** — `POST /memory/embed-batch` генерирует эмбеддинги для воспоминаний, у которых их нет
- **Асинхронные обновления** — при обновлении содержимого эмбеддинг перегенерируется

### Провайдеры эмбеддингов

Synapse поддерживает настраиваемых провайдеров эмбеддингов:

- **OpenAI** (`text-embedding-3-small`, `text-embedding-3-large`)
- **Локальные модели** (через Ollama или аналоги)
- **Кастомные** (реализуйте интерфейс эмбеддингов)

Настройка через переменные окружения:

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

### Пакетная генерация

Для mind с большим количеством воспоминаний без эмбеддингов:

```bash
# Generate embeddings for up to 100 memories
curl -X POST https://synapse.schaefer.zone/memory/embed-batch \
  -H "Authorization: Bearer YOUR_MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{"limit": 100}'

# Check progress
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/memory/embed-batch-status
```

## Производительность

| Операция | Задержка |
|-----------|---------|
| Генерация эмбеддинга (OpenAI) | 100–200 мс |
| Семантический поиск (1 тыс. воспоминаний) | 50–100 мс |
| Семантический поиск (10 тыс. воспоминаний) | 200–500 мс |
| Пакетная генерация (100 воспоминаний) | 10–20 с |

> [!NOTE]
> Семантический поиск медленнее FTS5 из-за векторных вычислений. Используйте
> FTS5 для известных ключевых слов, семантический — для концептуальных запросов.

## Ограничения

### Стоимость эмбеддингов

При использовании OpenAI генерация эмбеддингов стоит денег (~$0.02 за 1 млн
токенов для text-embedding-3-small). Для 10 000 воспоминаний со средним размером
100 токенов это ~$0.02 — незначительно.

### Холодный старт

Воспоминания, сохранённые до настройки эмбеддингов, не будут иметь эмбеддингов.
Запустите `POST /memory/embed-batch` для обратного заполнения.

### Зависимость от провайдера

Если провайдер эмбеддингов недоступен, семантический поиск корректно завершается
с ошибкой (возвращает пустой результат или ошибку). FTS5 продолжает работать.

## Когда эмбеддинги недоступны

Если сервис эмбеддингов не настроен:

- `GET /memory/semantic-search` возвращает 503 Service Unavailable
- `POST /memory` продолжает работать (просто эмбеддинг не генерируется)
- FTS5-поиск продолжает работать

## Лучшие практики

> [!TIP]
> - **Используйте семантический поиск для концептуальных запросов** — «как мы обрабатываем X?»
> - **Используйте FTS5 для конкретных терминов** — «docker swarm»
> - **Регулярно пополняйте эмбеддинги** — `POST /memory/embed-batch`
> - **Мониторьте здоровье провайдера** — семантический поиск зависит от него
> - **Комбинируйте с тегами** — семантика + фильтр по тегу сужает результаты

## Следующие шаги

- [FTS5-поиск](/docs/concepts/fts5-search)
- [Memory API](/docs/api/memory)
- [Архитектура](/docs/concepts/architecture)