{"title":"Busca semântica (embeddings)","slug":"semantic-search","category":"concepts","summary":"Busca conceitual de memória usando embeddings vetoriais — encontre por significado, não apenas palavras-chave.","audience":["human","llm"],"tags":["concept","semantic","embeddings","vector-search"],"difficulty":"advanced","updated":"2026-06-27","word_count":571,"read_minutes":3,"lang":"pt","translated":true,"requested_lang":"pt","content_markdown":"\n# Busca semântica (embeddings)\n\nO Synapse suporta busca semântica usando embeddings vetoriais. Diferente do\nFTS5 (correspondência de palavras-chave), a busca semântica encontra memórias\npor **significado** — mesmo que nenhuma palavra-chave corresponda.\n\n## Como funciona\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### O que são embeddings?\n\nEmbeddings são representações vetoriais numéricas de texto. Textos com\nsignificado similar têm vetores similares. O Synapse gera um vetor (ex.: 1536\ndimensões) para o conteúdo de cada memória.\n\n### Similaridade de cosseno\n\nPara encontrar memórias semanticamente similares, o Synapse calcula a\nsimilaridade de cosseno entre o vetor da consulta e cada vetor de memória.\nMaior similaridade = mais relevante.\n\n## Quando usar busca semântica\n\n### Use busca semântica quando:\n\n- Você quer \"memórias sobre X\" onde X é descrito de forma diferente do que foi armazenado\n- FTS5 não retorna resultados (nenhuma palavra-chave corresponde)\n- Você quer agrupamento conceitual (ex.: todas as memórias de \"deployment\", mesmo que algumas digam \"release\")\n- A consulta é uma pergunta: \"como tratamos autenticação?\"\n\n### Use FTS5 quando:\n\n- Você conhece as palavras-chave exatas\n- Você precisa de lógica booleana (AND, OR, NOT)\n- Você precisa de resposta sub-milissegundo\n- Você quer correspondência de frase\n\n## Endpoint\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\nResposta:\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## Exemplos\n\n### Encontrar memórias de deployment\n\n```bash\n# FTS5 might miss some — semantic catches all\ncurl .../memory/semantic-search?q=deployment+process\n```\n\nRetorna memórias sobre \"deployment\", \"release\", \"publishing\", \"rolling out\",\netc.\n\n### Encontrar padrões de autenticação\n\n```bash\ncurl .../memory/semantic-search?q=how+do+users+log+in\n```\n\nRetorna memórias sobre login, auth, JWT, gerenciamento de sessão, OAuth, etc.\n\n### Encontrar memórias similares\n\n```bash\n# Find memories similar to a specific one\ncurl .../memory/related/mem_001\n```\n\nUsa similaridade semântica (via tags compartilhadas E vetores de embedding).\n\n## Geração de embeddings\n\n### Quando os embeddings são gerados?\n\n- **No armazenamento de memória** — se o serviço de embeddings estiver configurado, o embedding é gerado sincronamente\n- **Geração em lote** — `POST /memory/embed-batch` gera embeddings para memórias que não os têm\n- **Atualizações assíncronas** — quando o conteúdo é atualizado, o embedding é regenerado\n\n### Provedores de embedding\n\nO Synapse suporta provedores de embedding configuráveis:\n\n- **OpenAI** (`text-embedding-3-small`, `text-embedding-3-large`)\n- **Modelos locais** (via Ollama ou similar)\n- **Customizado** (implemente a interface de embeddings)\n\nConfigure via variáveis de ambiente:\n\n```bash\nEMBEDDINGS_PROVIDER=openai\nEMBEDDINGS_API_KEY=sk-...\nEMBEDDINGS_MODEL=text-embedding-3-small\n```\n\n### Geração em lote\n\nPara minds com muitas memórias sem embeddings:\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## Desempenho\n\n| Operação | Latência |\n|----------|----------|\n| Gerar embedding (OpenAI) | 100-200ms |\n| Busca semântica (1k memórias) | 50-100ms |\n| Busca semântica (10k memórias) | 200-500ms |\n| Geração em lote (100 memórias) | 10-20s |\n\n> [!NOTE]\n> Busca semântica é mais lenta que FTS5 devido à computação vetorial. Use\n> FTS5 para palavras-chave conhecidas, semântica para consultas conceituais.\n\n## Limitações\n\n### Custo dos embeddings\n\nSe usar OpenAI, gerar embeddings custa dinheiro (~$0.02 por 1M tokens para\ntext-embedding-3-small). Para 10.000 memórias com média de 100 tokens cada,\nsão ~$0.02 — insignificante.\n\n### Cold start\n\nMemórias armazenadas antes de os embeddings serem configurados não terão\nembeddings. Execute `POST /memory/embed-batch` para preencher retroativamente.\n\n### Dependência de provedor\n\nSe o provedor de embeddings cair, a busca semântica falha graciosamente\n(retorna resultados vazios ou erro). FTS5 continua funcionando.\n\n## Quando embeddings não estão disponíveis\n\nSe o serviço de embeddings não estiver configurado:\n\n- `GET /memory/semantic-search` retorna 503 Service Unavailable\n- `POST /memory` ainda funciona (apenas nenhum embedding é gerado)\n- Busca FTS5 ainda funciona\n\n## Melhores práticas\n\n> [!TIP]\n> - **Use semântica para consultas conceituais** — \"como tratamos X?\"\n> - **Use FTS5 para termos específicos** — \"docker swarm\"\n> - **Preencha embeddings regularmente** — `POST /memory/embed-batch`\n> - **Monitore a saúde do provedor** — a busca semântica depende disso\n> - **Combine com tags** — semântica + filtro de tag estreita os resultados\n\n## Próximos passos\n\n- [Busca FTS5](/docs/concepts/fts5-search)\n- [API de Memória](/docs/api/memory)\n- [Arquitetura](/docs/concepts/architecture)\n","content_html":"

Busca semântica (embeddings)

\n

O Synapse suporta busca semântica usando embeddings vetoriais. Diferente do\nFTS5 (correspondência de palavras-chave), a busca semântica encontra memórias\npor significado — mesmo que nenhuma palavra-chave corresponda.

\n

Como funciona

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

O que são embeddings?

\n

Embeddings são representações vetoriais numéricas de texto. Textos com\nsignificado similar têm vetores similares. O Synapse gera um vetor (ex.: 1536\ndimensões) para o conteúdo de cada memória.

\n

Similaridade de cosseno

\n

Para encontrar memórias semanticamente similares, o Synapse calcula a\nsimilaridade de cosseno entre o vetor da consulta e cada vetor de memória.\nMaior similaridade = mais relevante.

\n

Quando usar busca semântica

\n

Use busca semântica quando:

\n\n

Use FTS5 quando:

\n\n

Endpoint

\n

GET /memory/semantic-search

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

Resposta:

\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}

