{"title":"Семантический поиск (эмбеддинги)","slug":"semantic-search","category":"concepts","summary":"Концептуальный поиск по памяти с использованием векторных эмбеддингов — поиск по смыслу, а не только по ключевым словам.","audience":["human","llm"],"tags":["concept","semantic","embeddings","vector-search"],"difficulty":"advanced","updated":"2026-06-27","word_count":528,"read_minutes":3,"lang":"ru","translated":true,"requested_lang":"ru","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 might miss some — semantic catches all\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, управлении сессиями, OAuth и т. д.\n\n### Найти похожие воспоминания\n\n```bash\n# Find memories similar to a specific one\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# Generate embeddings for up to 100 memories\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# Check progress\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 воспоминаний со средним размером\n100 токенов это ~$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":"<h1>Семантический поиск (эмбеддинги)</h1>\n<p>Synapse поддерживает семантический поиск с использованием векторных эмбеддингов.\nВ отличие от FTS5 (совпадение по ключевым словам), семантический поиск находит\nвоспоминания по <strong>смыслу</strong> — даже если ни одно ключевое слово не совпадает.</p>\n<h2>Как это работает</h2>\n<pre><code class=\"hljs language-plaintext\">1. Memory stored → embedding generated → vector stored\n2. Search query → embedding generated → vector compared\n3. Cosine similarity → top N results returned</code></pre><h3>Что такое эмбеддинги?</h3>\n<p>Эмбеддинги — это числовые векторные представления текста. Текст с похожим смыслом\nимеет похожие векторы. Synapse генерирует вектор (например, 1536 измерений) для\nсодержимого каждого воспоминания.</p>\n<h3>Косинусное сходство</h3>\n<p>Для поиска семантически похожих воспоминаний Synapse вычисляет косинусное сходство\nмежду вектором запроса и вектором каждого воспоминания. Чем выше сходство,\nтем выше релевантность.</p>\n<h2>Когда использовать семантический поиск</h2>\n<h3>Используйте семантический поиск, когда:</h3>\n<ul>\n<li>Вы хотите «воспоминания о X», где X описан иначе, чем хранится</li>\n<li>FTS5 возвращает ноль результатов (нет совпадений по ключевым словам)</li>\n<li>Нужна концептуальная группировка (например, все воспоминания о «deployment», даже если в некоторых написано «release»)</li>\n<li>Запрос — это вопрос: «как мы обрабатываем аутентификацию?»</li>\n</ul>\n<h3>Используйте FTS5, когда:</h3>\n<ul>\n<li>Вы знаете точные ключевые слова</li>\n<li>Нужна булева логика (AND, OR, NOT)</li>\n<li>Нужен ответ быстрее миллисекунды</li>\n<li>Нужно совпадение по фразе</li>\n</ul>\n<h2>Эндпоинт</h2>\n<h3>GET /memory/semantic-search</h3>\n<pre><code class=\"hljs language-bash\">curl -H <span class=\"hljs-string\">&quot;Authorization: Bearer YOUR_MIND_KEY&quot;</span> \\\n     <span class=\"hljs-string\">&quot;https://synapse.schaefer.zone/memory/semantic-search?q=container+orchestration&quot;</span></code></pre><p>Ответ:</p>\n<pre><code class=\"hljs language-json\"><span class=\"hljs-punctuation\">{</span>\n  <span class=\"hljs-attr\">&quot;results&quot;</span><span class=\"hljs-punctuation\">:</span> <span class=\"hljs-punctuation\">[</span>\n    <span class=\"hljs-punctuation\">{</span>\n      <span class=\"hljs-attr\">&quot;id&quot;</span><span class=\"hljs-punctuation\">:</span> <span class=\"hljs-string\">&quot;mem_001&quot;</span><span class=\"hljs-punctuation\">,</span>\n      <span class=\"hljs-attr\">&quot;category&quot;</span><span class=\"hljs-punctuation\">:</span> <span class=\"hljs-string\">&quot;project&quot;</span><span class=\"hljs-punctuation\">,</span>\n      <span class=\"hljs-attr\">&quot;key&quot;</span><span class=\"hljs-punctuation\">:</span> <span class=\"hljs-string\">&quot;project_synapse_deployment&quot;</span><span class=\"hljs-punctuation\">,</span>\n      <span class=\"hljs-attr\">&quot;content&quot;</span><span class=\"hljs-punctuation\">:</span> <span class=\"hljs-string\">&quot;Synapse deployed using Docker Swarm on vps1...&quot;</span><span class=\"hljs-punctuation\">,</span>\n      <span class=\"hljs-attr\">&quot;tags&quot;</span><span class=\"hljs-punctuation\">:</span> <span class=\"hljs-punctuation\">[</span><span class=\"hljs-string\">&quot;docker&quot;</span><span class=\"hljs-punctuation\">,</span> <span class=\"hljs-string\">&quot;swarm&quot;</span><span class=\"hljs-punctuation\">,</span> <span class=\"hljs-string\">&quot;deployment&quot;</span><span class=\"hljs-punctuation\">]</span><span class=\"hljs-punctuation\">,</span>\n      <span class=\"hljs-attr\">&quot;similarity&quot;</span><span class=\"hljs-punctuation\">:</span> <span class=\"hljs-number\">0.89</span>\n    <span class=\"hljs-punctuation\">}</span><span class=\"hljs-punctuation\">,</span>\n    <span class=\"hljs-punctuation\">{</span>\n      <span class=\"hljs-attr\">&quot;id&quot;</span><span class=\"hljs-punctuation\">:</span> <span class=\"hljs-string\">&quot;mem_042&quot;</span><span class=\"hljs-punctuation\">,</span>\n      <span class=\"hljs-attr\">&quot;category&quot;</span><span class=\"hljs-punctuation\">:</span> <span class=\"hljs-string\">&quot;fact&quot;</span><span class=\"hljs-punctuation\">,</span>\n      <span class=\"hljs-attr\">&quot;key&quot;</span><span class=\"hljs-punctuation\">:</span> <span class=\"hljs-string\">&quot;kubernetes_cluster&quot;</span><span class=\"hljs-punctuation\">,</span>\n      <span class=\"hljs-attr\">&quot;content&quot;</span><span class=\"hljs-punctuation\">:</span> <span class=\"hljs-string\">&quot;We use Kubernetes for production orchestration...&quot;</span><span class=\"hljs-punctuation\">,</span>\n      <span class=\"hljs-attr\">&quot;tags&quot;</span><span class=\"hljs-punctuation\">:</span> <span class=\"hljs-punctuation\">[</span><span class=\"hljs-string\">&quot;kubernetes&quot;</span><span class=\"hljs-punctuation\">,</span> <span class=\"hljs-string\">&quot;orchestration&quot;</span><span class=\"hljs-punctuation\">]</span><span class=\"hljs-punctuation\">,</span>\n      <span class=\"hljs-attr\">&quot;similarity&quot;</span><span class=\"hljs-punctuation\">:</span> <span class=\"hljs-number\">0.84</span>\n    <span class=\"hljs-punctuation\">}</span>\n  <span class=\"hljs-punctuation\">]</span>\n<span class=\"hljs-punctuation\">}</span></code></pre><h2>Примеры</h2>\n<h3>Найти воспоминания о развёртывании</h3>\n<pre><code class=\"hljs language-bash\"><span class=\"hljs-comment\"># FTS5 might miss some — semantic catches all</span>\ncurl .../memory/semantic-search?q=deployment+process</code></pre><p>Возвращает воспоминания о «deployment», «release», «publishing», «rolling out» и т. д.</p>\n<h3>Найти паттерны аутентификации</h3>\n<pre><code class=\"hljs language-bash\">curl .../memory/semantic-search?q=how+<span class=\"hljs-keyword\">do</span>+<span class=\"hljs-built_in\">users</span>+<span class=\"hljs-built_in\">log</span>+<span class=\"hljs-keyword\">in</span></code></pre><p>Возвращает воспоминания о login, auth, JWT, управлении сессиями, OAuth и т. д.</p>\n<h3>Найти похожие воспоминания</h3>\n<pre><code class=\"hljs language-bash\"><span class=\"hljs-comment\"># Find memories similar to a specific one</span>\ncurl .../memory/related/mem_001</code></pre><p>Использует семантическое сходство (через общие теги И векторы эмбеддингов).</p>\n<h2>Генерация эмбеддингов</h2>\n<h3>Когда генерируются эмбеддинги?</h3>\n<ul>\n<li><strong>При сохранении памяти</strong> — если сервис эмбеддингов настроен, эмбеддинг генерируется синхронно</li>\n<li><strong>Пакетная генерация</strong> — <code>POST /memory/embed-batch</code> генерирует эмбеддинги для воспоминаний, у которых их нет</li>\n<li><strong>Асинхронные обновления</strong> — при обновлении содержимого эмбеддинг перегенерируется</li>\n</ul>\n<h3>Провайдеры эмбеддингов</h3>\n<p>Synapse поддерживает настраиваемых провайдеров эмбеддингов:</p>\n<ul>\n<li><strong>OpenAI</strong> (<code>text-embedding-3-small</code>, <code>text-embedding-3-large</code>)</li>\n<li><strong>Локальные модели</strong> (через Ollama или аналоги)</li>\n<li><strong>Кастомные</strong> (реализуйте интерфейс эмбеддингов)</li>\n</ul>\n<p>Настройка через переменные окружения:</p>\n<pre><code class=\"hljs language-bash\">EMBEDDINGS_PROVIDER=openai\nEMBEDDINGS_API_KEY=sk-...\nEMBEDDINGS_MODEL=text-embedding-3-small</code></pre><h3>Пакетная генерация</h3>\n<p>Для mind с большим количеством воспоминаний без эмбеддингов:</p>\n<pre><code class=\"hljs language-bash\"><span class=\"hljs-comment\"># Generate embeddings for up to 100 memories</span>\ncurl -X POST https://synapse.schaefer.zone/memory/embed-batch \\\n  -H <span class=\"hljs-string\">&quot;Authorization: Bearer YOUR_MIND_KEY&quot;</span> \\\n  -H <span class=\"hljs-string\">&quot;Content-Type: application/json&quot;</span> \\\n  -d <span class=\"hljs-string\">&#x27;{&quot;limit&quot;: 100}&#x27;</span>\n\n<span class=\"hljs-comment\"># Check progress</span>\ncurl -H <span class=\"hljs-string\">&quot;Authorization: Bearer YOUR_MIND_KEY&quot;</span> \\\n     https://synapse.schaefer.zone/memory/embed-batch-status</code></pre><h2>Производительность</h2>\n<table>\n<thead>\n<tr>\n<th>Операция</th>\n<th>Задержка</th>\n</tr>\n</thead>\n<tbody><tr>\n<td>Генерация эмбеддинга (OpenAI)</td>\n<td>100–200 мс</td>\n</tr>\n<tr>\n<td>Семантический поиск (1 тыс. воспоминаний)</td>\n<td>50–100 мс</td>\n</tr>\n<tr>\n<td>Семантический поиск (10 тыс. воспоминаний)</td>\n<td>200–500 мс</td>\n</tr>\n<tr>\n<td>Пакетная генерация (100 воспоминаний)</td>\n<td>10–20 с</td>\n</tr>\n</tbody></table>\n<div class=\"callout callout-note\">Семантический поиск медленнее FTS5 из-за векторных вычислений. Используйте\nFTS5 для известных ключевых слов, семантический — для концептуальных запросов.</div><h2>Ограничения</h2>\n<h3>Стоимость эмбеддингов</h3>\n<p>При использовании OpenAI генерация эмбеддингов стоит денег (~$0.02 за 1 млн\nтокенов для text-embedding-3-small). Для 10 000 воспоминаний со средним размером\n100 токенов это ~$0.02 — незначительно.</p>\n<h3>Холодный старт</h3>\n<p>Воспоминания, сохранённые до настройки эмбеддингов, не будут иметь эмбеддингов.\nЗапустите <code>POST /memory/embed-batch</code> для обратного заполнения.</p>\n<h3>Зависимость от провайдера</h3>\n<p>Если провайдер эмбеддингов недоступен, семантический поиск корректно завершается\nс ошибкой (возвращает пустой результат или ошибку). FTS5 продолжает работать.</p>\n<h2>Когда эмбеддинги недоступны</h2>\n<p>Если сервис эмбеддингов не настроен:</p>\n<ul>\n<li><code>GET /memory/semantic-search</code> возвращает 503 Service Unavailable</li>\n<li><code>POST /memory</code> продолжает работать (просто эмбеддинг не генерируется)</li>\n<li>FTS5-поиск продолжает работать</li>\n</ul>\n<h2>Лучшие практики</h2>\n<div class=\"callout callout-ok\"></div><h2>Следующие шаги</h2>\n<ul>\n<li><a href=\"/docs/concepts/fts5-search\">FTS5-поиск</a></li>\n<li><a href=\"/docs/api/memory\">Memory API</a></li>\n<li><a href=\"/docs/concepts/architecture\">Архитектура</a></li>\n</ul>\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"]}