Hogyan használd a LlamaIndexet: Gyakorlati útmutató a nulláról a termelésig
Ha valaha is próbáltál retrieval-augmented generation (RAG) alkalmazást építeni, és azt gondoltad: „Miért ilyen bonyolult az embeddingek, a vektoradatbázisok és a promptok összekapcsolása?”, nem vagy egyedül. A LlamaIndex azért létezik, hogy ez a folyamat gyors, ésszerű és termelésre kész legyen. Ebben a gyakorlati, megoldásorientált útmutatóban végigvezetünk a LlamaIndex teljes használatán – adatbetöltés, indexelés, lekérdezés, értékelés és telepítés –, hogy valami megbízhatót szállíthass anélkül, hogy elvesznél a ragasztókódban.
Kérdésközpontú struktúrát fogunk használni, progresszív lépésekkel, futtatható kódrészletekkel és valós tippekkel. Akár egy chatbotot prototipizálsz belső dokumentumokhoz, akár egy tudásasszisztenst telepítesz ügyfelek számára, a LlamaIndex hatékony használatának elsajátítása napokat takaríthat meg.
: A LlamaIndex egy keretrendszer, amely segít összekapcsolni az adataidat nagy nyelvi modellekkel indexelési, visszakeresési és vezénylési eszközökkel – ideális RAG-hoz, ügynökökhöz és strukturált kimenetekhez.
Mi az a LlamaIndex és miért érdemes használni?
- A LlamaIndex egy adatkörnyezet LLM alkalmazásokhoz. Építőelemeket biztosít a következőkhöz:
- Betöltés: Fájlok, weboldalak, adatbázisok és API-k betöltése.
- Darabolás és indexelés: A nyers tartalmat lekérdezhető struktúrákká alakítja (vektor-, kulcsszó-, gráfindexek).
- Visszakeresés: Kontextus visszakeresése rugalmas stratégiákkal (BM25, hibrid, újrarendezés).
- Lekérdezési motorok és ügynökök: A visszakeresés, az eszközök és a promptok koherens QA élménnyé alakítása.
- Értékelés és monitorozás: A visszakeresés minőségének és a válasz relevanciájának megítélése.
- Mikor érdemes a LlamaIndexet használni:
- Robusztus RAG stacket szeretnél anélkül, hogy újra feltalálnád a darabolást, az embeddingeket és a visszakeresést.
- Több adatforrást kell kombinálnod (PDF-ek + Notion + SQL).
- Szeretnél kísérletezni hibrid visszakereséssel, újrarendezéssel vagy strukturált kimenetekkel.
- Alapvető gondolkodási modell a LlamaIndex használatának elsajátításakor:
- Adat → Csomópontok → Index → Visszakereső → Lekérdezési motor → Alkalmazás
Gyorsindítás: A minimális RAG hurok
Ez a leggyorsabb út egy működő prototípushoz. Dokumentumokat fogunk betölteni, vektorindexet építeni és kérdéseket feltenni.
# 1) Telepítés
# 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) A modell és az embeddingek konfigurálása
os.environ["OPENAI_API_KEY"] = "YOUR_KEY" # vagy használj bármilyen támogatott LLM/embedding szolgáltatót
llm = OpenAI(model="gpt-4o-mini")
embed_model = OpenAIEmbedding(model="text-embedding-3-small")
# 3) Dokumentumok betöltése (pl. ./data/*.pdf, .md, .txt)
docs = SimpleDirectoryReader("./data").load_data
# 4) Index létrehozása
index = VectorStoreIndex.from_documents(docs, embed_model=embed_model)
# 5) Lekérdezési motor létrehozása és kérdés feltevése
query_engine = index.as_query_engine(llm=llm)
response = query_engine.query("Melyek a dokumentumokban említett legfontosabb biztonsági gyakorlatok?")
print(response)
Ez a lényeg. Innen a valós alkalmazások jobb darabolást, újrarendezést, strukturált promptokat és megfigyelhetőséget adnak hozzá.
Betöltés: Hozd a saját adataidat (BYOD) a helyes módon
Amikor eldöntöd, hogyan használd a LlamaIndexet valós adatokhoz, válassz a forrásaidnak megfelelő betöltőket, és őrizd meg a struktúrát.
- Fájlok:
SimpleDirectoryReader, PDF/HTML/Markdown olvasók
- Web:
BeautifulSoupWebReader, sitemap olvasók
- SaaS: Notion, Confluence, Slack, Google Drive (összekötőkön keresztül)
- Adatbázisok: SQL és vektor adatbázisok (Pinecone, Weaviate, Chroma, Elasticsearch)
- Tipp: Normalizáld a metaadatokat (cím, szerző, URL, created_at). A jó metaadatok később felturbózzák az újrarendezést és a szűrést.
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
Darabolás és csomópont-elemzők: Ami belemegy, az jön ki
A darabolás helyes beállítása az egyik legfontosabb lépés a LlamaIndex hatékony használatának elsajátításakor.
- Miért fontos a darabolás?: Túl nagy → token puffadás és irreleváns visszakeresés. Túl kicsi → kontextus fragmentáció.
- Alapértelmezett értékek: Sok esetben ésszerű, de hangold a tartalomtípusodhoz.
- Technikai dokumentumok: 512–1024 token darabok 10–20%-os átfedéssel.
- GYIK: Kisebb darabok (256–512), hogy a K/V párok épek maradjanak.
- Jogi/Szabályzati: Nagyobb darabok (1024–1536) a definíciók + záradékok megőrzése érdekében.
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)]))
Indexelési stratégiák: Vektor, kulcsszó vagy hibrid?
A megfelelő index kiválasztása kulcsfontosságú. A jó hír: a LlamaIndex lehetővé teszi azok kombinálását.
- Vektorindex: Kiváló a szemantikus kereséshez. A legjobb az „X magyarázata” vagy a homályos lekérdezésekhez.
- Kulcsszó (BM25): Erős a pontos kifejezésekhez, azonosítókhoz, hibakódokhoz, naplókhoz.
- Hibrid: Kombináld mindkettőt; rendezd újra a legjobb jelölteket egy LLM-mel vagy keresztkódolóval.
from llama_index.core import VectorStoreIndex, SummaryIndex
from llama_index.core.retrievers import BM25Retriever
from llama_index.core.query_engine import RetrieverQueryEngine
# Vektorindex az előre elemzett csomópontokból
v_index = VectorStoreIndex(nodes)
# BM25 kulcsszó-visszakereső
bm25_retriever = BM25Retriever.from_defaults(nodes=nodes, similarity_top_k=6)
# Hibrid: jelöltek egyesítése, majd újrarendezés
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)
Újrarendezés és szűrők: Növeld a pontosságot anélkül, hogy túlfizetnél
Az újrarendezés javítja a válasz minőségét azáltal, hogy a visszakeresett darabokat relevanciájuk szerint rendezi át.
- Mikor érdemes újrarendezni?: Ha a felhasználók témán kívüli idézeteket vagy hosszú, párnázott kontextusokat jelentenek.
- Keresztkódolók (bi-encoder embedding keresés → keresztkódoló újrarendezés)
- LLM-alapú újrarendezés (költségesebb, néha okosabb a árnyalt szövegeken)
- Metaadat-szűrők (pl.
source == 'handbook', 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]
)
Promptolás és lekérdezési motorok: A kereséstől a válaszokig
A lekérdezési motor az a hely, ahol a visszakeresés találkozik a generálással. Ahhoz, hogy elsajátítsd a LlamaIndex használatát a termelésben, gondosan tervezd meg a promptokat és a válaszszintézist.
- Válaszszintézis stratégiák:
- Egyszerű „stuff” (összefűzés) kis kontextusokhoz
- Fa vagy map-reduce hosszabb kontextusokhoz
- Idézet mód a források megjelenítéséhez
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("Összegezd a belépési lépéseket, és idézd a forrásokat.")
print(ans)
- Egyéni promptok: Szabd testre a hangnemet, a strukturált kimeneteket vagy a korlátokat.
from llama_index.core.prompts import PromptTemplate
qa_tmpl = PromptTemplate(
"""
Te egy tömör, bizonyíték-központú asszisztens vagy. Csak a megadott kontextust használd.
Ha nem vagy biztos benne, mondd, hogy nem tudod. JSON visszaadása a következő kulcsokkal: válasz, források.
Kérdés: {query_str}
Kontextus: {context_str}
"""
)
query_engine = v_index.as_query_engine(text_qa_template=qa_tmpl)
Ügynökök és eszközök: Ha a visszakeresés nem elég
Néha a válaszokhoz műveletekre van szükség: SQL futtatására, API-k hívására vagy böngészésre. A LlamaIndex ügynökök koordinálják az eszközöket és az érvelést a visszakeresési folyamatoddal.
- Használati esetek: KPI irányítópultok (SQL eszköz), támogatási botok (jegykereső API), kutatási ügynökök (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("Mennyi volt a havi lemorzsolódás 2025 Q2-ben? Ha szükséges, kérdezd le az adatbázist.")
Értékelés: Ne szállíts vakon
A LlamaIndex felelősségteljes használatának elsajátítása azt jelenti, hogy a bevezetés előtt ellenőrizni kell a visszakeresést és a válaszokat is.
- Offline értékelés: Ítélje meg a visszakeresés recall/precision értékét egy címkézett halmazon.
- Online értékelés: Naplózza a felhasználói promptokat, mérje meg a elégedettséget, az elhajlási arányokat és a hallucinációkat.
- Beépített funkciók: A LlamaIndex értékelési segédeszközöket biztosít a hűséghez és a válasz relevanciájához.
from llama_index.core.evaluation import FaithfulnessEvaluator, RelevancyEvaluator
faith = FaithfulnessEvaluator(llm=llm)
rel = RelevancyEvaluator(llm=llm)
pred = query_engine.query("Sorold fel a SOC 2 kontrollcsaládokat a szabályzatunkban.")
print("hűséges?", faith.evaluate_response(pred))
print("releváns?", rel.evaluate_response(pred))
- Gyakorlati mérce: Belső asszisztensek esetében a széles körű bevezetés előtt a legjobb lekérdezésekre vonatkozóan >80%-os „hasznos” értékelést célozz meg.
Perzisztencia és vektoradatbázisok: Tedd skálázhatóvá
A memóriában épített indexek nem lesznek elegendőek a valós munkaterhelésekhez. Perzisztáld egy vektor adatbázisba, és engedélyezd a növekményes frissítéseket.
- Népszerű háttérrendszerek: Pinecone, Weaviate, Chroma, Elasticsearch/OpenSearch, Qdrant.
- Tipp: Használj névtereket bérlőnként vagy osztályonként; tartsd a metaadatokat gazdagon.
# Példa: 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)
Biztonság és irányítás: A rész, amelyet mindenki elfelejt
- PII kezelés: A betöltés során takard el vagy hasheld a érzékeny mezőket.
- Hozzáférés-vezérlés: Szűrj a felhasználói szerepkörök szerint metaadat-korlátozásokkal.
- Tartalom frissessége: Ütemezd újra a betöltést; jelöld meg a verziókat.
- Biztonság: Adj hozzá elutasítási irányelveket és csak forrásból származó korlátozásokat a promptokban.
# Példa: metaadat-alapú szűrés a lekérdezéskor
retriever = index.as_retriever(similarity_top_k=8)
retriever.metadata_filters = {"department": ["legal", "security"], "published": [True]}
A prototípustól a termelésig: Telepítési minták
- Szerver minta: Tegyen közzé egy
/query végpontot; tartsa az indexet melegen a memóriában.
- Szerver nélküli buktató: A hidegindítások + a nagy modellek ronthatják a késleltetést; fontold meg a felügyelt következtetést.
- Gyorsítótárazás: Gyorsítótárazd az embeddingeket és a gyakori lekérdezési eredményeket; engedélyezd a részleges frissítéseket.
- Megfigyelhetőség: Naplózd a visszakeresett csomópontokat, a tokenhasználatot, a válasz hosszát és a felhasználói visszajelzéseket.
# Minimális FastAPI wrapper
# 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]}
Valós tervek: Válaszd ki az utad
- Belső szabályzat asszisztens
- Index: Hibrid (BM25 + Vektor) újrarendezéssel
- Korlátok: Csak forrásból származó mód; „Nem tudom” tartalék
- KPI: A szabályzati kérdések megoldási aránya
- Index: Termékdokumentumok + kiadási megjegyzések + jegyek
- Ügynökök: API eszköz a rendelés/jegy állapotának ellenőrzéséhez
- KPI: Első kapcsolatfelvételi megoldás, elhajlás, CSAT
- Index: Web + PDF-ek + jegyzetek; erős deduplikáció
- Újrarendezés: Keresztkódoló; szintézis: map-reduce
- KPI: A betekintéshez szükséges idő; az idézetek pontossága
- Eszközök: SQL motor + RAG a metrikadefiníciókon
- Irányítás: Sor-szintű szabályzatok; lekérdezési audit
- KPI: Helyesség vs. valóságalap
Költség és késleltetés: Tartsd gyorsan (és olcsón)
- Embeddingek: Kötegelteld, ahol lehetséges; használj kisebb modelleket a visszahíváshoz, szelektíven rendezd újra.
- Kontextusméret: Törekedj a legrelevánsabb darabok 1–2k tokenjére.
- Gyorsítótárazás: Gyorsítótárazd a top-K visszakeresést a gyakori lekérdezésekhez; memoizáld az LLM hívásokat hashelt promptokkal.
- Párhuzamosság: Fan-out visszakeresés → fan-in újrarendezés a farok késleltetésének csökkentése érdekében.
Gyakori buktatók a LlamaIndex használatának elsajátításakor
- Túlzott darabolás, ami sekély, zajos visszakereséshez vezet
- Nincsenek metaadat-szűrők, ami miatt irreleváns források szivárognak be
- Egyetlen indextípusra támaszkodás minden tartalomhoz
- Értékelés kihagyása; minőségi mérce nélküli szállítás
- Az indexek elavulása; nincs ütemezett frissítés
Egyébként: A munkafolyamat felgyorsítása a szerkesztőben
Ahogy iterálsz a promptokon, a darabolókon és a visszakeresési beállításokon, érdemes megjegyezni, hogy egy olyan AI kódolási és kutatási oldalsáv, mint a Sider.ai, felgyorsíthatja a hurkot. Kézben tarthatod a kódrészleteket, a promptokat és az értékelési jegyzeteket, generálhatod a promptváltozások különbségeit, és gyorsan tesztelheted a variációkat anélkül, hogy elhagynád a böngésződet. Ez különösen hasznos, ha finomítod a LlamaIndex használatát a különböző visszakeresési stratégiák között. Lépésről lépésre ellenőrzőlista: A nulláról a termelésig
- Források betöltése és metaadatok normalizálása
- A darabméretek hangolása tartalomtípus szerint
- Vektor + BM25 indexek építése; hibrid visszakeresés engedélyezése
- Újrarendezés és metaadat-szűrők hozzáadása
- Promptok testreszabása; idézetek és elutasítási irányelvek engedélyezése
- Hűség és relevancia értékelése egy teszthalmazon
- Perzisztálás egy vektor adatbázisba; növekményes frissítések engedélyezése
- Megfigyelhetőség, gyorsítótárazás és RBAC szűrők hozzáadása
- API-ba csomagolás és SLA-k beállítása; hibamódok dokumentálása
Főbb tudnivalók
- Ha robusztus RAG alkalmazást szeretnél, a LlamaIndex használatának elsajátítása hetekig tartó ragasztómérnöki munkát takarít meg.
- Kezdd egyszerűen, majd rétegezd a hibrid visszakeresést, az újrarendezést és a strukturált promptokat.
- Értékelj, mielőtt skálázol; perzisztáld az indexeket és figyeld a minőséget a termelésben.
- Tervezz irányítást az első naptól kezdve – a biztonság nem egy utólagos kiegészítés.
Következő lépések
- Prototipizáld a gyorsindítást egy kis dokumentumhalmazon.
- Kísérletezz a hibrid visszakereséssel és egy újrarendezővel.
- Adj hozzá értékelést és idézeteket; kövesd nyomon a minőségi mutatókat.
- Térj át egy perzisztens vektor adatbázisra, és telepíts egy API-t.
GYIK
Q1:Mire használják a LlamaIndexet a RAG alkalmazásokban?
A LlamaIndex segít összekapcsolni az adataidat az LLM-ekkel betöltési, indexelési és visszakeresési összetevőkkel. Egyszerűsíti a RAG rendszerek építését a darabolás, a vektor/kulcsszó indexek és a lekérdezések vezénylésének kezelésével.
Q2:Hogyan válasszam ki a megfelelő indextípust a LlamaIndexben?
Használj vektorindexet a szemantikus lekérdezésekhez, BM25-öt a pontos egyezésekhez, például azonosítókhoz vagy kódokhoz, és hibrid megközelítést a legjobb általános recall és precision érdekében. Sok csapat kombinálja mindkettőt, és újrarendezést ad hozzá a top-K eredményekhez.
3. kérdés: Hogyan növelhetem a pontosságot a LlamaIndex használatakor?
Hangolja a chunk méreteket, adjon hozzá gazdag metaadatokat, engedélyezze a hibrid lekérdezést, és adjon hozzá egy újrarendezőt. Emellett valósítson meg értékelést a hitelesség és a relevancia érdekében, és használja az idézet módot a források megjelenítéséhez.
4. kérdés: Működik a LlamaIndex a meglévő vektoradatbázisommal?
Igen. A LlamaIndex integrálható olyan népszerű vektor tárolókkal, mint a Pinecone, Weaviate, Chroma, Qdrant és Elasticsearch. A skálázhatóság és a növekményes frissítések érdekében őrizze meg az indexeket.
5. kérdés: Hogyan telepíthetek egy LlamaIndex alkalmazást éles környezetbe?
Csomagolja be a lekérdező motort egy API-ba (pl. FastAPI), tárolja az adatokat egy vektor tárolóban, adjon hozzá gyorsítótárazást és megfigyelhetőséget, és folyamatosan értékelje a minőséget. A biztonság érdekében kényszerítse ki a metaadat szűrőket és a hozzáférés-vezérlést.