Semantik Arama (Hibrit Arama)

GET /v1/search, tenant'inizin indekslenmis dokumanlari uzerinde chunk seviyesinde hibrit arama yapar: vektor (anlam/semantik) arama ile kelime (tam metin/FTS) aramayi RRF (Reciprocal Rank Fusion) ile birlestirir. Sonuclar sayfa-atiflidir — hangi dokumanin hangi sayfasindan ve hangi bolumunden geldigini gosterir.

Sıralama hattı: sonuçlar ağırlıklı RRF (vektör + tam-metin) ile birleştirilir, ardından nihai sıralama için GPU cross-encoder (bge-reranker-v2-m3) ile yeniden sıralanır. Reranker erişilemezse RRF sıralaması sunulur — response şekli asla değişmez.

Bu uc nokta bir retrieval primitifidir: LLM sentezi YAPMAZ, yalniz ilgili metin parcalarini (chunk) siralayip doner. Kendi RAG/baglam katmaninizi kurmak istediginizde temel yapi tasidir. Hazir, sentezlenmis tek bir cevap istiyorsaniz bkz. Soru-Cevap.

Aramanin sonuc donebilmesi icin dokumanin once tamamlanmis olmasi (GET /v1/jobs/{id} -> completed) ve arka plandaki AI-indeksleme (chunk -> embed -> vektor) adiminin bitmis olmasi gerekir; bu adim completed sonrasi otomatik ve arka planda calisir — bkz. Polling ve Webhook.

Hibrit arama neden gerekli

Vektor (semantik) arama, sorguyla ayni kelimeleri kullanmayan ama anlamca yakin metinleri bulur (orn. "odeme suresi" sorgusu "30 gun icinde tediye edilir" gecen bir chunk'i yakalayabilir). Ama B/L no, fatura tutari, firma adi gibi tam eslesmesi gereken terimlerde zayiftir.

Kelime (FTS, tam metin) arama tam tersi bir profile sahiptir: tam eslesen terimleri kacirmaz ama anlamca yakin, farkli kelimeler kullanan metinleri bulamaz.

mode: hybrid (varsayilan), her iki sinyalden de genis bir aday havuzu cikarir, sonra bu iki siralamayi RRF ile tek bir birlesik siralamaya indirger: bir chunk her iki listede de ust siralarda ise birlesik skoru yukselir. Boylece bir sinyalin tek basina kacirdigi sonucu diger sinyal telafi eder. Yalniz semantik sinyal istiyorsaniz mode: semantic ile kelime tarafini devre disi birakabilirsiniz.

Auth

Tum M2M uc noktalari gibi Authorization: Bearer <api_key> basligi gerektirir (dip_live_... ya da dip_test_..., bkz. Baslangic ve Auth).

Query parametreleri

Parametre	Zorunlu	Aciklama
`q`	evet	Arama sorgusu (eksik/bos ise `400 invalid_request` doner)
`top_k`	hayir	Donecek sonuc sayisi, 1-20 arasi, varsayilan 5
`document_id`	hayir	Verilirse arama tek bir dokumana (`d_...`) scope edilir
`mode`	hayir	`hybrid` (varsayilan, vektor + kelime) ya da `semantic` (yalniz vektor)

Cevap

{
  "query": "fatura odeme kosullari",
  "mode": "hybrid",
  "results": [
    {
      "chunk_id": "8f14e45f-ceea-467e-9c2b-9d70a1cd0dc9",
      "score": 0.031147,
      "text": "Fatura tutari, teslim tarihinden itibaren 30 gun icinde odenir...",
      "document": { "id": "d_9c1a4e21", "external_item_ref": "INV-2026-0142" },
      "page_no": 3,
      "section": "Odeme Kosullari"
    }
  ]
}

results[], en alakali sonuc en basta olacak sekilde siralanmis doner; her eleman butun dokuman degil, tek bir chunk'tir.
text, chunk'in tam ham metnidir — kendi promptunuza baglam olarak dogrudan verebilirsiniz (/ask'in citations[].snippet alaninin aksine 200 karakterle kirpilmaz).
page_no / section, chunk'in kaynak dokuman icindeki konumudur (sayfa-atif); bazi chunk'larda bu alanlar null olabilir (sayfa/bolum bilgisi cikarilamadiginda). document.id ve document.external_item_ref hangi dokumandan geldigini gosterir.
score'un anlami mode'a gore degisir: hybrid'de RRF ile hesaplanan birlesik siralama degeridir (mutlak bir benzerlik olcusu degildir, yalniz kendi sonuc listeniz icinde siralama icin anlamlidir); semantic'te ise Qdrant'in dondurdugu ham kosinus benzerlik skorudur. Iki mod arasinda score degerlerini karsilastirmayin — olcekleri farklidir.

Kredi ve olcumleme

search modulu sorgu basi 0.02 kredidir (varsayilan fiyat); her basarili cagri, sonuc listesi bos donse bile bakiyeden dusulur — ucretlendirilen sey retrieval'in calismasidir, donen sonuc sayisi degil. dip_test_ key'ler bu ucretten muaftir; cagri yine de olculur (kullanim kaydi tutulur), sadece bakiyeden dusulmez.

Bakiye yetersizse istek hic calismadan (precheck asamasinda) 402 insufficient_credit doner — basarisiz/reddedilen bir istek icin ucret alinmaz.

Hatalar

HTTP	code	Aciklama
400	`invalid_request`	`q` eksik/gecersiz ya da `document_id` opak id olarak cozumlenemedi
401	`unauthorized`	Eksik, gecersiz veya revoke edilmis key
402	`insufficient_credit`	Bakiye, sorgu basi ucret icin yetersiz
403	`service_not_enabled`	Key'in entitlements listesinde `search` yok
429	`rate_limited`	`tenant_search` throttle scope'u (varsayilan 300/dk) asildi

Ne zaman kullanilir

Kendi RAG akisinizi kurmak istiyorsaniz (kendi LLM promptunuza baglam olusturmak, sonuclari kendi UI'inizda siralamak/filtrelemek gibi) /v1/search dogru secimdir — bir retrieval primitifidir, sentez yapmaz. Hazir, sayfa-atifli ve LLM ile sentezlenmis tek bir cevap istiyorsaniz sonraki adim Soru-Cevap (POST /v1/ask) uc noktasidir; ayni hibrit motoru kullanir ama sonuclari sizin yerinize sentezler.