LangChain ve LlamaIndex ile Yerel RAG Sistemi

Büyük dil modelleri eğitim verisinde görmemiş bilgileri ya hiç bilemez ya da eski bilgilerle yanıt verir. RAG (Retrieval-Augmented Generation, artırılmış üretim) bu sorunu, modelin yanıtlarını kendi belgelerinden çekilen pasajlara dayandırarak çözer. LangChain ve LlamaIndex, RAG hatlarını kurmayı standartlaştıran iki önde gelen Python çerçevesidir. Bu rehber, tamamen yerel bileşenlerle çalışan bir RAG sisteminin kurulumunu ve ayarlarını ele alır.

RAG Hattının Bileşenleri

Bir RAG hattı dört aşamadan oluşur. Yükleme: belgeler okunup metne dönüştürülür. Parçalama: uzun metinler, yönetilebilir parçalara bölünür. İndeksleme: her parça bir embedding modeliyle vektöre çevrilir ve vektör deposuna yazılır. Sorgu: kullanıcının sorusu vektöre çevrilir, depodan en benzer parçalar çekilir ve bu parçalar bağlam olarak LLM’e verilir. Sistemin kalitesi, her aşamanın ayrı ayrı ayarlanmasına bağlıdır; en güçlü model bile kötü parçalanmış belgelerden iyi yanıt üretemez.

Yerel kurgunun avantajı, bu dört aşamanın tamamının kendi donanımda çalışmasıdır: belgeler dışarı yüklenmez, model çağrıları ücretlendirilmez ve sistem çevrimdışı kullanılabilir.

Ön Koşullar

Yerel RAG düzeninin temel bileşeni Ollama’dır; hem üretici model hem embedding modeli buradan sağlanır. Kurulum öncesi Ollama’nın yüklü olması ve en az bir sohbet modeli ile bir embedding modelinin çekilmiş olması gerekir. Python 3.9 veya üzeri ve sanal ortam kullanımı önerilir. Embedding modeli küçük olsa da LLM bellek ihtiyacı model boyutuna göre belirlenir; 8B sınıfı model için 16 GB RAM veya 8 GB VRAM pratik eştir.

Ollama’da sohbet modeliyle birlikte embedding modeli de çekilir:

ollama pull llama3.1:8b
ollama pull nomic-embed-text

Kurulum Adımları

LlamaIndex ile Kurulum

1. Sanal ortamda gerekli paketler kurulur; çekirdek paket, Ollama entegrasyonu ve Chroma entegrasyonu birlikte eklenir.

pip install llama-index llama-index-llms-ollama llama-index-embeddings-ollama llama-index-vector-stores-chroma

2. Chroma istemci kütüphanesi kurulur.

pip install chromadb

3. Betikte Ollama, hem LLM hem embedding sağlayıcısı olarak tanımlanır; Settings nesnesi, çerçevenin tüm bileşenlerine bu ayarları dağıtır:

from llama_index.core import Settings, VectorStoreIndex, SimpleDirectoryReader
from llama_index.llms.ollama import Ollama
from llama_index.embeddings.ollama import OllamaEmbedding

Settings.llm = Ollama(model="llama3.1:8b")
Settings.embed_model = OllamaEmbedding(model_name="nomic-embed-text")

4. Belgeler okunup indekslenir ve sorgulanır:

documents = SimpleDirectoryReader("belgeler").load_data()
index = VectorStoreIndex.from_documents(documents)
query_engine = index.as_query_engine()
print(query_engine.query("Belgedeki ana konu nedir?"))

Bu akış, LlamaIndex’in resmî yerel RAG tarifine birebir uyar ve dakikalar içinde çalışan bir prototip üretir.

LangChain ile Kurulum

1. LangChain ve entegrasyon paketleri kurulur.

pip install langchain langchain-ollama langchain-chroma

2. Betikte Ollama LLM ve embedding’i, Chroma deposu ve belge yükleyici birleştirilir:

