{"title":"Семантичний пошук (ембеддинги)","slug":"semantic-search","category":"concepts","summary":"Концептуальний пошук спогадів із використанням векторних ембеддингів — пошук за змістом, а не лише за ключовими словами.","audience":["human","llm"],"tags":["concept","semantic","embeddings","vector-search"],"difficulty":"advanced","updated":"2026-06-27","word_count":505,"read_minutes":3,"lang":"uk","translated":true,"requested_lang":"uk","content_markdown":"\n# Семантичний пошук (ембеддинги)\n\nSynapse підтримує семантичний пошук за допомогою векторних ембеддингів. На відміну\nвід FTS5 (зіставлення ключових слів), семантичний пошук знаходить спогади за\n**змістом** — навіть якщо ключові слова не збігаються.\n\n## Як це працює\n\n```\n1. Memory stored → embedding generated → vector stored\n2. Search query → embedding generated → vector compared\n3. Cosine similarity → top N results returned\n```\n\n### Що таке ембеддинги?\n\nЕмбеддинги — це числові векторні представлення тексту. Текст зі схожим змістом\nмає схожі вектори. Synapse генерує вектор (напр. 1536 вимірів) для вмісту\nкожного спогаду.\n\n### Косинусна подібність\n\nДля пошуку семантично схожих спогадів Synapse обчислює косинусну подібність\nміж вектором запиту та вектором кожного спогаду. Більша подібність = більша\nрелевантність.\n\n## Коли використовувати семантичний пошук\n\n### Використовуйте семантичний пошук, коли:\n\n- Потрібні «спогади про X», де X описано інакше, ніж збережено\n- FTS5 не повертає результатів (немає збігу ключових слів)\n- Потрібне концептуальне групування (напр. усі спогади про «deployment», навіть якщо деякі кажуть «release»)\n- Запит є питанням: «як ми обробляємо автентифікацію?»\n\n### Використовуйте FTS5, коли:\n\n- Знаєте точні ключові слова\n- Потрібна булева логіка (AND, OR, NOT)\n- Потрібна затримка менше мілісекунди\n- Потрібен пошук фраз\n\n## Кінцева точка\n\n### GET /memory/semantic-search\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/memory/semantic-search?q=container+orchestration\"\n```\n\nВідповідь:\n\n```json\n{\n \"results\": [\n {\n \"id\": \"mem_001\",\n \"category\": \"project\",\n \"key\": \"project_synapse_deployment\",\n \"content\": \"Synapse deployed using Docker Swarm on vps1...\",\n \"tags\": [\"docker\", \"swarm\", \"deployment\"],\n \"similarity\": 0.89\n },\n {\n \"id\": \"mem_042\",\n \"category\": \"fact\",\n \"key\": \"kubernetes_cluster\",\n \"content\": \"We use Kubernetes for production orchestration...\",\n \"tags\": [\"kubernetes\", \"orchestration\"],\n \"similarity\": 0.84\n }\n ]\n}\n```\n\n## Приклади\n\n### Пошук спогадів про розгортання\n\n```bash\n# FTS5 може пропустити деякі — семантичний ловить усі\ncurl .../memory/semantic-search?q=deployment+process\n```\n\nПовертає спогади про «deployment», «release», «publishing», «rolling out» тощо.\n\n### Пошук шаблонів автентифікації\n\n```bash\ncurl .../memory/semantic-search?q=how+do+users+log+in\n```\n\nПовертає спогади про login, auth, JWT, session management, OAuth тощо.\n\n### Пошук подібних спогадів\n\n```bash\n# Знайти спогади, подібні до конкретного\ncurl .../memory/related/mem_001\n```\n\nВикористовує семантичну подібність (через спільні теги ТА вектори ембеддингів).\n\n## Генерування ембеддингів\n\n### Коли генеруються ембеддинги?\n\n- **При збереженні спогаду** — якщо службу ембеддингів налаштовано, ембеддинг генерується синхронно\n- **Пакетна генерація** — `POST /memory/embed-batch` генерує ембеддинги для спогадів, що їх не мають\n- **Асинхронні оновлення** — при оновленні вмісту ембеддинг регенерується\n\n### Постачальники ембеддингів\n\nSynapse підтримує настроюваних постачальників ембеддингів:\n\n- **OpenAI** (`text-embedding-3-small`, `text-embedding-3-large`)\n- **Локальні моделі** (через Ollama або подібні)\n- **Користувацькі** (реалізуйте інтерфейс ембеддингів)\n\nНалаштування через змінні середовища:\n\n```bash\nEMBEDDINGS_PROVIDER=openai\nEMBEDDINGS_API_KEY=sk-...\nEMBEDDINGS_MODEL=text-embedding-3-small\n```\n\n### Пакетна генерація\n\nДля mind-ів із багатьма спогадами без ембеддингів:\n\n```bash\n# Згенерувати ембеддинги для до 100 спогадів\ncurl -X POST https://synapse.schaefer.zone/memory/embed-batch \\\n -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"limit\": 100}'\n\n# Перевірити прогрес\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n https://synapse.schaefer.zone/memory/embed-batch-status\n```\n\n## Продуктивність\n\n| Операція | Затримка |\n|-----------|---------|\n| Генерування ембеддингу (OpenAI) | 100-200мс |\n| Семантичний пошук (1к спогадів) | 50-100мс |\n| Семантичний пошук (10к спогадів) | 200-500мс |\n| Пакетна генерація (100 спогадів) | 10-20с |\n\n> [!NOTE]\n> Семантичний пошук повільніший за FTS5 через обчислення векторів. Використовуйте\n> FTS5 для відомих ключових слів, семантичний — для концептуальних запитів.\n\n## Обмеження\n\n### Вартість ембеддингів\n\nЯкщо використовуєте OpenAI, генерування ембеддингів коштує гроші (~$0.02 за 1М\nтокенів для text-embedding-3-small). Для 10 000 спогадів у середньому по 100\nтокенів кожен — це ~$0.02, що несуттєво.\n\n### Холодний старт\n\nСпогади, збережені до налаштування ембеддингів, не матимуть ембеддингів. Запустіть\n`POST /memory/embed-batch` для заповнення.\n\n### Залежність від постачальника\n\nЯкщо постачальник ембеддингів недоступний, семантичний пошук м'яко завершується\nпомилкою (повертає порожні результати або помилку). FTS5 продовжує працювати.\n\n## Коли ембеддинги недоступні\n\nЯкщо службу ембеддингів не налаштовано:\n\n- `GET /memory/semantic-search` повертає 503 Service Unavailable\n- `POST /memory` продовжує працювати (просто ембеддинг не генерується)\n- Пошук FTS5 продовжує працювати\n\n## Найкращі практики\n\n> [!TIP]\n> - **Семантичний для концептуальних запитів** — «як ми обробляємо X?»\n> - **FTS5 для конкретних термінів** — «docker swarm»\n> - **Регулярно заповнюйте ембеддинги** — `POST /memory/embed-batch`\n> - **Моніторте стан постачальника** — від нього залежить семантичний пошук\n> - **Комбінуйте з тегами** — семантичний + фільтр тегів звужує результати\n\n## Наступні кроки\n\n- [Пошук FTS5](/docs/concepts/fts5-search)\n- [Memory API](/docs/api/memory)\n- [Архітектура](/docs/concepts/architecture)\n","content_html":"

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

\n

Synapse підтримує семантичний пошук за допомогою векторних ембеддингів. На відміну\nвід FTS5 (зіставлення ключових слів), семантичний пошук знаходить спогади за\nзмістом — навіть якщо ключові слова не збігаються.

\n

Як це працює

\n
1. Memory stored → embedding generated → vector stored\n2. Search query → embedding generated → vector compared\n3. Cosine similarity → top N results returned

Що таке ембеддинги?

\n

Ембеддинги — це числові векторні представлення тексту. Текст зі схожим змістом\nмає схожі вектори. Synapse генерує вектор (напр. 1536 вимірів) для вмісту\nкожного спогаду.

\n

Косинусна подібність

\n

Для пошуку семантично схожих спогадів Synapse обчислює косинусну подібність\nміж вектором запиту та вектором кожного спогаду. Більша подібність = більша\nрелевантність.

\n

Коли використовувати семантичний пошук

\n

Використовуйте семантичний пошук, коли:

\n\n

Використовуйте FTS5, коли:

\n\n

Кінцева точка

\n

GET /memory/semantic-search

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

Відповідь:

\n
{\n  "results": [\n    {\n      "id": "mem_001",\n      "category": "project",\n      "key": "project_synapse_deployment",\n      "content": "Synapse deployed using Docker Swarm on vps1...",\n      "tags": ["docker", "swarm", "deployment"],\n      "similarity": 0.89\n    },\n    {\n      "id": "mem_042",\n      "category": "fact",\n      "key": "kubernetes_cluster",\n      "content": "We use Kubernetes for production orchestration...",\n      "tags": ["kubernetes", "orchestration"],\n      "similarity": 0.84\n    }\n  ]\n}

Приклади

\n

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

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

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

\n

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

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

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

\n

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

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

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

\n

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

\n

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

\n\n

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

\n

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

\n\n

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

\n
EMBEDDINGS_PROVIDER=openai\nEMBEDDINGS_API_KEY=sk-...\nEMBEDDINGS_MODEL=text-embedding-3-small

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

\n

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

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

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

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
ОпераціяЗатримка
Генерування ембеддингу (OpenAI)100-200мс
Семантичний пошук (1к спогадів)50-100мс
Семантичний пошук (10к спогадів)200-500мс
Пакетна генерація (100 спогадів)10-20с
\n
Семантичний пошук повільніший за FTS5 через обчислення векторів. Використовуйте\nFTS5 для відомих ключових слів, семантичний — для концептуальних запитів.

Обмеження

\n

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

\n

Якщо використовуєте OpenAI, генерування ембеддингів коштує гроші (~$0.02 за 1М\nтокенів для text-embedding-3-small). Для 10 000 спогадів у середньому по 100\nтокенів кожен — це ~$0.02, що несуттєво.

\n

Холодний старт

\n

Спогади, збережені до налаштування ембеддингів, не матимуть ембеддингів. Запустіть\nPOST /memory/embed-batch для заповнення.

\n

Залежність від постачальника

\n

Якщо постачальник ембеддингів недоступний, семантичний пошук м'яко завершується\nпомилкою (повертає порожні результати або помилку). FTS5 продовжує працювати.

\n

Коли ембеддинги недоступні

\n

Якщо службу ембеддингів не налаштовано:

\n\n

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

\n

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

\n\n","urls":{"html":"/docs/concepts/semantic-search","text":"/docs/concepts/semantic-search?format=text","json":"/docs/concepts/semantic-search?format=json","llm":"/docs/concepts/semantic-search?format=llm"},"translations_available":["en","zh","hi","es","fr","ar","pt","ru","ja","de","it","ko","nl","pl","tr","sv","vi","th","id","uk"]}