{"title":"Pencarian Semantik (Embeddings)","slug":"semantic-search","category":"concepts","summary":"Pencarian memori konseptual menggunakan vektor embeddings — temukan berdasarkan makna, bukan hanya kata kunci.","audience":["human","llm"],"tags":["concept","semantic","embeddings","vector-search"],"difficulty":"advanced","updated":"2026-06-27","word_count":524,"read_minutes":3,"lang":"id","translated":true,"requested_lang":"id","content_markdown":"\n# Pencarian Semantik (Embeddings)\n\nSynapse mendukung pencarian semantik menggunakan vektor embeddings. Berbeda\ndengan FTS5 (pencocokan kata kunci), pencarian semantik menemukan memori\nberdasarkan **makna** — bahkan jika tidak ada kata kunci yang cocok.\n\n## Cara Kerja\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### Apa itu embeddings?\n\nEmbeddings adalah representasi vektor numerik dari teks. Teks dengan makna\nserupa memiliki vektor yang serupa. Synapse membuat vektor (mis. 1536 dimensi)\nuntuk konten setiap memori.\n\n### Cosine similarity\n\nUntuk menemukan memori yang mirip secara semantik, Synapse menghitung cosine\nsimilarity antara vektor kueri dan setiap vektor memori. Kesamaan lebih tinggi\n= lebih relevan.\n\n## Kapan Menggunakan Pencarian Semantik\n\n### Gunakan pencarian semantik ketika:\n\n- Anda ingin \"memori tentang X\" di mana X dideskripsikan secara berbeda dari yang disimpan\n- FTS5 tidak mengembalikan hasil (tidak ada cocok kata kunci)\n- Anda ingin pengelompokan konseptual (mis. semua memori \"deployment\", bahkan jika beberapa menyebut \"release\")\n- Kueri adalah pertanyaan: \"bagaimana kita menangani autentikasi?\"\n\n### Gunakan FTS5 ketika:\n\n- Anda tahu kata kunci persis\n- Anda memerlukan logika boolean (AND, OR, NOT)\n- Anda memerlukan respons sub-milidetik\n- Anda ingin pencocokan frasa\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\nRespons:\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## Contoh\n\n### Mencari memori deployment\n\n```bash\n# FTS5 might miss some — semantic catches all\ncurl .../memory/semantic-search?q=deployment+process\n```\n\nMengembalikan memori tentang \"deployment\", \"release\", \"publishing\", \"rolling out\",\ndll.\n\n### Mencari pola autentikasi\n\n```bash\ncurl .../memory/semantic-search?q=how+do+users+log+in\n```\n\nMengembalikan memori tentang login, auth, JWT, manajemen sesi, OAuth, dll.\n\n### Mencari memori serupa\n\n```bash\n# Find memories similar to a specific one\ncurl .../memory/related/mem_001\n```\n\nMenggunakan kesamaan semantik (melalui tag bersama DAN vektor embeddings).\n\n## Pembuatan Embedding\n\n### Kapan embeddings dibuat?\n\n- **Saat penyimpanan memori** — jika layanan embeddings dikonfigurasi, embedding dibuat secara sinkron\n- **Pembuatan batch** — `POST /memory/embed-batch` membuat embeddings untuk memori yang belum memilikinya\n- **Pembaruan asinkron** — saat konten diperbarui, embedding dibuat ulang\n\n### Provider embedding\n\nSynapse mendukung provider embedding yang dapat dikonfigurasi:\n\n- **OpenAI** (`text-embedding-3-small`, `text-embedding-3-large`)\n- **Model lokal** (melalui Ollama atau serupa)\n- **Khusus** (implementasikan antarmuka embeddings)\n\nKonfigurasi melalui variabel lingkungan:\n\n```bash\nEMBEDDINGS_PROVIDER=openai\nEMBEDDINGS_API_KEY=sk-...\nEMBEDDINGS_MODEL=text-embedding-3-small\n```\n\n### Pembuatan batch\n\nUntuk mind dengan banyak memori yang belum memiliki 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## Performa\n\n| Operasi | Latensi |\n|-----------|---------|\n| Membuat embedding (OpenAI) | 100-200ms |\n| Pencarian semantik (1k memori) | 50-100ms |\n| Pencarian semantik (10k memori) | 200-500ms |\n| Pembuatan batch (100 memori) | 10-20s |\n\n> [!NOTE]\n> Pencarian semantik lebih lambat dari FTS5 karena komputasi vektor. Gunakan\n> FTS5 untuk kata kunci yang diketahui, semantik untuk kueri konseptual.\n\n## Batasan\n\n### Biaya embeddings\n\nJika menggunakan OpenAI, membuat embeddings memerlukan biaya (~$0,02 per 1M\ntoken untuk text-embedding-3-small). Untuk 10.000 memori rata-rata 100 token\nmasing-masing, itu ~$0,02 — dapat diabaikan.\n\n### Cold start\n\nMemori yang disimpan sebelum embeddings dikonfigurasi tidak akan memiliki\nembeddings. Jalankan `POST /memory/embed-batch` untuk backfill.\n\n### Ketergantungan provider\n\nJika provider embeddings tidak aktif, pencarian semantik gagal dengan baik\n(mengembalikan hasil kosong atau error). FTS5 masih berfungsi.\n\n## Saat Embeddings Tidak Tersedia\n\nJika layanan embeddings tidak dikonfigurasi:\n\n- `GET /memory/semantic-search` mengembalikan 503 Service Unavailable\n- `POST /memory` masih berfungsi (hanya tidak ada embedding yang dibuat)\n- Pencarian FTS5 masih berfungsi\n\n## Praktik Terbaik\n\n> [!TIP]\n> - **Gunakan semantik untuk kueri konseptual** — \"bagaimana kita menangani X?\"\n> - **Gunakan FTS5 untuk istilah spesifik** — \"docker swarm\"\n> - **Backfill embeddings secara teratur** — `POST /memory/embed-batch`\n> - **Pantau kesehatan provider** — pencarian semantik bergantung padanya\n> - **Kombinasikan dengan tag** — semantik + filter tag mempersempit hasil\n\n## Langkah Berikutnya\n\n- [Pencarian FTS5](/docs/concepts/fts5-search)\n- [Memory API](/docs/api/memory)\n- [Arsitektur](/docs/concepts/architecture)\n","content_html":"

Pencarian Semantik (Embeddings)

\n

Synapse mendukung pencarian semantik menggunakan vektor embeddings. Berbeda\ndengan FTS5 (pencocokan kata kunci), pencarian semantik menemukan memori\nberdasarkan makna — bahkan jika tidak ada kata kunci yang cocok.

\n

Cara Kerja

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

Apa itu embeddings?

\n

Embeddings adalah representasi vektor numerik dari teks. Teks dengan makna\nserupa memiliki vektor yang serupa. Synapse membuat vektor (mis. 1536 dimensi)\nuntuk konten setiap memori.

\n

Cosine similarity

\n

Untuk menemukan memori yang mirip secara semantik, Synapse menghitung cosine\nsimilarity antara vektor kueri dan setiap vektor memori. Kesamaan lebih tinggi\n= lebih relevan.

\n

Kapan Menggunakan Pencarian Semantik

\n

Gunakan pencarian semantik ketika:

\n\n

Gunakan FTS5 ketika:

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

Respons:

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

Contoh

\n

Mencari memori deployment

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

Mengembalikan memori tentang "deployment", "release", "publishing", "rolling out",\ndll.

\n

Mencari pola autentikasi

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

Mengembalikan memori tentang login, auth, JWT, manajemen sesi, OAuth, dll.

\n

Mencari memori serupa

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

Menggunakan kesamaan semantik (melalui tag bersama DAN vektor embeddings).

\n

Pembuatan Embedding

\n

Kapan embeddings dibuat?

\n\n

Provider embedding

\n

Synapse mendukung provider embedding yang dapat dikonfigurasi:

\n\n

Konfigurasi melalui variabel lingkungan:

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

Pembuatan batch

\n

Untuk mind dengan banyak memori yang belum memiliki 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

Performa

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
OperasiLatensi
Membuat embedding (OpenAI)100-200ms
Pencarian semantik (1k memori)50-100ms
Pencarian semantik (10k memori)200-500ms
Pembuatan batch (100 memori)10-20s
\n
Pencarian semantik lebih lambat dari FTS5 karena komputasi vektor. Gunakan\nFTS5 untuk kata kunci yang diketahui, semantik untuk kueri konseptual.

Batasan

\n

Biaya embeddings

\n

Jika menggunakan OpenAI, membuat embeddings memerlukan biaya (~$0,02 per 1M\ntoken untuk text-embedding-3-small). Untuk 10.000 memori rata-rata 100 token\nmasing-masing, itu ~$0,02 — dapat diabaikan.

\n

Cold start

\n

Memori yang disimpan sebelum embeddings dikonfigurasi tidak akan memiliki\nembeddings. Jalankan POST /memory/embed-batch untuk backfill.

\n

Ketergantungan provider

\n

Jika provider embeddings tidak aktif, pencarian semantik gagal dengan baik\n(mengembalikan hasil kosong atau error). FTS5 masih berfungsi.

\n

Saat Embeddings Tidak Tersedia

\n

Jika layanan embeddings tidak dikonfigurasi:

\n\n

Praktik Terbaik

\n

Langkah Berikutnya

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