Yerelde RAG Asistanı Kurulumu: Python, FAISS ve FastAPI ile Adım Adım

RAG nedir ve neden yerelde kurmalısınız?

RAG (Retrieval-Augmented Generation), bir büyük dil modelinin (LLM) yanıt üretmeden önce kendi veritabanınızdan veya belgeliklerinizden ilgili parçaları çekmesini sağlayan bir yaklaşım. Böylece model, güncel ve doğrulanabilir bilgiye dayanarak cevap verir, halüsinasyon oranı düşer ve alanınıza özgü bir asistan elde edersiniz. Bu yazıda, internete kapalı bir ortamda, Python, FAISS ve FastAPI kullanarak hızlı ve hafif bir RAG asistanını nasıl kurabileceğinizi adım adım anlatıyorum.

Mimari bileşenler ve gereksinimler

Minimal bir RAG sistemi dört temel bileşenden oluşur: metin ön işleme ve parçalara ayırma, embedding üretimi, vektör dizin (FAISS) ve yanıt üretici (LLM). Yerel kurulum için Python 3.10+ bir ortam, sentence-transformers ile çok dilli bir embedding modeli, faiss-cpu dizini ve HTTP üzerinden istek alıp yanıtlamak için FastAPI yeterli. İsterseniz yanıt üretici olarak Ollama üzerinden Llama 3 ailesi gibi bir yerel modeli kullanabilir, ya da sisteminize uygun bir başka LLM’i bağlayabilirsiniz.

Kurulum adımları: ortam, paketler ve veri hazırlığı

Önce izole bir Python sanal ortamı oluşturun ve temel paketleri kurun. Gerekli çekirdek paketler tipik olarak fastapi, uvicorn, faiss-cpu, sentence-transformers, pydantic ve metin işleme için regex/unidecode gibi küçük yardımcılar olur. Eğer yerel bir model kullanacaksanız Ollama’yı yükleyip örneğin “llama3” veya “mistral” gibi bir modeli indirin. Belgelerinizi tek bir klasörde toplayın; PDF, DOCX ve düz metinleri mümkünse metne dönüştürüp temizleyin. Tekrarlayan başlıklar, sayfa dipnotları ve tablolar metni kirlettiği için önceden sadeleştirme yapmak ileride kaliteyi ciddi biçimde artırır.

Embedding üretimi ve FAISS ile dizinleme

RAG’in çekirdeği, metni anlam uzayına taşıyan embedding’lerdir. Türkçe ağırlıklı bir kurulum için çok dilli bir model seçmek pratik olur. intfloat/multilingual-e5-base veya sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2 iyi başlangıç seçenekleridir. Belgeleri 500–800 karakter aralığında, 50–100 karakter örtüşmeli parçalara bölerseniz hem hatırlama oranı hem bağlam bütünlüğü dengelenir. Her parçayı embedding modelinden geçirip bir vektör matrisi üretin; ardından FAISS’te IndexFlatIP (cosine benzeri iç çarpım) veya daha büyük veri için HNSW/IVF tabanlı bir dizin kurun. Dizin ve meta verileri (ör. belge kimliği, başlık, sayfa numarası) disk üzerinde saklayarak soğuk başlatma sürelerini azaltabilirsiniz.

Sorgu işleme hattı: geri getirme, yeniden sıralama ve yanıt üretimi

İstemci bir soru sorduğunda önce soruyu embedding modellerinden geçirip FAISS’e benzerlik araması yapın. İlk aşamada genellikle top-k=5–8 yeterlidir. Sonuçları kalite için hafif bir yeniden sıralama (re-rank) aşamasından geçirmek özellikle uzun ve benzer parçalarda fark yaratır; isterseniz küçük bir cross-encoder veya basit bir skor birleştirme (benzerlik + anahtar kelime çakışması) yaklaşımı kullanın. Son olarak en iyi 3–5 parçayı bir prompt şablonunda LLM’e vererek yanıt üretin. İyi bir şablon, modele “yalnızca verilen bağlama dayanması”, “kaynakları listelemesi” ve “emin olmadığı noktalarda netçe belirtmesi” yönünde talimatlar içerir. Bu aşamada streaming yanıt (chunk bazlı) hem his olarak daha hızlıdır hem de istemci tarafında kullanıcı deneyimini iyileştirir.

