Soru-Cevap (RAG)

POST /v1/ask, retrieval (bilgi getirme) ve LLM sentezini tek cagrida birlestiren bir kolaylik katmanidir: sorgunuzu alir, /v1/search ile ayni hibrit (RRF) motorla ilgili chunk'lari bulur ve yalnizca bu chunk'lardan sentezlenmis, sayfa atifli bir cevap doner.

Search'ten farki

/v1/search bir retrieval primitifidir — sonuc olarak bir chunk listesi doner, sentez yapmaz; kendi RAG akisinizi (kendi promptunuz/LLM'iniz ile) kurmak istediginizde temel yapi tasidir. /v1/ask ayni retrieval katmanini kullanir ama sentez adimini da sizin yerinize yapar: hazir, kaynak atifli bir cevap metni alirsiniz.

Nasil calisir (retrieve -> generate)

1. Retrieve — query, /v1/search ile ayni hibrit (vektor + kelime, RRF) motora gonderilir; top_k (varsayilan 5, maksimum 20) chunk getirilir. document_id verilirse arama tek bir dokumana scope edilir.
2. Baglam yoksa — hic chunk bulunamazsa LLM'e hic gidilmez; sabit ve durust bir cevap donulur: "Bu soruya belgelerde yanit bulunamadi." Bu cagri yine de basarili sayilir ve normal sekilde ucretlendirilir.
3. Generate — chunk bulunduysa her biri [Kaynak: belge=..., sayfa=..., bolum=...] basligiyla bir baglam bloguna donusturulur (bloklar --- ile ayrilir) ve motor-bagimsiz, OpenAI-uyumlu bir /chat/completions uc noktasina (dusuk sicaklik, temperature=0.1) gonderilir. Gecici hatalarda (5xx/timeout) exponential backoff ile tekrar denenir; kalici hatalarda (4xx) veya sunucu tarafinda RAG yapilandirilmamissa RagError firlatilir (→ 503).
4. Cevap — LLM'in urettigi metin answer alaninda doner. Pasajlar numaralidir ([S1], [S2], ...) ve model her iddiayi kaynak numarasiyla isaretler; citations[] yalniz cevapta gercekten atif yapilan kaynaklari icerir (her biri source_no tasir).

Auth

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

Istek

Content-Type: application/json govdesi:

{
  "query": "fatura odeme kosullari nedir?",
  "top_k": 5,
  "document_id": null
}

Cevap

{
  "query": "fatura odeme kosullari nedir?",
  "answer": "...[belge/sayfa 3]...",
  "citations": [
    {
      "document_id": "...",
      "external_item_ref": "...",
      "page_no": 3,
      "section": "Odeme Kosullari",
      "chunk_id": "...",
      "snippet": "..."
    }
  ]
}

citations[] yalniz cevabin gercekten atif yaptigi kaynaklari icerir (answer metnindeki [S#] isaretleriyle source_no uzerinden birebir eslesir) — retrieval'in getirdigi ama kullanilmayan chunk'lar artik kaynak olarak sunulmaz. Durust cevap "belgede bulunamadi" ise citations bostur. Retrieval ayrica bir reranker alaka tabani uygular (RERANK_MIN_SCORE): cross-encoder'in tabanin altinda puanladigi adaylar senteze hic ulasmaz — cevabi olmayan soru "kotulerin en iyisi" kaynak kartlari uretmez. snippet, atif yapilan chunk metninin ilk 200 karakteridir.

Sadik kalma (hallucination yok)

Sentez sistem promptu modele su kurallari dayatir: sadece verilen baglamdaki bilgiyi kullan, her onemli iddiadan sonra [S#] bicimli atif ver, cevap baglamda yoksa bunu acikca soyle ("bu bilgi belgede bulunamadi"), asla uydurma. Baglam (chunk) hic bulunamazsa bu kurala gerek kalmadan sabit, durust bir cevap donulur — LLM'e hic gidilmez.

Kredi ve ucretlendirme

/v1/ask, varsayilan olarak 0.20 kredi/sorgudur — /v1/search'ten daha pahalidir cunku hem embed hem de LLM adimini icerir. Istek oncesi bakiye kontrol edilir (yetersizse 402 insufficient_credit); sentez basarisiz olursa (503) ucret dusulmez, yalniz basarili cevapta dusulur. dip_test_... test key'leri query ucretinden muaftir (kullanim yine de olculur, bakiyeden dusulmez).

Hatalar

Notlar

/v1/ask, retrieve+generate adimlarini tek cagriya sikistiran bir kolaylik uc noktasidir; kendi promptunuzu/LLM'inizi kullanmak isterseniz /v1/search ile kendi RAG akisinizi kendiniz kurabilirsiniz.

Cross-check: belgeler arasi celiski denetimi

POST /v1/cross-check, islenmis 2+ belgenin (ust sinir YOK — belge sayisi artinca her belge ortak butce icinde en onemli iddialariyla temsil edilir) dogrulanmis mantik iddialarini birbiriyle karsilastirir ve belgeler-arasi bulgular doner — celiskiler ("belge A X diyor, belge B degilini kanitliyor") ve destek ciftleri (bir belgedeki yukumluluk, digerindeki yerine-getirme kaniti).

{ "document_ids": ["d_...", "d_..."] }

Mekanizma, mantik katmaninin halusinasyon kalkanini miras alir: karsilastirilan iddialar zaten cikarim aninda belge metnine karsi dogrulanmistir (her biri sayfa numarasi + birebir alinti tasir) ve modelin onerdigi her bulgu deterministik olarak denetlenir — yalnizca bilinen iddia id'lerine isaret edebilir, iki taraf FARKLI belgelerden olmak zorundadir ve yanittaki statement/alinti/sayfa modelin ekosundan degil sunucu kayitlarindan doldurulur. Bos findings gecerli bir cevaptir; model emin olmadigi cifti yazmamakla yukumludur.

Kapsama sistematiktir, modelin dikkatiyle sinirli degildir: aday ciftler once deterministik uretilir — her iddia (Docsfra'nin kendi altyapisinda) embed edilip DIGER belgelerin en benzer iddialariyla eslestirilir, ayrica belirgin ortak token (referans no, tutar, tarih) tasiyan her cift aday olur — ve her aday model tarafindan TEK TEK yargilanir (celiski / destek / yok). Ayri bir serbest-tarama gecisi, benzerligin yakalayamayacagi kural-vs-ihlal ciftlerini bulur (or. "tum belgeler Ingilizce olmali" kurali vs Almanca bir cumle). Tum kanallar cift-anahtariyla birlesir; sonuclar cagridan cagriya kararlidir ve deterministik sirayla doner (once celiskiler). Yanittaki stats objesi kac iddia ve kac aday ciftin incelendigini raporlar.

{
  "documents": [{ "document_id": "d_...", "label": "..." }],
  "version": "xchk-v1",
  "findings": [
    {
      "kind": "contradiction",
      "explanation": "…",
      "a": { "document_id": "d_...", "node_id": "g2-c2", "statement": "…", "quote": "…", "page_no": 4, "span": {"start": 120, "end": 180} },
      "b": { "document_id": "d_...", "node_id": "g7-r1", "statement": "…", "quote": "…", "page_no": 27, "span": {"start": 40, "end": 130} }
    }
  ]
}

Gereksinim ve ucretlendirme: her belge tenant'iniza ait olmali ve mantik katmani uretilmis olmalidir (aksi halde 422 reasoning_not_available; bilinmeyen id icin 404 document_not_found). Cagri 1 ask sorgusu olarak ucretlendirilir (ayni oran, ayni throttle; 503 crosscheck_unavailable durumunda kredi dusulmez). Ayni yetenek Console'da Capraz Denetim sayfasinda ve MCP'de cross_check tool'u olarak da vardir.