from langchain_ollama import ChatOllama, OllamaEmbeddings
from langchain_chroma import Chroma
from langchain_community.document_loaders import PyPDFLoader

llm = ChatOllama(model="llama3.1:8b")
embeddings = OllamaEmbeddings(model="nomic-embed-text")

3. Belgeler yüklenip parçalanarak depoya yazılır ve RAG zinciri kurulur.

LangChain’in gücü, bu zincirin ötesine geçen iş akışlarında ortaya çıkar: çok adımlı akışlar, ajanlar ve uygulama entegrasyonları aynı çatı altında kurulabilir.

Vektör Deposu Seçimi

Kişisel projelerde en pratik seçenek Chroma gibi gömülü depolardır; ayrı sunucu kurulumu gerektirmez, veriyi yerel klasörde tutar ve pip ile saniyeler içinde kurulur. Hacim büyüdüğünde veya çok kullanıcılı erişim gerektiğinde sunucu tabanlı çözümler öne çıkar: Qdrant hızlı filtreleme yetenekleriyle, Milvus ölçeklenebilirliğiyle, PGVector ise PostgreSQL altyapısını zaten kullanan ekiplerin veritabanını yeniden kurmadan kullanabilmesiyle öne çıkar. Seçim kriterleri dört başlıkta toplanır: veri hacmi, eşzamanlı erişim ihtiyacı, filtreleme gereksinimleri ve işletim yükünü üstlenecek kaynak. Prototipten üretime geçişte depoyu değiştirmek, çerçevelerin soyutlama katmanları sayesinde genellikle az kod değişikliği ister.

Embedding Modeli ve Kalite Ayarları

Yerel embedding için nomic-embed-text gibi küçük ve hızlı modeller standart tercih olmuştur; Türkçe içerik ağırlıklıysa çok dilli embedding modelleri denenmeli ve gerçek belgelerle karşılaştırılmalıdır. Parçalama ayarları kaliteyi en çok etkileyen değişkendir: parça boyutu çok küçükse bağlam kopuk, çok büyükse arama isabeti düşer; 500-1000 token civarı bir aralıkla başlanıp parça örtüşmesi eklenerek ince ayar yapılır. Sorgu aşamasında çekilecek parça sayısı (top-k) ayarı, bağlam penceresiyle denge kurulacak biçimde seçilir.

Değerlendirme için bir soru-cevap seti oluşturulup sistemin yanıtları elle denetlenmelidir; yanıttaki bilgi hangi parçadan geldiğinin gösterilmesi (kaynak atıfları) hem denetimi kolaylaştırır hem güvenilirliği artırır. Kaynak atıf desteği her iki çerçevede de hazır gelir; yanıta katkıda bulunan düğümlerin kaynak belgeleri sorgu motorundan istenebilir ve arayüzde yanıtın altında listelenebilir. Türkçe belgelerle çalışırken parçalayıcının cümle sınırı tanımına dikkat edilmelidir; noktalama farkları, parçaların beklenmedik yerlerde bölünmesine yol açabilir ve örtüşme oranı bu kaybı telafi eder. Ayrıca belge meta verilerinin (başlık, tarih, bölüm adı) parçalara taşınması, hem arama filtrelerini hem kaynak gösterimini güçlendirir.

Gelişmiş RAG Teknikleri

Temel hattı kurduktan sonra kaliteyi artıran bir dizi teknik devreye alınabilir. Hibrit arama, vektör benzerliğini anahtar kelime aramasıyla birleştirir; tam terim eşleşmelerinin (ürün kodları, tarihler, özel isimler) vektör aramasında kaybolmasını önler. Yeniden sıralama (reranking), vektör aramasından gelen ilk aday listesini daha güçlü bir modelle yeniden puanlayıp en ilgili parçaları başa taşır; küçük bir yerel yeniden sıralayıcı model, top-k sonucun kalitesini belirgin biçimde artırır.