FastAPI ile uç noktalar ve basit bir API tasarımı

Sunucu tarafında iki temel uç nokta yeterlidir: /index ve /query. İlk uç nokta yeni belge eklemeyi, embedding ve dizine yazmayı üstlenir. İkincisi kullanıcı sorusunu alır, geri getirme ve yeniden sıralama yapar, LLM’den gelen yanıtı döndürür. Yanıta kaynak parçaların kimliklerini ve güven puanlarını dahil ederseniz istemci tarafında “bu cevabın kanıtı” şeritleri gösterebilirsiniz. Üretim ortamında CORS ayarlarını, basit bir oran sınırlama (rate limit) ve temel kimlik doğrulamayı eklemeyi unutmayın.

Performans, kalite ve bakım ipuçları

İlk indekslemeyi hızlandırmak için toplu gömme (batch) boyutunu donanımınıza göre ayarlayın; CPU’da 16–64 arası genelde güvenlidir. Dizin aramasında hız/kalite dengesini sağlamak üzere IVF ya da HNSW gibi yaklaşık yakın komşu (ANN) yapılarını deneyin ve geri getirme anında efSearch benzeri parametreleri kademeli artırın. Kalite için chunk boyutu ve örtüşmesini alanınıza göre yeniden ayarlayın; teknik dökümanlarda daha uzun, SSS türü içerikte ise daha kısa parçalar daha iyi sonuç verir. Ayrıca yinelenen metinleri, versiyonlanmış kopyaları ve tarih geçmişlerini indeks dışında tutmak, cevapların tekrara düşmesini engeller.

Düzenli bir değerlendirme seti oluşturun: 30–50 soruluk, doğru cevap ve kaynak eşleşmesi içeren bir küçük benchmark ile sürümler arasında regresyon olup olmadığını görebilirsiniz. Ölçüt olarak geri getirme için recall@k, cevap üretimi için ise doğruluk, faydalılık ve kaynak isabetini manuel etiketleme ile kontrol etmek etkilidir. Basit bir geri bildirim mekanizması (kullanıcı oylaması, “yanlıştı/düzelt” düğmesi) gerçek kullanımda iyileştirme fırsatlarını hızla ortaya çıkarır.

Güvenlik, gizlilik ve dağıtım

Yerel RAG sistemleri çoğu zaman hassas verilerle çalışır. Bu nedenle PII tespiti ve maskeleme, uçtan uca TLS, erişim loglarının minimal ve anonim tutulması önemlidir. Küçük bir ek katman olarak belirli sorgulara kural tabanlı filtre uygulayabilir, gizli etiketli içerikleri yanıt bağlamına girmeden önce temizleyebilirsiniz. Dağıtım için hafif bir konteyner imajı, tek bir health-check uç noktası ve kalıcı depolama bağlanmış bir FAISS dizini çoğu ekip için yeterli, ölçeklenebilir ve sürdürülebilir bir başlangıç sunar.

Sonuç

Python, FAISS ve FastAPI ile yerelde çalışan bir RAG asistanı kurmak sanıldığından daha erişilebilir. Doğru embedding modeli, düzenli bir parçalara ayırma stratejisi ve iyi tasarlanmış bir prompt ile, alanınıza özel, hızlı ve güvenilir bir bilgi asistanına sahip olursunuz. İlk sürümü basit tutun, kullanım verisi geldikçe yeniden sıralama ve değerlendirme mekanizmasını güçlendirin; böylece hem maliyeti hem karmaşıklığı kontrol altında tutarken yüksek kaliteli cevaplar üreten bir sistem inşa edebilirsiniz.

Yerelde RAG Kurulumu: Ollama ve FAISS ile Belgelerinizden Akıllı Arama

RAG nedir, neden yerel çalıştırmalıyım?

