Семантичний пошук (ембеддинги)

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

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

Відповідь:

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

Приклади

Пошук спогадів про розгортання

# FTS5 може пропустити деякі — семантичний ловить усі
curl .../memory/semantic-search?q=deployment+process

Повертає спогади про «deployment», «release», «publishing», «rolling out» тощо.

Пошук шаблонів автентифікації

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

Повертає спогади про login, auth, JWT, session management, OAuth тощо.

Пошук подібних спогадів

# Знайти спогади, подібні до конкретного
curl .../memory/related/mem_001

Використовує семантичну подібність (через спільні теги ТА вектори ембеддингів).

Генерування ембеддингів

Коли генеруються ембеддинги?

• При збереженні спогаду — якщо службу ембеддингів налаштовано, ембеддинг генерується синхронно
• Пакетна генерація — POST /memory/embed-batch генерує ембеддинги для спогадів, що їх не мають
• Асинхронні оновлення — при оновленні вмісту ембеддинг регенерується

Постачальники ембеддингів

Synapse підтримує настроюваних постачальників ембеддингів:

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

Налаштування через змінні середовища:

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

Пакетна генерація

Для mind-ів із багатьма спогадами без ембеддингів:

# Згенерувати ембеддинги для до 100 спогадів
curl -X POST https://synapse.schaefer.zone/memory/embed-batch \
  -H "Authorization: Bearer YOUR_MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{"limit": 100}'

# Перевірити прогрес
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/memory/embed-batch-status

Продуктивність

Обмеження

Вартість ембеддингів

Якщо використовуєте 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 продовжує працювати

Найкращі практики

Наступні кроки

• Пошук FTS5
• Memory API
• Архітектура