DS-50 — Çok-belgeli SSS Botu (metadata + değerlendirme)

Modül: RAG ve Vektör Veritabanları (ML-08) • Süre: 2-3 saat

🎯 Proje Senaryosu

Kurgusal bir kafe "Kahve Molası" için bir SSS botu kuruyorsun. Elinde birden çok belge var ve her biri bir KATEGORİ'ye ait: Menü, Saatler, Rezervasyon, Olanaklar, Ödeme. Kullanıcı doğal dille soruyor: "Kafe saat kaçta açık?", "Kart ile ödeme var mı?"

DS-49'da temel RAG hattını (parçala → embed → getir → cevap) kurdun. Bu projede bir adım öteye geçiyorsun:

• Metadata: her parçaya kategorisini taşırsın — böylece bir chunk'ın nereden geldiğini bilirsin.
• Metadata filtre: aramayı istenirse tek bir kategoriyle sınırlarsın (ör. sadece "Menü" içinde ara).
• Değerlendirme: sistemin ne kadar iyi getirdiğini ölçersin (hit-rate ve MRR) — "iyi çalışıyor gibi" demek yerine sayı verirsin.

Odak DS-49'dan farklı: burada iş metadata + ÖLÇÜM. LLM/cevap üretimi yok; retrieval'ın kalitesine odaklanıyorsun.

🧩 Kuracağın Hat

1. load_belgeler — ~5 belge, her biri {"baslik", "kategori", "metin"}
2. parcala / chunkla_belgeler — overlap'li böl, her parçaya kaynak + kategori ekle
3. benzerlik — iki vektör arası cosine (elle)
4. indeksle — her parçayı embed et
5. getir — soruya en yakın top-k parça; kategori verilirse sadece o kategoride ara (metadata filtre)
6. degerlendir — küçük bir gold set üzerinden hit-rate ve MRR hesapla

📏 Değerlendirme Nedir? (önemli)

gold = (soru, doğru_kategori) ikilileri. Her soru için getir çalıştırıp dönen chunk'ların kategorilerine bakarsın:

• Hit-rate: doğru kategori ilk k sonuç içinde geçen soruların oranı. "Kaç soruda doğru yeri buldu?"
• MRR (Mean Reciprocal Rank): doğru kategorinin ilk göründüğü sıranın tersi (1. sıradaysa 1.0, 2. sıradaysa 0.5...). Ortalaması. "Doğru yeri ne kadar üste koydu?"

İkisi de 0-1 arası. Bu metrikler retrieval sistemlerini kıyaslamanın standart yoludur.

🔌 embed Nasıl Çalışıyor? (önemli)

Fonksiyonların embed'i parametre olarak alır (dependency injection):

• embed: metin (str) → sayı listesi (vektör). Gerçekte sentence-transformers ya da OpenAI embedding.
• Testlerde deterministik sahte embed verilir → API key GEREKMEZ, puan hep aynı.
• Bu projede LLM/cevap üretimi yok — odak retrieval + metadata + ölçüm.

Aynı kod, sadece verdiğin fonksiyon değişir — bu, test edilebilir RAG kodu yazmanın profesyonel yoludur.

📦 Kurulum

python -m venv venv
source venv/bin/activate        # Windows: venv\Scripts\activate
pip install -r requirements.txt

python watch.py                 # otomatik test (dosya değişince)
# veya
pytest tests/test_question.py -v

🔑 Kaizu Bağlantısı — kaizu_config.py

USER_ID'ni Kaizu profilinden alıp yaz (PROJECT_ID'ye dokunma). Testler geçince skor otomatik gider.

🔑 API key? (opsiyonel)

Puanlama için gerekmez (mock). Gerçek embed ile denemek istersen cp .env.example .env + anahtarını koy (.env asla commit edilmez).