Büyük dil modelleri etkileyici cevaplar üretebiliyor ancak kaynaklara dayanmayan “halüsinasyon” üretme eğilimleri var. Retrieval-Augmented Generation (RAG), modelin yanıtlarını gerçek belgelerinizden çekilen parçalarla destekleyerek bu sorunu azaltır. Yerel RAG, tüm süreci bilgisayarınızda çalıştırarak gizlilik, düşük gecikme ve maliyet avantajı sağlar. Bu yazıda Ollama + FAISS ikilisiyle, PDF’leriniz, notlarınız veya wiki sayfalarınız üzerinde çalışan pratik bir yerel RAG kurulumunun yolunu göstereceğim.

Mimari bileşenler

1) LLM (Yanıtlayıcı): Yerelde çalıştırmak için Ollama üzerinden Llama 3, Mistral veya benzeri açık modellerden birini seçebilirsiniz. Kuantize edilmiş sürümler (ör. Q4_K_M) düşük donanımda bile kabul edilebilir hız sunar.

2) Vektörleştirici (Embedding): Metni sabit boyutlu vektörlere dönüştürür. Türkçe desteği güçlü olan bge veya e5 tabanlı modeller iyi sonuç verir. Embedding modeli LLM’den ayrı olabilir; bu esneklik performansı artırır.

3) Vektör Veritabanı (FAISS): Belgelerinizin vektörlerini indeksleyip en benzer parçaları hızla getirir. FAISS hafif, açık kaynak ve yerel kurulum için idealdir.

4) Orkestrasyon: Basit bir RAG için ek çerçeve şart değil. Sıra; sorguyu vektörleştir, FAISS’ten en yakın doküman parçalarını getir, bu parçaları bağlam olarak LLM’e ver ve yanıtı oluştur şeklinde ilerler. İsterseniz LangChain veya LlamaIndex kullanabilirsiniz; ancak bu yazı minimal ve anlaşılır yaklaşımı tercih ediyor.

Adım adım kurulum

Önkoşullar: 8–16 GB RAM, modern bir CPU yeterli. GPU varsa daha hızlı olur. İşletim sistemi olarak macOS, Windows (WSL dahil) veya Linux uygundur.

1) Ollama’yı kurun: Ollama resmi sitesinden sisteminize uygun kurulum paketini indirin ve kurun. Terminalde “ollama run llama3” gibi bir komutla modeli test edebilirsiniz. İlk çalıştırmada model indirilecektir.

2) Embedding modelini hazırlayın: Python ortamı kurup sentence-transformers gibi bir kütüphane ile bge veya e5 tabanlı çok dilli bir modeli indirin. Türkçe metinler için bu aileler genellikle dengeli sonuç verir. Üretimde aynı tokenizer ve model sürümünü koruyarak tutarlılık sağlayın.

3) Belgeleri içe aktarın ve parçalara bölün: PDF, Markdown veya HTML kaynaklarınızı metne dönüştürün. Chunking stratejinizi belirleyin: 400–800 kelime aralığı ve %10–20 örtüşme (overlap) çoğu senaryo için iyi bir başlangıçtır. Başlık, bölüm, sayfa numarası gibi meta verileri saklamayı unutmayın.

4) FAISS ile indeks oluşturun: Her parçayı embedding modele verip vektörünü alın ve FAISS’e ekleyin. Büyük veri için IVF+PQ gibi yapılandırmalar disk ve bellek kullanımını dengeler. Küçük veri setlerinde düz L2 veya kosinüs benzerliği yeterli olur.

5) Sorgu akışı: Kullanıcı sorusunu embedding’e çevirin, FAISS’ten top-k (ör. k=5) en yakın parçayı çekin. Bu parçaları bir “bağlam” şablonunda birleştirip Ollama’ya aktarın. Prompt içinde “Sadece aşağıdaki bağlamdan yararlan” gibi net yönergeler verin. Yanıtı kaynak bağlantılarıyla birlikte sunmak güven yaratır.

