{"title":"Ricerca semantica (embedding)","slug":"semantic-search","category":"concepts","summary":"Ricerca concettuale delle memorie usando embedding vettoriali — trova per significato, non solo per parole chiave.","audience":["human","llm"],"tags":["concept","semantic","embeddings","vector-search"],"difficulty":"advanced","updated":"2026-06-27","word_count":576,"read_minutes":3,"lang":"it","translated":true,"requested_lang":"it","content_markdown":"\n# Ricerca semantica (embedding)\n\nSynapse supporta la ricerca semantica usando embedding vettoriali. A differenza\ndi FTS5 (corrispondenza per parola chiave), la ricerca semantica trova le\nmemorie per **significato** — anche se nessuna parola chiave corrisponde.\n\n## Come funziona\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### Cosa sono gli embedding?\n\nGli embedding sono rappresentazioni vettoriali numeriche del testo. Testo con\nsignificato simile ha vettori simili. Synapse genera un vettore (es. 1536\ndimensioni) per il contenuto di ogni memoria.\n\n### Similarità del coseno\n\nPer trovare memorie semanticamente simili, Synapse calcola la similarità del\ncoseno tra il vettore della query e ogni vettore di memoria. Similarità più\nalta = più rilevante.\n\n## Quando usare la ricerca semantica\n\n### Usi la ricerca semantica quando:\n\n- Vuole \"memorie su X\" dove X è descritto diversamente da come è salvato\n- FTS5 non restituisce risultati (nessuna corrispondenza di parola chiave)\n- Vuole raggruppamento concettuale (es. tutte le memorie \"deployment\", anche se alcune dicono \"release\")\n- La query è una domanda: \"come gestiamo l'autenticazione?\"\n\n### Usi FTS5 quando:\n\n- Conosce le parole chiave esatte\n- Ha bisogno di logica booleana (AND, OR, NOT)\n- Ha bisogno di risposta sub-millisecond\n- Vuole corrispondenza di 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\nRisposta:\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## Esempi\n\n### Trova memorie sul deployment\n\n```bash\n# FTS5 might miss some — semantic catches all\ncurl .../memory/semantic-search?q=deployment+process\n```\n\nRestituisce memorie su \"deployment\", \"release\", \"publishing\", \"rolling out\",\necc.\n\n### Trova pattern di autenticazione\n\n```bash\ncurl .../memory/semantic-search?q=how+do+users+log+in\n```\n\nRestituisce memorie su login, auth, JWT, gestione sessioni, OAuth, ecc.\n\n### Trova memorie simili\n\n```bash\n# Find memories similar to a specific one\ncurl .../memory/related/mem_001\n```\n\nUsa similarità semantica (tramite tag condivisi E vettori di embedding).\n\n## Generazione degli embedding\n\n### Quando vengono generati gli embedding?\n\n- **Su memorizzazione** — se il servizio embedding è configurato, l'embedding viene generato in modo sincrono\n- **Generazione batch** — `POST /memory/embed-batch` genera embedding per le memorie che ne sono sprovviste\n- **Aggiornamenti asincroni** — quando il contenuto viene aggiornato, l'embedding viene rigenerato\n\n### Provider di embedding\n\nSynapse supporta provider di embedding configurabili:\n\n- **OpenAI** (`text-embedding-3-small`, `text-embedding-3-large`)\n- **Modelli locali** (tramite Ollama o simili)\n- **Personalizzato** (implementi l'interfaccia embeddings)\n\nConfiguri tramite variabili di ambiente:\n\n```bash\nEMBEDDINGS_PROVIDER=openai\nEMBEDDINGS_API_KEY=sk-...\nEMBEDDINGS_MODEL=text-embedding-3-small\n```\n\n### Generazione batch\n\nPer menti con molte memorie sprovviste di embedding:\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## Prestazioni\n\n| Operazione | Latenza |\n|-----------|---------|\n| Genera embedding (OpenAI) | 100-200ms |\n| Ricerca semantica (1k memorie) | 50-100ms |\n| Ricerca semantica (10k memorie) | 200-500ms |\n| Generazione batch (100 memorie) | 10-20s |\n\n> [!NOTE]\n> La ricerca semantica è più lenta di FTS5 a causa del calcolo vettoriale. Usi\n> FTS5 per parole chiave note, semantica per query concettuali.\n\n## Limitazioni\n\n### Costo degli embedding\n\nSe usa OpenAI, generare embedding costa denaro (~$0,02 per 1M token per\ntext-embedding-3-small). Per 10.000 memorie con una media di 100 token ciascuna,\nsono ~$0,02 — trascurabile.\n\n### Cold start\n\nLe memorie salvate prima che gli embedding fossero configurati non avranno\nembedding. Esegua `POST /memory/embed-batch` per backfill.\n\n### Dipendenza dal provider\n\nSe il provider di embedding è down, la ricerca semantica fallisce in modo\ngrazioso (restituisce risultati vuoti o errore). FTS5 continua a funzionare.\n\n## Quando gli embedding non sono disponibili\n\nSe il servizio embedding non è configurato:\n\n- `GET /memory/semantic-search` restituisce 503 Service Unavailable\n- `POST /memory` funziona comunque (solo senza embedding generato)\n- La ricerca FTS5 funziona ancora\n\n## Best practice\n\n> [!TIP]\n> - **Usi la semantica per query concettuali** — \"come gestiamo X?\"\n> - **Usi FTS5 per termini specifici** — \"docker swarm\"\n> - **Faccia backfill degli embedding regolarmente** — `POST /memory/embed-batch`\n> - **Monitori la salute del provider** — la ricerca semantica dipende da esso\n> - **Combini con i tag** — semantica + filtro tag restringe i risultati\n\n## Prossimi passi\n\n- [Ricerca FTS5](/docs/concepts/fts5-search)\n- [Memory API](/docs/api/memory)\n- [Architettura](/docs/concepts/architecture)\n","content_html":"

Ricerca semantica (embedding)

\n

Synapse supporta la ricerca semantica usando embedding vettoriali. A differenza\ndi FTS5 (corrispondenza per parola chiave), la ricerca semantica trova le\nmemorie per significato — anche se nessuna parola chiave corrisponde.

\n

Come funziona

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

Cosa sono gli embedding?

\n

Gli embedding sono rappresentazioni vettoriali numeriche del testo. Testo con\nsignificato simile ha vettori simili. Synapse genera un vettore (es. 1536\ndimensioni) per il contenuto di ogni memoria.

\n

Similarità del coseno

\n

Per trovare memorie semanticamente simili, Synapse calcola la similarità del\ncoseno tra il vettore della query e ogni vettore di memoria. Similarità più\nalta = più rilevante.

\n

Quando usare la ricerca semantica

\n

Usi la ricerca semantica quando:

\n\n

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

Risposta:

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

Esempi

\n

Trova memorie sul deployment

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

Restituisce memorie su "deployment", "release", "publishing", "rolling out",\necc.

\n

Trova pattern di autenticazione

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

Restituisce memorie su login, auth, JWT, gestione sessioni, OAuth, ecc.

\n

Trova memorie simili

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

Usa similarità semantica (tramite tag condivisi E vettori di embedding).

\n

Generazione degli embedding

\n

Quando vengono generati gli embedding?

\n\n

Provider di embedding

\n

Synapse supporta provider di embedding configurabili:

\n\n

Configuri tramite variabili di ambiente:

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

Generazione batch

\n

Per menti con molte memorie sprovviste di embedding:

\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

Prestazioni

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
OperazioneLatenza
Genera embedding (OpenAI)100-200ms
Ricerca semantica (1k memorie)50-100ms
Ricerca semantica (10k memorie)200-500ms
Generazione batch (100 memorie)10-20s
\n
La ricerca semantica è più lenta di FTS5 a causa del calcolo vettoriale. Usi\nFTS5 per parole chiave note, semantica per query concettuali.

Limitazioni

\n

Costo degli embedding

\n

Se usa OpenAI, generare embedding costa denaro (~$0,02 per 1M token per\ntext-embedding-3-small). Per 10.000 memorie con una media di 100 token ciascuna,\nsono ~$0,02 — trascurabile.

\n

Cold start

\n

Le memorie salvate prima che gli embedding fossero configurati non avranno\nembedding. Esegua POST /memory/embed-batch per backfill.

\n

Dipendenza dal provider

\n

Se il provider di embedding è down, la ricerca semantica fallisce in modo\ngrazioso (restituisce risultati vuoti o errore). FTS5 continua a funzionare.

\n

Quando gli embedding non sono disponibili

\n

Se il servizio embedding non è configurato:

\n\n

Best practice

\n

Prossimi passi

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