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

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 might miss some — semantic catches all
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, управлении сессиями, OAuth и т. д.

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

# 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 или аналоги)
• Кастомные (реализуйте интерфейс эмбеддингов)

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

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

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

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

# 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 генерация эмбеддингов стоит денег (~$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
• Архитектура