6) Hafif bir API ekleyin: FastAPI gibi bir çerçeveyle tek uç noktalı bir servis hazırlayabilirsiniz. İstek geldiğinde sorguyu vektörleştirir, FAISS’ten bağlamı getirir, Ollama’ya iletir ve akışlı yanıtı geri döndürür. Böylece masaüstü, web veya mobil istemciler kolayca entegre olur.

7) Değerlendirme ve iyileştirme: Kaliteyi ölçmek için sık sorulan 20–30 soruluk bir test seti hazırlayın. Cevap doğruluğu, kaynak kapsama (coverage) ve ilk token gecikmesi gibi metrikleri izleyin. Top-k, chunk boyutu, MMR (çeşitlilik odaklı getirme) ve sıcaklık (temperature) ayarlarını kademeli değiştirerek A/B testleri yapın.

Performans ve pratik ipuçları

Kuantizasyon: LLM’i Q4 seviyesinde çalıştırmak performans/kalite dengesini iyileştirir. CPU’da dahi kabul edilebilir yanıt hızları elde edilir.

Prompt mühendisliği: Türkçe bağlam sağladığınızda, talimatları da Türkçe verin. “Kaynaklardan alıntı yap, emin değilsen belirt” gibi yönlendirmeler halüsinasyonu azaltır.

Önbellekleme: Sık soruların embedding ve arama sonuçlarını disk üzerinde önbelleğe alın. Bu, hem gecikmeyi hem de CPU yükünü düşürür.

Filtreler: FAISS yanında meta veri filtreleri tutarak tarih, yazar, kategori gibi sınırlamalarla daha doğru sonuçlar alabilirsiniz.

Türkçe desteği: Embedding modelinin Türkçe kapsaması kritiktir. İlk denemelerde Türkçe/multilingual modelleri karşılaştırın; bazen küçük ama iyi eğitilmiş bir embedding modeli büyük bir fark yaratır.

Gizlilik, güvenlik ve bakım

Yerel RAG’in en büyük artısı, belgelerinizin makine dışına çıkmamasıdır. Yine de PII içeren veri setlerini şifreli depolamak, cihazınızda tam disk şifreleme kullanmak ve indeks dosyalarına erişimi kısıtlamak önemlidir. Modelleri ve bağımlılıkları düzenli güncelleyin; embedding modelini değiştirdiğinizde indeksinizi yeniden oluşturmanız gerektiğini unutmayın.

Sorun giderme

İndeks tutarsızlığı: Farklı embedding model veya sürüm değişikliği, alakasız sonuçlar doğurur. Tek sürüm standardı belirleyin.

Dil karışması: Çok dilli veri setlerinde karışık diller zayıf eşleşmeye yol açabilir. Belgeleri dil bazında ayrı indekslemek kaliteyi yükseltir.

Kaynak tüketimi: RAM yetmiyorsa daha agresif chunking veya IVF+PQ yapılandırmasına geçin. LLM tarafında daha küçük bir model deneyin.

Sonuç

Ollama ve FAISS ile kurulan yerel RAG, gizliliğe duyarlı ortamlarda hızlı ve güvenilir bir bilgi erişim katmanı sunar. Doğru embedding seçimi, iyi bir chunking stratejisi ve disiplinli değerlendirmeyle; şirket içi dokümantasyondan akademik arşivlere kadar pek çok kullanım senaryosunda arama ve soru-cevap kalitesini belirgin biçimde artırabilirsiniz. Küçük adımlarla başlayın, metriklerle ölçün ve yapı taşlarını gerektikçe büyütün; kısa sürede günlük iş akışınızda fark yaratacaktır.

RAG Tabanlı Kendi Yapay Zekâ Asistanınızı Kurun: LangChain ve LlamaIndex ile Adım Adım Rehber

Üretken yapay zekâ (GenAI) uygulamaları hızla yaygınlaşırken, doğru ve güncel bilgiye dayalı yanıtlar üretmek için en çok konuşulan yaklaşım RAG (Retrieval-Augmented Generation) oldu. Bu yazıda, RAG nedir, hangi durumlarda kullanılır, hangi araçları tercih etmelisiniz ve LangChain ile LlamaIndex kullanarak nasıl adım adım bir RAG hattı (pipeline) kurabilirsiniz sorularına pratik ve güncel bir rehberle yanıt vereceğim.

