rag-assistant

Problem

Dökümanlara soru sormanın yaygın yolu, dökümanı bir bulut API'sine göndermekten geçiyor. Burada tersini kurmak istedim: ilk model indirmesinden sonra internet, API anahtarı ve bulut olmadan çalışan, her cevabı hangi dosyadan geldiğini söyleyerek veren bir döküman soru-cevap asistanı. İkinci kısıt öğretilebilirlik: depo aynı zamanda RAG'i sıfırdan kuran altı haftalık bir plan (docs/one_month_plan.md) ve haftalık alıştırmalar (examples/) içeriyor, yani kod hem çalışan bir sistem hem ders materyali olmak zorundaydı.

Yaklaşım

Beş katmanlı, dosya sınırları net bir yapı kurdum: arayüz (ui_streamlit.py / main.py) → uygulama (generation.answer_query) → geri getirme (retrieval.get_top_chunks) → veri (SQLite rag.db, db.py) → yapay zekâ (foundry_client). İki akış var. Ingest tek seferlik: data/*.md okunur, chunk_text() ile paragraf temelli parçalanır, her parça embedding'e çevrilir ve JSON metni olarak SQLite'a yazılır; tüm ingest tek transaction içinde döner ki yarıda çökerse veritabanı yarım kalmasın. Sorgu akışı: soru embed edilir, saklı her vektörle cosine similarity hesaplanır, en iyi 3 parça alınır, skor eşiğini geçerse prompt kurulup cihaz üzerindeki modele sorulur. Eşik geçilmezse model hiç çağrılmaz — uydurma cevabın en ucuz önlemi soruyu modele hiç sormamak.

Kararlar ve takaslar

• 01Vektör veritabanı yerine ham kuvvet cosine similarity seçtim, çünkü 5-10 dökümanlık bir bilgi tabanında sorgu vektörünü saklı her vektörle Python'da karşılaştırmak yeterince hızlı ve sıfır ek bağımlılık istiyor; alternatif ayrı bir vektör DB'si ya da SQLite vektör eklentisiydi — depo notlarına göre o ancak birkaç bin parçanın üstünde gerekli hale geliyor.
• 02SDK'ya dokunan tek dosya kuralı koydum (foundry_client.py), çünkü Foundry Local SDK'sının embedding cevap şekli sürümler arasında değişiyor ve bunu tek bir _extract_embedding fonksiyonunda soğurmak istedim; alternatif her modülün SDK'yı doğrudan import etmesiydi, o zaman bir sürüm değişimi dört dosyayı birden kırıyordu.
• 03Chat modeli olarak qwen2.5-1.5b'de karar kıldım, çünkü depo notlarına göre qwen2.5-0.5b daha hızlıydı ama Türkçede zayıf kaldı, phi-3.5-mini ise CPU'da cevap başına yaklaşık iki dakika sürdü; alternatifler bunlardı ve 1.5B ölçüsü hız ile kalitenin kesiştiği yer oldu. Her iki model de açılışta bir kez yüklenir (warm-up), böylece ilk soru diğerleri kadar hızlı cevaplanır.
• 04Kısa parçaları komşusuyla birleştirdim (MIN_CHARS=150), çünkü "## Başlık" ya da tek kod satırı gibi kısa metinlerin embedding'i çok odaklı olduğu için üst sıraya çıkıyor ama bilgi taşımıyor; alternatif sabit pencereli bölmeydi, o retrieval'ın ilk sırasını başlıklarla dolduruyordu.
• 05Modelin "bilmiyorum" demesini, talimatı tekrar etmesinden ayrı ele aldım: talimat tekrarı (ECHO_MARKERS) güvenilmez sayılıp en iyi pasajla değiştirilir, gerçek ret (REFUSAL_MARKERS) ise saygı görüp tek biçimli fallback cümlesine çevrilir — yalnızca retrieval çok güçlüyken (STRONG_SCORE=0.60) pasaj kaynağıyla gösterilir. Alternatif her tatmin etmeyen cevabı en iyi chunk ile ezmekti; o meşru "bilgim yok" cevabını da yok ediyordu.

Sonuç

Depoda kayıtlı ölçüm var: eval/results.md, 2026-07-27 00:28 koşumu — 26 test sorusunun 22'si geçti, 4'ü kaldı, soru başına ortalama 44.53 saniye. Cevaplanamaz dört sorunun dördü de doğru şekilde "bilgim yok" fallback'ine düştü; dört kenar durumu (boş girdi, tek kelime, çok genel soru, çok uzun soru) çökmeden işlendi. Kalan dört hatanın niteliği önemli: dördün üçü anahtar-kelime eşleşmesi hatası; dördüncüsü gerçek bir arıza — 15. soruda cevap dökümanlarda varken sistem fallback döndü (README bunu ayrı bir zayıf nokta olarak yazıyor) — model donanım hızlandırmayı "GPU" kelimesini kullanmadan anlatıyor, eşiği "0.45" sayısını alıntılamadan açıklıyor. Yani bu bir anahtar-kelime kontrolü, insan değerlendirmesi değil; README bunu bilinen zayıf nokta olarak listeliyor ve çözüm olarak soru başına birden çok kabul edilebilir anahtar kelime ya da ikinci bir model turuyla notlama öneriyor. Ölçümün yapıldığı donanım raporda belirtilmemiş, o yüzden 44.53 saniyeyi bir donanım iddiasına çevirmiyorum.

Teknolojiler