# Семантический поиск (эмбеддинги)
SUMMARY: Концептуальный поиск по памяти с использованием векторных эмбеддингов — поиск по смыслу, а не только по ключевым словам.

Семантический поиск (эмбеддинги)
Synapse поддерживает семантический поиск с использованием векторных эмбеддингов.
В отличие от FTS5 (совпадение по ключевым словам), семантический поиск находит
воспоминания по смыслу — даже если ни одно ключевое слово не совпадает.
Как это работает
[CODE BLOCK]
Что такое эмбеддинги?
Эмбеддинги — это числовые векторные представления текста. Текст с похожим смыслом
имеет похожие векторы. Synapse генерирует вектор (например, 1536 измерений) для
содержимого каждого воспоминания.
Косинусное сходство
Для поиска семантически похожих воспоминаний Synapse вычисляет косинусное сходство
между вектором запроса и вектором каждого воспоминания. Чем выше сходство,
тем выше релевантность.
Когда использовать семантический поиск
Используйте семантический поиск, когда:
- Вы хотите «воспоминания о X», где X описан иначе, чем хранится
- FTS5 возвращает ноль результатов (нет совпадений по ключевым словам)
- Нужна концептуальная группировка (например, все воспоминания о «deployment», даже если в некоторых написано «release»)
- Запрос — это вопрос: «как мы обрабатываем аутентификацию?»
Используйте FTS5, когда:
- Вы знаете точные ключевые слова
- Нужна булева логика (AND, OR, NOT)
- Нужен ответ быстрее миллисекунды
- Нужно совпадение по фразе
Эндпоинт
GET /memory/semantic-search
[CODE BLOCK]
Ответ:
[CODE BLOCK]
Примеры
Найти воспоминания о развёртывании
[CODE BLOCK]
Возвращает воспоминания о «deployment», «release», «publishing», «rolling out» и т. д.
Найти паттерны аутентификации
[CODE BLOCK]
Возвращает воспоминания о login, auth, JWT, управлении сессиями, OAuth и т. д.
Найти похожие воспоминания
[CODE BLOCK]
Использует семантическое сходство (через общие теги И векторы эмбеддингов).
Генерация эмбеддингов
Когда генерируются эмбеддинги?
- При сохранении памяти — если сервис эмбеддингов настроен, эмбеддинг генерируется синхронно
- Пакетная генерация —  генерирует эмбеддинги для воспоминаний, у которых их нет
- Асинхронные обновления — при обновлении содержимого эмбеддинг перегенерируется
Провайдеры эмбеддингов
Synapse поддерживает настраиваемых провайдеров эмбеддингов:
- OpenAI (, )
- Локальные модели (через Ollama или аналоги)
- Кастомные (реализуйте интерфейс эмбеддингов)
Настройка через переменные окружения:
[CODE BLOCK]
Пакетная генерация
Для mind с большим количеством воспоминаний без эмбеддингов:
[CODE BLOCK]
Производительность
| Операция | Задержка |
|-----------|---------|
| Генерация эмбеддинга (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 — незначительно.
Холодный старт
Воспоминания, сохранённые до настройки эмбеддингов, не будут иметь эмбеддингов.
Запустите  для обратного заполнения.
Зависимость от провайдера
Если провайдер эмбеддингов недоступен, семантический поиск корректно завершается
с ошибкой (возвращает пустой результат или ошибку). FTS5 продолжает работать.
Когда эмбеддинги недоступны
Если сервис эмбеддингов не настроен:
-  возвращает 503 Service Unavailable
-  продолжает работать (просто эмбеддинг не генерируется)
- FTS5-поиск продолжает работать
Лучшие практики
> [!TIP]
> - Используйте семантический поиск для концептуальных запросов — «как мы обрабатываем X?»
> - Используйте FTS5 для конкретных терминов — «docker swarm»
> - Регулярно пополняйте эмбеддинги — 
> - Мониторьте здоровье провайдера — семантический поиск зависит от него
> - Комбинируйте с тегами — семантика + фильтр по тегу сужает результаты
Следующие шаги
- FTS5-поиск
- Memory API
- Архитектура