RAG nedir ve neden önemli? Klasik büyük dil modelleri yalnızca eğitim verisiyle sınırlıdır ve güncelliği hızla kaybedebilir. RAG, modelin yanıt üretmeden önce bir vektör veritabanından ilgili belgeleri geri çağırmasını (retrieval) sağlar. Bu sayede hem güncel hem de şirket içi özel bilgilere dayalı doğru, kaynaklı ve denetlenebilir yanıtlar üretirsiniz. Özellikle doküman asistanları, müşteri destek botları, teknik bilgi tabanı arayüzleri ve kurumsal arama projelerinde RAG çok etkili bir çözümdür.

Gereksinimler ve genel mimari Basit bir RAG hattı için üç bileşen gerekir: (1) Metinlerinizi parçalara (chunk) ayırıp sayısal vektörlere dönüştüren bir gömme (embedding) modeli; (2) Bu vektörleri saklayıp benzerlik araması yapan bir vektör veritabanı; (3) Geri çağrılan metinleri kullanıp yanıt üreten bir LLM. Ek olarak, yeniden sıralama (reranking), sorgu genişletme (query expansion) ve değerlendirme (eval) katmanlarıyla kaliteyi artırabilirsiniz.

Vektör veritabanı seçimi Başlangıç için gömülü ve kurulumu kolay Chroma iyi bir seçenek. Hafif, hızlı ve yerelde deney yapmak için ideal. FAISS, tek makinede yüksek performanslı aramalar için tercih edilebilir. Üretim ortamlarında ise Pinecone, Weaviate, Qdrant gibi servisler ölçeklenebilirlik ve yönetim kolaylığı sunar. Seçimde verinizin büyüklüğü, gecikme ihtiyaçları, bütçe ve regülasyon gereksinimlerini dikkate alın.

Embedding modeli seçimi Ücretli ve yüksek kaliteli bir seçenek arıyorsanız OpenAI’nin text-embedding-3-large modeli güçlü bir taban sunar. Açık kaynak tarafta bge-large, e5-large veya instructor-xl aileleri yaygın ve iyi sonuç veriyor. Türkçe performansı kritikse çok dilli destek sunan modelleri tercih edin ve mümkünse küçük bir doğrulama kümesi üzerinde kısa bir A/B testi yapın.

Parçalama stratejisi (chunking) Parça boyutu ve bindirme (overlap) kaliteyi doğrudan etkiler. 300–800 karakter aralığı genelde güvenli bir başlangıçtır; teknik belgelerde 1000–1500 karaktere çıkmak bağlam bütünlüğünü korumaya yardımcı olabilir. 10–20% arası bindirme, cümlelerin iki parça arasında bölünmesini yumuşatır.

LangChain ile hızlı başlangıç

LangChain, veri yükleme, parçalama, embedding, vektör dizinleme ve sorgulama adımlarını modüler şekilde birleştirmenizi kolaylaştırır. Pratik akış şu şekildedir: Belgeleri yükleyin, metinleri parçalara ayırın, embedding üretin, Chroma’ya kaydedin, ardından bir RetrievalQA zinciri oluşturun. Örnek kurulum adımı olarak komut satırında pip install langchain chromadb sentence-transformers komutunu kullanabilirsiniz. Basit bir sorgu akışı ise şu mantıkta ilerler: retriever.get_relevant_documents(soru) ile ilgili parçaları alın, ardından llm.invoke(prompt + bağlam) ile yanıt üretin. LangChain’in Runnable ve LCEL (LangChain Expression Language) soyutlamaları, üretim ortamında gözlemlenebilir, loglanabilir ve test edilebilir zincirler kurmayı kolaylaştırır.

Artıları: Zengin entegrasyon ekosistemi, güçlü zincir soyutlamaları, hızlı prototipleme. Eksileri: Çok modüllü yapı karmaşıklığa yol açabilir; versiyon uyumluluğuna dikkat etmek gerekir.

