{"title":"Búsqueda semántica (embeddings)","slug":"semantic-search","category":"concepts","summary":"Búsqueda conceptual de memoria usando embeddings vectoriales — encuentre por significado, no solo por palabras clave.","audience":["human","llm"],"tags":["concept","semantic","embeddings","vector-search"],"difficulty":"advanced","updated":"2026-06-27","word_count":578,"read_minutes":3,"lang":"es","translated":true,"requested_lang":"es","content_markdown":"\n# Búsqueda semántica (embeddings)\n\nSynapse admite búsqueda semántica usando embeddings vectoriales. A diferencia\nde FTS5 (coincidencia por palabra clave), la búsqueda semántica encuentra\nmemorias por **significado** — incluso si no coincide ninguna palabra clave.\n\n## Cómo 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### ¿Qué son los embeddings?\n\nLos embeddings son representaciones vectoriales numéricas del texto. El texto\ncon significado similar tiene vectores similares. Synapse genera un vector (p.\nej. 1536 dimensiones) por el contenido de cada memoria.\n\n### Similitud coseno\n\nPara encontrar memorias semánticamente similares, Synapse calcula la similitud\ncoseno entre el vector de la consulta y cada vector de memoria. Mayor similitud\n= más relevante.\n\n## Cuándo usar búsqueda semántica\n\n### Use búsqueda semántica cuando:\n\n- Quiere \"memorias sobre X\" donde X se describe de forma diferente a como está\n almacenado\n- FTS5 no devuelve resultados (sin coincidencia de palabra clave)\n- Quiere agrupación conceptual (p. ej. todas las memorias de \"deployment\",\n incluso si algunas dicen \"release\")\n- La consulta es una pregunta: \"¿cómo gestionamos la autenticación?\"\n\n### Use FTS5 cuando:\n\n- Conoce palabras clave exactas\n- Necesita lógica booleana (AND, OR, NOT)\n- Necesita respuesta sub-milisegundo\n- Quiere coincidencia 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\nRespuesta:\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## Ejemplos\n\n### Buscar memorias de despliegue\n\n```bash\n# FTS5 might miss some — semantic catches all\ncurl .../memory/semantic-search?q=deployment+process\n```\n\nDevuelve memorias sobre \"deployment\", \"release\", \"publishing\", \"rolling out\",\netc.\n\n### Buscar patrones de autenticación\n\n```bash\ncurl .../memory/semantic-search?q=how+do+users+log+in\n```\n\nDevuelve memorias sobre login, auth, JWT, gestión de sesiones, OAuth, etc.\n\n### Buscar memorias similares\n\n```bash\n# Find memories similar to a specific one\ncurl .../memory/related/mem_001\n```\n\nUsa similitud semántica (vía etiquetas compartidas Y vectores de embedding).\n\n## Generación de embeddings\n\n### ¿Cuándo se generan los embeddings?\n\n- **Al almacenar memoria** — si el servicio de embeddings está configurado, el\n embedding se genera de forma síncrona\n- **Generación en lote** — `POST /memory/embed-batch` genera embeddings para\n memorias que no los tienen\n- **Actualizaciones asíncronas** — cuando se actualiza el contenido, el\n embedding se regenera\n\n### Proveedores de embeddings\n\nSynapse admite proveedores de embeddings configurables:\n\n- **OpenAI** (`text-embedding-3-small`, `text-embedding-3-large`)\n- **Modelos locales** (vía Ollama o similar)\n- **Personalizado** (implementar la interfaz de embeddings)\n\nConfigúrelos mediante variables de entorno:\n\n```bash\nEMBEDDINGS_PROVIDER=openai\nEMBEDDINGS_API_KEY=sk-...\nEMBEDDINGS_MODEL=text-embedding-3-small\n```\n\n### Generación en lote\n\nPara minds con muchas memorias sin 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## Rendimiento\n\n| Operación | Latencia |\n|-----------|---------|\n| Generate embedding (OpenAI) | 100-200ms |\n| Semantic search (1k memories) | 50-100ms |\n| Semantic search (10k memories) | 200-500ms |\n| Batch generation (100 memories) | 10-20s |\n\n> [!NOTE]\n> La búsqueda semántica es más lenta que FTS5 debido al cálculo vectorial. Use\n> FTS5 para palabras clave conocidas, semántica para consultas conceptuales.\n\n## Limitaciones\n\n### Costo de embeddings\n\nSi usa OpenAI, generar embeddings cuesta dinero (~$0.02 por 1M tokens para\ntext-embedding-3-small). Para 10.000 memorias de promedio 100 tokens cada una,\nson ~$0.02 — despreciable.\n\n### Arranque en frío\n\nLas memorias almacenadas antes de configurar los embeddings no los tendrán.\nEjecute `POST /memory/embed-batch` para rellenarlas.\n\n### Dependencia del proveedor\n\nSi el proveedor de embeddings está caído, la búsqueda semántica falla de forma\ngraciosa (devuelve resultados vacíos o un error). FTS5 sigue funcionando.\n\n## Cuando los embeddings no están disponibles\n\nSi el servicio de embeddings no está configurado:\n\n- `GET /memory/semantic-search` devuelve 503 Service Unavailable\n- `POST /memory` sigue funcionando (solo no se genera embedding)\n- La búsqueda FTS5 sigue funcionando\n\n## Mejores prácticas\n\n> [!TIP]\n> - **Use semántica para consultas conceptuales** — \"¿cómo gestionamos X?\"\n> - **Use FTS5 para términos específicos** — \"docker swarm\"\n> - **Rellene los embeddings regularmente** — `POST /memory/embed-batch`\n> - **Monitoree la salud del proveedor** — la búsqueda semántica depende de él\n> - **Combine con etiquetas** — semántica + filtro por etiqueta acota resultados\n\n## Próximos pasos\n\n- [Búsqueda FTS5](/docs/concepts/fts5-search)\n- [API de Memory](/docs/api/memory)\n- [Arquitectura](/docs/concepts/architecture)\n","content_html":"

Búsqueda semántica (embeddings)

\n

Synapse admite búsqueda semántica usando embeddings vectoriales. A diferencia\nde FTS5 (coincidencia por palabra clave), la búsqueda semántica encuentra\nmemorias por significado — incluso si no coincide ninguna palabra clave.

\n

Cómo funciona

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

¿Qué son los embeddings?

\n

Los embeddings son representaciones vectoriales numéricas del texto. El texto\ncon significado similar tiene vectores similares. Synapse genera un vector (p.\nej. 1536 dimensiones) por el contenido de cada memoria.

\n

Similitud coseno

\n

Para encontrar memorias semánticamente similares, Synapse calcula la similitud\ncoseno entre el vector de la consulta y cada vector de memoria. Mayor similitud\n= más relevante.

\n

Cuándo usar búsqueda semántica

\n

Use búsqueda semántica cuando:

\n\n

Use FTS5 cuando:

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

Respuesta:

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

Ejemplos

\n

Buscar memorias de despliegue

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

Devuelve memorias sobre "deployment", "release", "publishing", "rolling out",\netc.

\n

Buscar patrones de autenticación

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

Devuelve memorias sobre login, auth, JWT, gestión de sesiones, OAuth, etc.

\n

Buscar memorias similares

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

Usa similitud semántica (vía etiquetas compartidas Y vectores de embedding).

\n

Generación de embeddings

\n

¿Cuándo se generan los embeddings?

\n\n

Proveedores de embeddings

\n

Synapse admite proveedores de embeddings configurables:

\n\n

Configúrelos mediante variables de entorno:

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

Generación en lote

\n

Para minds con muchas memorias sin 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

Rendimiento

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
OperaciónLatencia
Generate embedding (OpenAI)100-200ms
Semantic search (1k memories)50-100ms
Semantic search (10k memories)200-500ms
Batch generation (100 memories)10-20s
\n
La búsqueda semántica es más lenta que FTS5 debido al cálculo vectorial. Use\nFTS5 para palabras clave conocidas, semántica para consultas conceptuales.

Limitaciones

\n

Costo de embeddings

\n

Si usa OpenAI, generar embeddings cuesta dinero (~$0.02 por 1M tokens para\ntext-embedding-3-small). Para 10.000 memorias de promedio 100 tokens cada una,\nson ~$0.02 — despreciable.

\n

Arranque en frío

\n

Las memorias almacenadas antes de configurar los embeddings no los tendrán.\nEjecute POST /memory/embed-batch para rellenarlas.

\n

Dependencia del proveedor

\n

Si el proveedor de embeddings está caído, la búsqueda semántica falla de forma\ngraciosa (devuelve resultados vacíos o un error). FTS5 sigue funcionando.

\n

Cuando los embeddings no están disponibles

\n

Si el servicio de embeddings no está configurado:

\n\n

Mejores prácticas

\n

Próximos pasos

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