Exemplos

\n

Encontrar memórias de deployment

\n
# FTS5 might miss some — semantic catches all\ncurl .../memory/semantic-search?q=deployment+process

Retorna memórias sobre "deployment", "release", "publishing", "rolling out",\netc.

\n

Encontrar padrões de autenticação

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

Retorna memórias sobre login, auth, JWT, gerenciamento de sessão, OAuth, etc.

\n

Encontrar memórias similares

\n
# Find memories similar to a specific one\ncurl .../memory/related/mem_001

Usa similaridade semântica (via tags compartilhadas E vetores de embedding).

\n

Geração de embeddings

\n

Quando os embeddings são gerados?

\n\n

Provedores de embedding

\n

O Synapse suporta provedores de embedding configuráveis:

\n\n

Configure via variáveis de ambiente:

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

Geração em lote

\n

Para minds com muitas memórias sem embeddings:

\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

Desempenho

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
OperaçãoLatência
Gerar embedding (OpenAI)100-200ms
Busca semântica (1k memórias)50-100ms
Busca semântica (10k memórias)200-500ms
Geração em lote (100 memórias)10-20s
\n
Busca semântica é mais lenta que FTS5 devido à computação vetorial. Use\nFTS5 para palavras-chave conhecidas, semântica para consultas conceituais.

Limitações

\n

Custo dos embeddings

\n

Se usar OpenAI, gerar embeddings custa dinheiro (~$0.02 por 1M tokens para\ntext-embedding-3-small). Para 10.000 memórias com média de 100 tokens cada,\nsão ~$0.02 — insignificante.

\n

Cold start

\n

Memórias armazenadas antes de os embeddings serem configurados não terão\nembeddings. Execute POST /memory/embed-batch para preencher retroativamente.

\n

Dependência de provedor

\n

Se o provedor de embeddings cair, a busca semântica falha graciosamente\n(retorna resultados vazios ou erro). FTS5 continua funcionando.

\n

Quando embeddings não estão disponíveis

\n

Se o serviço de embeddings não estiver configurado:

\n\n

Melhores práticas

\n

Próximos passos

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