LlamaIndex ile belgeden yanıta

LlamaIndex, endekse odaklı bir tasarım sunar ve doküman odaklı akışlarda sade bir deneyim sağlar. Document ve Node yapılarıyla parça yönetimi şeffaftır; ServiceContext ile LLM ve embedding ayarlarını merkezi olarak kontrol edersiniz. Özet akış şudur: Belgeleri okuyun, VectorStoreIndex oluşturun, ardından query_engine veya chat_engine üzerinden sorgulayın. Basit bir kurulum için pip install llama-index chromadb yeterlidir. LlamaIndex ayrıca reranker ve response synthesizer yapılarıyla çıktı kalitesini artırmak için gömülü seçenekler sunar.

Artıları: Doküman merkezli tasarım, hızlı “belgeden yanıta” kurulum, iyi dokümantasyon. Eksileri: Çok özel iş akışlarında esneklik için ek özelleştirme gerekebilir; bazı ileri seviye özellikler sürümlere göre değişebilir.

Kaliteyi artırma teknikleri

Sorgu genişletme: Kullanıcının kısa sorusunu, olası eşanlamlılar ve bağlamla zenginleştirerek arama kalitesini artırabilirsiniz. RAG-Fusion veya çoklu sorgu tekniğiyle farklı varyantları arayıp birleştirmek iyi sonuç verir.

HyDE (Hypothetical Document Embeddings): Modelden, soruya dair “varsayımsal bir cevap” üretmesini isteyip bunu embedding’e çevirerek arama yapın; özellikle belgenin dili ile soru dili farklı olduğunda işe yarar.

Yeniden sıralama (Reranking): İlk 10 sonucu aldıktan sonra bir reranker modeliyle en iyi 3–5 sonucu seçin. Açık kaynak bge-reranker veya bulut tabanlı hizmetler (ör. Cohere Rerank) yaygın tercih edilir.

İstem (prompt) şablonları: Kaynakları listelemeyi zorunlu kılan, halüsinasyonu azaltan net yönergeler kullanın. Örnek: “Yanıtlarken yalnızca verilen bağlamı kullan. Emin değilsen ‘Bu bilgi bağlamda yok’ de. En sonda kullandığın kaynak başlıklarını sırala.”

Değerlendirme ve gözlemlenebilirlik

RAG projelerinde değerlendirme kritik önemdedir. Küçük ama temsil gücü yüksek bir test seti oluşturun. Doğruluk, alaka, kaynak kapsamı, yanıt uzunluğu ve gecikme gibi metrikleri izleyin. RAGAS gibi değerlendirme çerçeveleri yararlıdır. Üretimde ise isabet oranı, geri çağırma (recall), oturum başına iyi yanıt oranı ve kullanıcı memnuniyeti (thumbs up/down) gibi iş metriklerini takip edin.

Güvenlik, maliyet ve gizlilik

Kurumsal verilerle çalışırken erişim kontrolü, PII maskeleme ve denetim kayıtları (audit logs) şarttır. Maliyet tarafında embedding üretimi ve vektör arama en büyük kalemler olabilir; partisyonlama, sıkıştırma (PQ/IVF) ve önbellekleme ile maliyeti düşürün. Gizlilik gereksinimi yüksekse açık kaynak embedding ve yerel vektör veritabanı ile tamamen şirket içi (on-prem) kurulum yapılabilir.

Sonuç RAG, üretken yapay zekâyı pratik ve güvenilir hale getiren güçlü bir yöntemdir. Hızlı prototipleme için LangChain ve LlamaIndex iki sağlam seçenektir: İlki geniş entegrasyonları ve zincir mimarisiyle esneklik sunarken, ikincisi doküman odaklı basitliğiyle hızlı değer üretir. Doğru embedding, uygun vektör veritabanı, dikkatli chunking ve iyi bir değerlendirme disipliniyle kısa sürede, şirket verinizle konuşabilen sağlam bir asistan inşa edebilirsiniz.