Sorgu dönüştürme, kullanıcının sorusunu aramaya daha uygun biçimlere çevirir. Sorgu genişletme, tek soruyu birkaç alternatif sorguya bölerek taramayı genişletir; sorgu yeniden yazma, muğlak ifadeleri netleştirir; çok adımlı sorgulama, tek yanıttan çözülemeyen soruları alt sorulara ayırır. Bağlam sıkıştırma da pratik bir tekniktir: getirilen parçalarda soruya alakasız cümleler ayıklanarak LLM’in bağlam penceresi verimli kullanılır. Bu tekniklerin hiçbiri tek başına sihirli değildir; önce temel hattın parçalama ve arama ayarları sağlamlaştırılmalı, sonra ölçümle doğrulanarak teknikler tek tek eklenmelidir.

Üretime Taşıma

Prototipten üretime geçiş, teknik olmaktan çok işletme meselesidir. İlk başlık indeksleme boru hattının otomasyonudur: belgeler değiştikçe indeks güncellenmelidir; değişen belgenin yalnızca ilgili parçalarının yeniden işlenmesi, büyük kümede sürekli indekslemeyi ekonomik kılar. İkinci başlık gözlemdir: sorgu sayısı, gecikme, getirilen parçaların kullanım oranı ve model yanıt uzunluğu gibi ölçütler toplanmalıdır. Üçüncü başlık geri bildirim döngüsüdür; kullanıcıların yanıtları oylaması veya kaynak atıflarını incelemesi, kalite düşüşünü erken sinyaller.

Güvenlik ve gizlilik tarafında yerel RAG’ın temel vaadi korunmalıdır: belgeler ve sorgular dışarı gitmez. Ancak sistem internete açık hâle getiriliyorsa kimlik doğrulama katmanı eklenmeli, bilgi bankalarının erişim yetkileri kullanıcı bazında sınırlandırılmalıdır; aksi hâlde herkes her belgeye soru sorabilir. Versiyon yönetimi de üretime özgü bir konudur: embedding modeli değiştirildiğinde tüm indeks yeniden oluşturulmalıdır, çünkü eski vektörler yeni modelle sorgulanan vektörlerle aynı uzayda ölçülemez. Bu geçişlerin planlı yapılması, hizmet kesintisini önler. Son olarak kapasite: belge kümesi büyüdükçe vektör depo sunucusuna geçiş, model talebi büyüdükçe vLLM gibi yüksek verimli sunuculara geçiş, büyümenin doğal adımlarıdır.

Yaygın Hatalar ve İpuçları

En sık görülen hata, embedding modelinin indeksleme ile sorgu aşamasında farklı olmasıdır; depoya yazan ve depodan okuyan embedding aynı model olmalıdır, aksi hâlde arama anlamsız sonuç verir. İkinci hata, Ollama’nın çalışmamasıdır; bağlantı hatasında ollama list ile sunucunun ayakta ve modelin çekilmiş olduğu doğrulanır. Üçüncüsü, PDF yükleyicilerin tablo ve çok sütunlu sayfalarda düzgün metin çıkaramamasıdır; sorunlu belgeler için alternatif yükleyiciler denenmeli, çıkan metin elle örneklenerek denetlenmelidir.

Performans ipuçları olarak, indeksleme işleminin bir kez yapılıp diskte kalıcı hâle getirilmesi (Chroma’da persist dizini tanımlanması) her açılışta yeniden indekslemeyi önler; büyük belge kümelerinde indeksleme toplu olarak ve sakın bir saatte çalıştırılmalıdır. Sorgu gecikmesinin büyük kısmı LLM üretimindedir; modelin GPU’ya tam yüklendiğinden emin olmak, algılanan hızı belirgin artırır. Son olarak hem LangChain hem LlamaIndex hızla değişen paket yapısına sahiptir; entegrasyon paketleri ayrı sürümlendiği için sürümlerin birlikte test edilerek yükseltilmesi, kırılgan bağımlılık sorunlarını önler.