LlamaIndex Nasıl Kullanılır: Sıfırdan Üretime Pratik Bir Kılavuz
Eğer daha önce bir retrieval-augmented generation (RAG) uygulaması oluşturmaya çalıştıysanız ve “Gömme (embedding) işlemleri, vektör depoları ve istemleri bağlamak neden bu kadar karmaşık?” diye düşündüyseniz, yalnız değilsiniz. , bu hattı hızlı, mantıklı ve üretime hazır hale getirmek için var. Bu pratik, çözüm odaklı kılavuzda, 'i uçtan uca nasıl kullanacağınızı (veri alımı, indeksleme, sorgulama, değerlendirme ve dağıtım) adım adım göstereceğiz, böylece tutkal kodunda kaybolmadan güvenilir bir şeyler gönderebilirsiniz.
Aşamalı adımlar, çalıştırılabilir kod parçacıkları ve gerçek dünya ipuçlarıyla soru odaklı bir yapı kullanacağız. İster dahili belgeler için bir sohbet robotu prototipi oluşturuyor, ister müşteriler için bir bilgi asistanı dağıtıyor olun, 'i etkili bir şekilde nasıl kullanacağınızı öğrenmek size günler kazandıracaktır.
: , verilerinizi indeksleme, erişim ve düzenleme araçlarıyla büyük dil modellerine bağlamanıza yardımcı olan bir çerçevedir. RAG, agent'lar ve yapılandırılmış çıktılar için idealdir.
Nedir ve Neden Kullanılır?
- LlamaIndex, LLM uygulamaları için bir veri çerçevesidir. Aşağıdakiler için yapı taşları sağlar:
- Alım (Ingestion): Dosyaları, web sayfalarını, veri tabanlarını ve API'leri yükleyin.
- Parçalama ve İndeksleme: Ham içeriği sorgulanabilir yapılara dönüştürün (vektör, anahtar kelime, grafik indeksleri).
- Erişim (Retrieval): Esnek stratejilerle (BM25, hibrit, yeniden sıralama) bağlamı alın.
- Sorgu Motorları ve Agent'lar: Erişim, araçlar ve istemleri tutarlı bir Soru-Cevap deneyiminde birleştirin.
- Değerlendirme ve İzleme: Erişim kalitesini ve yanıt alaka düzeyini değerlendirin.
- LlamaIndex ne zaman kullanılır:
- Parçalama, gömme ve erişimi yeniden icat etmeden sağlam bir RAG yığını istiyorsunuz.
- Birden çok veri kaynağını (PDF'ler + Notion + SQL) birleştirmeniz gerekiyor.
- Hibrit erişim, yeniden sıralama veya yapılandırılmış çıktılarla deneme yapmak istiyorsunuz.
- LlamaIndex LlamaIndex'i nasıl kullanacağınızı öğrenirken:
- Veri → Düğümler → İndeks → Erişimci → Sorgu Motoru → Uygulama
Hızlı Başlangıç: Minimum RAG Döngüsü
Bu, çalışan bir prototipe ulaşmanın en hızlı yoludur. Belgeleri yükleyeceğiz, bir vektör indeksi oluşturacağız ve sorular soracağız.
# 1) Yükleyin
# pip install llama-index llama-index-embeddings-openai llama-index-llms-openai
import os
from llama_index.core import VectorStoreIndex, SimpleDirectoryReader
from llama_index.embeddings.openai import OpenAIEmbedding
from llama_index.llms.openai import OpenAI
# 2) Modelinizi + gömmelerinizi yapılandırın
os.environ["OPENAI_API_KEY"] = "YOUR_KEY" # veya desteklenen herhangi bir LLM/gömme sağlayıcısını kullanın
llm = OpenAI(model="gpt-4o-mini")
embed_model = OpenAIEmbedding(model="text-embedding-3-small")
# 3) Belgeleri yükleyin (örn., ./data/*.pdf, .md, .txt)
docs = SimpleDirectoryReader("./data").load_data
# 4) Bir indeks oluşturun
index = VectorStoreIndex.from_documents(docs, embed_model=embed_model)
# 5) Bir sorgu motoru oluşturun ve bir soru sorun
query_engine = index.as_query_engine(llm=llm)
response = query_engine.query("Belgelerde bahsedilen temel güvenlik uygulamaları nelerdir?")
print(response)
İşin özü bu. Buradan itibaren, gerçek uygulamalar daha iyi parçalama, yeniden sıralama, yapılandırılmış istemler ve gözlemlenebilirlik ekler.
Alım: Kendi Verinizi Getirin (BYOD) Doğru Şekilde
'i gerçek veriler için nasıl kullanacağınıza karar verirken, kaynaklarınıza uygun ve yapıyı koruyan yükleyicileri seçin.
- Dosyalar:
SimpleDirectoryReader, PDF/HTML/Markdown okuyucuları
- Web:
BeautifulSoupWebReader, site haritası okuyucuları
- SaaS: Notion, Confluence, Slack, Google Drive (bağlayıcılar aracılığıyla)
- Veri tabanları: SQL ve vektör DB'leri (Pinecone, Weaviate, Chroma, Elasticsearch)
- İpucu: Meta verileri normalleştirin (başlık, yazar, URL, created_at). İyi meta veriler, daha sonra yeniden sıralamayı ve filtrelemeyi süper şarj eder.
from llama_index.core import SimpleDirectoryReader
from llama_index.readers.web import SimpleWebPageReader
file_docs = SimpleDirectoryReader("./policies").load_data
web_docs = SimpleWebPageReader(html_to_text=True).load_data
all_docs = file_docs + web_docs
Parçalama ve Düğüm Ayrıştırıcıları: Çöp Girişi, Çöp Çıkışı
Parçalamayı doğru yapmak, 'i etkili bir şekilde nasıl kullanacağınızı öğrenirken en önemli adımlardan biridir.
- Parçalama neden önemlidir: Çok büyük → belirteç şişkinliği ve alakasız erişim. Çok küçük → bağlam parçalanması.
- Varsayılanlar: Birçok durum için makul, ancak içerik türünüz için ayarlayın.
- Teknik belgeler: %10-20 örtüşme ile 512-1024 belirteç öbekleri.
- SSS: Soru/Cevap çiftlerini bozulmadan tutmak için daha küçük öbekler (256-512).
- Yasal/Politika: Tanımları + maddeleri korumak için daha büyük öbekler (1024-1536).
from llama_index.core.node_parser import SentenceSplitter
from llama_index.core import Document
parser = SentenceSplitter(chunk_size=800, chunk_overlap=100)
nodes = []
for d in all_docs:
nodes.extend(parser.get_nodes_from_documents([Document(text=d.text, metadata=d.metadata)]))
İndeks Stratejileri: Vektör, Anahtar Kelime veya Hibrit?
Doğru indeksi seçmek çok önemlidir. İyi haber: , bunları birleştirmenize olanak tanır.
- Vektör İndeksi: Semantik arama için harika. "X'i açıklayın" veya belirsiz sorgular için en iyisi.
- Anahtar Kelime (BM25): Kesin terimler, kimlikler, hata kodları, günlükler için güçlü.
- Hibrit: Her ikisini de birleştirin; en iyi adayları bir LLM veya çapraz kodlayıcı ile yeniden sıralayın.
from llama_index.core import VectorStoreIndex, SummaryIndex
from llama_index.core.retrievers import BM25Retriever
from llama_index.core.query_engine import RetrieverQueryEngine
# Önceden ayrıştırılmış düğümlerden vektör indeksi
v_index = VectorStoreIndex(nodes)
# BM25 anahtar kelime erişimcisi
bm25_retriever = BM25Retriever.from_defaults(nodes=nodes, similarity_top_k=6)
# Hibrit: adayları birleştirin, ardından yeniden sıralayın
from llama_index.core.retrievers import RouterRetriever
from llama_index.retrievers.merge import MergerRetriever
v_retriever = v_index.as_retriever(similarity_top_k=6)
hybrid = MergerRetriever(retrievers=[v_retriever, bm25_retriever], top_k=8)
query_engine = RetrieverQueryEngine.from_args(retriever=hybrid)
Yeniden Sıralama ve Filtreler: Aşırı Ödeme Yapmadan Hassasiyeti Artırın
Yeniden sıralama, alınan öbekleri alaka düzeyine göre yeniden sıralayarak yanıt kalitesini artırır.
- Ne zaman yeniden sıralanır: Kullanıcılar konu dışı alıntılar veya uzun, dolgulu bağlamlar bildirirse.
- Çapraz kodlayıcılar (çift kodlayıcı gömme araması → çapraz kodlayıcı yeniden sıralama)
- LLM tabanlı yeniden sıralama (daha maliyetli, bazen nüanslı metinlerde daha akıllıca)
- Meta veri filtreleri (örn.,
source == 'el kitabı', created_at > 2024-01-01)
from llama_index.postprocessor.flag_embedding_reranker import FlagEmbeddingReranker
from llama_index.core.query_engine import RetrieverQueryEngine
reranker = FlagEmbeddingReranker(top_n=5, model="BAAI/bge-reranker-base")
query_engine = v_index.as_query_engine(
similarity_top_k=12,
node_postprocessors=[reranker]
)
İstemler ve Sorgu Motorları: Aramadan Yanıtlara
Bir sorgu motoru, erişimin üretimi karşıladığı yerdir. 'i üretimde nasıl kullanacağınızda uzmanlaşmak için, istemleri ve yanıt sentezini dikkatlice tasarlayın.
- Yanıt sentezi stratejileri:
- Küçük bağlamlar için basit "stuff" (birleştirme)
- Daha uzun bağlamlar için ağaç veya harita azaltma
- Kaynakları göstermek için alıntı modu
from llama_index.core.response_synthesizers import get_response_synthesizer
from llama_index.core import ServiceContext
synth = get_response_synthesizer(response_mode="tree_summarize")
query_engine = v_index.as_query_engine(response_synthesizer=synth)
ans = query_engine.query("İşe alım adımlarını özetleyin ve kaynakları belirtin.")
print(ans)
- Özel istemler: Tonu, yapılandırılmış çıktıları veya korkulukları uyarlayın.
from llama_index.core.prompts import PromptTemplate
qa_tmpl = PromptTemplate(
"""
Siz kısa ve kanıt odaklı bir asistansınız. Yalnızca sağlanan bağlamı kullanın.
Emin değilseniz, bilmediğinizi söyleyin. Şu anahtarlarla JSON döndürün: yanıt, kaynaklar.
Soru: {query_str}
Bağlam: {context_str}
"""
)
query_engine = v_index.as_query_engine(text_qa_template=qa_tmpl)
Agent'lar ve Araçlar: Erişim Yeterli Olmadığında
Bazen yanıtlar eylemler gerektirir: SQL çalıştırmak, API'leri çağırmak veya göz atmak. agent'ları, erişim hattınızla araçları ve akıl yürütmeyi koordine eder.
- Kullanım durumları: KPI panoları (SQL aracı), destek botları (bilet arama API'si), araştırma agent'ları (web + RAG).
from llama_index.core.agent import ReActAgent
from llama_index.tools.sql import SQLQueryEngineTool
from sqlalchemy import create_engine
engine = create_engine("sqlite:///analytics.db")
sql_tool = SQLQueryEngineTool.from_engine(engine)
agent = ReActAgent.from_tools([sql_tool], llm=llm, verbose=True)
agent.chat("2025'in 2. çeyreğindeki aylık müşteri kaybı neydi? Gerekirse, DB'yi sorgulayın.")
Değerlendirme: Körlemesine Yayın Yapmayın
'i sorumlu bir şekilde nasıl kullanacağınızı öğrenmek, dağıtımdan önce hem erişimi hem de yanıtları doğrulamak anlamına gelir.
- Çevrimdışı değerlendirme: Etiketli bir kümede erişim hatırlama/kesinliğini değerlendirin.
- Çevrimiçi değerlendirme: Kullanıcı istemlerini günlüğe kaydedin, memnuniyeti, sapma oranlarını ve halüsinasyonları ölçün.
- LlamaIndex: LlamaIndex, doğruluk ve yanıt alaka düzeyi için değerlendirme yardımcıları sağlar.
from llama_index.core.evaluation import FaithfulnessEvaluator, RelevancyEvaluator
faith = FaithfulnessEvaluator(llm=llm)
rel = RelevancyEvaluator(llm=llm)
pred = query_engine.query("Politikamızdaki SOC 2 kontrol ailelerini listeleyin.")
print("sadık mı?", faith.evaluate_response(pred))
print("alakalı mı?", rel.evaluate_response(pred))
- Pratik bar: Dahili asistanlar için, geniş lansmandan önce en iyi sorgularda >%80 "yararlı" derecelendirmeyi hedefleyin.
Kalıcılık ve Vektör Depoları: Ölçeklenebilir Hale Getirin
Bellekte oluşturulan indeksler gerçek iş yükleri için yeterli olmayacaktır. Bir vektör DB'sinde kalıcı hale getirin ve artımlı güncellemeleri etkinleştirin.
- Popüler arka uçlar: Pinecone, Weaviate, Chroma, Elasticsearch/OpenSearch, Qdrant.
- İpucu: Kiracı veya departman başına ad alanları kullanın; meta verileri zengin tutun.
# Örnek: Chroma
# pip install chromadb llama-index-vector-stores-chroma
from llama_index.vector_stores.chroma import ChromaVectorStore
from llama_index.core import StorageContext
import chromadb
chroma_client = chromadb.PersistentClient(path="./chroma_store")
collection = chroma_client.get_or_create_collection("company_knowledge")
vector_store = ChromaVectorStore(chroma_collection=collection)
storage_context = StorageContext.from_defaults(vector_store=vector_store)
index = VectorStoreIndex.from_documents(all_docs, storage_context=storage_context)
Güvenlik ve Yönetişim: Herkesin Unuttuğu Kısım
- PII işleme: Alım sırasında hassas alanları düzeltin veya karma hale getirin.
- Erişim kontrolleri: Meta veri kısıtlamalarıyla kullanıcı rollerine göre filtreleyin.
- İçerik tazeliği: Yeniden almayı planlayın; sürümleri işaretleyin.
- Güvenlik: İsteklerde ret politikaları ve yalnızca kaynak kısıtlamaları ekleyin.
# Örnek: sorgu zamanında meta veri tabanlı filtreleme
retriever = index.as_retriever(similarity_top_k=8)
retriever.metadata_filters = {"department": ["legal", "security"], "published": [True]}
Prototipden Üretime: Dağıtım Desenleri
- Sunucu deseni: Bir
/query uç noktası yayınlayın; indeksi bellekte sıcak tutun.
- Sunucusuz tuzak: Soğuk başlatmalar + büyük modeller gecikmeyi etkileyebilir; yönetilen çıkarımı düşünün.
- Önbelleğe alma: Gömme işlemlerini ve sık sorgu sonuçlarını önbelleğe alın; kısmi güncellemeleri etkinleştirin.
- Gözlemlenebilirlik: Alınan düğümleri, belirteç kullanımını, yanıt uzunluğunu ve kullanıcı geri bildirimini günlüğe kaydedin.
# Minimal FastAPI sarmalayıcı
# pip install fastapi uvicorn
from fastapi import FastAPI
app = FastAPI
qe = index.as_query_engine(llm=llm)
@app.post("/query")
async def query(payload: dict):
q = payload.get("q", "")
resp = qe.query(q)
return {"answer": str(resp), "sources": [s.node.metadata for s in resp.source_nodes]}
Gerçek Dünya Planları: Yolunuzu Seçin
- İndeks: Yeniden sıralama ile hibrit (BM25 + Vektör)
- Korkuluklar: Yalnızca kaynak modu; "Bilmiyorum" geri dönüşü
- KPI: Politika soruları için çözüm oranı
- Müşteri Destek Yardımcı Pilotu
- İndeks: Ürün belgeleri + sürüm notları + biletler
- Agent'lar: Sipariş/bilet durumunu kontrol etmek için API aracı
- KPI: İlk temas çözümü, sapma, CSAT
- İndeks: Web + PDF'ler + notlar; güçlü yineleme giderme
- Yeniden sıralama: Çapraz kodlayıcı; sentez: harita azaltma
- KPI: İçgörüye ulaşma süresi; alıntı doğruluğu
- Araçlar: Metrik tanımlarında SQL motoru + RAG
- Yönetişim: Satır düzeyi politikalar; sorgu denetimi
- KPI: Gerçekliğe karşı doğruluk
Maliyet ve Gecikme: Hızlı (ve Ucuz) Tutun
- Gömme işlemleri: Mümkün olduğunca toplu işleyin; geri çağırma için daha küçük modeller kullanın, seçici olarak yeniden sıralayın.
- Bağlam boyutu: En alakalı öbeklerin 1-2k belirtecini hedefleyin.
- Önbelleğe alma: Sıcak sorgular için en iyi-K erişimini önbelleğe alın; karma istemlerle LLM çağrılarını not alın.
- Paralellik: Kuyruk gecikmesini azaltmak için fan-out erişimi → fan-in yeniden sıralama.
'i Nasıl Kullanacağınızı Öğrenirken Sık Karşılaşılan Tuzaklar
- Aşırı öbekleme, sığ, gürültülü erişime yol açar
- Meta veri filtreleri yok, bu da alakasız kaynakların içeri sızmasına neden oluyor
- Tüm içerik için tek bir indeks türüne güvenmek
- Değerlendirmeyi atlamak; bir kalite çubuğu olmadan göndermek
- İndekslerin eski olmasına izin vermek; planlı yenileme yok
Bu Arada: Düzenleyicide İş Akışınızı Hızlandırma
İstemler, öbekleyiciler ve erişim ayarlarında yineleme yaparken, Sider.ai gibi bir AI kodlama ve araştırma kenar çubuğunun döngüyü hızlandırabileceğini belirtmekte fayda var. Tarayıcınızdan ayrılmadan kod parçacıklarını, istemleri ve değerlendirme notlarını el altında tutabilir, istem değişikliklerinin farklarını oluşturabilir ve varyasyonları hızla test edebilirsiniz. Bu, farklı erişim stratejileri arasında 'i nasıl kullanacağınızı ayarlarken özellikle kullanışlıdır. Adım Adım Kontrol Listesi: Sıfırdan Üretime
- Kaynakları alın ve meta verileri normalleştirin
- İçerik türüne göre öbek boyutlarını ayarlayın
- Vektör + BM25 indeksleri oluşturun; hibrit erişimi etkinleştirin
- Yeniden sıralama ve meta veri filtreleri ekleyin
- İstemleri özelleştirin; alıntıları ve ret politikasını etkinleştirin
- Bir test kümesinde doğruluğu ve alaka düzeyini değerlendirin
- Bir vektör deposunda kalıcı hale getirin; artımlı güncellemeleri etkinleştirin
- Gözlemlenebilirlik, önbelleğe alma ve RBAC filtreleri ekleyin
- Bir API'ye sarın ve SLA'ları ayarlayın; arıza modlarını belgeleyin
Temel Çıkarımlar
- Sağlam bir RAG uygulaması istiyorsanız, 'i nasıl kullanacağınızı öğrenmek size haftalarca tutkal mühendisliğinden tasarruf sağlayacaktır.
- Basit başlayın, ardından hibrit erişim, yeniden sıralama ve yapılandırılmış istemler ekleyin.
- Ölçeklendirmeden önce değerlendirin; indeksleri kalıcı hale getirin ve üretimde kaliteyi izleyin.
- İlk günden yönetişim için tasarlayın; güvenlik bir eklenti değildir.
Sonraki Adımlar
- Hızlı başlangıç prototipini küçük bir belge kümesinde oluşturun.
- Hibrit erişim ve bir yeniden sıralayıcı ile deneme yapın.
- Değerlendirme ve alıntılar ekleyin; kalite metriklerini izleyin.
- Kalıcı bir vektör deposuna geçin ve bir API dağıtın.
SSS
S1: , RAG uygulamalarında ne için kullanılır?
, verilerinizi alım, indeksleme ve erişim bileşenleriyle LLM'lere bağlamanıza yardımcı olur. Parçalama, vektör/anahtar kelime indeksleri ve sorgu düzenlemesini ele alarak RAG sistemleri oluşturmayı kolaylaştırır.
S2: 'te doğru indeks türünü nasıl seçerim?
Semantik sorgular için bir vektör indeksi, kimlikler veya kodlar gibi kesin eşleşmeler için BM25 ve en iyi genel geri çağırma ve kesinlik için hibrit bir yaklaşım kullanın. Birçok ekip her ikisini de birleştirir ve en iyi-K sonuçları için yeniden sıralama ekler.
S3: LlamaIndex kullanırken doğruluğu nasıl artırabilirim?
Parça boyutlarını ayarlayın, zengin meta veriler ekleyin, hibrit erişimi etkinleştirin ve bir yeniden sıralayıcı ekleyin. Ayrıca, güvenilirlik ve alaka düzeyi için değerlendirme uygulayın ve kaynakları göstermek için alıntı modunu kullanın.
S4: LlamaIndex mevcut vektör veritabanımla çalışabilir mi?
Evet. LlamaIndex, Pinecone, Weaviate, Chroma, Qdrant ve Elasticsearch gibi popüler vektör depolarıyla entegre olur. Ölçeklenebilirlik ve artımlı güncellemeler için indeksleri kalıcı hale getirin.
S5: Bir LlamaIndex uygulamasını üretime nasıl dağıtabilirim?
Sorgu motorunuzu bir API (örn. FastAPI) içinde sarın, verileri bir vektör deposunda kalıcı hale getirin, önbelleğe alma ve gözlemlenebilirlik ekleyin ve kaliteyi sürekli olarak değerlendirin. Güvenlik için meta veri filtrelerini ve erişim kontrolünü uygulayın.