{"title":"Anlamsal Arama (Gömmeler)","slug":"semantic-search","category":"concepts","summary":"Vektör gömmeleri kullanarak kavramsal bellek arama — yalnızca anahtar kelimelerle değil, anlamla bulun.","audience":["human","llm"],"tags":["concept","semantic","embeddings","vector-search"],"difficulty":"advanced","updated":"2026-06-27","word_count":495,"read_minutes":2,"lang":"tr","translated":true,"requested_lang":"tr","content_markdown":"\n# Anlamsal Arama (Gömmeler)\n\nSynapse, vektör gömmeleri kullanarak anlamsal aramayı destekler. FTS5'ten (anahtar kelime eşleştirme) farklı olarak anlamsal arama bellekleri **anlama** göre bulur — hiçbir anahtar kelime eşleşmese bile.\n\n## Nasıl Çalışır\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### Gömmeler nedir?\n\nGömmeler, metnin sayısal vektör temsilleridir. Benzer anlama sahip metinlerin benzer vektörleri vardır. Synapse, her belleğin içeriği için bir vektör (örn. 1536 boyut) üretir.\n\n### Kosinüs benzerliği\n\nAnlamsal olarak benzer bellekleri bulmak için Synapse, sorgu vektörü ile her bellek vektörü arasındaki kosinüs benzerliğini hesaplar. Daha yüksek benzerlik = daha alakalı.\n\n## Anlamsal Arama Ne Zaman Kullanılır\n\n### Anlamsal aramayı şu durumda kullanın:\n\n- Saklandığından farklı şekilde tanımlanan \"X hakkındaki bellekler\" istediğinizde\n- FTS5 sonuç döndürmediğinde (anahtar kelime eşleşmesi yok)\n- Kavramsal gruplandırma istediğinizde (örn. tüm \"dağıtım\" bellekleri, bazıları \"release\" dese bile)\n- Sorgu bir soru olduğunda: \"kimlik doğrulamayı nasıl ele alıyoruz?\"\n\n### FTS5'i şu durumda kullanın:\n\n- Tam anahtar kelimeleri biliyorsanız\n- Boolean mantığı (AND, OR, NOT) gerekiyorsa\n- Milisaniyenin altında yanıt gerekiyorsa\n- Deyim eşleştirme istiyorsanız\n\n## Uç Nokta\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\nYanıt:\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## Örnekler\n\n### Dağıtım belleklerini bul\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\" vb. hakkındaki bellekleri döndürür.\n\n### Kimlik doğrulama desenlerini bul\n\n```bash\ncurl .../memory/semantic-search?q=how+do+users+log+in\n```\n\nLogin, auth, JWT, oturum yönetimi, OAuth vb. hakkındaki bellekleri döndürür.\n\n### Benzer bellekleri bul\n\n```bash\n# Find memories similar to a specific one\ncurl .../memory/related/mem_001\n```\n\nAnlamsal benzerlik kullanır (paylaşılan etiketler VE gömme vektörleri aracılığıyla).\n\n## Gömme Üretimi\n\n### Gömmeler ne zaman üretilir?\n\n- **Bellek saklandığında** — gömme hizmeti yapılandırılmışsa, gömme senkron olarak üretilir\n- **Toplu üretim** — `POST /memory/embed-batch`, gömmesi eksik olan bellekler için gömme üretir\n- **Asenkron güncellemeler** — içerik güncellendiğinde gömme yeniden üretilir\n\n### Gömme sağlayıcıları\n\nSynapse, yapılandırılabilir gömme sağlayıcılarını destekler:\n\n- **OpenAI** (`text-embedding-3-small`, `text-embedding-3-large`)\n- **Yerel modeller** (Ollama veya benzeri ile)\n- **Özel** (gömme arayüzünü uygulayın)\n\nOrtam değişkenleriyle yapılandırın:\n\n```bash\nEMBEDDINGS_PROVIDER=openai\nEMBEDDINGS_API_KEY=sk-...\nEMBEDDINGS_MODEL=text-embedding-3-small\n```\n\n### Toplu üretim\n\nGömmesi eksik birçok belleği olan mind'ler için:\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## Performans\n\n| İşlem | Gecikme |\n|-----------|---------|\n| Gömme üretimi (OpenAI) | 100-200ms |\n| Anlamsal arama (1k bellek) | 50-100ms |\n| Anlamsal arama (10k bellek) | 200-500ms |\n| Toplu üretim (100 bellek) | 10-20s |\n\n> [!NOTE]\n> Anlamsal arama, vektör hesaplaması nedeniyle FTS5'ten daha yavaştır. Bilinen anahtar kelimeler için FTS5, kavramsal sorgular için anlamsal arama kullanın.\n\n## Sınırlamalar\n\n### Gömme maliyeti\n\nOpenAI kullanıyorsanız, gömme üretimi paraya mal olur (text-embedding-3-small için 1M token başına ~$0.02). Ortalama 100 token olan 10.000 bellek için ~$0.02 — ihmal edilebilir.\n\n### Soğuk başlangıç\n\nGömmeler yapılandırılmadan önce saklanan belleklerin gömmesi olmaz. Geri doldurmak için `POST /memory/embed-batch` çalıştırın.\n\n### Sağlayıcı bağımlılığı\n\nGömme sağlayıcısı çökerse, anlamsal arama zarif bir şekilde başarısız olur (boş sonuçlar veya hata döndürür). FTS5 hala çalışır.\n\n## Gömmeler Mevcut Değilse\n\nGömme hizmeti yapılandırılmamışsa:\n\n- `GET /memory/semantic-search` 503 Service Unavailable döndürür\n- `POST /memory` hala çalışır (sadece gömme üretilmez)\n- FTS5 arama hala çalışır\n\n## En İyi Uygulamalar\n\n> [!TIP]\n> - **Kavramsal sorgular için anlamsal kullanın** — \"X'i nasıl ele alıyoruz?\"\n> - **Belirli terimler için FTS5 kullanın** — \"docker swarm\"\n> - **Gömmeleri düzenli olarak geri doldurun** — `POST /memory/embed-batch`\n> - **Sağlayıcı sağlığını izleyin** — anlamsal arama buna bağlıdır\n> - **Etiketlerle birleştirin** — anlamsal + etiket filtresi sonuçları daraltır\n\n## Sonraki Adımlar\n\n- [FTS5 Arama](/docs/concepts/fts5-search)\n- [Memory API](/docs/api/memory)\n- [Mimari](/docs/concepts/architecture)\n","content_html":"

Anlamsal Arama (Gömmeler)

\n

Synapse, vektör gömmeleri kullanarak anlamsal aramayı destekler. FTS5'ten (anahtar kelime eşleştirme) farklı olarak anlamsal arama bellekleri anlama göre bulur — hiçbir anahtar kelime eşleşmese bile.

\n

Nasıl Çalışır

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

Gömmeler nedir?

\n

Gömmeler, metnin sayısal vektör temsilleridir. Benzer anlama sahip metinlerin benzer vektörleri vardır. Synapse, her belleğin içeriği için bir vektör (örn. 1536 boyut) üretir.

\n

Kosinüs benzerliği

\n

Anlamsal olarak benzer bellekleri bulmak için Synapse, sorgu vektörü ile her bellek vektörü arasındaki kosinüs benzerliğini hesaplar. Daha yüksek benzerlik = daha alakalı.

\n

Anlamsal Arama Ne Zaman Kullanılır

\n

Anlamsal aramayı şu durumda kullanın:

\n\n

FTS5'i şu durumda kullanın:

\n\n

Uç Nokta

\n

GET /memory/semantic-search

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

Yanıt:

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

Örnekler

\n

Dağıtım belleklerini bul

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

"deployment", "release", "publishing", "rolling out" vb. hakkındaki bellekleri döndürür.

\n

Kimlik doğrulama desenlerini bul

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

Login, auth, JWT, oturum yönetimi, OAuth vb. hakkındaki bellekleri döndürür.

\n

Benzer bellekleri bul

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

Anlamsal benzerlik kullanır (paylaşılan etiketler VE gömme vektörleri aracılığıyla).

\n

Gömme Üretimi

\n

Gömmeler ne zaman üretilir?

\n\n

Gömme sağlayıcıları

\n

Synapse, yapılandırılabilir gömme sağlayıcılarını destekler:

\n\n

Ortam değişkenleriyle yapılandırın:

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

Toplu üretim

\n

Gömmesi eksik birçok belleği olan mind'ler için:

\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

Performans

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
İşlemGecikme
Gömme üretimi (OpenAI)100-200ms
Anlamsal arama (1k bellek)50-100ms
Anlamsal arama (10k bellek)200-500ms
Toplu üretim (100 bellek)10-20s
\n
Anlamsal arama, vektör hesaplaması nedeniyle FTS5'ten daha yavaştır. Bilinen anahtar kelimeler için FTS5, kavramsal sorgular için anlamsal arama kullanın.

Sınırlamalar

\n

Gömme maliyeti

\n

OpenAI kullanıyorsanız, gömme üretimi paraya mal olur (text-embedding-3-small için 1M token başına ~$0.02). Ortalama 100 token olan 10.000 bellek için ~$0.02 — ihmal edilebilir.

\n

Soğuk başlangıç

\n

Gömmeler yapılandırılmadan önce saklanan belleklerin gömmesi olmaz. Geri doldurmak için POST /memory/embed-batch çalıştırın.

\n

Sağlayıcı bağımlılığı

\n

Gömme sağlayıcısı çökerse, anlamsal arama zarif bir şekilde başarısız olur (boş sonuçlar veya hata döndürür). FTS5 hala çalışır.

\n

Gömmeler Mevcut Değilse

\n

Gömme hizmeti yapılandırılmamışsa:

\n\n

En İyi Uygulamalar

\n

Sonraki Adımlar

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